Metadata-Version: 2.4
Name: MomentRT
Version: 0.10.0
Summary: Deterministic light transport using angular-moment methods.
Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/MartinPdeS/MomentRT
Project-URL: Repository, https://github.com/MartinPdeS/MomentRT
Project-URL: Issues, https://github.com/MartinPdeS/MomentRT/issues
Project-URL: Documentation, https://martinpdes.github.io/MomentRT/docs/latest/
Keywords: radiative transfer,light transport,diffusion,spherical harmonics,finite element method,tissue optics
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Topic :: Scientific/Engineering :: Visualization
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Framework :: Jupyter
Classifier: Framework :: Sphinx
Requires-Python: >=3.11
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: numpy>=1.26
Requires-Dist: scipy>=1.12
Requires-Dist: pint>=0.24
Requires-Dist: matplotlib>=3.8
Requires-Dist: plotly<7,>=6
Requires-Dist: gmsh<5,>=4.13
Provides-Extra: release
Requires-Dist: martinpdes-maintenance==0.2.3; extra == "release"
Provides-Extra: testing
Requires-Dist: martinpdes-maintenance[testing]==0.2.3; extra == "testing"
Provides-Extra: documentation
Requires-Dist: MartinPdeS-docs<0.6,>=0.5; extra == "documentation"
Provides-Extra: dev
Requires-Dist: martinpdes-maintenance[quality]==0.2.3; extra == "dev"
Dynamic: license-file

|logo|

.. list-table::
   :widths: 35 65
   :header-rows: 1

   * - Badge
     - Status
   * - Python versions
     - |python|
   * - Documentation
     - |docs|
   * - Tests
     - |tests|
   * - Coverage workflow
     - |coverage|
   * - PyPI package
     - |pypi|
   * - PyPI downloads
     - |pypi_downloads|
   * - Anaconda package
     - |anaconda|
   * - Anaconda downloads
     - |anaconda_downloads|
   * - Latest Anaconda release
     - |anaconda_date|

MomentRT
========

**MomentRT** is an open-source Python package for deterministic light
transport using angular-moment methods. It models steady-state P1 diffusion
in homogeneous infinite media and finite structured samples. Its API keeps the
sample, illumination, mesh, and solver explicit, and its results include
unit-bearing optical fields and power diagnostics.

Features
--------

* Analytical P1 diffusion from an isotropic point source in an infinite,
  homogeneous medium.
* Boundary-aware P1 diffusion for finite samples, solved with linear
  tetrahedral finite elements.
* Layered samples with box and sphere structures, plus resolved material
  cross-sections.
* Explicit diffuse surface illumination and Robin or reflecting conditions
  on all six sample faces.
* Interactive Plotly views for sample geometry, fluence, sections, and
  element-centered flux. Volume plots include an opacity control.
* Unit-bearing fields, per-face escaping power, and solver diagnostics.
* Circular contact detector apertures with explicit angular acceptance under
  a Lambertian escape model.
* Tabulated wavelength-dependent materials and monochromatic sweeps on a
  fixed source, sample, and detector geometry.
* Detector mesh-refinement studies and reusable finite-element preparation
  across wavelengths.
* A coupled SP3 finite-element solver with explicit scattering anisotropy and
  matched-index boundaries, alongside the P1 diffusion solver.
* A full three-dimensional P3 finite-element solver with matched-index faces.
* Scalar Henyey–Greenstein, isotropic, Rayleigh, and tabulated scattering
  phase functions for SP3 and P3.

Source spectra and linear detector responsivity support explicit broadband
optical-power and photocurrent integration.

MomentRT offers P1, SP3, and P3 approximations. The finite P1 solver is
``P1`` and the analytical infinite-medium solver is ``InfiniteP1``. Their
previous names, ``Diffusion`` and ``InfiniteDiffusion``, remain available as
aliases. MomentRT does not currently solve the
full radiative transfer equation or implement collimated LED
propagation, free-space detector optics,
time dependence, or inverse estimation. Read the `scientific guide`_ for the equations,
approximations, validation limits, and complete workflow.

