gitronics 0.6.2__tar.gz → 0.6.4__tar.gz

gitronics-0.6.4/.github/workflows/ci.yml

@@ -0,0 +1,136 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+env:
+  CARGO_TERM_COLOR: always
+
+jobs:
+  rust:
+    name: Rust tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          components: clippy, rustfmt
+
+      - name: Set up Python (Required for PyO3 test linking)
+        id: setup-python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Configure PyO3 Python path
+        shell: bash
+        run: |
+          echo "PYO3_PYTHON=${{ steps.setup-python.outputs.python-path }}" >> $GITHUB_ENV
+          if [[ "$RUNNER_OS" == "macOS" ]]; then
+            PYLIB=$(python3 -c "import sysconfig; print(sysconfig.get_config_var('LIBDIR'))")
+            PYVER=$(python3 -c "import sysconfig; print(sysconfig.get_config_var('LDVERSION'))")
+            echo "RUSTFLAGS=-L${PYLIB} -lpython${PYVER}" >> $GITHUB_ENV
+          fi
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: rustfmt
+        run: cargo fmt --all --check
+
+      - name: Test
+        run: cargo test --workspace --features pyo3/auto-initialize
+
+      - name: Clippy
+        run: cargo clippy --workspace -- -D warnings
+
+  ruff:
+    name: Python lint (ruff)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      # Pinned so a new ruff release can't fail CI unexpectedly; bump deliberately.
+      - name: ruff lint
+        run: uvx ruff@0.15.21 check python
+
+      - name: ruff format
+        run: uvx ruff@0.15.21 format --check python
+
+  python:
+    name: Python tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Rust stable
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Cache cargo registry
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            target
+          key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+
+      - name: Install maturin and pytest
+        run: pip install maturin pytest
+
+      - name: Build and install Python package (dev mode)
+        run: pip install -e .
+
+      - name: Run Python tests
+        run: pytest
+
+  report-viewer:
+    name: Report viewer (JS)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          cache: npm
+          cache-dependency-path: report/package-lock.json
+
+      - name: Install test dependencies
+        working-directory: report
+        run: npm ci
+
+      # The viewer and vendored library are inlined by `include_str!` —
+      # there is no bundle step, so this job never runs cargo and cargo
+      # never runs node.
+      - name: Syntax check
+        working-directory: report
+        run: node --check report.js
+
+      - name: Render tests (jsdom)
+        working-directory: report
+        run: node --test 'test/*.test.mjs'

{gitronics-0.6.2 → gitronics-0.6.4}/.gitignore

@@ -5,3 +5,6 @@ __pycache__/
 *.pyd
 *.pdb
 /site
+node_modules/
+.pytest_cache/
+.ruff_cache/

{gitronics-0.6.2 → gitronics-0.6.4}/Cargo.lock

@@ -124,12 +124,30 @@ version = "2.11.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c4512299f36f043ab09a583e57bceb5a5aab7a73db1805848e8fef3c9e8c78b3"
 
+[[package]]
+name = "block-buffer"
+version = "0.10.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+dependencies = [
+ "generic-array",
+]
+
 [[package]]
 name = "bumpalo"
 version = "3.20.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "5d20789868f4b01b2f2caec9f5c4e0213b41e3e5702a50157d699ae31ced2fcb"
 
+[[package]]
+name = "castaway"
+version = "0.2.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dec551ab6e7578819132c713a93c022a05d60159dc86e7a7050223577484c55a"
+dependencies = [
+ "rustversion",
+]
+
 [[package]]
 name = "cc"
 version = "1.2.62"
@@ -207,12 +225,35 @@ version = "1.0.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"
 
+[[package]]
+name = "compact_str"
+version = "0.9.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9dfdd1c2274d9aa354115b09dc9a901d6c5576818cdf70d14cae2bdb47df00ab"
+dependencies = [
+ "castaway",
+ "cfg-if",
+ "itoa",
+ "rustversion",
+ "ryu",
+ "static_assertions",
+]
+
 [[package]]
 name = "core-foundation-sys"
 version = "0.8.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 
+[[package]]
+name = "cpufeatures"
+version = "0.2.17"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
+dependencies = [
+ "libc",
+]
+
 [[package]]
 name = "crossbeam-deque"
 version = "0.8.6"
@@ -238,6 +279,26 @@ version = "0.8.21"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
 
+[[package]]
+name = "crypto-common"
+version = "0.1.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+dependencies = [
+ "generic-array",
+ "typenum",
+]
+
+[[package]]
+name = "digest"
+version = "0.10.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+dependencies = [
+ "block-buffer",
+ "crypto-common",
+]
+
 [[package]]
 name = "dunce"
 version = "1.0.5"
@@ -349,6 +410,16 @@ dependencies = [
  "slab",
 ]
 
+[[package]]
+name = "generic-array"
+version = "0.14.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
+dependencies = [
+ "typenum",
+ "version_check",
+]
+
 [[package]]
 name = "getrandom"
 version = "0.3.4"
