gate-converter

Comprehensive, version-aware, loss-aware migration framework for GATE 9.x macros and GATE 10 / OpenGATE Python — covering imaging (PET/SPECT/CT), dosimetry, radiotherapy (photon/electron/proton/carbon-ion), treatment plans, phase space, motion, optical, actors, and advanced physics.

Convert GATE simulation projects between GATE 9.x versions, migrate GATE 9.x macros to GATE 10 Python, and reverse-convert structured GATE 10 code back to GATE 9 macros — with a canonical intermediate representation, a real macro parser, a bidirectional digitizer engine (legacy 9.0–9.2 ↔ manager 9.3+), a 23-actor registry with rich actor/plan models, domain plug-ins, static validation, semantic diffs, and honest loss/unsupported reporting. No GATE installation needed for conversion.

Installation

pip install gate-converter
pip install gate-converter[gui]    # optional PySide6 comparison GUI

Python ≥ 3.9. See docs/markdown/installation.md.

Quick start

gateconvert inspect old_project/ --from 9.2
gateconvert convert old_project --from 9.2 --to 9.4.2 -o pet94 --allow-lossy
gateconvert convert old_project --to 10.1.1 -o pet10 --allow-lossy

from gate_converter import convert_project
result = convert_project("old_project/", "9.2", "10.1.1", "pet10/", allow_lossy=True)

Supported versions

9.0, 9.1, 9.2, 9.3, 9.4, 9.4.1, 9.4.2, 10.0.0, 10.0.1, 10.0.2, 10.1, 10.1.1. Full registry: version_registry.json / .csv. Non-existent tags (9.0.1, 9.1.1…) are rejected.

Domains (only listed with matrix evidence)

• Imaging: PET (EXACT), SPECT/CT (PARTIAL) — domains/imaging
• Dosimetry: voxel dose+uncertainty, LET, fluence, TLE, Edep (supported config migration); dose rate/dose-to-water/ROI (PARTIAL); RBE/biological (UNSUPPORTED — external postprocessing) — DOSIMETRY_SUPPORT_MATRIX.csv
• Radiotherapy: proton PBS, carbon/generic ions, TPS plans, phase-space beams (supported config); photon/electron linac, MLC, patient CT (PARTIAL) — RADIOTHERAPY_SUPPORT_MATRIX.csv
• Actors: 23 discovered, 13 fully supported, 9 partial, 1 unsupported (custom) — ACTOR_SUPPORT_MATRIX.csv, actor_coverage_report.md
• Phase space: actor→file→source pipeline (PARTIAL/SUPPORTED)
• Treatment plans: generic field/layer/spot model + TPS text parsing
• Motion/optical/advanced physics: structural (PARTIAL); custom C++ (UNSUPPORTED by design)

Conversion examples

• 9.x → 9.x: gateconvert convert proj --from 9.2 --to 9.4.2
• 9.x → 10: gateconvert convert proj --to 10.1.1 (multi-file Python output)
• 10 → 9.x: gateconvert reverse gate10_proj --to 9.2
• Digitizer only: gateconvert digitizer old.mac --to 9.3

Digitizer conversion

Legacy (/gate/digitizer/Singles|Coincidences, ≤9.2) ↔ DigitizerManager (/gate/digitizerMgr/..., 9.3+) via a canonical digitizer graph. Spblurring and coincidence pulse processors were not ported upstream → reported LOSSY/UNSUPPORTED, never silently dropped. Multi-SD chains convert forward natively, merge (APPROXIMATE) in reverse. Matrix: digitizer_compatibility_matrix.csv.

GATE 10 migration / reverse conversion

Forward generation emits simulation.py geometry.py materials.py sources.py physics.py digitizer.py actors.py acquisition.py config.py run.py using the target profile's API (10.0.x vs 10.1.x filter API). Reverse parsing is AST-static and never executes code; arbitrary Python is best-effort — see gate10_python_conversion_capability.md.

CLI

detect-version inspect validate convert digitizer reverse compare report test audit actors dosimetry radiotherapy coverage gaps validate-actor validate-dosimetry validate-radiotherapy with --verbose --quiet --json --strict --allow-lossy --dry-run --report --validate-runtime --strict-scientific --domain imaging|dosimetry|radiotherapy|actors|all. Details: docs/markdown/cli.md.

Python API

convert_project, parse_gate_project, parse_gate10_project, inspect_project, detect_gate_version, validate_project, compare_projects, convert_digitizer, generate_gate10, generate_gate9, validate_imaging, validate_dosimetry, validate_radiotherapy, validate_actors, CanonicalActor, TreatmentPlan, parse_tps_text, actor_map, compare_profiles — see docs/markdown/api.md.

Validation

Static validation + semantic (canonical-level) diffs + round-trip hash comparison + optional real-GATE execution (--validate-runtime, else honestly NOT AVAILABLE). Runtime runs are never faked. See docs/markdown/validation.md and reports/GATE_Converter_Scientific_Validation_Report.docx.

Limitations

Custom Geant4 C++ hooks, arbitrary dynamic Python, Spblurring→9.3+, and coincidence processors cannot convert exactly. Full statement: docs/markdown/limitations.md.

Examples

examples/: basic 9.0, 9.2 PET, legacy/new digitizers, 9.4 alias PET, complex multi-SD PET benchmark, GATE 10 reference.

Development / testing

pip install -e .[dev]
pytest            # + coverage for parser/conversion core
ruff check src tests
python -m mypy src/gate_converter --ignore-missing-imports
python -m build && twine check dist/*
python final_audit.py

PyPI deployment

Package gate-converter 1.0.0 is build-ready (pyproject.toml, sdist + wheel, twine check clean). Not auto-uploaded — publish explicitly with twine upload dist/* only when requested.

License

Apache-2.0 (LICENSE); third-party notices in THIRD_PARTY_NOTICES.txt. Independent toolkit, not affiliated with the OpenGATE collaboration.