Installation
------------

Install the released Python package:

.. code-block:: console

   python -m pip install MomentRT

Or install the conda package and its dependencies:

.. code-block:: console

   conda install -c martinpdes -c conda-forge momentrt

Verify the installation with the same Python interpreter you will use for your
calculations:

.. code-block:: console

   python -c "import MomentRT; print(MomentRT.__version__)"

The package includes Plotly for interactive plots.

First simulation
----------------

The infinite-medium solver is a quick way to calculate and inspect a fluence
field. This example uses explicit units and places the source between grid
nodes, avoiding the singular point-source location.

.. code-block:: python

   import numpy as np
   import MomentRT

   from MomentRT import (
       CartesianMesh,
       HomogeneousMedium,
       InfiniteP1,
       Material,
       PointSource,
       Simulation,
       ureg,
   )

   material = Material(
       absorption=0.02 / ureg.millimeter,
       reduced_scattering=1.0 / ureg.millimeter,
       refractive_index=1.4,
       phase_function=MomentRT.phase_function.HenyeyGreenstein(),
   )

   medium = HomogeneousMedium(material=material)

   mesh = CartesianMesh(
       shape=(40, 40, 40),
       spacing=np.full(3, 0.4) * ureg.millimeter,
       origin=np.full(3, -7.8) * ureg.millimeter,
   )

   source = PointSource(
       position=np.zeros(3) * ureg.millimeter,
       wavelength=970 * ureg.nanometer,
       optical_power=1 * ureg.milliwatt,
   )

   solver = InfiniteP1()

   simulation = Simulation(
       medium=medium,
       source=source,
       mesh=mesh,
       solver=solver,
   )

   result = simulation.run()

   figure = result.fluence.plot(
       scale="log",
   )

``result.fluence`` is a nodal fluence-rate field with units of W/m². The
infinite solver evaluates an analytical Green function; the observation grid
does not create physical sample boundaries.

Finite-sample FEM workflow
--------------------------

For a finite sample, define its geometry and materials, create a mesh, specify
surface illumination and all six boundary faces, then run ``P1``. This
example uses the same explicit effective reflectance on each face and a
circular diffuse source on the upper face.

.. code-block:: python

   import numpy as np
   import MomentRT

   from MomentRT import (
       TetrahedralMesh,
       P1,
       Material,
       RobinBoundary,
       Simulation,
       StructuredMedium,
       SurfaceSource,
       ureg,
   )

   background = Material(
       absorption=0.02 / ureg.millimeter,
       reduced_scattering=1.0 / ureg.millimeter,
       refractive_index=1.4,
       phase_function=MomentRT.phase_function.HenyeyGreenstein(),
   )

   upper_material = Material(
       absorption=0.04 / ureg.millimeter,
       reduced_scattering=1.5 / ureg.millimeter,
       refractive_index=1.4,
       phase_function=MomentRT.phase_function.HenyeyGreenstein(),
   )

   sample = StructuredMedium(
       origin=(-4, -4, 0) * ureg.millimeter,
       size=(8, 8, 4) * ureg.millimeter,
   )

   sample.add_background(material=background)

   sample.add_layer(
       name="Upper layer",
       thickness=1 * ureg.millimeter,
       material=upper_material,
   )

   mesh = TetrahedralMesh.from_sample(
       sample=sample,
       resolution=0.5 * ureg.millimeter,
   )

   source = SurfaceSource(
       face="z_min",
       position=np.array([0, 0, 0]) * ureg.millimeter,
       radius=1 * ureg.millimeter,
       wavelength=970 * ureg.nanometer,
       optical_power=1 * ureg.milliwatt,
   )

   boundary = RobinBoundary(effective_reflectance=0.5)

   solver = P1(
       boundaries=MomentRT.Boundaries.uniform(condition=boundary),
   )

   simulation = Simulation(
       medium=sample,
       source=source,
       mesh=mesh,
       solver=solver,
   )

   geometry = simulation.plot_system(
       show=False,
   )

   result = simulation.run()

   figure = result.fluence.plot(
       view="volume",
       scale="log",
       display_resolution=0.4 * ureg.millimeter,
   )

   print(f"Incoming power: {result.energy_balance['incoming_power']}")
   print(f"Absorbed power: {result.energy_balance['absorbed_power']}")
   print(f"Escaping power: {result.energy_balance['escaping_power']}")

