Metadata-Version: 2.4
Name: gate-converter
Version: 1.1.1
Summary: Version-aware, loss-aware migration toolkit for GATE 9.x macros and GATE 10 / OpenGATE Python projects
Author-email: Rasool Safari <r.safari@shirazu.ac.ir>
License: Apache-2.0
Project-URL: Homepage, https://github.com/Rsafarii/gate-converter
Project-URL: Documentation, https://github.com/Rsafarii/gate-converter#readme
Project-URL: Repository, https://github.com/Rsafarii/gate-converter
Keywords: gate,opengate,geant4,monte-carlo,pet,medical-physics,migration
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pyyaml>=6.0
Requires-Dist: packaging>=23.0
Requires-Dist: rich>=12.0
Requires-Dist: networkx>=2.8
Requires-Dist: numpy>=1.22
Requires-Dist: matplotlib>=3.5
Requires-Dist: python-docx>=1.1
Provides-Extra: gui
Requires-Dist: PySide6>=6.4; extra == "gui"
Provides-Extra: test
Requires-Dist: pytest>=7.0; extra == "test"
Requires-Dist: coverage>=7.0; extra == "test"
Requires-Dist: hypothesis>=6.0; extra == "test"
Provides-Extra: dev
Requires-Dist: build; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: coverage; extra == "dev"
Requires-Dist: hypothesis; extra == "dev"
Provides-Extra: all
Requires-Dist: PySide6>=6.4; extra == "all"
Requires-Dist: pytest>=7.0; extra == "all"
Requires-Dist: coverage>=7.0; extra == "all"
Requires-Dist: hypothesis>=6.0; extra == "all"
Dynamic: license-file

# 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

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

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

## Quick start

```bash
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
```

```python
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

```bash
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.