@@ -390,7 +461,7 @@ dependencies = [
 
 [[package]]
 name = "gitronics"
-version = "0.6.2"
+version = "0.6.4"
 dependencies = [
  "chrono",
  "clap",
@@ -402,11 +473,14 @@ dependencies = [
  "logtest",
  "migjorn",
  "path-clean",
+ "pathdiff",
  "pyo3",
  "rayon",
  "regex",
  "serde",
  "serde-saphyr",
+ "serde_json",
+ "sha2",
  "tempfile",
  "thiserror",
  "walkdir",
@@ -636,21 +710,25 @@ dependencies = [
 
 [[package]]
 name = "migjorn"
-version = "0.2.2"
+version = "0.3.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ce11924d4ef1f0496f0be14e68860ab11bbc0b63222057d03bc92b22b4084f3d"
+checksum = "ecf4b3b5db557a6100d1767eb22295cbd70521d1678a34584644356ff140865c"
 dependencies = [
+ "compact_str",
  "migjorn-syntax",
+ "rayon",
  "rustc-hash",
 ]
 
 [[package]]
 name = "migjorn-syntax"
-version = "0.2.2"
+version = "0.3.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "42d3806f43fee8380cfaa0e26e9fee3a2dbece142e5314b6c7f9a0babf03fe05"
+checksum = "f7bce9c260eb5e8f964a98d313dd84ceb805e979b31ecdcdef5b90a059e5eb58"
 dependencies = [
- "rustc-hash",
+ "compact_str",
+ "memchr",
+ "rayon",
 ]
 
 [[package]]
@@ -686,6 +764,12 @@ version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "17359afc20d7ab31fdb42bb844c8b3bb1dabd7dcf7e68428492da7f16966fcef"
 
+[[package]]
+name = "pathdiff"
+version = "0.2.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "df94ce210e5bc13cb6651479fa48d14f601d9858cfe0467f43ae157023b938d3"
+
 [[package]]
 name = "pin-project-lite"
 version = "0.2.17"
@@ -757,6 +841,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "94f6cbe86ef3bf18998d9df6e0f3fc1050a8c5efa409bf712e661a4366e010fb"
 dependencies = [
  "once_cell",
+ "python3-dll-a",
  "target-lexicon",
 ]
 
@@ -795,6 +880,15 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "python3-dll-a"
+version = "0.2.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "d80ba7540edb18890d444c5aa8e1f1f99b1bdf26fb26ae383135325f4a36042b"
+dependencies = [
+ "cc",
+]
+
 [[package]]
 name = "quote"
 version = "1.0.45"
@@ -890,6 +984,12 @@ version = "1.0.22"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "b39cdef0fa800fc44525c84ccb54a029961a8215f9619753635a9c0d2538d46d"
 
+[[package]]
+name = "ryu"
+version = "1.0.23"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"
+
 [[package]]
 name = "same-file"
 version = "1.0.6"
@@ -960,6 +1060,7 @@ version = "1.0.149"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86"
 dependencies = [
+ "indexmap",
  "itoa",
  "memchr",
  "serde",
@@ -967,6 +1068,17 @@ dependencies = [
  "zmij",
 ]
 
+[[package]]
+name = "sha2"
+version = "0.10.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
+ "digest",
+]
+
 [[package]]
 name = "shlex"
 version = "1.3.0"
@@ -985,6 +1097,12 @@ version = "1.15.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "67b1b7a3b5fe4f1376887184045fcf45c69e92af734b7aaddc05fb777b6fbd03"
 
+[[package]]
+name = "static_assertions"
+version = "1.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a2eb9349b6444b326872e140eb1cf5e7c522154d69e7a0ffb0fb81c06b37543f"
+
 [[package]]
 name = "strsim"
 version = "0.11.1"
@@ -1041,6 +1159,12 @@ dependencies = [
  "syn",
 ]
 
+[[package]]
+name = "typenum"
+version = "1.20.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"
+
 [[package]]
 name = "unicode-ident"
 version = "1.0.24"

{gitronics-0.6.2 → gitronics-0.6.4}/Cargo.toml

@@ -1,9 +1,17 @@
 [package]
 name = "gitronics"
-version = "0.6.2"
+version = "0.6.4"
 edition = "2024"
 description = "Build MCNP neutronics models from modular components"
 license = "EUPL-1.2"
+# The published crate includes the viewer and vendored library it inlines; the
+# viewer's test harness and its dependencies are development-only.
+exclude = [
+    "report/test",
+    "report/node_modules",
+    "report/package.json",
+    "report/package-lock.json",
+]
 readme = "README.md"
 
 [[bin]]
@@ -15,11 +23,16 @@ name = "gitronics"
 crate-type = ["cdylib", "rlib"]
 
 [dependencies]
-pyo3 = { version = "0.23", features = ["extension-module", "abi3-py39"] }
-migjorn = { version = "0.2.2" }
+pyo3 = { version = "0.23", features = [
+    "extension-module",
+    "abi3-py39",
+    "generate-import-lib",
+] }
+migjorn = "0.3.11"
 walkdir = "2.5.0"
 serde = { version = "1.0.228", features = ["derive"] }
 serde-saphyr = "0.0.26"
+serde_json = { version = "1.0", features = ["preserve_order"] }
 thiserror = "2.0.18"
 rayon = "1.12.0"
 log = "0.4.29"
@@ -31,6 +44,8 @@ indexmap = { version = "2.14.0", features = ["serde"] }
 git2 = "0.21.0"
 dunce = "1.0.5"
 path-clean = "1.0.1"
+sha2 = "0.10"
+pathdiff = "0.2"
 
 [dev-dependencies]
 tempfile = "3.0"

{gitronics-0.6.2 → gitronics-0.6.4}/PKG-INFO

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

gitronics-0.6.4/README.md

@@ -0,0 +1,188 @@
+<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 
+# Or to generate a wheel for distribution:
+maturin build --release --target x86_64-pc-windows-gnu --zig -i python3.12
+```
+</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.