The finite ``P1`` solver uses P1 diffusion with linear tetrahedral FEM.
The recommended ``TetrahedralMesh`` conforms to sample interfaces; its
resolution is a target element size. Refine the mesh to assess convergence.
Tetrahedral fluence plots interpolate onto a separate display grid. The sample
mesh must span the sample exactly. Internal refractive indices
must be equal because the solver models continuous fluence and does not
resolve refracting interfaces. ``SurfaceSource.optical_power`` is diffuse
power already coupled into the sample; incident beam propagation and
specular entry losses are not included. The supplied effective reflectance
is a diffuse partial-current coefficient, not a Fresnel value inferred from
refractive index.

Visualization
-------------

The default fluence plot is a Plotly volume view. Adjust opacity from 0 to 1
using its browser slider, or choose a starting value with ``opacity``:

.. code-block:: python

   figure = result.fluence.plot(
       view="volume",
       scale="log",
       display_resolution=0.4 * ureg.millimeter,
       opacity=0.12,
       show=False,
   )

   figure.write_html("fluence.html")

Other scalar-field views include central mesh ``slices`` and
``isosurfaces``. ``result.flux.plot()`` displays element-centered diffusive
flux vectors. ``sample.plot()`` shows the transparent construction surfaces;
``sample.plot_section(...)`` displays a sampled material or optical-property
map. Log color scales change the displayed colors only; hover values retain
their physical units.

The following figures were generated from MomentRT examples and results.
The live documentation contains interactive Plotly versions.

.. image:: https://raw.githubusercontent.com/MartinPdeS/MomentRT/master/docs/source/_static/images/sample-geometry.png
   :width: 900
   :align: center
   :alt: MomentRT view of a layered sample with a spherical inclusion.

.. image:: https://raw.githubusercontent.com/MartinPdeS/MomentRT/master/docs/source/_static/images/infinite-fluence-volume.png
   :width: 900
   :align: center
   :alt: Logarithmic volume rendering of fluence around an isotropic point source.

.. image:: https://raw.githubusercontent.com/MartinPdeS/MomentRT/master/docs/source/_static/images/finite-fluence-slices.png
   :width: 900
   :align: center
   :alt: Logarithmic fluence on three central planes in a finite sample.

Documentation
-------------

The `online documentation <https://martinpdes.github.io/MomentRT/>`_ includes:

* The P1 moment equations, infinite-medium Green function, and approximation
  limits.
* The finite-sample Robin boundary condition, weak form, and FEM assembly.
* Complete workflows, visualization guidance, results, and API reference.
* An executable `example gallery
  <https://martinpdes.github.io/MomentRT/docs/latest/gallery/index.html>`_.

From the repository root, reuse a development ``.venv`` (or create one as
described below), then build the docs and run the examples with:

.. code-block:: console

   .venv/bin/python -m pip install -e ".[documentation]"
   make docs PYTHON=.venv/bin/python

Common issues
-------------

* **Point-source singularity:** do not place an observation node exactly at
  the point source. MomentRT reports this instead of silently regularizing it.
* **No visible internal interface:** construction plots use transparent
  geometry surfaces. Use a sampled section to inspect the resolved material
  precedence.
* **Finite solver rejects refractive indices:** the current FEM formulation
  requires equal internal refractive indices; it does not model internal
  refraction.
* **Unexpected surface-source power:** source power is already coupled diffuse
  power in the sample. Collimated illumination and specular entry losses are
  outside the model.
