gitronics 0.6.1__tar.gz → 0.6.3__tar.gz

{gitronics-0.6.1 → gitronics-0.6.3}/Cargo.lock

@@ -390,7 +390,7 @@ dependencies = [
 
 [[package]]
 name = "gitronics"
-version = "0.6.1"
+version = "0.6.3"
 dependencies = [
  "chrono",
  "clap",

{gitronics-0.6.1 → gitronics-0.6.3}/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "gitronics"
-version = "0.6.1"
+version = "0.6.3"
 edition = "2024"
 description = "Build MCNP neutronics models from modular components"
 license = "EUPL-1.2"

{gitronics-0.6.1 → gitronics-0.6.3}/PKG-INFO

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

gitronics-0.6.3/README.md

@@ -0,0 +1,186 @@
+<div align="center">
+  <img src="docs/assets/hero.svg" alt="Gitronics — assemble MCNP neutronics models from modular, version-controlled components" width="100%">
+</div>
+
+<p align="center">
+  <a href="https://github.com/Fusion4Energy/gitronics/actions/workflows/ci.yml"><img alt="CI" src="https://github.com/Fusion4Energy/gitronics/actions/workflows/ci.yml/badge.svg"></a>
+  <a href="https://pypi.org/project/gitronics/"><img alt="PyPI" src="https://img.shields.io/pypi/v/gitronics?color=F5A623&label=pypi"></a>
+  <a href="https://pypi.org/project/gitronics/"><img alt="Python" src="https://img.shields.io/pypi/pyversions/gitronics?color=F5A623"></a>
+  <a href="https://github.com/Fusion4Energy/gitronics/blob/main/LICENSE"><img alt="License" src="https://img.shields.io/badge/license-EUPL--1.2-38D9C0"></a>
+  <a href="https://fusion4energy.github.io/gitronics/latest/"><img alt="Docs" src="https://img.shields.io/badge/docs-fusion4energy.github.io-4A5768"></a>
+  <a href="https://doi.org/10.1016/j.fusengdes.2025.115248"><img alt="Publication" src="https://img.shields.io/badge/DOI-10.1016%2Fj.fusengdes.2025.115248-blue"></a>
+</p>
+
+<p align="center">
+  <b>Docs:</b> <a href="https://fusion4energy.github.io/gitronics/latest/">fusion4energy.github.io/gitronics</a>
+  &nbsp;·&nbsp;
+  <a href="https://fusion4energy.github.io/gitronics/latest/getting_started/">Getting Started</a>
+  &nbsp;·&nbsp;
+  <a href="https://fusion4energy.github.io/gitronics/latest/examples/">Examples</a>
+</p>
+
+---
+
+## What is Gitronics?
+
+Large [MCNP](https://mcnp.lanl.gov/) neutronics models are traditionally kept in a **single, enormous input file**. That makes them nearly impossible to review, hard to develop in parallel, and painful to turn into variants.
+
+**Gitronics** is a methodology — and a small, fast tool — for maintaining an MCNP model as a collection of **independent, version-controlled files** that are assembled on demand:
+
+```bash
+gitronics build configurations/baseline.yaml -o output/
+```
+
+Each file describes one part of the model (a piece of geometry, a set of materials, a source, a group of tallies). A [YAML](https://yaml.org/) configuration declares which pieces to combine and where — so a single `gitronics build` produces one self-contained `assembled.mcnp`.
+
+> The Gitronics methodology already maintains some of the most complex neutronics models of the [ITER](https://www.iter.org/) fusion reactor and the [JT-60SA](https://www.jt60sa.org/) tokamak.
+
+---
+
+## Why it's different
+
+| Monolithic MCNP input | Gitronics project |
+| --- | --- |
+| One giant file — `git diff` is meaningless | Each component in its own file — diffs are reviewable |
+| Variants = copy the whole file and edit | Variants = swap components via config inheritance, zero duplication |
+| One person edits at a time | Teams develop sub-models independently, in parallel |
+| "Which model produced this result?" | Every build stamps the **git commit hash + timestamp** into the header |
+
+The order of every card in the output is **deterministic**, so two builds of the same configuration are byte-for-byte comparable.
+
+---
+
+## How it works
+
+<div align="center">
+  <img src="docs/assets/flow_readme.svg" alt="Envelope structure, filler models, and data cards are combined by a YAML configuration through 'gitronics build' into a single assembled.mcnp file plus an HTML report" width="100%">
+</div>
+
+`gitronics build` reads a configuration, loads every referenced component, inserts the correct `FILL` cards into the envelope cells, runs validation checks (duplicate IDs, missing cards, …), and writes a single MCNP input plus an HTML build report.
+
+A project is organized like this:
+
+```text
+my_project/
+├── reference_model/
+│   ├── envelope_structure.mcnp     ← level-0 cells (the "shell")
+│   ├── filler_models/              ← per-universe MCNP snippets
+│   │   ├── universe_101.mcnp
+│   │   └── universe_101.metadata
+│   └── data_cards/
+│       ├── materials/
+│       ├── sources/
+│       └── tallies/
+├── configurations/
+│   └── baseline.yaml               ← declares which fillers go where
+└── output/
+    └── assembled.mcnp              ← produced by `gitronics build`
+```
+
+A configuration file simply maps envelope cells to the fillers and data cards that belong in them:
+
+```yaml
+project_roots: [..]
+
+envelope_structure: envelope_structure
+source: volumetric_source
+materials: [materials]
+tallies: [fine_mesh]
+
+envelopes:
+  blanket_sector_01_r1_c01: universe_101
+  blanket_sector_01_r1_c02: universe_103
+  divertor_cassette_18: null  # intentionally left empty
+```
+
+---
+
+## Installation
+
+Gitronics ships as a Python package with a compiled Rust core. Pre-built wheels are on [PyPI](https://pypi.org/project/gitronics/) — no Rust toolchain required.
+
+```bash
+pip install gitronics
+```
+
+**Requirements:** Python **3.9+** on Linux, macOS (Intel & Apple Silicon), or Windows x86-64.
+
+<details>
+<summary>Build from source</summary>
+
+Requires the stable [Rust toolchain](https://rustup.rs/) and [maturin](https://github.com/PyO3/maturin) ≥ 1.0.
+
+```bash
+git clone https://github.com/Fusion4Energy/gitronics
+cd gitronics
+pip install maturin
+maturin develop --release
+```
+</details>
+
+---
+
+## Quick start
+
+Build the bundled example project:
+
+```bash
+cd example_project
+gitronics build configurations/valid_configuration.yaml --output-path output/
+```
+
+You'll find the assembled model in `output/assembled.mcnp`, with a header recording exactly how it was built:
+
+```text
+C ============================================================
+C  Built by gitronics v0.1.0
+C  Configuration : configurations/valid_configuration.yaml
+C  Git commit    : v0.5.18-3-g04d555a
+C  Date / time   : 2026-06-23 12:34:51
+C ============================================================
+```
+
+### Migrate an existing model
+
+Already have a monolithic MCNP input? Split it into a ready-to-build Gitronics project:
+
+```bash
+gitronics migrate my_big_model.mcnp -o project/
+```
+
+### Python API
+
+The same workflow is available from Python — handy for automation and parametric studies:
+
+```python
+import gitronics
+
+# Equivalent to: gitronics build configurations/baseline.yaml -o output/
+gitronics.run(["gitronics", "build", "configurations/baseline.yaml", "-o", "output/"])
+```
+
+---
+
+## Documentation
+
+The full guide lives at **[fusion4energy.github.io/gitronics](https://fusion4energy.github.io/gitronics/latest/)**:
+
+- [Concepts](https://fusion4energy.github.io/gitronics/latest/getting_started/concepts/) — the vocabulary of a Gitronics project
+- [Project Structure](https://fusion4energy.github.io/gitronics/latest/getting_started/project_structure/) & [File Types](https://fusion4energy.github.io/gitronics/latest/getting_started/file_types/)
+- [Configuration File](https://fusion4energy.github.io/gitronics/latest/getting_started/configuration_file/) — inheritance, overrides, and variants
+- [Building a Model](https://fusion4energy.github.io/gitronics/latest/getting_started/building_a_model/) & [Migrating](https://fusion4energy.github.io/gitronics/latest/getting_started/migrating/)
+- [Best Practices](https://fusion4energy.github.io/gitronics/latest/best_practices/)
+
+---
+
+## Citing Gitronics
+
+If Gitronics supports your work, please cite:
+
+> Cubi, A., et al. *Novel modular and Git-based approach for the management and development of radiation transport models.* Fusion Engineering and Design, 2025. [doi:10.1016/j.fusengdes.2025.115248](https://doi.org/10.1016/j.fusengdes.2025.115248)
+
+---
+
+## License
+
+Distributed under the [EUPL-1.2](LICENSE) license.

gitronics-0.6.3/docs/assets/anatomy-light.svg

@@ -0,0 +1,56 @@
+<svg width="100%" viewBox="0 0 820 472" role="img"
+     aria-label="How an envelope cell is filled: an envelope cell in envelope_structure.mcnp carries a $ @env:blanket_01 placeholder, and a filler model defines a universe with U=101. During gitronics build the placeholder becomes a FILL=101 card in assembled.mcnp, with the transformation taken from the filler's metadata."
+     xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace">
+  <defs>
+    <linearGradient id="amber" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#FFD173"/>
+      <stop offset="100%" stop-color="#F5A623"/>
+    </linearGradient>
+  </defs>
+
+  <rect x="0" y="0" width="820" height="472" rx="18" fill="#FFFFFF"/>
+  <rect x="1" y="1" width="818" height="470" rx="17" fill="none" stroke="#E2E6EC" stroke-width="1.5"/>
+
+  <!-- eyebrows -->
+  <text x="24" y="42" fill="#6B7684" font-size="12" font-weight="700" letter-spacing="1">ENVELOPE CELL &#183; placeholder</text>
+  <text x="424" y="42" fill="#6B7684" font-size="12" font-weight="700" letter-spacing="1">FILLER MODEL &#183; universe</text>
+
+  <!-- envelope card -->
+  <rect x="24" y="54" width="372" height="128" rx="12" fill="#F5F7FA" stroke="#D7DDE6"/>
+  <circle cx="48" cy="82" r="5" fill="#F5A623"/>
+  <text x="64" y="87" fill="#6B7684" font-size="14">envelope_structure.mcnp</text>
+  <line x1="40" y1="100" x2="380" y2="100" stroke="#E4E9F0"/>
+  <text x="44" y="130" font-size="15" fill="#2B3440">21055 0  1 -2 8 -7 -6 -5</text>
+  <text x="44" y="158" font-size="15"><tspan fill="#8A93A0">&#160;&#160;&#160;&#160;&#160;imp:n=1&#160;&#160;</tspan><tspan fill="#B26A00" font-weight="700">$ @env:blanket_01</tspan></text>
+
+  <!-- filler card -->
+  <rect x="424" y="54" width="372" height="128" rx="12" fill="#F5F7FA" stroke="#D7DDE6"/>
+  <circle cx="448" cy="82" r="5" fill="#0E8C7C"/>
+  <text x="464" y="87" fill="#6B7684" font-size="14">blanket_v3.mcnp</text>
+  <line x1="440" y1="100" x2="780" y2="100" stroke="#E4E9F0"/>
+  <text x="444" y="130" font-size="15" fill="#2B3440">1001 14 -7.89  1001 -1002</text>
+  <text x="444" y="158" font-size="15"><tspan fill="#8A93A0">&#160;&#160;&#160;&#160;&#160;imp:n=1&#160;&#160;</tspan><tspan fill="#0E8C7C" font-weight="700">U=101</tspan></text>
+
+  <!-- merge lines into the build pill -->
+  <g fill="none" stroke="#A8B0BC" stroke-width="2.4">
+    <path d="M 210 182 C 210 205 302 210 344 210"/>
+    <path d="M 610 182 C 610 205 518 210 476 210"/>
+  </g>
+  <rect x="345" y="194" width="130" height="32" rx="16" fill="url(#amber)"/>
+  <text x="410" y="215" fill="#20160A" font-size="13" font-weight="700" text-anchor="middle">gitronics build</text>
+
+  <!-- single arrow down into the assembled card -->
+  <line x1="410" y1="226" x2="410" y2="274" stroke="#A8B0BC" stroke-width="2.4"/>
+  <path d="M 403 270 L 410 282 L 417 270 Z" fill="#A8B0BC"/>
+
+  <!-- assembled card (lowered for arrowhead clearance) -->
+  <rect x="70" y="288" width="680" height="128" rx="12" fill="#FFF8EC" stroke="#E7C98A"/>
+  <circle cx="94" cy="316" r="5" fill="#F5A623"/>
+  <text x="110" y="321" fill="#6B7684" font-size="14">assembled.mcnp</text>
+  <line x1="86" y1="334" x2="734" y2="334" stroke="#EFE0C0"/>
+  <text x="94" y="364" font-size="15" fill="#2B3440">21055 0  1 -2 8 -7 -6 -5</text>
+  <text x="94" y="392" font-size="15"><tspan fill="#8A93A0">&#160;&#160;&#160;&#160;&#160;imp:n=1&#160;&#160;</tspan><tspan fill="#B26A00" font-weight="700">FILL=101</tspan><tspan fill="#8A93A0" font-size="13">  (transform from .metadata)</tspan></text>
+
+  <!-- caption -->
+  <text x="410" y="450" fill="#8A93A0" font-size="13" text-anchor="middle">Gitronics replaces the placeholder with a FILL card during build &#8212; the geometry files stay independent.</text>
+</svg>

gitronics-0.6.3/docs/assets/anatomy.svg

@@ -0,0 +1,56 @@
+<svg width="100%" viewBox="0 0 820 472" role="img"
+     aria-label="How an envelope cell is filled: an envelope cell in envelope_structure.mcnp carries a $ @env:blanket_01 placeholder, and a filler model defines a universe with U=101. During gitronics build the placeholder becomes a FILL=101 card in assembled.mcnp, with the transformation taken from the filler's metadata."
+     xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace">
+  <defs>
+    <linearGradient id="amber" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#FFD173"/>
+      <stop offset="100%" stop-color="#F5A623"/>
+    </linearGradient>
+  </defs>
+
+  <rect x="0" y="0" width="820" height="472" rx="18" fill="#0B0E15"/>
+  <rect x="1" y="1" width="818" height="470" rx="17" fill="none" stroke="#1C2634" stroke-width="1.5"/>
+
+  <!-- eyebrows -->
+  <text x="24" y="42" fill="#8A97A8" font-size="12" font-weight="700" letter-spacing="1">ENVELOPE CELL &#183; placeholder</text>
+  <text x="424" y="42" fill="#8A97A8" font-size="12" font-weight="700" letter-spacing="1">FILLER MODEL &#183; universe</text>
+
+  <!-- envelope card -->
+  <rect x="24" y="54" width="372" height="128" rx="12" fill="#0E1622" stroke="#293646"/>
+  <circle cx="48" cy="82" r="5" fill="#F5A623"/>
+  <text x="64" y="87" fill="#8A97A8" font-size="14">envelope_structure.mcnp</text>
+  <line x1="40" y1="100" x2="380" y2="100" stroke="#1E2836"/>
+  <text x="44" y="130" font-size="15" fill="#C7D0DD">21055 0  1 -2 8 -7 -6 -5</text>
+  <text x="44" y="158" font-size="15"><tspan fill="#9AA6B8">&#160;&#160;&#160;&#160;&#160;imp:n=1&#160;&#160;</tspan><tspan fill="#FFC24B">$ @env:blanket_01</tspan></text>
+
+  <!-- filler card -->
+  <rect x="424" y="54" width="372" height="128" rx="12" fill="#0E1622" stroke="#293646"/>
+  <circle cx="448" cy="82" r="5" fill="#38D9C0"/>
+  <text x="464" y="87" fill="#8A97A8" font-size="14">blanket_v3.mcnp</text>
+  <line x1="440" y1="100" x2="780" y2="100" stroke="#1E2836"/>
+  <text x="444" y="130" font-size="15" fill="#C7D0DD">1001 14 -7.89  1001 -1002</text>
+  <text x="444" y="158" font-size="15"><tspan fill="#9AA6B8">&#160;&#160;&#160;&#160;&#160;imp:n=1&#160;&#160;</tspan><tspan fill="#38D9C0">U=101</tspan></text>
+
+  <!-- merge lines into the build pill -->
+  <g fill="none" stroke="#4A5768" stroke-width="2.4">
+    <path d="M 210 182 C 210 205 302 210 344 210"/>
+    <path d="M 610 182 C 610 205 518 210 476 210"/>
+  </g>
+  <rect x="345" y="194" width="130" height="32" rx="16" fill="url(#amber)"/>
+  <text x="410" y="215" fill="#20160A" font-size="13" font-weight="700" text-anchor="middle">gitronics build</text>
+
+  <!-- single arrow down into the assembled card -->
+  <line x1="410" y1="226" x2="410" y2="274" stroke="#4A5768" stroke-width="2.4"/>
+  <path d="M 403 270 L 410 282 L 417 270 Z" fill="#4A5768"/>
+
+  <!-- assembled card (lowered for arrowhead clearance) -->
+  <rect x="70" y="288" width="680" height="128" rx="12" fill="#100E08" stroke="#4A3B18"/>
+  <circle cx="94" cy="316" r="5" fill="#F5A623"/>
+  <text x="110" y="321" fill="#8A97A8" font-size="14">assembled.mcnp</text>
+  <line x1="86" y1="334" x2="734" y2="334" stroke="#241d0e"/>
+  <text x="94" y="364" font-size="15" fill="#C7D0DD">21055 0  1 -2 8 -7 -6 -5</text>
+  <text x="94" y="392" font-size="15"><tspan fill="#9AA6B8">&#160;&#160;&#160;&#160;&#160;imp:n=1&#160;&#160;</tspan><tspan fill="#FFC24B" font-weight="700">FILL=101</tspan><tspan fill="#6E7A8A" font-size="13">  (transform from .metadata)</tspan></text>
+
+  <!-- caption -->
+  <text x="410" y="450" fill="#5C6675" font-size="13" text-anchor="middle">Gitronics replaces the placeholder with a FILL card during build &#8212; the geometry files stay independent.</text>
+</svg>

gitronics-0.6.3/docs/assets/flow-light.svg

@@ -0,0 +1,61 @@
+<svg width="100%" viewBox="0 0 820 600" role="img"
+     aria-label="Gitronics build pipeline: modular components (envelope structure, filler models, data cards) and a YAML configuration are combined by gitronics build into a single assembled.mcnp deck plus an HTML build report."
+     xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace">
+  <defs>
+    <linearGradient id="amber" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#FFD173"/>
+      <stop offset="100%" stop-color="#F5A623"/>
+    </linearGradient>
+  </defs>
+
+  <rect x="0" y="0" width="820" height="600" rx="20" fill="#FFFFFF"/>
+  <rect x="1" y="1" width="818" height="598" rx="19" fill="none" stroke="#E2E6EC" stroke-width="1.5"/>
+
+  <!-- Stage 1: modular components -->
+  <rect x="70" y="34" width="680" height="204" rx="14" fill="#F5F7FA" stroke="#D7DDE6"/>
+  <text x="96" y="70" fill="#6B7684" font-size="15" font-weight="700" letter-spacing="2">MODULAR COMPONENTS</text>
+  <g font-size="17">
+    <rect x="96" y="86" width="628" height="40" rx="8" fill="#EDF1F6" stroke="#DCE3EC"/>
+    <circle cx="122" cy="106" r="5" fill="#F5A623"/>
+    <text x="142" y="112" fill="#2B3440">envelope_structure.mcnp</text>
+    <rect x="96" y="134" width="628" height="40" rx="8" fill="#EDF1F6" stroke="#DCE3EC"/>
+    <circle cx="122" cy="154" r="5" fill="#F5A623"/>
+    <text x="142" y="160" fill="#2B3440">filler_models/*.mcnp</text>
+    <rect x="96" y="182" width="628" height="40" rx="8" fill="#EDF1F6" stroke="#DCE3EC"/>
+    <circle cx="122" cy="202" r="5" fill="#0E8C7C"/>
+    <text x="142" y="208" fill="#2B3440">data_cards/ &#183; materials &#183; source &#183; tallies</text>
+  </g>
+
+  <!-- arrow 1 -->
+  <line x1="410" y1="238" x2="410" y2="262" stroke="#A8B0BC" stroke-width="2.6"/>
+  <path d="M 403 258 L 410 268 L 417 258 Z" fill="#A8B0BC"/>
+
+  <!-- Stage 2: configuration -->
+  <rect x="220" y="268" width="380" height="62" rx="12" fill="#EAF6F3" stroke="#BFE3DC"/>
+  <text x="410" y="306" fill="#0E8C7C" font-size="17" text-anchor="middle">configurations/baseline.yaml</text>
+
+  <!-- arrow 2 -->
+  <line x1="410" y1="330" x2="410" y2="354" stroke="#A8B0BC" stroke-width="2.6"/>
+  <path d="M 403 350 L 410 360 L 417 350 Z" fill="#A8B0BC"/>
+
+  <!-- Stage 3: build engine -->
+  <rect x="290" y="360" width="240" height="78" rx="16" fill="url(#amber)"/>
+  <text x="410" y="407" fill="#20160A" font-size="24" font-weight="800" text-anchor="middle">gitronics build</text>
+
+  <!-- split arrows to outputs -->
+  <line x1="410" y1="438" x2="410" y2="460" stroke="#A8B0BC" stroke-width="2.6"/>
+  <line x1="245" y1="460" x2="575" y2="460" stroke="#A8B0BC" stroke-width="2.6"/>
+  <line x1="245" y1="460" x2="245" y2="478" stroke="#A8B0BC" stroke-width="2.6"/>
+  <line x1="575" y1="460" x2="575" y2="478" stroke="#A8B0BC" stroke-width="2.6"/>
+  <path d="M 238 474 L 245 484 L 252 474 Z" fill="#A8B0BC"/>
+  <path d="M 568 474 L 575 484 L 582 474 Z" fill="#A8B0BC"/>
+
+  <!-- Stage 4: outputs -->
+  <rect x="90" y="486" width="310" height="68" rx="12" fill="#FFF8EC" stroke="#E7C98A"/>
+  <text x="245" y="526" fill="#B26A00" font-size="18" font-weight="700" text-anchor="middle">assembled.mcnp</text>
+  <rect x="420" y="486" width="310" height="68" rx="12" fill="#F5F7FA" stroke="#D7DDE6"/>
+  <text x="575" y="526" fill="#2B3440" font-size="18" text-anchor="middle">build_report.html</text>
+
+  <!-- footer -->
+  <text x="410" y="584" fill="#8A93A0" font-size="14" text-anchor="middle">Every build stamps the git commit hash and timestamp into the model header.</text>
+</svg>

gitronics-0.6.3/docs/assets/flow.svg

@@ -0,0 +1,61 @@
+<svg width="100%" viewBox="0 0 820 600" role="img"
+     aria-label="Gitronics build pipeline: modular components (envelope structure, filler models, data cards) and a YAML configuration are combined by gitronics build into a single assembled.mcnp deck plus an HTML build report."
+     xmlns="http://www.w3.org/2000/svg" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace">
+  <defs>
+    <linearGradient id="amber" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#FFD173"/>
+      <stop offset="100%" stop-color="#F5A623"/>
+    </linearGradient>
+  </defs>
+
+  <rect x="0" y="0" width="820" height="600" rx="20" fill="#0B0E15"/>
+  <rect x="1" y="1" width="818" height="598" rx="19" fill="none" stroke="#1C2634" stroke-width="1.5"/>
+
+  <!-- Stage 1: modular components -->
+  <rect x="70" y="34" width="680" height="204" rx="14" fill="#0E1622" stroke="#293646"/>
+  <text x="96" y="70" fill="#8A97A8" font-size="15" font-weight="700" letter-spacing="2">MODULAR COMPONENTS</text>
+  <g font-size="17">
+    <rect x="96" y="86" width="628" height="40" rx="8" fill="#131C2A" stroke="#22303F"/>
+    <circle cx="122" cy="106" r="5" fill="#F5A623"/>
+    <text x="142" y="112" fill="#D6DEEA">envelope_structure.mcnp</text>
+    <rect x="96" y="134" width="628" height="40" rx="8" fill="#131C2A" stroke="#22303F"/>
+    <circle cx="122" cy="154" r="5" fill="#F5A623"/>
+    <text x="142" y="160" fill="#D6DEEA">filler_models/*.mcnp</text>
+    <rect x="96" y="182" width="628" height="40" rx="8" fill="#131C2A" stroke="#22303F"/>
+    <circle cx="122" cy="202" r="5" fill="#38D9C0"/>
+    <text x="142" y="208" fill="#D6DEEA">data_cards/ &#183; materials &#183; source &#183; tallies</text>
+  </g>
+
+  <!-- arrow 1 -->
+  <line x1="410" y1="238" x2="410" y2="262" stroke="#4A5768" stroke-width="2.6"/>
+  <path d="M 403 258 L 410 268 L 417 258 Z" fill="#4A5768"/>
+
+  <!-- Stage 2: configuration -->
+  <rect x="220" y="268" width="380" height="62" rx="12" fill="#101C1A" stroke="#2E4A46"/>
+  <text x="410" y="306" fill="#8FE7DA" font-size="17" text-anchor="middle">configurations/baseline.yaml</text>
+
+  <!-- arrow 2 -->
+  <line x1="410" y1="330" x2="410" y2="354" stroke="#4A5768" stroke-width="2.6"/>
+  <path d="M 403 350 L 410 360 L 417 350 Z" fill="#4A5768"/>
+
+  <!-- Stage 3: build engine -->
+  <rect x="290" y="360" width="240" height="78" rx="16" fill="url(#amber)"/>
+  <text x="410" y="407" fill="#20160A" font-size="24" font-weight="800" text-anchor="middle">gitronics build</text>
+
+  <!-- split arrows to outputs -->
+  <line x1="410" y1="438" x2="410" y2="460" stroke="#4A5768" stroke-width="2.6"/>
+  <line x1="245" y1="460" x2="575" y2="460" stroke="#4A5768" stroke-width="2.6"/>
+  <line x1="245" y1="460" x2="245" y2="478" stroke="#4A5768" stroke-width="2.6"/>
+  <line x1="575" y1="460" x2="575" y2="478" stroke="#4A5768" stroke-width="2.6"/>
+  <path d="M 238 474 L 245 484 L 252 474 Z" fill="#4A5768"/>
+  <path d="M 568 474 L 575 484 L 582 474 Z" fill="#4A5768"/>
+
+  <!-- Stage 4: outputs -->
+  <rect x="90" y="486" width="310" height="68" rx="12" fill="#12100A" stroke="#4A3B18"/>
+  <text x="245" y="526" fill="#FFC24B" font-size="18" font-weight="700" text-anchor="middle">assembled.mcnp</text>
+  <rect x="420" y="486" width="310" height="68" rx="12" fill="#0E1622" stroke="#293646"/>
+  <text x="575" y="526" fill="#B9C3D1" font-size="18" text-anchor="middle">build_report.html</text>
+
+  <!-- footer -->
+  <text x="410" y="584" fill="#5C6675" font-size="14" text-anchor="middle">Every build stamps the git commit hash and timestamp into the model header.</text>
+</svg>

gitronics-0.6.3/docs/assets/flow_readme.svg

@@ -0,0 +1,69 @@
+<svg width="100%" viewBox="0 0 1200 300" role="img"
+     aria-label="Build flow: envelope structure, filler models, and data cards are combined by a YAML configuration through gitronics build into a single assembled.mcnp file plus an HTML report"
+     xmlns="http://www.w3.org/2000/svg" font-family="ui-sans-serif, -apple-system, Segoe UI, Roboto, Helvetica, Arial, sans-serif">
+  <defs>
+    <linearGradient id="amber2" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0%" stop-color="#FFD173"/>
+      <stop offset="100%" stop-color="#F5A623"/>
+    </linearGradient>
+  </defs>
+
+  <rect x="0" y="0" width="1200" height="300" rx="20" fill="#0B0E15"/>
+  <rect x="1" y="1" width="1198" height="298" rx="19" fill="none" stroke="#1C2634" stroke-width="1.5"/>
+
+  <!-- INPUT stack -->
+  <text x="60" y="52" fill="#8A97A8" font-size="13" font-weight="700" letter-spacing="2">MODULAR COMPONENTS</text>
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="15">
+    <rect x="60" y="70" width="250" height="46" rx="10" fill="#111A27" stroke="#2A3646"/>
+    <circle cx="84" cy="93" r="5" fill="#FFC24B"/>
+    <text x="100" y="98" fill="#D6DEEA">envelope_structure.mcnp</text>
+    <rect x="60" y="126" width="250" height="46" rx="10" fill="#111A27" stroke="#2A3646"/>
+    <circle cx="84" cy="149" r="5" fill="#FFC24B"/>
+    <text x="100" y="154" fill="#D6DEEA">filler_models/*.mcnp</text>
+    <rect x="60" y="182" width="250" height="46" rx="10" fill="#111A27" stroke="#2A3646"/>
+    <circle cx="84" cy="205" r="5" fill="#38D9C0"/>
+    <text x="100" y="210" fill="#D6DEEA">data_cards/*</text>
+  </g>
+
+  <!-- config node -->
+  <text x="392" y="52" fill="#8A97A8" font-size="13" font-weight="700" letter-spacing="2">CONFIG</text>
+  <rect x="392" y="112" width="160" height="76" rx="12" fill="#101C1A" stroke="#2E4A46"/>
+  <text x="472" y="146" fill="#8FE7DA" font-size="14" font-weight="700" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace">baseline</text>
+  <text x="472" y="167" fill="#5FA69C" font-size="13" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace">.yaml</text>
+
+  <!-- arrows components -> config -->
+  <g stroke="#37424F" stroke-width="2" fill="none">
+    <path d="M 310 93 C 350 93 356 150 390 150"/>
+    <path d="M 310 149 L 390 150"/>
+    <path d="M 310 205 C 350 205 356 150 390 150"/>
+  </g>
+
+  <!-- arrow config -> build -->
+  <g stroke="#4A5768" stroke-width="2.4" fill="none">
+    <path d="M 552 150 L 636 150"/>
+  </g>
+  <path d="M 632 144 L 644 150 L 632 156 Z" fill="#4A5768"/>
+
+  <!-- build engine -->
+  <rect x="648" y="106" width="196" height="88" rx="14" fill="url(#amber2)"/>
+  <text x="746" y="146" fill="#20160A" font-size="18" font-weight="800" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace">gitronics</text>
+  <text x="746" y="172" fill="#3A2A10" font-size="16" font-weight="700" text-anchor="middle" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace">build</text>
+
+  <!-- arrow build -> outputs -->
+  <g stroke="#4A5768" stroke-width="2.4" fill="none">
+    <path d="M 844 150 L 928 150"/>
+  </g>
+  <path d="M 924 144 L 936 150 L 924 156 Z" fill="#4A5768"/>
+
+  <!-- outputs -->
+  <text x="940" y="52" fill="#8A97A8" font-size="13" font-weight="700" letter-spacing="2">DETERMINISTIC OUTPUT</text>
+  <g font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="15">
+    <rect x="940" y="106" width="210" height="46" rx="10" fill="#12100A" stroke="#4A3B18"/>
+    <text x="964" y="134" fill="#FFC24B">assembled.mcnp</text>
+    <rect x="940" y="162" width="210" height="46" rx="10" fill="#111A27" stroke="#2A3646"/>
+    <text x="964" y="190" fill="#B9C3D1">build_report.html</text>
+  </g>
+
+  <!-- footer note -->
+  <text x="60" y="272" fill="#5C6675" font-size="14" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace">Every build stamps the git commit hash + timestamp into the model header &#8212; reproducible by design.</text>
+</svg>