gitronics 0.5.3__tar.gz → 0.5.5__tar.gz

gitronics-0.5.5/.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: Docs
+
+on:
+    push:
+        tags:
+            - "v[0-9]+.[0-9]+.[0-9]*"
+    # Allow manual triggering from the Actions tab
+    workflow_dispatch:
+
+permissions:
+    contents: write # needed to push to gh-pages branch
+
+jobs:
+    deploy-docs:
+        name: Build & deploy documentation
+        runs-on: ubuntu-latest
+
+        steps:
+            - uses: actions/checkout@v4
+              with:
+                  # Fetch full history so mike can read previous deployments
+                  fetch-depth: 0
+
+            - name: Set up Python
+              uses: actions/setup-python@v5
+              with:
+                  python-version: "3.11"
+
+            - name: Install documentation dependencies
+              run: pip install -r docs/requirements.txt
+
+            - name: Extract version from tag
+              id: version
+              run: |
+                  # Strip the leading "v" so MkDocs sees "1.2.3", not "v1.2.3"
+                  VERSION="${GITHUB_REF_NAME#v}"
+                  echo "version=$VERSION" >> "$GITHUB_OUTPUT"
+
+            - name: Build & deploy to GitHub Pages
+              run: |
+                  git config user.name  "github-actions[bot]"
+                  git config user.email "github-actions[bot]@users.noreply.github.com"
+                  # Deploy this version and update the "latest" alias
+                  pip install mike
+                  mike deploy --push --update-aliases "${{ steps.version.outputs.version }}" latest
+                  mike set-default --push latest

{gitronics-0.5.3 → gitronics-0.5.5}/.gitignore

@@ -4,3 +4,4 @@ __pycache__/
 *.so
 *.pyd
 *.pdb
+/site

{gitronics-0.5.3 → gitronics-0.5.5}/Cargo.lock