* **Slow or changing fields under refinement:** element-centroid materials,
  source quadrature, interface alignment, and P1 validity can all affect the
  result. Refine meshes and compare independent references; energy balance
  alone does not validate the physical approximation.
* **Log plot rejects values:** logarithmic rendering requires strictly
  positive values and does not clip zeros or negative values.

Developer setup
---------------

Clone the repository, install the development extras, and build the docs with
the same Python interpreter used for development:

.. code-block:: console

   git clone https://github.com/MartinPdeS/MomentRT.git
   cd MomentRT
   python3 -m venv .venv
   .venv/bin/python -m pip install -e ".[testing,documentation,dev,release]"
   make check typecheck docstring-check PYTHON=.venv/bin/python
   make docs PYTHON=.venv/bin/python

``make check`` runs quality checks and tests. The codebase intentionally keeps
the package flat, with type hints and NumPy-style API docstrings. Run
``make typecheck docstring-check`` to validate annotations and public
parameter documentation.

See the `contributor guide
<https://github.com/MartinPdeS/MomentRT/blob/master/CONTRIBUTING.rst>`_ for
platform setup, reference-data regeneration, release commands, and the API
compatibility policy. User-visible changes and scientific corrections are
recorded in the `changelog
<https://github.com/MartinPdeS/MomentRT/blob/master/CHANGELOG.md>`_.

Citation and license
--------------------

MomentRT is distributed under the MIT license. If you use it in research,
cite the version recorded in ``CITATION.cff``. For bibliographic metadata,
see the `CITATION.cff file
<https://github.com/MartinPdeS/MomentRT/blob/master/CITATION.cff>`_.

.. _scientific guide: https://martinpdes.github.io/MomentRT/docs/latest/theory.html

.. |logo| image:: https://raw.githubusercontent.com/MartinPdeS/MomentRT/master/docs/images/logo.svg
   :alt: MomentRT — light transport through a finite element volume.
   :width: 800
   :target: https://martinpdes.github.io/MomentRT/docs/latest/

.. |python| image:: https://img.shields.io/pypi/pyversions/MomentRT.svg
   :alt: Python versions
   :target: https://pypi.org/project/MomentRT/
.. |docs| image:: https://github.com/MartinPdeS/MomentRT/actions/workflows/deploy_documentation.yml/badge.svg?branch=master
   :alt: Documentation build status
   :target: https://martinpdes.github.io/MomentRT/
.. |tests| image:: https://github.com/MartinPdeS/MomentRT/actions/workflows/tests.yml/badge.svg?branch=master
   :alt: Test workflow status
   :target: https://github.com/MartinPdeS/MomentRT/actions/workflows/tests.yml
.. |coverage| image:: https://github.com/MartinPdeS/MomentRT/actions/workflows/deploy_coverage.yml/badge.svg?branch=master
   :alt: Coverage workflow status
   :target: https://github.com/MartinPdeS/MomentRT/actions/workflows/deploy_coverage.yml
.. |pypi| image:: https://img.shields.io/pypi/v/MomentRT.svg
   :alt: PyPI version
   :target: https://pypi.org/project/MomentRT/
.. |pypi_downloads| image:: https://img.shields.io/pypi/dm/MomentRT.svg
   :alt: Monthly PyPI downloads
   :target: https://pypi.org/project/MomentRT/
.. |anaconda| image:: https://anaconda.org/martinpdes/momentrt/badges/version.svg
   :alt: Anaconda version
   :target: https://anaconda.org/martinpdes/momentrt
.. |anaconda_downloads| image:: https://anaconda.org/martinpdes/momentrt/badges/downloads.svg
   :alt: Anaconda downloads
   :target: https://anaconda.org/martinpdes/momentrt
.. |anaconda_date| image:: https://anaconda.org/martinpdes/momentrt/badges/latest_release_relative_date.svg
   :alt: Latest Anaconda release date
   :target: https://anaconda.org/martinpdes/momentrt
