simind-python-connector 2.0.0__tar.gz → 3.0.0__tar.gz

{simind_python_connector-2.0.0 → simind_python_connector-3.0.0}/MANIFEST.in

@@ -1,7 +1,5 @@
 include README.md
 include LICENSE
-include requirements.txt
-include requirements-dev.txt
 recursive-include simind_python_connector/data *.atn
 recursive-include simind_python_connector/data *.json
 recursive-include simind_python_connector/configs *.smc *.yaml

{simind_python_connector-2.0.0/simind_python_connector.egg-info → simind_python_connector-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simind-python-connector
-Version: 2.0.0
+Version: 3.0.0
 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>
@@ -15,11 +15,11 @@ 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.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Python: >=3.9
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy>=1.20.0
@@ -29,6 +29,7 @@ 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"
@@ -39,6 +40,8 @@ Requires-Dist: build; extra == "dev"
 Requires-Dist: twine; extra == "dev"
 Provides-Extra: examples
 Requires-Dist: matplotlib>=3.0.0; extra == "examples"
+Provides-Extra: recon
+Requires-Dist: scipy; extra == "recon"
 Dynamic: license-file
 
 # simind-python-connector
@@ -48,7 +51,7 @@ Python SIMIND Monte Carlo Connector.
 [![Tests](https://github.com/samdporter/simind-python-connector/workflows/Tests/badge.svg)](https://github.com/samdporter/simind-python-connector/actions)
 [![Documentation Status](https://readthedocs.org/projects/simind-python-connector/badge/?version=latest)](https://simind-python-connector.readthedocs.io/en/latest/?badge=latest)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
 
 A Python toolkit that lets you run SIMIND from Python and use the outputs in
 common reconstruction ecosystems (STIR, SIRF, PyTomography).
@@ -66,6 +69,7 @@ install a licensed SIMIND installation.
 - [Full Documentation](https://simind-python-connector.readthedocs.io/)
 - [Installation](https://simind-python-connector.readthedocs.io/en/latest/installation.html)
 - [Backend Support](https://simind-python-connector.readthedocs.io/en/latest/backends.html) - adaptor dependency matrix
+- [Reconstruction with SIMIND corrections](https://simind-python-connector.readthedocs.io/en/latest/reconstruction.html)
 
 ## What This Package Does
 1. Runs SIMIND from Python with a minimal, explicit API.
@@ -75,6 +79,7 @@ install a licensed SIMIND installation.
 - **Connector-first API** - `SimindPythonConnector` for direct SIMIND execution from Python
 - **Package Adaptors** - STIR/SIRF/PyTomography adaptors for reconstruction workflows
 - **Native reconstruction workflows** - Use STIR/SIRF/PyTomography reconstruction tools with generated SIMIND data
+- **Reconstruction with SIMIND corrections (optional)** - `simind_python_connector.recon`: Monte Carlo scatter and Fu & Qi residual correction in SIRF OSEM and CIL algorithms
 - **Dual scoring support** - SCATTWIN and PENETRATE
 - **DICOM builders** - DICOM-driven setup utilities for scanner/input preparation
 - **Advanced Schneider2000 density conversion** - 44-segment HU-to-density mapping
@@ -116,7 +121,7 @@ Install from conda:
 conda install -c conda-forge stir "numpy<2.0"
 ```
 
-**Important**: As of November 2025, the STIR conda package (v6.3.0) requires NumPy < 2.0 due to binary compatibility issues with NumPy 2.x. The package was compiled against NumPy 1.x and will crash with memory errors if NumPy 2.x is installed. This should be resolved in future STIR releases.
+**Note**: If STIR from conda-forge fails with NumPy binary-compatibility errors, install `numpy<2`.
 
 Or build from source:
 ```bash

{simind_python_connector-2.0.0 → simind_python_connector-3.0.0}/README.md

@@ -5,7 +5,7 @@ Python SIMIND Monte Carlo Connector.
 [![Tests](https://github.com/samdporter/simind-python-connector/workflows/Tests/badge.svg)](https://github.com/samdporter/simind-python-connector/actions)
 [![Documentation Status](https://readthedocs.org/projects/simind-python-connector/badge/?version=latest)](https://simind-python-connector.readthedocs.io/en/latest/?badge=latest)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
-[![Python Version](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/downloads/)
+[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
 
 A Python toolkit that lets you run SIMIND from Python and use the outputs in
 common reconstruction ecosystems (STIR, SIRF, PyTomography).
@@ -23,6 +23,7 @@ install a licensed SIMIND installation.
 - [Full Documentation](https://simind-python-connector.readthedocs.io/)
 - [Installation](https://simind-python-connector.readthedocs.io/en/latest/installation.html)
 - [Backend Support](https://simind-python-connector.readthedocs.io/en/latest/backends.html) - adaptor dependency matrix
+- [Reconstruction with SIMIND corrections](https://simind-python-connector.readthedocs.io/en/latest/reconstruction.html)
 
 ## What This Package Does
 1. Runs SIMIND from Python with a minimal, explicit API.
@@ -32,6 +33,7 @@ install a licensed SIMIND installation.
 - **Connector-first API** - `SimindPythonConnector` for direct SIMIND execution from Python
 - **Package Adaptors** - STIR/SIRF/PyTomography adaptors for reconstruction workflows
 - **Native reconstruction workflows** - Use STIR/SIRF/PyTomography reconstruction tools with generated SIMIND data
+- **Reconstruction with SIMIND corrections (optional)** - `simind_python_connector.recon`: Monte Carlo scatter and Fu & Qi residual correction in SIRF OSEM and CIL algorithms
 - **Dual scoring support** - SCATTWIN and PENETRATE
 - **DICOM builders** - DICOM-driven setup utilities for scanner/input preparation
 - **Advanced Schneider2000 density conversion** - 44-segment HU-to-density mapping
@@ -73,7 +75,7 @@ Install from conda:
 conda install -c conda-forge stir "numpy<2.0"
 ```
 
-**Important**: As of November 2025, the STIR conda package (v6.3.0) requires NumPy < 2.0 due to binary compatibility issues with NumPy 2.x. The package was compiled against NumPy 1.x and will crash with memory errors if NumPy 2.x is installed. This should be resolved in future STIR releases.
+**Note**: If STIR from conda-forge fails with NumPy binary-compatibility errors, install `numpy<2`.
 
 Or build from source:
 ```bash

{simind_python_connector-2.0.0 → simind_python_connector-3.0.0}/docs/api.rst

@@ -60,35 +60,55 @@ Converters
    :undoc-members:
    :show-inheritance:
 
-.. automodule:: simind_python_connector.converters.dicom_to_stir
+.. automodule:: simind_python_connector.converters.simind_to_stir
    :members:
    :undoc-members:
    :show-inheritance:
 
-.. automodule:: simind_python_connector.converters.simind_to_stir
+Normalisation
+-------------
+
+.. automodule:: simind_python_connector.normalisation
    :members:
    :undoc-members:
    :show-inheritance:
 
-Utilities
----------
+Reconstruction with SIMIND corrections
+--------------------------------------
 
-.. automodule:: simind_python_connector.utils.stir_utils
+.. automodule:: simind_python_connector.recon.updates
    :members:
-   :undoc-members:
-   :show-inheritance:
 
-.. automodule:: simind_python_connector.utils.simind_utils
+.. automodule:: simind_python_connector.recon.projector
    :members:
-   :undoc-members:
-   :show-inheritance:
 
-.. automodule:: simind_python_connector.utils.io_utils
+.. automodule:: simind_python_connector.recon.corrections
+   :members:
+
+.. automodule:: simind_python_connector.recon.cil
+   :members:
+
+.. automodule:: simind_python_connector.recon.osem
+   :members:
+
+.. automodule:: simind_python_connector.recon.diagnostics
+   :members:
+
+Phantoms
+--------
+
+.. automodule:: simind_python_connector.phantoms
+   :members:
+
+Utilities
+---------
+
+.. automodule:: simind_python_connector.utils.simind_utils
    :members:
    :undoc-members:
    :show-inheritance:
 
-.. automodule:: simind_python_connector.utils.interfile_numpy
+.. automodule:: simind_python_connector.utils.interfile
    :members:
    :undoc-members:
    :show-inheritance:

{simind_python_connector-2.0.0 → simind_python_connector-3.0.0}/docs/backends.rst

@@ -26,31 +26,3 @@ The adaptors are responsible for converting input/output object types across
 package boundaries. Reconstruction-system objects (for example, a PyTomography
 system matrix) should be created directly in the target package.
 
-Backend Abstraction Module
---------------------------
-
-The ``simind_python_connector.backends`` module provides optional helper APIs for
-working with SIRF/STIR image and acquisition wrapper objects.
-
-Quick example:
-
-.. code-block:: python
-
-    from simind_python_connector.backends import get_backend, set_backend
-
-    backend = get_backend()  # auto-detect: "sirf" or "stir"
-    print(f"Using backend: {backend}")
-
-    # Optional explicit override
-    set_backend("stir")
-
-Main helper functions include:
-
-- ``get_backend()``
-- ``set_backend(backend)``
-- ``reset_backend()``
-- ``create_image_data(...)``
-- ``create_acquisition_data(...)``
-- ``unwrap(...)``
-
-These helpers are independent from the connector/adaptor execution API.

{simind_python_connector-2.0.0 → simind_python_connector-3.0.0}/docs/changelog.rst

@@ -7,6 +7,34 @@ All notable changes to this project are documented in this file.
 
 The format is based on `Keep a Changelog <https://keepachangelog.com/en/1.0.0/>`_, and this project adheres to `Semantic Versioning <https://semver.org/spec/v2.0.0.html>`_.
 
+3.0.0 - 2026-10-09
+------------------
+
+Breaking Changes
+~~~~~~~~~~~~~~~~
+
+- Python 3.10 or newer is required.
+- Removed the backend wrappers and legacy Interfile and STIR utility modules.
+  Use the native adaptors and ``simind_python_connector.utils.interfile``.
+- Photon-history scaling and runtime switches now reject invalid values.
+
+Added
+~~~~~
+
+- Measured acquisition geometry, activity scaling, anisotropic voxel maps and
+  SIMIND MPI execution.
+- Analytic and library phantoms, voxelisation and native adaptor ground truth.
+- Optional SIMIND scatter and residual corrections for SIRF and CIL workflows.
+
+Fixed
+~~~~~
+
+- PyTomography image-axis conversions reverse z slices to match its SIMIND
+  reader. Source and attenuation maps now agree with native tensor slice order.
+- Added asymmetric real-reader regressions and a sparse two-view SIMIND smoke
+  test for axial source placement.
+- Consolidated Interfile parsing and geometry handling to follow STIR semantics.
+
 2.0.0 - 2026-10-09
 ------------------
 

{simind_python_connector-2.0.0 → simind_python_connector-3.0.0}/docs/conf.py

@@ -13,7 +13,7 @@ sys.path.insert(0, os.path.abspath(".."))
 project = "simind-python-connector"
 copyright = f"{datetime.now().year}, Sam Porter, Efstathios Varzakis"
 author = "Sam Porter, Efstathios Varzakis"
-release = "2.0.0"
+release = "3.0.0"
 for dist_name in ("simind-python-connector",):
     try:
         release = importlib_metadata.version(dist_name)
@@ -38,7 +38,7 @@ source_suffix = {
 }
 
 templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "superpowers/**"]
 
 # Options for HTML output
 html_theme = "sphinx_rtd_theme"

{simind_python_connector-2.0.0 → simind_python_connector-3.0.0}/docs/examples/04_custom_config.py

@@ -12,13 +12,6 @@ from pathlib import Path
 from simind_python_connector import SimulationConfig, configs
 
 
-try:
-    from simind_python_connector.backends import get_backend, set_backend
-except ImportError:  # backend libraries intentionally absent in core container
-    get_backend = None
-    set_backend = None
-
-
 TEMPLATE_PATH = configs.get("input.smc")  # Path to a template configuration file
 
 
@@ -172,6 +165,9 @@ def demonstrate_new_api_usage():
 
     # Configure runtime/config switches and run
     connector.add_runtime_switch('NN', 10)
+    connector.configure_phantom(phantom)  # or configure_voxel_phantom(...)
+    # A configuration-defined phantom also works: without configure_phantom()
+    # the connector warns and runs the phantom from Index 14/15.
     outputs = connector.run()
     """
     )
@@ -193,36 +189,5 @@ if __name__ == "__main__":
         description="Create and manage custom SIMIND configurations",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    parser.add_argument(
-        "--backend",
-        type=str,
-        choices=["sirf", "stir"],
-        help=(
-            "Force a specific backend (sirf or stir). "
-            "If not specified, auto-detection is used."
-        ),
-    )
-    args = parser.parse_args()
-
-    # Set backend if specified and backend layer is available.
-    if args.backend:
-        if set_backend is None:
-            print(
-                f"Backend '{args.backend}' requested, "
-                "but backend libraries are not installed."
-            )
-        else:
-            set_backend(args.backend)
-
-    # Print backend status (core config workflow does not require one).
-    print(f"\n{'=' * 60}")
-    if get_backend is None:
-        print("Using backend: NONE (core configuration mode)")
-    else:
-        try:
-            print(f"Using backend: {get_backend().upper()}")
-        except ImportError:
-            print("Using backend: NONE (backend libraries unavailable)")
-    print(f"{'=' * 60}\n")
-
+    parser.parse_args()
     main()

{simind_python_connector-2.0.0 → simind_python_connector-3.0.0/docs}/examples/06_schneider_density_conversion.py

@@ -299,24 +299,5 @@ if __name__ == "__main__":
         description="Demonstrate Schneider density conversion functionality",
         formatter_class=argparse.RawDescriptionHelpFormatter,
     )
-    parser.add_argument(
-        "--backend",
-        type=str,
-        choices=["sirf", "stir"],
-        help=(
-            "Force a specific backend (sirf or stir). "
-            "Note: This example doesn't use backends, but the argument is "
-            "provided for consistency."
-        ),
-    )
-    args = parser.parse_args()
-
-    # This example does not use backend implementations directly, but accepts
-    # the argument for consistency with the rest of the examples.
-    if args.backend:
-        print(
-            f"Note: Backend argument '{args.backend}' "
-            "specified but not used in this example."
-        )
-
+    parser.parse_args()
     main()

simind_python_connector-3.0.0/docs/examples/09_mc_scatter_osem.py

@@ -0,0 +1,89 @@
+#!/usr/bin/env python
+"""
+MC scatter in the forward model with SIRF OSEM.
+
+1. Simulate "measured" data with SIMIND (PENETRATE, known activity) in a
+   template geometry and add Poisson noise.
+2. Reconstruct it with OSEM twice: without scatter correction, and with a
+   SIMIND scatter estimate (all events minus the geometric primary, scaled to
+   the fast model) refreshed every 2 epochs.
+3. Print the hot-sphere contrast error of both against the truth.
+
+Tiny on purpose: 32^3 voxels, 30 views, NN = 1. Needs SIRF and SIMIND.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from _mc_scatter_common import (
+    contrast_error,
+    fast_model_factory,
+    image,
+    phantom,
+    print_updates,
+    scatter_updater,
+    simulate_measured,
+    template,
+)
+
+from simind_python_connector.recon import AdditiveUpdater, UpdateSchedule
+from simind_python_connector.recon.osem import run_osem_with_corrections
+
+
+NUM_SUBSETS = 5
+EPOCHS_PER_UPDATE = 2
+NUM_UPDATES = 3
+
+
+def main() -> None:
+    if shutil.which("simind") is None:
+        raise RuntimeError("SIMIND executable not found in PATH.")
+    output_dir = Path("output/mc_scatter_osem")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    activity, mu = phantom()
+    activity_image, mu_image = image(activity), image(mu)
+    template_data = template(output_dir)
+    measured = simulate_measured(output_dir, template_data, activity_image, mu_image)
+
+    make_model = fast_model_factory(mu_image)
+    full_model = make_model()
+    full_model.set_up(measured, activity_image)
+    initial = activity_image.get_uniform_copy(1.0)
+    subiterations = EPOCHS_PER_UPDATE * NUM_SUBSETS
+
+    # One pass with the same number of subiterations and a zero additive term;
+    # with num_updates=0 the updater never asks for an estimate.
+    baseline = run_osem_with_corrections(
+        measured,
+        make_model,
+        initial,
+        AdditiveUpdater(None, UpdateSchedule(every=1), measured.get_uniform_copy(0)),
+        NUM_SUBSETS,
+        subiterations_per_update=subiterations * (NUM_UPDATES + 1),
+        num_updates=0,
+    )
+    updater = scatter_updater(
+        output_dir, template_data, mu_image, measured, full_model, subiterations
+    )
+    corrected = run_osem_with_corrections(
+        measured,
+        make_model,
+        initial,
+        updater,
+        NUM_SUBSETS,
+        subiterations_per_update=subiterations,
+        num_updates=NUM_UPDATES,
+    )
+
+    print_updates(updater)
+    before = contrast_error(baseline, activity)
+    after = contrast_error(corrected, activity)
+    print(f"hot-sphere contrast error, no scatter correction: {before:.1%}")
+    print(f"hot-sphere contrast error, SIMIND scatter:        {after:.1%}")
+
+
+if __name__ == "__main__":
+    main()

simind_python_connector-3.0.0/docs/examples/10_mc_scatter_cil.py

@@ -0,0 +1,103 @@
+#!/usr/bin/env python
+"""
+MC scatter in the forward model with CIL.
+
+The same data as example 09, reconstructed with CIL's ISTA over subset
+Kullback-Leibler objectives. The AdaptiveSensitivity preconditioner with a
+unit step makes each ISTA step an MLEM update. A CorrectionCallback refreshes
+the SIMIND scatter estimate every 10 iterations and swaps it into the
+objectives. Installed CIL calls back at iteration 0 before the first update,
+then after later updates. Passing stop_at=ITERATIONS (an exclusive bound)
+records refreshes at 10, 20 and 30 only, each consumed by a later iteration.
+
+Tiny on purpose: 32^3 voxels, 30 views, NN = 1. Needs SIRF, CIL and SIMIND.
+"""
+
+from __future__ import annotations
+
+import shutil
+from pathlib import Path
+
+from _mc_scatter_common import (
+    contrast_error,
+    fast_model_factory,
+    image,
+    phantom,
+    print_updates,
+    scatter_updater,
+    simulate_measured,
+    template,
+)
+from cil.optimisation.algorithms import ISTA
+from cil.optimisation.functions import IndicatorBox, SumFunction
+from cil.optimisation.utilities import AdaptiveSensitivity
+
+from simind_python_connector.recon.cil import (
+    CorrectionCallback,
+    build_subset_objectives,
+)
+
+
+NUM_SUBSETS = 5
+ITERATIONS = 40
+UPDATE_EVERY = 10
+
+
+def _ista(objectives, initial, full_model, callbacks):
+    algorithm = ISTA(
+        initial=initial,
+        f=SumFunction(*objectives.functions),
+        g=IndicatorBox(lower=0),
+        step_size=1.0,
+        preconditioner=AdaptiveSensitivity(full_model, max_iterations=ITERATIONS + 1),
+    )
+    algorithm.run(ITERATIONS, callbacks=callbacks)
+    return algorithm.solution
+
+
+def main() -> None:
+    if shutil.which("simind") is None:
+        raise RuntimeError("SIMIND executable not found in PATH.")
+    output_dir = Path("output/mc_scatter_cil")
+    output_dir.mkdir(parents=True, exist_ok=True)
+
+    activity, mu = phantom()
+    activity_image, mu_image = image(activity), image(mu)
+    template_data = template(output_dir)
+    measured = simulate_measured(output_dir, template_data, activity_image, mu_image)
+
+    make_model = fast_model_factory(mu_image)
+    full_model = make_model()
+    full_model.set_up(measured, activity_image)
+    initial = activity_image.get_uniform_copy(1.0)
+    zero = measured.get_uniform_copy(0)
+
+    baseline_objectives = build_subset_objectives(
+        measured, zero, make_model, NUM_SUBSETS, initial
+    )
+    baseline = _ista(baseline_objectives, initial, full_model, callbacks=[])
+
+    objectives = build_subset_objectives(
+        measured, zero, make_model, NUM_SUBSETS, initial
+    )
+    updater = scatter_updater(
+        output_dir,
+        template_data,
+        mu_image,
+        measured,
+        full_model,
+        UPDATE_EVERY,
+        stop_at=ITERATIONS,
+    )
+    callback = CorrectionCallback(updater, objectives)
+    corrected = _ista(objectives, initial, full_model, callbacks=[callback])
+
+    print_updates(updater)
+    before = contrast_error(baseline, activity)
+    after = contrast_error(corrected, activity)
+    print(f"hot-sphere contrast error, no scatter correction: {before:.1%}")
+    print(f"hot-sphere contrast error, SIMIND scatter:        {after:.1%}")
+
+
+if __name__ == "__main__":
+    main()