pytomography 3.3.2__tar.gz → 4.0.0__tar.gz

{pytomography-3.3.2 → pytomography-4.0.0}/.gitignore

@@ -6,4 +6,8 @@ notebook_testing
 stir_testing
 dist/
 test_files
-*docs/build*
+*docs/build*
+# docs build
+docs/build/
+.venv-docs/
+.venv-data/

pytomography-4.0.0/CITATION.cff

@@ -0,0 +1,44 @@
+cff-version: 1.2.0
+message: "If you use PyTomography in your research, please cite the paper below."
+title: PyTomography
+type: software
+license: MIT
+repository-code: "https://github.com/PyTomography/PyTomography"
+url: "https://pytomography.readthedocs.io"
+authors:
+  - family-names: Polson
+    given-names: Lucas A.
+  - name: "The PyTomography contributors"
+preferred-citation:
+  type: article
+  title: "PyTomography: A python library for medical image reconstruction"
+  journal: SoftwareX
+  volume: 29
+  start: 102020
+  year: 2025
+  doi: 10.1016/j.softx.2024.102020
+  authors:
+    - family-names: Polson
+      given-names: Lucas A.
+    - family-names: Fedrigo
+      given-names: Roberto
+    - family-names: Li
+      given-names: Chenguang
+    - family-names: Sabouri
+      given-names: Maziar
+    - family-names: Dzikunu
+      given-names: Obed
+    - family-names: Ahamed
+      given-names: Shadab
+    - family-names: Karakatsanis
+      given-names: Nicolas
+    - family-names: Kurkowska
+      given-names: Sara
+    - family-names: Sheikhzadeh
+      given-names: Peyman
+    - family-names: Esquinas
+      given-names: Pedro
+    - family-names: Rahmim
+      given-names: Arman
+    - family-names: Uribe
+      given-names: Carlos

pytomography-4.0.0/PKG-INFO