@@ -384,7 +384,7 @@ dependencies = [
 
 [[package]]
 name = "gitronics"
-version = "0.5.3"
+version = "0.5.5"
 dependencies = [
  "chrono",
  "clap",

{gitronics-0.5.3 → gitronics-0.5.5}/Cargo.toml

@@ -1,9 +1,10 @@
 [package]
 name = "gitronics"
-version = "0.5.3"
+version = "0.5.5"
 edition = "2024"
 description = "Build MCNP neutronics models from modular components"
 license = "EUPL-1.2"
+readme = "README.md"
 
 [[bin]]
 name = "gitronics"

{gitronics-0.5.3 → gitronics-0.5.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gitronics
-Version: 0.5.3
+Version: 0.5.5
 Classifier: Programming Language :: Rust
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy

gitronics-0.5.5/README.md

@@ -0,0 +1,103 @@
+<div align="center">
+  <img src="docs/logo.png" alt="Gitronics logo" width="140"/>
+  <h1>Gitronics</h1>
+  <p><strong>Build MCNP neutronics models from modular, version-controlled components.</strong></p>
+
+  [![CI](https://github.com/Fusion4Energy/gitronics/actions/workflows/ci.yml/badge.svg)](https://github.com/Fusion4Energy/gitronics/actions/workflows/ci.yml)
+  [![Docs](https://github.com/Fusion4Energy/gitronics/actions/workflows/docs.yml/badge.svg)](https://fusion4energy.github.io/gitronics/latest/)
+  [![PyPI](https://img.shields.io/pypi/v/gitronics)](https://pypi.org/project/gitronics/)
+  [![License: EUPL-1.2](https://img.shields.io/badge/License-EUPL--1.2-blue.svg)](LICENSE)
+</div>
+
+---
+
+Gitronics lets you decompose a monolithic **MCNP** input file into independent, version-controllable components — universe filler models, an envelope structure, and separate data cards — and reassemble them at build time via a YAML configuration.
+
+**Full documentation: [fusion4energy.github.io/gitronics](https://fusion4energy.github.io/gitronics/latest/)**
+
+## Why?
+
+| Problem with monolithic models | Gitronics solution |
+|---|---|
+| `git diff` is unreadable | Each component is a separate file |
+| Running variants means copying the whole file | Override only the fields that change |
+| Teams can't work on sub-models in parallel | Each filler model is independent |
+| Hard to know exactly what was run | Commit hash and timestamp written into every assembled file |
+
+## Installation
+
+```bash
+pip install gitronics
+```
+
+Requires Python 3.9+. Pre-built wheels for Linux, macOS, and Windows are published to PyPI — no Rust toolchain needed.
+
+## Quick start
+
+**Migrate an existing model:**
+
+```bash
+gitronics migrate path/to/my_model.mcnp --output-path ./my_project
+```
+
+**Build a model:**
+
+```bash
+gitronics build my_project/configurations/baseline.yaml --output-path my_project/output/
+```
+
+**Get help:**
+
+```bash
+gitronics --help
+gitronics build --help
+gitronics migrate --help
+```
+
+## Project layout
+
+```
+my_project/
+├── configurations/
+│   ├── baseline.yaml          ← declares which fillers go where
+│   └── variant_A.yaml         ← inherits baseline, overrides selected envelopes
+├── output/
+│   └── .gitignore
+└── reference_model/
+    ├── envelope_structure.mcnp
+    ├── filler_models/
+    │   ├── component_A.mcnp
+    │   └── component_B.mcnp
+    └── data_cards/
+        ├── materials/
+        ├── sources/
+        └── tallies/
+```
+
+## Configuration example
+
+```yaml
+project_roots: [..]
+
+envelope_structure: envelope_structure
+source: dt_plasma
+materials: [all_materials]
+tallies: [tritium_breeding_ratio]
+
+envelopes:
+  blanket_inner: blanket_v3
+  blanket_outer: blanket_reference
+  divertor:      null           # void — no FILL card inserted
+```
+
+Configurations support inheritance: a variant config can set `overrides: baseline.yaml` and override only the fields that differ.
+
+## Documentation
+
+The full documentation covers installation, CLI reference, configuration options, best practices, and worked examples:
+
+**[fusion4energy.github.io/gitronics](https://fusion4energy.github.io/gitronics/latest/)**
+
+## License
+
+[EUPL-1.2](LICENSE)

gitronics-0.5.5/docs/best-practices.md

@@ -0,0 +1,99 @@
+# Best Practices
+
+## Project layout
+
+### Keep one project per repository
+
+Each Gitronics project should live in its own repository (or a well-isolated subdirectory in a mono-repo). This makes branch history, tagging, and code review meaningful.
+
+### Use `.gitignore` in `output/`
+
+The `migrate` command creates an `output/.gitignore` that ignores all files in that directory. Never commit assembled MCNP files — they are build artefacts and can be reproduced from the sources.
+
+### Prefer shallow directory trees for `project_roots`
+
+Deeply nested source trees slow down file discovery. Keep filler models, data cards, and the envelope structure in predictable directories at one or two levels deep.
+
+---
+
+## Naming conventions
+
+### Use descriptive, lowercase stem names
+
+Stem names appear in configuration files and in assembled-model metadata. Choose names that describe the *physics content*, not the version or date:
+
+| Avoid | Prefer |
+|---|---|
+| `model_2024_v3_final` | `blanket_tungsten_fw` |
+| `mat_13` | `reduced_activation_ferritic_steel` |
+| `tally1` | `tritium_breeding_ratio` |
+
+### Match envelope names to physical regions
+
+Envelope names in the configuration file (`envelopes:` map) must match the placeholder comments written in the envelope structure file. Naming them after the physical component they represent makes configurations self-documenting.
+
+---
+
+## Configuration management
+
+### Use a baseline + override hierarchy
+
+Define a `baseline.yaml` that represents the full reference model. Create separate configuration files for each assessment or variant that override only the fields that differ. This minimises duplication and makes it easy to see what changed between assessments.
+
+```
+configurations/
+├── baseline.yaml               ← full reference model
+├── void_check.yaml             ← overrides: baseline; all envelopes → null
+├── sensitivity_study_A.yaml    ← overrides: baseline; changes one filler
+└── assessment_specific/
+    └── design_point_X.yaml     ← multi-level override chain
+```
+
+### Pin `project_roots` carefully
+
+`project_roots` is resolved relative to the configuration file. Using `[..]` (the parent directory of `configurations/`) is the conventional choice and keeps paths stable when the project is cloned to different machines.
+
+---
+
+## Filler model design
+
+### One universe per file
+
+Each filler model file should contain exactly one universe. This keeps the granularity consistent and makes `git blame` and `git log` useful at the component level.
+
+### Record transformation intent in metadata
+
+If a filler model is placed with a transformation (`TR` card), document that in the `.metadata` file so the relationship between filler geometry and its placement is explicit. Avoid hardcoding transformations inside the filler MCNP file itself.
+
+### Avoid cross-references between fillers
+
+Filler models should be self-contained. Cells in one filler should not reference surfaces or materials defined in another filler. Use the envelope structure for any shared bounding surfaces.
+
+---
+
+## Reproducibility
+
+### Tag releases
+
+Every time you build a model for a formal assessment or publication, create a git tag. Gitronics records the commit hash in the assembled file's metadata, but a tag makes it trivially easy to check out the exact source state later.
+
+```bash
+git tag -a v1.2.0 -m "Design freeze for TDR submission"
+git push origin v1.2.0
+```
+
+### Include metadata files in version control
+
+The `.metadata` files alongside each filler model are part of the source. Commit them alongside the `.mcnp` files.
+
+---
+
+## Performance
+
+### Use `RUST_LOG=info` during development
+
+The `info` log level prints the files being loaded and the transformations being applied without being too verbose. Use `debug` only when diagnosing unexpected behaviour.
+
+### Keep filler models small
+
+Very large filler models (tens of thousands of cells) slow down parsing. If a sub-model has grown large, consider whether it can be further decomposed into nested universes.

gitronics-0.5.5/docs/changelog.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to Gitronics are documented here.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+<!-- TODO: Keep this file updated with each release. -->
+
+## [Unreleased]
+
+---
+
+## [0.1.0] — initial release
+
+### Added
+
+- `build` command: assemble an MCNP model from modular components and a YAML configuration.
+- `migrate` command: decompose a monolithic MCNP input file into a Gitronics project structure.
+- Configuration inheritance via the `overrides` key.
+- Multi-root project support via `project_roots`.
+- Per-envelope void override (set filler to `null`).
+- Python package (`pip install gitronics`) with `gitronics` CLI entry-point.
+- Assembled model metadata header (version, git commit hash, build timestamp).

gitronics-0.5.5/docs/examples.md

@@ -0,0 +1,110 @@
+# Examples
+
+## `example_project` — minimal working project
+
+The repository ships with a small example project in `example_project/`. It demonstrates the essential project layout and a valid configuration file.
+
+### Structure
+
+```
+example_project/
+├── configurations/
+│   └── valid_configuration.yaml
+├── output/
+│   └── .gitignore
+└── reference_model/
+    ├── envelope_structure.mcnp
+    ├── envelope_structure.metadata
+    └── filler_models/
+        ├── filler_model_1.mcnp
+        ├── filler_model_1.metadata
+        └── filler_model_2.mcnp
+```
+
+### Configuration
+
+```yaml title="example_project/configurations/valid_configuration.yaml"
+project_roots: [..]
+
+envelope_structure: envelope_structure
+
+source: volumetric_source
+materials: [materials]
+transformations: [my_transform]
+tallies: [fine_mesh]
+
+envelopes:
+  my_envelope_name_1: filler_model_1
+  envelope_name_2: filler_model_2
+```
+
+### Building it
+
+```bash
+cd example_project
+gitronics build configurations/valid_configuration.yaml --output-path output/
+```
+
+---
+
+## `big_example` — large-scale fusion model
+
+The `big_example/` directory contains a real-world-scale configuration for a tokamak neutronics model, showcasing how Gitronics handles large numbers of envelopes and multiple configuration variants.
+
+### Configuration variants
+
+| File | Description |
+|---|---|
+| `baseline.yaml` | Full reference model with all blanket sectors and fillers. |
+| `baseline_void_check.yaml` | Same geometry, all fillers replaced with void — useful for checking cell volumes. |
+| `in_vessel_only.yaml` | Only the in-vessel components; useful for fast scoping calculations. |
+
+### Envelope / filler pattern
+
+The baseline configuration maps blanket sectors to their corresponding filler models row by row:
+
+```yaml
+envelopes:
+  blanket_sector_01_r1_c03: blk_dt1_w_fd_row_1_c03
+  blanket_sector_01_r1_c02: blk_dt1_w_fd_row_1_c02
+  blanket_sector_01_r1_c01: blk_dt1_w_fd_row_1_c01
+  # ...
+```
+
+The `baseline_void_check.yaml` uses `overrides: baseline.yaml` and sets all envelopes to `null`, leaving the geometry intact but removing all materials — a standard MCNP void-check technique.
+
+### Running a build
+
+```bash
+cd big_example
+gitronics build configurations/baseline.yaml --output-path output/
+```
+
+---
+
+## Migrating your own model
+
+<!-- TODO: Add a worked example using a publicly available MCNP benchmark model -->
+
+!!! note "Fill in this section"
+    If you have a representative public MCNP model you can share, add a migration walkthrough here showing:
+
+    1. The original monolithic input file
+    2. The `gitronics migrate` command
+    3. The resulting project structure
+    4. Any manual clean-up steps needed
+
+---
+
+## Using the Python API
+
+Gitronics can also be driven from Python, which is useful when integrating with automated workflows or parametric studies:
+
+```python
+import gitronics
+
+# Build a model — equivalent to running the CLI
+gitronics.run(["gitronics", "build", "configurations/baseline.yaml", "-o", "output/"])
+```
+
+<!-- TODO: Expand with richer Python workflow examples if the Python API grows -->

gitronics-0.5.5/docs/getting-started.md

@@ -0,0 +1,105 @@
+# Getting Started
+
+This page walks you through two typical entry points:
+
+1. **Starting fresh** — migrating an existing monolithic MCNP model into a Gitronics project.
+2. **Building** — assembling a model from an existing Gitronics project.
+
+---
+
+## Migrating an existing model
+
+If you already have a monolithic MCNP input file, use the `migrate` command to convert it into a Gitronics project structure automatically.
+
+```bash
+gitronics migrate path/to/my_model.mcnp --output-path ./my_project
+```
+
+This produces:
+
+```
+my_project/
+├── configurations/
+│   └── baseline.yaml          ← ready-to-use baseline configuration
+├── output/
+│   └── .gitignore
+└── reference_model/
+    ├── envelope_structure.mcnp
+    ├── envelope_structure.metadata
+    └── filler_models/
+        ├── universe_101.mcnp
+        ├── universe_101.metadata
+        └── ...
+```
+
+!!! tip
+    The `migrate` command does its best to identify universe boundaries automatically.
+    Review the generated `envelope_structure.mcnp` and filler models to confirm they look correct before committing.
+
+After migration, verify the round-trip by running a build:
+
+```bash
+gitronics build my_project/configurations/baseline.yaml --output-path my_project/output
+```
+
+---
+
+## Building a model
+
+Given a Gitronics project, the `build` command assembles the MCNP input file:
+
+```bash
+gitronics build configurations/baseline.yaml
+```
+
+By default the assembled file is written to the current directory. Use `--output-path` to redirect it:
+
+```bash
+gitronics build configurations/baseline.yaml --output-path output/
+```
+
+The output file is `assembled.mcnp` in the specified directory.
+
+### What happens during a build
+
+1. The configuration file (and any parent configs it inherits from) is loaded and merged.
+2. All referenced files are located under the configured `project_roots`.
+3. `FILL` cards are injected into the envelope cells to reference the correct universe IDs.
+4. Filler models are appended to the envelope structure.
+5. Data cards (materials, source, tallies, transformations) are concatenated.
+6. A metadata comment block is written to the top of the output file recording the configuration name, build date, gitronics version, and git commit hash.
+
+---
+
+## Initialising a project from scratch
+
+If you are starting a new model rather than migrating an existing one, create the directory layout manually:
+
+```
+my_project/
+├── configurations/
+│   └── baseline.yaml
+├── output/
+│   └── .gitignore   (contents: *)
+└── reference_model/
+    ├── envelope_structure.mcnp
+    ├── envelope_structure.metadata
+    ├── filler_models/
+    └── data_cards/
+        ├── materials/
+        ├── sources/
+        └── tallies/
+```
+
+Then write a minimal `baseline.yaml`:
+
+```yaml
+project_roots: [..]
+
+envelope_structure: envelope_structure
+
+envelopes:
+  my_envelope: my_filler_model
+```
+
+See the [Configuration Reference](usage/configuration.md) for all available keys.

gitronics-0.5.5/docs/index.md

@@ -0,0 +1,45 @@
+# Gitronics
+
+**Gitronics** is a tool for assembling [MCNP](https://mcnp.lanl.gov/) neutronics models from modular, version-controlled components.
+
+Instead of maintaining a single monolithic MCNP input file, Gitronics lets you decompose a model into independent universe *filler models*, an *envelope structure*, and separate data cards (materials, sources, tallies, transformations). These components are assembled at build time according to a YAML configuration file.
+
+This workflow enables:
+
+- **Version control** — each component lives in its own file, making `git diff` meaningful.
+- **Parametric variants** — swap geometry fillers or data cards via configuration inheritance without duplicating files.
+- **Parallelism** — teams can develop different sub-models independently.
+- **Reproducibility** — each assembled model records the git commit hash and build timestamp in its metadata.
+
+---
+
+## How it works
+
+```
+reference_model/
+├── envelope_structure.mcnp   ← level-0 cells (the "shell" of the model)
+├── filler_models/            ← per-universe MCNP snippets
+│   ├── universe_101.mcnp
+│   └── ...
+└── data_cards/
+    ├── materials/
+    ├── sources/
+    └── tallies/
+
+configurations/
+└── baseline.yaml             ← declares which fillers go where
+
+output/
+└── assembled.mcnp            ← produced by `gitronics build`
+```
+
+The `build` command reads a configuration file, loads all referenced components, inserts `FILL` cards into the envelope cells, and writes a single self-contained MCNP input file.
+
+---
+
+## Quick links
+
+- [Installation](installation.md)
+- [Getting Started](getting-started.md)
+- [Configuration Reference](usage/configuration.md)
+- [Examples](examples.md)

gitronics-0.5.5/docs/installation.md

@@ -0,0 +1,54 @@
+# Installation
+
+Gitronics is distributed as a Python package containing a compiled Rust extension. Pre-built wheels are published to [PyPI](https://pypi.org/project/gitronics/) for the most common platforms; no Rust toolchain is required for end users.
+
+## Requirements
+
+- Python **3.9** or later
+- A supported platform: Linux x86\_64 / aarch64, macOS x86\_64 / Apple Silicon, Windows x86\_64
+
+## Install from PyPI
+
+```bash
+pip install gitronics
+```
+
+After installation the `gitronics` command is available in your shell:
+
+```bash
+gitronics --help
+```
+
+## Install from source
+
+Building from source requires:
+
+- [Rust](https://rustup.rs/) (stable toolchain)
+- [maturin](https://github.com/PyO3/maturin) ≥ 1.0
+
+```bash
+git clone https://github.com/gitronics/gitronics  # TODO: update URL
+cd gitronics
+pip install maturin
+maturin develop --release
+```
+
+## Verifying the installation
+
+```bash
+gitronics --help
+# Usage: gitronics <COMMAND>
+# Commands:
+#   build    Build an MCNP model from a project configuration
+#   migrate  Take a traditional monolithic MCNP model and migrate it to a Gitronics project structure
+#   help     Print this message or the help of the given subcommand(s)
+```
+
+## Building the documentation locally
+
+```bash
+pip install -r docs/requirements.txt
+mkdocs serve
+```
+
+Open [http://127.0.0.1:8000](http://127.0.0.1:8000) in your browser.

gitronics-0.5.5/docs/requirements.txt

@@ -0,0 +1,3 @@
+mkdocs-material
+mkdocs-autorefs
+mike

gitronics-0.5.5/docs/usage/build.md

@@ -0,0 +1,52 @@
+# `build` — Assemble a Model
+
+The `build` command reads a YAML configuration file and assembles a ready-to-run MCNP input file.
+
+## Synopsis
+
+```
+gitronics build <CONFIG> [--output-path <DIR>]
+```
+
+| Argument | Description |
+|---|---|
+| `CONFIG` | Path to the configuration YAML file (absolute or relative to cwd). |
+| `-o`, `--output-path` | Directory to write `assembled.mcnp` into. Defaults to `.` (current directory). |
+
+## Example
+
+```bash
+gitronics build configurations/in_vessel_only.yaml --output-path output/
+```
+
+## Output
+
+On success, the following files are written to `--output-path`:
+
+| File | Description |
+|---|---|
+| `assembled.mcnp` | The complete, self-contained MCNP input deck. |
+
+The top of `assembled.mcnp` contains a metadata comment block:
+
+```
+C ============================================================
+C  Built by gitronics v0.1.0
+C  Configuration : configurations/in_vessel_only.yaml
+C  Git commit    : a1b2c3d4e5f6...
+C  Date / time   : 2025-01-15T14:32:00Z
+C ============================================================
+```
+
+## How files are located
+
+Gitronics searches all directories listed in `project_roots` (defined in the configuration) for files referenced by stem name. Any file whose stem (name without extension) matches a key in the configuration is a candidate. This means you can organise your project files into subdirectories however you like, as long as each stem name is unique across all `project_roots`.
+
+## Logging
+
+Set the `RUST_LOG` environment variable to control verbosity:
+
+```bash
+RUST_LOG=info gitronics build configurations/baseline.yaml
+RUST_LOG=debug gitronics build configurations/baseline.yaml
+```

gitronics-0.5.5/docs/usage/configuration.md

@@ -0,0 +1,162 @@
+# Configuration Reference
+
+Gitronics configurations are YAML files that declare which components to include in an assembled model.
+
+## Full example
+
+```yaml
+# Where to search for referenced files (relative to this config file's directory)
+project_roots: [..]
+
+# Inherit from a parent config and override selected fields
+overrides: null
+
+# File stem of the envelope structure MCNP file
+envelope_structure: envelope_structure
+
+# Data card files (stems) to include
+source: volumetric_source
+materials: [materials_v2, extra_nuclides]
+transformations: [sector_transforms]
+tallies: [fine_mesh_tally, heating_tally]
+
+# Maps envelope cell names to filler model stems
+# Set a value to null to leave that envelope void (no FILL card inserted)
+envelopes:
+  blanket_sector_01: blanket_v3
+  divertor_outer:    divertor_cassette
+  shielding_block:   null
+```
+
+---
+
+## Field reference
+
+### `project_roots`
+
+```yaml
+project_roots: [.., ../shared_models]
+```
+
+A list of directory paths (relative to the config file or absolute) that Gitronics searches recursively for referenced files. Paths are resolved at load time.
+
+- **Type:** `list[path]` or `null`
+- **Default:** `null` (must be provided by the base config in an inheritance chain)
+
+---
+
+### `overrides`
+
+```yaml
+overrides: ../configurations/baseline.yaml
+```
+
+Path to a *parent* configuration. If set, the parent is loaded first and the current file is merged on top of it. Fields present in the current file take precedence; the parent provides defaults.
+
+- **Type:** `path` or `null`
+- **Default:** `null` (standalone config)
+
+!!! info "Inheritance"
+    Inheritance chains can be arbitrarily deep. The `envelopes` map is merged entry-by-entry: the override can add new envelopes or change specific ones without repeating the full list.
+
+---
+
+### `envelope_structure`
+
+```yaml
+envelope_structure: envelope_structure
+```
+
+Stem name of the MCNP file that contains the level-0 cells. Each cell that should be filled with a filler universe must have a placeholder comment `C @<envelope_name>` on the line before it (inserted automatically by `migrate`).
+
+- **Type:** `string` or `null`
+
+---
+
+### `source`
+
+```yaml
+source: volumetric_plasma_dt
+```
+
+Stem name of the file containing the SDEF / source data card.
+
+- **Type:** `string` or `null`
+
+---
+
+### `materials`
+
+```yaml
+materials: [structural_materials, tritium_breeding_materials]
+```
+
+List of stem names for material definition files. Files are concatenated in the listed order.
+
+- **Type:** `list[string]` or `null`
+
+---
+
+### `transformations`
+
+```yaml
+transformations: [sector_transforms, assembly_transforms]
+```
+
+List of stem names for transformation card files (`TR` cards). Files are concatenated in the listed order.
+
+- **Type:** `list[string]` or `null`
+
+---
+
+### `tallies`
+
+```yaml
+tallies: [flux_tally, heating_tally]
+```
+
+List of stem names for tally card files. Files are concatenated in the listed order.
+
+- **Type:** `list[string]` or `null`
+
+---
+
+### `envelopes`
+
+```yaml
+envelopes:
+  blanket_sector_01: blanket_v3
+  divertor_outer:    null
+```
+
+A mapping from **envelope cell name** (as declared in the envelope structure file) to a **filler model stem name**. Setting a value to `null` leaves the envelope void — no `FILL` card is inserted for that cell.
+
+- **Type:** `map[string, string | null]`
+- **Default:** `{}` (empty map)
+
+---
+
+## Configuration inheritance example
+
+A common pattern is to have a `baseline.yaml` that declares the full reference model, and assessment-specific configs that override only what changes:
+
+```yaml title="configurations/baseline.yaml"
+project_roots: [..]
+envelope_structure: envelope_structure
+source: dt_plasma
+materials: [all_materials]
+tallies: []
+envelopes:
+  blanket_inner: blanket_reference
+  blanket_outer: blanket_reference
+  divertor: divertor_reference
+```
+
+```yaml title="configurations/assessment_A.yaml"
+overrides: baseline.yaml
+tallies: [heating_mesh]
+envelopes:
+  blanket_inner: blanket_variant_A
+```
+
+When `assessment_A.yaml` is built, `blanket_inner` uses `blanket_variant_A` while `blanket_outer` and `divertor` fall back to the baseline values.

gitronics-0.5.5/docs/usage/migrate.md

@@ -0,0 +1,63 @@
+# `migrate` — Convert a Monolithic Model
+
+The `migrate` command takes a traditional single-file MCNP input deck and decomposes it into a Gitronics project structure.
+
+## Synopsis
+
+```
+gitronics migrate <MCNP_INPUT> [--output-path <DIR>]
+```
+
+| Argument | Description |
+|---|---|
+| `MCNP_INPUT` | Path to the original monolithic MCNP input file. |
+| `-o`, `--output-path` | Root directory for the new project. Defaults to `./project`. |
+
+## Example
+
+```bash
+gitronics migrate models/tokamak_2025.mcnp --output-path ./tokamak_project
+```
+
+## What it produces
+
+```
+<output-path>/
+├── configurations/
+│   └── baseline.yaml             ← reproduces the original model exactly
+├── output/
+│   └── .gitignore                ← ignores all build outputs in git
+└── reference_model/
+    ├── envelope_structure.mcnp   ← level-0 cells
+    ├── envelope_structure.metadata
+    └── filler_models/
+        ├── universe_<id>.mcnp    ← one file per universe
+        ├── universe_<id>.metadata
+        └── ...
+```
+
+### How universes are extracted
+
+Each universe found in the model is written to its own `universe_<id>.mcnp` file. Cells belonging to universe 0 (the root lattice) are retained in the envelope structure.
+
+### Metadata files
+
+Each filler model is accompanied by a `.metadata` YAML file. These files describe how the filler should be placed and can specify per-envelope transformation cards. Edit them to add transformations after migration.
+
+## Verifying the round-trip
+
+After migration, rebuild the model and verify it matches the original:
+
+```bash
+gitronics build tokamak_project/configurations/baseline.yaml \
+    --output-path tokamak_project/output
+diff models/tokamak_2025.mcnp tokamak_project/output/assembled.mcnp
+```
+
+!!! note
+    Minor formatting differences (whitespace, line ordering within a section) are expected. The geometry and physics data should be functionally identical.
+
+## Limitations
+
+- Data cards (materials, tallies, source) are written to a single `data_cards.source` file. After migration you may wish to split these into separate files under `reference_model/data_cards/`.
+- The migration does not attempt to detect repeated structures or simplify the model.

gitronics-0.5.5/mkdocs.yml

@@ -0,0 +1,77 @@
+site_name: Gitronics
+site_description: Build MCNP neutronics models from modular components
+site_url: https://fusion4energy.github.io/gitronics/latest/
+repo_url: https://github.com/Fusion4Energy/gitronics
+repo_name: Fusion4Energy/gitronics
+edit_uri: edit/main/docs/
+
+theme:
+  name: material
+  logo: logo.png
+  favicon: logo.png
+  palette:
+    - scheme: default
+      primary: deep purple
+      accent: teal
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      primary: deep purple
+      accent: teal
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+  features:
+    - navigation.tabs
+    - navigation.sections
+    - navigation.expand
+    - navigation.path
+    - navigation.top
+    - search.highlight
+    - search.share
+    - content.code.copy
+    - content.code.annotate
+    - content.tabs.link
+    - toc.integrate
+
+plugins:
+  - search
+  - autorefs
+
+extra:
+  version:
+    provider: mike
+    default: latest
+
+markdown_extensions:
+  - admonition
+  - pymdownx.details
+  - pymdownx.superfences
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.tabbed:
+      alternate_style: true
+  - pymdownx.tasklist:
+      custom_checkbox: true
+  - attr_list
+  - md_in_html
+  - tables
+  - footnotes
+  - toc:
+      permalink: true
+
+nav:
+  - Home: index.md
+  - Installation: installation.md
+  - Getting Started: getting-started.md
+  - Usage:
+      - Build: usage/build.md
+      - Migrate: usage/migrate.md
+      - Configuration Reference: usage/configuration.md
+  - Best Practices: best-practices.md
+  - Examples: examples.md
+  - Changelog: changelog.md

gitronics-0.5.5/python/gitronics/__main__.py

@@ -0,0 +1,3 @@
+from gitronics import _cli_main
+
+_cli_main()

{gitronics-0.5.3 → gitronics-0.5.5}/src/build_model.rs

@@ -1,10 +1,10 @@
 use crate::project_manager::ProjectManager;
-use crate::types::{AssembledMetadata, CellId, EnvelopeName, FillerName, UniverseId};
+use crate::types::{CellId, EnvelopeName, FillerName, UniverseId};
 use crate::utils::GitronicsError;
 
 use git2::Repository;
 use log::{info, warn};
-use migjorn::{Card, CellParam, DataCard, Model, ParamType};
+use migjorn::{Card, CellCard, CellParam, DataCard, Model, ParamType};
 use regex::Regex;
 use std::{collections::HashMap, path::Path, sync::LazyLock};
 use std::{env, fs};
@@ -63,8 +63,8 @@ pub fn build_model(config_path: &Path, output_path: &Path) -> Result<(), Gitroni
 
     // Write model
     let assembled_path = project_manager.output_path().join("assembled.mcnp");
+    write_assembled_header(&mut envelope_structure, config_path)?;
     envelope_structure.write_to_file(&assembled_path)?;
-    write_assembled_metadata(&project_manager, config_path)?;
     fs::write(output_path.join(".gitignore"), "*\n")?;
 
     info!(
@@ -168,25 +168,37 @@ fn get_universe_id_of_model(model: &Model) -> Result<UniverseId, GitronicsError>
         .ok_or_else(|| GitronicsError::FirstCellWithoutUniverseID(FillerName::from(model)))
 }
 
-fn write_assembled_metadata(
-    project_manager: &ProjectManager,
+fn write_assembled_header(
+    assembled_model: &mut Model,
     config_path: &Path,
 ) -> Result<(), GitronicsError> {
     let configuration = config_path.display().to_string();
     let date_time = chrono::Utc::now().format("%Y-%m-%d %H:%M:%S").to_string();
     let gitronics_version = env!("CARGO_PKG_VERSION");
     let commit_hash = get_hash_of_project();
-    let assembled_metadata = AssembledMetadata {
-        configuration,
-        date_time,
-        gitronics_version: gitronics_version.to_string(),
-        git_commit_hash: commit_hash,
-    };
-    let metadata_path = project_manager.output_path().join("assembled.metadata");
-    let yaml_content = serde_saphyr::to_string(&assembled_metadata).map_err(|e| {
-        GitronicsError::YamlSerialize(metadata_path.display().to_string(), e.to_string())
-    })?;
-    fs::write(&metadata_path, yaml_content)?;
+
+    let banner = format!(
+        "C ============================================================
+C  Built by gitronics v{gitronics_version}
+C  Configuration : {configuration}
+C  Git commit    : {commit_hash}
+C  Date / time   : {date_time}
+C ============================================================"
+    );
+    let new_card_text = format!(
+        "{banner}\n{}",
+        assembled_model
+            .cells
+            .first()
+            .map(|c| c.original_text())
+            .unwrap_or_default()
+    );
+
+    let banner_card = CellCard::try_from(new_card_text.as_str())
+        .expect("Adding comments as header should not fail");
+
+    // Replace the first cell (previously a comment placeholder) with the banner card
+    assembled_model.cells[0] = banner_card;
     Ok(())
 }
 

{gitronics-0.5.3 → gitronics-0.5.5}/src/types.rs

@@ -11,15 +11,6 @@ use indexmap::IndexMap;
 use migjorn::Model;
 use serde::{Deserialize, Serialize};
 
-/// Metadata associated with an assembled model
-#[derive(Debug, Serialize, Deserialize)]
-pub struct AssembledMetadata {
-    pub configuration: String,
-    pub date_time: String,
-    pub gitronics_version: String,
-    pub git_commit_hash: String,
-}
-
 /// Metadata associated with a filler model, describing how it should be placed.
 #[derive(Debug, Serialize, Deserialize)]
 pub struct FillerMetadata {