Metadata-Version: 2.4
Name: simind-python-connector
Version: 2.0.1
Summary: Python SIMIND Monte Carlo connector with STIR/SIRF/PyTomography adaptors
Author-email: Sam Porter <sam.porter.18@ucl.ac.uk>, Rebecca Gillen <rebecca.gillen.18@ucl.ac.uk>, "Efstathios (Stahis) Varzakis" <efstathios.varzakis.22@ucl.ac.uk>
Maintainer-email: Sam Porter <sam.porter.18@ucl.ac.uk>
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/samdporter/simind-python-connector
Project-URL: Documentation, https://simind-python-connector.readthedocs.io/
Project-URL: Repository, https://github.com/samdporter/simind-python-connector
Project-URL: Issues, https://github.com/samdporter/simind-python-connector/issues
Project-URL: Changelog, https://github.com/samdporter/simind-python-connector/blob/main/CHANGELOG.md
Keywords: SPECT,Monte Carlo,medical imaging,SIMIND,SIRF,STIR
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20.0
Requires-Dist: pydicom>=2.0.0
Requires-Dist: pyyaml>=5.4.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: pytest-mock; extra == "dev"
Requires-Dist: scipy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Requires-Dist: sphinx-autodoc-typehints; extra == "dev"
Requires-Dist: sphinx-gallery<0.23,>=0.22; extra == "dev"
Requires-Dist: pooch>=1.8; extra == "dev"
Requires-Dist: myst-parser; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: build; extra == "dev"
Requires-Dist: setuptools>=77.0.3; extra == "dev"
Requires-Dist: wheel; extra == "dev"
Requires-Dist: twine; extra == "dev"
Provides-Extra: examples
Requires-Dist: matplotlib>=3.0.0; extra == "examples"
Requires-Dist: pooch>=1.8; extra == "examples"
Provides-Extra: recon
Requires-Dist: scipy; extra == "recon"
Dynamic: license-file

# simind-python-connector

Python tools for running SIMIND and using its projections with STIR, SIRF, and
PyTomography. Python 3.10 or newer is required. SIMIND is licensed separately
and is not included with this package; this project is independent of the
SIMIND project and Lund University.

## Start here

See the [workflow tutorial](docs/tutorial.rst) for an ordered path through a
core simulation, known-activity NEMA phantom, reconstruction, scatter
correction, and measured-data calibration. The [gallery](docs/auto_examples/index.rst)
has every tutorial with its figures and printed output. Rendered documentation,
including the gallery, is built from the tagged repository; source distributions
contain the example sources rather than the generated gallery. The
[documentation](https://simind-python-connector.readthedocs.io/) explains
installation, geometry, normalisation, backend options, and the
[observed SIMIND output-component mapping](docs/simind_validation.md).

Install the package and example plotting dependencies:

```bash
pip install "simind-python-connector[examples]"
```

Select a SIMIND executable and its matching data directory. The binary and
`smc_dir` must come from the same release. Set `SIMIND_BIN` explicitly or put
`simind` on `PATH`; set `SMC_DIR` when required by your installation.

```bash
export SIMIND_BIN=/path/to/simind-v9/simind
export PATH=/path/to/simind-v9:$PATH
export SMC_DIR=/path/to/simind-v9/smc_dir/
export SIMIND_VERSION=9
```

Select version `8` or `9` explicitly. The connector uses this choice to place
voxel source and density maps in the same physical coordinates; the default
is version 8. A constructor's `simind_version` overrides `SIMIND_VERSION`.

Use the installed connector directly:

```python
import numpy as np
from simind_python_connector import SimindPythonConnector, configs

connector = SimindPythonConnector(
    configs.get("Example.yaml"), "output/basic", "case01", simind_version=9
)
source = np.zeros((32, 32, 32), dtype=np.float32)
source[12:20, 12:20, 12:20] = 1
connector.configure_voxel_phantom(source, np.zeros_like(source), voxel_size_mm=4)
connector.set_energy_windows([126], [154], [0])
connector.add_runtime_switch("NN", 1)
outputs = connector.run()
print(outputs["tot_w1"].projection.shape)
```

Run a complete core simulation example from a source checkout:

```bash
python examples/getting_started/plot_01_basic_simulation.py
```

The core connector does not require STIR, SIRF, or PyTomography. Install only
the optional backend used by your workflow; see
[installation](docs/installation.rst). The NEMA examples need the optional
phantomgen package; the install command is in the tutorial.

## Example map

- `examples/getting_started/plot_01`–`plot_06`: core NumPy simulations, windows, configurations, scoring,
  and density conversion.
- `examples/backends/plot_07a` / `07b` / `07c`: STIR / SIRF / PyTomography adaptors.
- `examples/backends/plot_08a` / `08b` / `08c`: DICOM setup for STIR / SIRF / PyTomography.
- `examples/phantoms/plot_09` / `plot_10`: the SIMIND analytic phantom library,
  and a known-activity NEMA/IEC simulation reconstructed with SIRF OSEM.
- `examples/mc_scatter/plot_11`–`plot_13`: Monte Carlo scatter in SIRF OSEM,
  scatter normalisation, and residual correction.
- `examples/cil/plot_14` / `plot_15`: CIL scatter correction, and an
  RDP-regularised SVRG reconstruction.
- `examples/real_data/plot_16a` / `16b` / `16c`: CT-to-SPECT conversion with
  STIR / SIRF / PyTomography for the measured Y-90 phantom.
- `examples/real_data/plot_17`: the Y-90 effective attenuation energy with SIRF.

The real-data pages are rendered case studies on restricted Y-90 input, not
reproducible tutorials. See [datasets](docs/datasets.rst) for the availability
statement.

Lower `quantization_scale`, fewer projections, or a mostly-zero source map can
make smoke runs faster. These settings reduce history statistics; they do not
set projection counts. For quantitative output, use known activity and
acquisition time or normalise against a measured or analytic reference. Keep
`NN >= 1`.

## License

Apache 2.0. See [LICENSE](LICENSE).
