Cypher

Cypher is a Python front-end for Cyclus, an agent-based nuclear fuel cycle simulator. It lets users define Cyclus simulations with composable Python objects, generate readable XML inputs, and run them through Cyclus.

The project takes inspiration from the Python input API provided by OpenMC. Where the two simulators have analogous concepts, Cypher should feel familiar to OpenMC users while remaining faithful to Cyclus's own model and terminology.

Important

Cypher is in pre-alpha development. Its public API will continue to evolve.

Naming

• PyPI distribution: cyclus-cypher
• Python import: cypher
• Source repository: dean-krueger/cypher

The distribution and import names intentionally differ. Ordinary package installation under the cyclus-cypher distribution name is planned, but the recommended evaluation path today is the container described below.

# planned package name; not the recommended milestone-five install path yet
python -m pip install cyclus-cypher

import cypher

See the user guide, examples guide, and complete examples/bakery.py authoring example. Technical reviewers may also want the code tour.

Nested Archetype Fields

Cypher recursively supports standard nested C++ archetype types built from scalars, std::vector, std::list, std::set, std::pair, and std::map. Generated signatures and stubs describe the accepted Python shape, while Python's help(cycamore.Source), describe_field(), field_example(), and field_example_value() make discovered fields inspectable in IPython. Validation and XML serialization use the same recursive model, including deeply nested structures such as map<string, map<string, pair<double, string>>>.

See Nested container fields for the accepted Python forms and a complete Cycamore Separations example.

Current roadmap documents: milestone two execution, milestone three container, and milestone four grammar compatibility, and milestone five documentation. See Cypher Container for the local image workflow.

Development

Create a virtual environment and install the package with its development tools:

python -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"

Run the initial checks with:

ruff check .
pytest
python -m build
python -m twine check dist/*

Container

Build the notebook-ready image locally:

docker build -t cypher:local .

The image builds on the official Cymetric environment and includes Cyclus, Cycamore, Cymetric, Cypher, IPython, and the Python (Cypher) Jupyter kernel. Its scientific notebook stack includes NumPy, pandas, Matplotlib, SciPy, and Seaborn, plus Graphviz support for Cymetric flow graphs. It is intended for VS Code Dev Containers with a mounted /workspace rather than launching JupyterLab itself.

The build runs discovery, verifies the registered kernel including a simple Matplotlib plot, and runs the bakery example through Cyclus.

The current upstream image is Linux amd64; multi-architecture support is not part of this milestone. The current alpha is available with:

docker pull deankrueger/cypher:alpha

License

Cypher is available under the BSD 3-Clause License, matching the Cyclus ecosystem. See LICENSE.