@@ -0,0 +1,85 @@
+Metadata-Version: 2.5
+Name: pytomography
+Version: 4.0.0
+Summary: Package to perform tomographic image reconstruction
+Project-URL: Homepage, https://github.com/PyTomography/PyTomography
+Project-URL: Documentation, https://pytomography.readthedocs.io
+Project-URL: Bug Tracker, https://github.com/PyTomography/PyTomography/issues
+Project-URL: Discussions, https://github.com/PyTomography/PyTomography/discussions
+Author-email: Luke Polson <lukepolson@outlook.com>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+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
+Requires-Dist: h5py>=3.11.0
+Requires-Dist: matplotlib>=3.8.0
+Requires-Dist: nibabel>=5.1.0
+Requires-Dist: numba>=0.59
+Requires-Dist: numpy>=1.24.2
+Requires-Dist: pandas>=2.2
+Requires-Dist: pydicom>=3.0.1
+Requires-Dist: rt-utils>=1.2.0
+Requires-Dist: scipy>=1.10.1
+Requires-Dist: spectarf>=0.1
+Requires-Dist: torch>=2.4
+Requires-Dist: torchrbf
+Requires-Dist: uproot>=5.2.1
+Provides-Extra: dev
+Requires-Dist: myst-nb>=1.1; extra == 'dev'
+Requires-Dist: petsird<0.10,>=0.9; extra == 'dev'
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: pydata-sphinx-theme>=0.16; extra == 'dev'
+Requires-Dist: pytest-xdist; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: pyyaml; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Requires-Dist: sphinx-autoapi>=3.3; extra == 'dev'
+Requires-Dist: sphinx-autobuild; extra == 'dev'
+Requires-Dist: sphinx-copybutton; extra == 'dev'
+Requires-Dist: sphinx-design; extra == 'dev'
+Requires-Dist: sphinx<9,>=8; extra == 'dev'
+Provides-Extra: doc
+Requires-Dist: myst-nb>=1.1; extra == 'doc'
+Requires-Dist: pydata-sphinx-theme>=0.16; extra == 'doc'
+Requires-Dist: pyyaml; extra == 'doc'
+Requires-Dist: sphinx-autoapi>=3.3; extra == 'doc'
+Requires-Dist: sphinx-autobuild; extra == 'doc'
+Requires-Dist: sphinx-copybutton; extra == 'doc'
+Requires-Dist: sphinx-design; extra == 'doc'
+Requires-Dist: sphinx<9,>=8; extra == 'doc'
+Provides-Extra: petsird
+Requires-Dist: petsird<0.10,>=0.9; extra == 'petsird'
+Provides-Extra: test
+Requires-Dist: petsird<0.10,>=0.9; extra == 'test'
+Requires-Dist: pytest-xdist; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: pyyaml; extra == 'test'
+Description-Content-Type: text/markdown
+
+
+
+# <img src="https://pytomography.readthedocs.io/en/latest/_static/PT1.png" alt= “” width="5%">  PyTomography    <img src="https://www.bccrc.ca/dept/io-programs/qurit/sites/qurit/files/FINAL_QURIT_PNG_60.png" alt= “” width="10%">
+
+[![Tests on development](https://github.com/PyTomography/PyTomography/actions/workflows/tests.yml/badge.svg?branch=development&event=push)](https://github.com/PyTomography/PyTomography/actions/workflows/tests.yml?query=branch%3Adevelopment+event%3Apush)
+[![Tests on docs/v4-site](https://github.com/PyTomography/PyTomography/actions/workflows/tests.yml/badge.svg?branch=docs/v4-site&event=push)](https://github.com/PyTomography/PyTomography/actions/workflows/tests.yml?query=branch%3Adocs%2Fv4-site+event%3Apush)
+![Contributors](https://img.shields.io/github/contributors/qurit/PyTomography?style=plastic)
+![Forks](https://img.shields.io/github/forks/qurit/PyTomography)
+![Stars](https://img.shields.io/github/stars/qurit/PyTomography)
+![Issues](https://img.shields.io/github/issues/qurit/PyTomography)
+
+# Getting Started
+We have prepared a very detailed documentation guide available at [readthedocs](https://pytomography.readthedocs.io/en/latest/). If you have any additional questions, please ask them in [GitHub Discussions](https://github.com/PyTomography/PyTomography/discussions/categories/q-a). To contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+# Research Paper
+If you use PyTomography in your own research, please cite the corresponding research paper:
+
+**Lucas A. Polson, Roberto Fedrigo, Chenguang Li, Maziar Sabouri, Obed Dzikunu, Shadab Ahamed, Nicolas Karakatsanis, Sara Kurkowska, Peyman Sheikhzadeh, Pedro Esquinas, Arman Rahmim, and Carlos Uribe.** *PyTomography: A python library for medical image reconstruction.* SoftwareX, Volume 29, 2025, Page 102020. https://www.sciencedirect.com/science/article/pii/S235271102400390X
+
+# License
+This work is licensed under an MIT license, as is found in the LICENSE file.
+

{pytomography-3.3.2 → pytomography-4.0.0}/README.md

@@ -2,13 +2,15 @@
 
 # <img src="https://pytomography.readthedocs.io/en/latest/_static/PT1.png" alt= “” width="5%">  PyTomography    <img src="https://www.bccrc.ca/dept/io-programs/qurit/sites/qurit/files/FINAL_QURIT_PNG_60.png" alt= “” width="10%">
 
+[![Tests on development](https://github.com/PyTomography/PyTomography/actions/workflows/tests.yml/badge.svg?branch=development&event=push)](https://github.com/PyTomography/PyTomography/actions/workflows/tests.yml?query=branch%3Adevelopment+event%3Apush)
+[![Tests on docs/v4-site](https://github.com/PyTomography/PyTomography/actions/workflows/tests.yml/badge.svg?branch=docs/v4-site&event=push)](https://github.com/PyTomography/PyTomography/actions/workflows/tests.yml?query=branch%3Adocs%2Fv4-site+event%3Apush)
 ![Contributors](https://img.shields.io/github/contributors/qurit/PyTomography?style=plastic)
 ![Forks](https://img.shields.io/github/forks/qurit/PyTomography)
 ![Stars](https://img.shields.io/github/stars/qurit/PyTomography)
 ![Issues](https://img.shields.io/github/issues/qurit/PyTomography)
 
 # Getting Started
-We have prepared a very detailed documentation guide available at [readthedocs](https://pytomography.readthedocs.io/en/latest/). If you have any additional questions, please ask them on the [discourse website](https://pytomography.discourse.group/).
+We have prepared a very detailed documentation guide available at [readthedocs](https://pytomography.readthedocs.io/en/latest/). If you have any additional questions, please ask them in [GitHub Discussions](https://github.com/PyTomography/PyTomography/discussions/categories/q-a). To contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 # Research Paper
 If you use PyTomography in your own research, please cite the corresponding research paper:

pytomography-4.0.0/examples/README.md

@@ -0,0 +1,70 @@
+# PyTomography example scripts
+
+Plain-Python versions of every tutorial: the code that computes and saves the results, without the plots,
+what only the plots need, or the explanations, so you can read a whole pipeline at a glance or run it as a
+script. Each file links to the full tutorial on the docs site.
+
+These files are generated from the notebooks in `docs/source/notebooks` by `docs/tools/export_scripts.py`.
+Edit the notebook, then run that script; CI checks the two match.
+
+Each script downloads the data it reads with `pytomography.datasets.fetch()`; the Tutorial data page of the
+docs lists every dataset.
+
+## SPECT
+
+| Script | What it does |
+|---|---|
+| [`spect/01_simind_introduction.py`](spect/01_simind_introduction.py) | A complete OSEM pipeline on Monte Carlo data, from projections to a reconstructed image. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_siminddata.html) |
+| [`spect/02_dicom_introduction.py`](spect/02_dicom_introduction.py) | Reconstruct a phantom exported from a clinical scanner and compare with the vendor image. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_dicomdata.html) |
+| [`spect/03_reconstruction_algorithms.py`](spect/03_reconstruction_algorithms.py) | OSEM, BSREM, OSMAPOSL and KEM side by side on the same data. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_algorithms.html) |
+| [`spect/04_accuracy_against_known_truth.py`](spect/04_accuracy_against_known_truth.py) | Measure bias and noise in each sphere of a simulated phantom, with OSEM and BSREM. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_accuracy_known_truth.html) |
+| [`spect/05_multiple_bed_positions.py`](spect/05_multiple_bed_positions.py) | Reconstruct several bed positions and stitch them into one volume. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_dicommultibed.html) |
+| [`spect/06_multiple_photopeaks.py`](spect/06_multiple_photopeaks.py) | Joint reconstruction over two photopeaks of the same isotope. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_dualpeak.html) |
+| [`spect/07_uncertainty_estimation.py`](spect/07_uncertainty_estimation.py) | Voxel and region uncertainty that comes out of the reconstruction itself. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_uncertainty_spect.html) |
+| [`spect/08_hybrid_monte_carlo_simulated.py`](spect/08_hybrid_monte_carlo_simulated.py) | Monte Carlo scatter estimated inside the reconstruction loop with SIMIND. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_spect_mc.html) |
+| [`spect/09_hybrid_monte_carlo_measured.py`](spect/09_hybrid_monte_carlo_measured.py) | The same hybrid approach on measured data. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_spect_mc2.html) |
+| [`spect/10_ge_starguide.py`](spect/10_ge_starguide.py) | A 12-head CZT system with body-contour sweeps. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_starguide.html) |
+| [`spect/11_psfs_from_angular_response_functions.py`](spect/11_psfs_from_angular_response_functions.py) | The collimator and detector simulated once, the PSF at any distance, and what each camera parameter changes. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_arf_psf.html) |
+| [`spect/12_ac_225_psf_modelling_simind.py`](spect/12_ac_225_psf_modelling_simind.py) | Alpha-emitter imaging with PSFs from Monte Carlo ARFs (spectarf), penetration and collimator scatter included. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_ac225_simind_recon.html) |
+| [`spect/13_ac_225_psf_modelling_dicom.py`](spect/13_ac_225_psf_modelling_dicom.py) | The same ARF PSFs on a measured Symbia T2 scan with a non-circular orbit. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_ac225_dicom_recon.html) |
+| [`spect/14_ac_225_dual_photopeak.py`](spect/14_ac_225_dual_photopeak.py) | One image from the 218 and 440 keV photopeaks (ARF PSFs at 440 keV), against each peak alone. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_ac225_dualpeak.html) |
+| [`spect/15_cardiac_reorientation.py`](spect/15_cardiac_reorientation.py) | Reconstruct myocardial perfusion data and reorient it to the short axis. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_CardiacReorientation.html) |
+| [`spect/16_reconstruction_algorithms_on_measured_data.py`](spect/16_reconstruction_algorithms_on_measured_data.py) | OSEM, OSMAPOSL, BSREM and KEM on a measured NEMA phantom, compared by sphere contrast, background noise and data fit at every iteration. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_algorithms_measured.html) |
+| [`spect/17_filtered_back_projection_spect.py`](spect/17_filtered_back_projection_spect.py) | Filtered back projection of a Lu-177 NEMA phantom scan, with Chang's attenuation correction, next to OSEM. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_fbp_spect.html) |
+| [`spect/18_cgls_on_a_patient.py`](spect/18_cgls_on_a_patient.py) | Conjugate gradients for least squares on a two-bed Lu-177 PSMA patient, beside OSEM: the exact transpose it needs, when to stop, a diagonal preconditioner, weighted least squares, and its negative values. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_cgls.html) |
+| [`spect/19_kernel_em_with_a_pet_prior.py`](spect/19_kernel_em_with_a_pet_prior.py) | Lu-177 SPECT of the Zubal phantom reconstructed with kernels from a Ga-68 PET image: one from its intensities, one learned by a 3D U-Net, beside MLEM. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_kernel_deep_kernel_spect_recon.html) |
+
+## PET
+
+| Script | What it does |
+|---|---|
+| [`pet/01_pet_introduction_list_mode_and_sinograms.py`](pet/01_pet_introduction_list_mode_and_sinograms.py) | Reconstruct the same true coincidences as list mode and as sinograms, with normalisation and attenuation. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_pet_introduction.html) |
+| [`pet/02_gate_sinogram.py`](pet/02_gate_sinogram.py) | Non-TOF sinogram reconstruction of a simulated brain phantom with scatter and randoms. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_PETGATE_scat_sino.html) |
+| [`pet/03_gate_tof_sinogram.py`](pet/03_gate_tof_sinogram.py) | Time-of-flight sinogram reconstruction with TOF scatter estimation. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_PETGATE_scat_sinoTOF.html) |
+| [`pet/04_gate_list_mode.py`](pet/04_gate_list_mode.py) | List-mode reconstruction with scatter and randoms correction. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_PETGATE_scat_lm.html) |
+| [`pet/05_gate_tof_list_mode.py`](pet/05_gate_tof_list_mode.py) | Time-of-flight list-mode reconstruction with TOF scatter. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_PETGATE_scat_lmTOF.html) |
+| [`pet/06_ge_discovery_mi.py`](pet/06_ge_discovery_mi.py) | Clinical list mode exported from GE Duetto, with time of flight. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_GE_HDF5.html) |
+| [`pet/07_pet_uncertainty_estimation.py`](pet/07_pet_uncertainty_estimation.py) | Uncertainty estimates for a clinical PET reconstruction. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_uncertainty_pet.html) |
+| [`pet/08_petsird_list_mode.py`](pet/08_petsird_list_mode.py) | A Siemens Biograph mMR scan in ETSI's open PETSIRD format, reconstructed without and with scatter correction. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_PETSIRD.html) |
+| [`pet/09_deep_image_prior.py`](pet/09_deep_image_prior.py) | Build a PyTorch network and use it as the image model inside the reconstruction. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_PETGATE_DIP.html) |
+
+## CT
+
+| Script | What it does |
+|---|---|
+| [`ct/01_dicom_ct_pd.py`](ct/01_dicom_ct_pd.py) | Filtered back projection of raw projections from a 3rd-generation clinical CT scanner, then the settings that reproduce the scanner's own images. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_CT_GEN3.html) |
+| [`ct/02_cone_beam_micro_ct.py`](ct/02_cone_beam_micro_ct.py) | FDK and OS-SART on a laboratory micro-CT scan of glass beads, with the centre of rotation found from the data. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_CT_microct.html) |
+| [`ct/03_filtered_back_projection_ct_windows_and_memory.py`](ct/03_filtered_back_projection_ct_windows_and_memory.py) | Helical filtered back projection of a clinical chest CT with six windows, their noise against resolution, and the memory settings that fit a given machine. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_fbp_ct.html) |
+
+## Proton CT
+
+| Script | What it does |
+|---|---|
+| [`pct/01_single_sided_proton_ct_of_the_abdomen.py`](pct/01_single_sided_proton_ct_of_the_abdomen.py) | A simulated 330 MeV scan with a calorimeter behind the patient and nothing in front, reconstructed by two-pass filtered back projection and SART along curved paths, and scored on organs and range errors against the true stopping power. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_pct_abdomen.html) |
+
+## Building with PyTomography
+
+| Script | What it does |
+|---|---|
+| [`development/01_implementing_a_new_system_matrix.py`](development/01_implementing_a_new_system_matrix.py) | Write your own forward and back projector and reuse every algorithm in the library. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_examplesystemmatrix.html) |
+| [`development/02_plotting_utilities.py`](development/02_plotting_utilities.py) | Fused SPECT/CT views and other figure helpers. [Tutorial](https://pytomography.readthedocs.io/en/latest/notebooks/t_plotting.html) |

pytomography-4.0.0/pyproject.toml

@@ -0,0 +1,97 @@
+[build-system]
+requires = ["hatchling", "toml"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pytomography"
+version = "4.0.0"
+
+
+authors = [
+  { name="Luke Polson", email="lukepolson@outlook.com" },
+]
+description = "Package to perform tomographic image reconstruction"
+readme = "README.md"
+requires-python = ">=3.10"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+dependencies = [
+  "numpy>=1.24.2",
+  "scipy>=1.10.1",
+  "pydicom>=3.0.1",
+  "torch>=2.4",
+  "matplotlib>=3.8.0",
+  "uproot>=5.2.1",
+  "rt_utils>=1.2.0",
+  "nibabel>=5.1.0",
+  "h5py>=3.11.0",
+  "torchrbf",
+  "pandas>=2.2",
+  "numba>=0.59",
+  # SPECT PSFs from Monte Carlo angular response functions (ARFs), from the camera tables of pytomography.io.SPECT.
+  # Its fast NVIDIA engine is its extra: pip install "spectarf[cuda]" (the docs' Installation page)
+  "spectarf>=0.1",
+]
+
+[tool.hatch.metadata]
+allow-direct-references = true
+
+[project.urls]
+"Homepage" = "https://github.com/PyTomography/PyTomography"
+"Documentation" = "https://pytomography.readthedocs.io"
+"Bug Tracker" = "https://github.com/PyTomography/PyTomography/issues"
+"Discussions" = "https://github.com/PyTomography/PyTomography/discussions"
+
+# The sdist ships the package and its metadata only: docs/ (tutorial notebooks with outputs) and .github/ stay in the
+# repository.
+[tool.hatch.build.targets.sdist]
+include = [
+  "src/pytomography",
+  "README.md",
+  "LICENSE",
+  "CITATION.cff",
+  "pyproject.toml",
+]
+
+[project.optional-dependencies]
+# PETSIRD list mode, read with ETSI's package: 0.9 is the format of ETSI's converters and STIR
+petsird = [
+  "petsird>=0.9,<0.10",
+]
+test = [
+  "pytest>=8",
+  "pytest-xdist",
+  "pyyaml",
+  "petsird>=0.9,<0.10",
+]
+dev = [
+  "pytomography[test,doc]",
+  "pre-commit",
+  "ruff",
+]
+doc = [
+  "sphinx>=8,<9",
+  "pydata-sphinx-theme>=0.16",
+  "myst-nb>=1.1",
+  "sphinx-design",
+  "sphinx-copybutton",
+  "sphinx-autoapi>=3.3",
+  "sphinx-autobuild",
+  "pyyaml",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["src/pytomography/tests"]
+markers = [
+  "gpu: needs a CUDA device (skipped without one)",
+  "data: needs the tutorial data in PYTOMOGRAPHY_DATA (skipped without it)",
+  "network: checks the data hosts over the internet (skipped unless PYTOMOGRAPHY_NETWORK_TESTS=1)",
+]

pytomography-4.0.0/src/pytomography/__init__.py

@@ -0,0 +1,185 @@
+"""Quantitative SPECT, PET and CT reconstruction.
+
+PyTomography reconstructs images from projection data. Data goes through four kinds of objects:
+
+* :mod:`pytomography.io` reads raw data (DICOM, SIMIND, GATE, PETSIRD, vendor formats) into PyTomography's standard
+  form: the measured data, an ``object_meta`` (the image grid, in mm, placed in the patient) and a ``proj_meta``
+  (the acquisition), and saves images;
+* :mod:`pytomography.projectors` holds the system matrices, which map an object to projections (``forward``) and
+  projections back to the object (``backward``, the back projection), built from the
+  :mod:`pytomography.transforms` that model attenuation, resolution and so on;
+* :mod:`pytomography.likelihoods` compares predicted and measured projections;
+* :mod:`pytomography.algorithms` reconstructs, optionally with :mod:`pytomography.priors` and
+  :mod:`pytomography.callbacks`.
+
+The settings below apply to the whole library: ``device``, the device the computations run on (CUDA when available,
+else Apple's MPS, else the CPU; change it with :func:`set_device`), the floating point type and a host memory budget
+for the memory-heavy steps.
+"""
+import torch
+import os
+import shutil
+import sys
+from importlib.metadata import version
+
+__version__: str = version('pytomography')
+
+# Silence parallelproj import
+os.environ['PARALLELPROJ_SILENT_IMPORT'] = '1'
+
+if not sys.warnoptions:
+    import warnings
+    warnings.simplefilter("ignore")
+
+_GPU_CHECK_URL = "https://pytomography.readthedocs.io/en/latest/ai.html#check-that-pytomography-uses-the-gpu"
+
+
+def _device_message(device: torch.device, nvidia_smi: str | None, cuda_visible_devices: str | None) -> str | None:
+    """What PyTomography says at import about the device it found.
+
+    A machine with an NVIDIA GPU (``nvidia-smi`` installed) where PyTorch cannot use it gets a warning with the likely
+    cause: a broken install runs on the CPU without failing, many times slower, and is easily taken for PyTomography's
+    normal speed.
+
+    Args:
+        device (torch.device): The device PyTomography found.
+        nvidia_smi (str | None): Path of ``nvidia-smi``, or None if it is not installed.
+        cuda_visible_devices (str | None): The ``CUDA_VISIBLE_DEVICES`` environment variable, or None if unset.
+
+    Returns:
+        str | None: The message, or None on a CUDA GPU.
+    """
+    if device.type == "cuda":
+        return None
+    if device.type == "mps":
+        return "PyTomography found an Apple Silicon GPU (mps); support for it is experimental."
+    if nvidia_smi is None:
+        return "PyTomography did not find a GPU on this machine, so it runs on the CPU."
+    if cuda_visible_devices is not None and cuda_visible_devices.strip() in ("", "-1"):
+        cause = f"CUDA_VISIBLE_DEVICES={cuda_visible_devices!r} hides the GPU; unset it to use the GPU."
+    elif torch.version.cuda is None:
+        cause = (f"PyTorch {torch.__version__} is a CPU-only build: reinstall PyTorch with the command for your CUDA "
+                 "version from https://pytorch.org/get-started/locally/.")
+    else:
+        cause = (f"PyTorch {torch.__version__} is built for CUDA {torch.version.cuda} but cannot use the GPU: the NVIDIA "
+                 "driver may be too old for it (nvidia-smi shows the newest CUDA version the driver supports).")
+    return ("WARNING: this machine has an NVIDIA GPU, but PyTomography is running on the CPU, which is many times "
+            f"slower. {cause} See {_GPU_CHECK_URL}")
+
+
+def _parallelproj_message(device: torch.device | str, cuda_enabled: bool) -> str | None:
+    """What PyTomography says when PET or CT is imported with parallelproj's CPU build although PyTorch uses a CUDA
+    GPU: the PET and CT projectors then run on the CPU, many times slower.
+
+    Args:
+        device (torch.device | str): PyTomography's device.
+        cuda_enabled (bool): ``parallelproj_core.cuda_enabled``.
+
+    Returns:
+        str | None: The message, or None when there is nothing to say.
+    """
+    if torch.device(device).type != "cuda" or cuda_enabled:
+        return None
+    return ("WARNING: PyTomography uses the GPU, but parallelproj is its CPU build, so PET and CT projections run on the "
+            "CPU, many times slower. Install the libparallelproj build that matches your CUDA version, e.g. "
+            '`conda install -c conda-forge "libparallelproj=*=cuda130*" parallelproj`. See ' + _GPU_CHECK_URL)
+
+
+def _say(message: str | None) -> None:
+    if message:
+        print(message, file=sys.stderr if message.startswith("WARNING") else sys.stdout)
+
+
+_parallelproj_checked = False
+
+
+def _check_parallelproj(parallelproj_core) -> None:
+    """Warns once, when PET or CT is first imported, if parallelproj is its CPU build on a GPU machine."""
+    global _parallelproj_checked
+    if not _parallelproj_checked:
+        _parallelproj_checked = True
+        _say(_parallelproj_message(device, bool(getattr(parallelproj_core, "cuda_enabled", False))))
+
+
+device = torch.device("cuda" if torch.cuda.is_available() else "mps" if torch.backends.mps.is_available() else "cpu")
+"""The device PyTomography computes on: CUDA when PyTorch sees an NVIDIA GPU, else Apple's MPS, else the CPU. Change it
+with :func:`set_device`. On import, PyTomography warns if the machine has an NVIDIA GPU that PyTorch cannot use."""
+_say(_device_message(device, shutil.which("nvidia-smi"), os.environ.get("CUDA_VISIBLE_DEVICES")))
+dtype = torch.float32
+"""The floating point type of PyTomography's tensors. Set it with :func:`set_dtype`."""
+delta = 1e-11
+"""A small number added to denominators to avoid dividing by zero (set by :func:`set_dtype`)."""
+verbose = False
+"""A flag set by :func:`set_verbose`. No part of the library reads it at present."""
+
+def set_dtype(dt: float):
+    """Sets the floating point type of PyTomography's tensors, and torch's default type.
+
+    Also sets :data:`delta` to suit the type: 1e-5 for ``torch.float16``, 1e-11 for ``torch.float32`` (other types
+    leave it unchanged).
+
+    Args:
+        dt (torch.dtype): The type, e.g. ``torch.float32``.
+    """
+    global dtype
+    global delta
+    dtype = dt
+    torch.set_default_dtype(dt)
+    if dt==torch.float16:
+        delta = 1e-5
+    elif dt==torch.float32:
+        delta = 1e-11
+
+def set_device(d: str):
+    """Sets the device PyTomography computes on.
+
+    Args:
+        d (str | torch.device): The device, e.g. ``'cuda'``, ``'cuda:1'`` or ``'cpu'``.
+    """
+    global device
+    device = d
+
+def set_verbose(b: bool):
+    """Sets the :data:`verbose` flag.
+
+    Args:
+        b (bool): The new value.
+    """
+    global verbose
+    verbose = b
+
+memory_budget = None
+"""Host memory (RAM), in bytes, that PyTomography's memory-heavy steps plan for, or None for no budget. Set it with
+:func:`set_memory_budget`."""
+
+def set_memory_budget(gb: float | None):
+    """Sets how much host memory (RAM), in GB, PyTomography's memory-heavy steps may use.
+
+    They split their work to fit:
+
+    * steps that go through every pair of crystals of a PET scanner (normalization weights and sinograms, the list mode
+      sensitivity image; 411 million pairs for the Siemens Biograph mMR) do so in blocks sized from the budget;
+    * a sinogram that would take more than a quarter of the budget is built one subset of angles at a time instead of
+      whole (a :class:`~pytomography.io.PET.LazySinogram`), e.g. a time of flight sinogram;
+    * helical CT filtered back projection rebins a chunk of views at a time, at most an eighth of the budget;
+    * a reconstruction whose subsets would not fit stops before it starts, with the number of subsets that would.
+
+    The results do not depend on the budget. Without one (the default), blocks have fixed sizes, and sinograms are
+    built whole unless one would take more than 8 GB (a TOF sinogram of a clinical scanner).
+
+    To see what a reconstruction will need before running it, ask its system matrix or algorithm: ``estimate_memory``
+    gives the peak RAM and GPU memory for given settings (e.g. ``n_subsets``), and ``plan_memory`` the fastest settings
+    that fit a RAM and GPU budget, by default what is free on this machine (see :mod:`pytomography.utils.memory`).
+
+    Args:
+        gb (float | None): Memory budget in GB, or None for no budget.
+
+    Raises:
+        ValueError: If ``gb`` is not positive.
+    """
+    global memory_budget
+    if gb is not None and gb <= 0:
+        raise ValueError(f"the memory budget must be positive, got {gb} GB")
+    memory_budget = None if gb is None else float(gb) * 1e9
+    
+    

pytomography-4.0.0/src/pytomography/algorithms/__init__.py

@@ -0,0 +1,27 @@
+"""Reconstruction algorithms.
+
+Statistical algorithms take a likelihood (:mod:`pytomography.likelihoods`), and some a prior
+(:mod:`pytomography.priors`); calling one with the number of iterations and subsets reconstructs:
+
+* :class:`OSEM` and :class:`MLEM`: ordered subset expectation maximisation;
+* :class:`OSMAPOSL`, :class:`BSREM`, :class:`RBIMAP`: maximum a posteriori, with a prior;
+* :class:`RBIEM`: rescaled block iterative EM;
+* :class:`KEM`: the kernel method (with :class:`~pytomography.projectors.shared.KEMSystemMatrix`);
+* :class:`SART`: simultaneous algebraic reconstruction (least squares, e.g. CT);
+* :class:`PGAAMultiBedSPECT`: several SPECT bed positions reconstructed together and stitched;
+* :class:`PreconditionedGradientAscentAlgorithm`: the base class of all of them;
+* :class:`DIPRecon`: the deep image prior.
+
+:class:`FilteredBackProjection` is the analytic reconstruction of SPECT and CT projections.
+:class:`CGLS` solves unweighted least squares with a matched forward/adjoint pair, allowing negative image values.
+
+Example:
+    .. code-block:: python
+
+        likelihood = PoissonLogLikelihood(system_matrix, projections)
+        recon = OSEM(likelihood)(n_iters=4, n_subsets=8)
+"""
+from .preconditioned_gradient_ascent import PreconditionedGradientAscentAlgorithm, OSEM, OSMAPOSL, BSREM, KEM, RBIEM, RBIMAP, SART, PGAAMultiBedSPECT, MLEM
+from .fbp import FilteredBackProjection
+from .dip_recon import DIPRecon
+from .cgls import CGLS