MomentRT 0.1.0__tar.gz

momentrt-0.1.0/.zenodo.json

@@ -0,0 +1,21 @@
+{
+  "title": "MomentRT: deterministic light transport using angular-moment methods",
+  "description": "MomentRT is a Python package for deterministic light transport using angular-moment methods. It includes finite-element diffusion through structured media and tools for visualizing optical fields.",
+  "creators": [
+    {
+      "name": "Poinsinet de Sivry-Houle, Martin"
+    }
+  ],
+  "license": "mit",
+  "upload_type": "software",
+  "access_right": "open",
+  "version": "0.1.0",
+  "keywords": [
+    "radiative transfer",
+    "light transport",
+    "diffusion",
+    "finite element method",
+    "tissue optics"
+  ],
+  "publication_date": "2026-10-28"
+}

momentrt-0.1.0/CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+message: "If you use MomentRT in research, please cite the software version used."
+title: "MomentRT"
+type: software
+version: "0.1.0"
+authors:
+  - family-names: "Poinsinet de Sivry-Houle"
+    given-names: "Martin"
+abstract: >
+  MomentRT is a Python package for deterministic light transport using
+  angular-moment methods. It includes finite-element diffusion through
+  structured media and tools for visualizing optical fields.
+license: "MIT"
+keywords:
+  - radiative transfer
+  - light transport
+  - diffusion
+  - finite element method
+  - tissue optics

momentrt-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Martin Poinsinet de Sivry-Houle
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

momentrt-0.1.0/MANIFEST.in

@@ -0,0 +1,4 @@
+include LICENSE
+include CITATION.cff
+include .zenodo.json
+include conda.recipe/meta.yaml

momentrt-0.1.0/MomentRT/__init__.py

@@ -0,0 +1,39 @@
+"""Deterministic light transport using angular-moment methods."""
+
+from ._version import __version__
+from .boundary import ReflectingBoundary, RobinBoundary
+from .diffusion import Diffusion, InfiniteDiffusion
+from .fields import ScalarField, VectorField
+from .geometry import Box, Layer, Sphere
+from .material import Material
+from .medium import HomogeneousMedium, StructuredMedium
+from .mesh import CartesianMesh
+from .results import SimulationResult
+from .sections import SampleSection
+from .simulation import Simulation
+from .source import PointSource, SurfaceSource, UniformSurfaceSource
+from .units import ureg
+
+__all__ = [
+    "Diffusion",
+    "RobinBoundary",
+    "ReflectingBoundary",
+    "SurfaceSource",
+    "UniformSurfaceSource",
+    "VectorField",
+    "Box",
+    "Layer",
+    "Sphere",
+    "StructuredMedium",
+    "CartesianMesh",
+    "HomogeneousMedium",
+    "InfiniteDiffusion",
+    "Material",
+    "PointSource",
+    "SampleSection",
+    "ScalarField",
+    "Simulation",
+    "SimulationResult",
+    "ureg",
+    "__version__",
+]

momentrt-0.1.0/MomentRT/_version.py

@@ -0,0 +1,3 @@
+"""Package version shared with release metadata."""
+
+__version__ = version = "0.1.0"

momentrt-0.1.0/MomentRT/boundary.py

@@ -0,0 +1,45 @@
+"""Explicit partial-current boundary conditions for steady-state diffusion."""
+
+import numpy as np
+
+from .units import ureg
+
+FACES = ("x_min", "x_max", "y_min", "y_max", "z_min", "z_max")
+
+
+class RobinBoundary:
+    """Diffuse internal reflection with an explicitly supplied effective reflectance.
+
+    This is a partial-current coefficient, not normal-incidence Fresnel R.
+    No refractive-index-to-reflectance approximation is selected implicitly.
+    With R=effective_reflectance, beta=(1-R)/(2(1+R)) and outward net
+    current J.n = beta Phi - 2 I_in/(1+R). I_in is incoming diffuse
+    partial current already coupled into the sample (W/m^2).
+    """
+
+    def __init__(self, *, effective_reflectance):
+        value = effective_reflectance
+
+        if (
+            isinstance(value, (ureg.Quantity, bool))
+            or not np.isscalar(value)
+            or not np.isfinite(value)
+            or not 0 <= value < 1
+        ):
+            raise ValueError("effective_reflectance must be a plain number in [0, 1).")
+
+        self.effective_reflectance = value
+
+    @property
+    def leakage_coefficient(self):
+        return (1 - self.effective_reflectance) / (2 * (1 + self.effective_reflectance))
+
+    @property
+    def source_factor(self):
+        return 2 / (1 + self.effective_reflectance)
+
+
+class ReflectingBoundary:
+    """Zero normal current; illumination on this face is unsupported."""
+
+    leakage_coefficient = 0.0

momentrt-0.1.0/MomentRT/diffusion.py

@@ -0,0 +1,327 @@
+"""Analytical steady-state diffusion Green function in an infinite medium."""
+
+import numpy as np
+
+from .fields import ScalarField
+from .medium import HomogeneousMedium
+from .source import PointSource
+from .units import ureg
+
+
+class InfiniteDiffusion:
+    """Evaluate Phi = P exp(-sqrt(mu_a/D) r) / (4 pi D r).
+
+    No boundary, Fresnel interface, or finite-source correction is applied.
+    The observation window does not truncate the physical medium.
+    """
+
+    def solve(self, *, medium, source, mesh):
+        if not isinstance(medium, HomogeneousMedium):
+            raise TypeError(
+                "InfiniteDiffusion supports only HomogeneousMedium; finite structured samples require a boundary-aware solver."
+            )
+
+        if not isinstance(source, PointSource):
+            raise TypeError(
+                "InfiniteDiffusion requires an embedded PointSource, not surface illumination."
+            )
+
+        absorption = medium.material.absorption.to("1/m").magnitude
+
+        scattering = medium.material.reduced_scattering.to("1/m").magnitude
+
+        diffusion_length = 1 / (3 * (absorption + scattering))
+
+        displacement = mesh.points.to("m").magnitude - source.position.to("m").magnitude
+
+        distance = np.linalg.norm(displacement, axis=-1)
+
+        if np.any(distance == 0):
+            raise ValueError(
+                "The point source is singular; choose a grid that excludes its position."
+            )
+
+        values = (
+            source.optical_power.to("W").magnitude
+            * np.exp(-np.sqrt(absorption / diffusion_length) * distance)
+            / (4 * np.pi * diffusion_length * distance)
+        )
+
+        return ScalarField(
+            mesh=mesh,
+            values=values * ureg.watt / ureg.meter**2,
+            name="Fluence rate",
+            metadata={
+                "transport": "infinite-medium steady-state P1 diffusion",
+                "wavelength": source.wavelength,
+                "source_position": source.position,
+            },
+        )
+
+
+class Diffusion:
+    """Steady-state P1 diffusion with linear tetrahedral finite elements.
+
+    All six boundary faces must be configured explicitly. Material properties
+    are constant per element, sampled at its centroid. Interfaces not aligned
+    to element faces are approximated and require mesh refinement. Continuous
+    fluence assumes equal refractive indices across all internal regions;
+    internal index jumps are rejected rather than silently ignored.
+    """
+
+    def __init__(self, *, boundaries):
+        from .boundary import FACES, ReflectingBoundary, RobinBoundary
+
+        if set(boundaries) != set(FACES):
+            raise ValueError(f"Configure exactly these boundary faces: {FACES}.")
+
+        if any(
+            not isinstance(condition, (RobinBoundary, ReflectingBoundary))
+            for condition in boundaries.values()
+        ):
+            raise TypeError("Each face requires RobinBoundary or ReflectingBoundary.")
+
+        self.boundaries = dict(boundaries)
+
+    def solve(self, *, medium, source, mesh):
+        from scipy.sparse import coo_matrix
+        from scipy.sparse.linalg import spsolve
+
+        from .boundary import RobinBoundary
+        from .fem import (
+            boundary_triangles,
+            element_geometry,
+            source_load,
+            tetrahedralize,
+            triangle_areas,
+        )
+        from .fields import VectorField
+        from .medium import StructuredMedium
+        from .results import SimulationResult
+        from .source import SurfaceSource, UniformSurfaceSource
+
+        if not isinstance(medium, StructuredMedium):
+            raise TypeError("Diffusion requires a finite StructuredMedium.")
+
+        if not isinstance(source, UniformSurfaceSource):
+            raise TypeError("Diffusion requires SurfaceSource or UniformSurfaceSource.")
+
+        if medium.background is None:
+            raise ValueError("Configure the sample background before solving.")
+
+        materials = [
+            medium.background,
+            *(shape.material for shape in medium.structures),
+        ]
+
+        if any(
+            material.refractive_index != medium.background.refractive_index
+            for material in materials
+        ):
+            raise ValueError(
+                "Internal refractive-index jumps are not supported by this continuous-fluence FEM solver."
+            )
+
+        lower = medium.origin.to("m").magnitude
+
+        upper = (medium.origin + medium.size).to("m").magnitude
+
+        mesh_lower = mesh.origin.to("m").magnitude
+
+        mesh_upper = (
+            mesh_lower + (np.asarray(mesh.shape) - 1) * mesh.spacing.to("m").magnitude
+        )
+
+        if not np.allclose(
+            mesh_lower, lower, rtol=1e-12, atol=1e-15
+        ) or not np.allclose(mesh_upper, upper, rtol=1e-12, atol=1e-15):
+            raise ValueError(
+                "The mesh must span exactly the finite sample; use CartesianMesh.from_sample()."
+            )
+
+        condition = self.boundaries[source.face]
+
+        if not isinstance(condition, RobinBoundary):
+            raise ValueError("The illuminated face requires a RobinBoundary.")
+
+        if isinstance(source, SurfaceSource):
+            axis = "xyz".index(source.face[0])
+
+            position = source.position.to("m").magnitude
+
+            face_coordinate = (
+                lower[axis] if source.face.endswith("min") else upper[axis]
+            )
+
+            if not np.isclose(position[axis], face_coordinate, rtol=1e-12, atol=1e-15):
+                raise ValueError("Source position must lie on its configured face.")
+
+            in_plane = [i for i in range(3) if i != axis]
+
+            radius = source.radius.to("m").magnitude
+
+            if np.any(position[in_plane] - radius < lower[in_plane]) or np.any(
+                position[in_plane] + radius > upper[in_plane]
+            ):
+                raise ValueError("The entire illumination disk must fit on its face.")
+
+        points = mesh.points.to("m").magnitude.reshape(-1, 3)
+
+        tetrahedra = tetrahedralize(mesh=mesh)
+
+        volumes, gradients = element_geometry(points=points, tetrahedra=tetrahedra)
+
+        centers = points[tetrahedra].mean(axis=1)
+
+        labels = medium.material_labels(points=centers * ureg.meter)
+
+        absorption = np.array(
+            [material.absorption.to("1/m").magnitude for material in materials]
+        )[labels]
+
+        scattering = np.array(
+            [material.reduced_scattering.to("1/m").magnitude for material in materials]
+        )[labels]
+
+        coefficient = 1 / (3 * (absorption + scattering))
+
+        stiffness = (
+            volumes[:, None, None]
+            * coefficient[:, None, None]
+            * np.einsum("tik,tjk->tij", gradients, gradients)
+        )
+
+        mass = (
+            volumes[:, None, None]
+            * absorption[:, None, None]
+            * (np.ones((4, 4)) + np.eye(4))
+            / 20
+        )
+
+        rows = np.broadcast_to(tetrahedra[:, :, None], stiffness.shape).ravel()
+
+        columns = np.broadcast_to(tetrahedra[:, None, :], stiffness.shape).ravel()
+
+        row_blocks = [rows]
+
+        column_blocks = [columns]
+
+        data_blocks = [(stiffness + mass).ravel()]
+
+        faces = boundary_triangles(tetrahedra=tetrahedra, shape=mesh.shape)
+
+        nodal_leakage = {}
+
+        for face, triangles in faces.items():
+            areas = triangle_areas(points=points, triangles=triangles)
+
+            beta = self.boundaries[face].leakage_coefficient
+
+            boundary_mass = (
+                beta * areas[:, None, None] * (np.ones((3, 3)) + np.eye(3)) / 12
+            )
+
+            row_blocks.append(
+                np.broadcast_to(triangles[:, :, None], boundary_mass.shape).ravel()
+            )
+
+            column_blocks.append(
+                np.broadcast_to(triangles[:, None, :], boundary_mass.shape).ravel()
+            )
+
+            data_blocks.append(boundary_mass.ravel())
+
+            weights = np.zeros(len(points))
+
+            np.add.at(weights, triangles.ravel(), np.repeat(beta * areas / 3, 3))
+
+            nodal_leakage[face] = weights
+
+        matrix = coo_matrix(
+            (
+                np.concatenate(data_blocks),
+                (np.concatenate(row_blocks), np.concatenate(column_blocks)),
+            ),
+            shape=(len(points), len(points)),
+        ).tocsr()
+
+        local_load, sampled_area = source_load(
+            points=points, triangles=faces[source.face], source=source
+        )
+
+        load = np.zeros(len(points))
+
+        np.add.at(
+            load,
+            faces[source.face].ravel(),
+            local_load.ravel() * condition.source_factor,
+        )
+
+        values = spsolve(matrix, load)
+
+        if not np.all(np.isfinite(values)):
+            raise RuntimeError("The diffusion solve returned nonfinite fluence.")
+
+        relative_residual = np.linalg.norm(matrix @ values - load) / np.linalg.norm(
+            load
+        )
+
+        if relative_residual > 1e-8:
+            raise RuntimeError(
+                f"Diffusion linear residual is too large: {relative_residual:g}."
+            )
+
+        absorbed = np.sum(absorption * volumes * values[tetrahedra].mean(axis=1))
+
+        power = source.optical_power.to("W").magnitude
+
+        escaping = {
+            face: float(weights @ values) for face, weights in nodal_leakage.items()
+        }
+
+        # Remove the incident-field contribution to the gross Robin leakage.
+        # This distinguishes outgoing transmitted partial current from net current.
+        escaping[source.face] -= 2 * condition.leakage_coefficient * power
+
+        flux_values = -coefficient[:, None] * np.einsum(
+            "ti,tij->tj", values[tetrahedra], gradients
+        )
+
+        fluence = ScalarField(
+            mesh=mesh,
+            values=values.reshape(mesh.shape) * ureg.watt / ureg.meter**2,
+            name="Fluence rate",
+            metadata={
+                "transport": "steady-state tetrahedral P1 FEM diffusion",
+                "wavelength": source.wavelength,
+                "coefficient_sampling": "element centroid",
+                "source_face": source.face,
+            },
+        )
+
+        flux = VectorField(
+            positions=centers * ureg.meter,
+            values=flux_values * ureg.watt / ureg.meter**2,
+            name="Diffusive flux",
+        )
+
+        return SimulationResult(
+            fluence=fluence,
+            flux=flux,
+            energy_balance={
+                "incoming_power": source.optical_power,
+                "absorbed_power": absorbed * ureg.watt,
+                "escaping_power": sum(escaping.values()) * ureg.watt,
+                "residual_power": (power - absorbed - sum(escaping.values()))
+                * ureg.watt,
+            },
+            outgoing_power_by_face={
+                face: value * ureg.watt for face, value in escaping.items()
+            },
+            diagnostics={
+                "linear_relative_residual": relative_residual,
+                "source_quadrature_area": sampled_area * ureg.meter**2,
+                "tetrahedron_count": len(tetrahedra),
+                "minimum_fluence": values.min() * ureg.watt / ureg.meter**2,
+            },
+        )

momentrt-0.1.0/MomentRT/fem.py

@@ -0,0 +1,122 @@
+"""Linear tetrahedral FEM kernels on a conforming Cartesian subdivision."""
+
+from itertools import permutations
+
+import numpy as np
+
+
+def tetrahedralize(*, mesh):
+    """Split each voxel into six tetrahedra sharing its lower/upper diagonal."""
+    shape = np.asarray(mesh.shape)
+
+    cells = np.stack(
+        np.meshgrid(*(np.arange(n - 1) for n in shape), indexing="ij"), axis=-1
+    ).reshape(-1, 3)
+
+    tetrahedra = []
+
+    for order in permutations(range(3)):
+        offsets = np.zeros((4, 3), dtype=int)
+
+        for step, axis in enumerate(order, start=1):
+            offsets[step] = offsets[step - 1]
+
+            offsets[step, axis] += 1
+
+        indices = cells[:, None, :] + offsets
+
+        tetrahedra.append(np.ravel_multi_index(indices.transpose(2, 0, 1), shape))
+
+    return np.concatenate(tetrahedra)
+
+
+def element_geometry(*, points, tetrahedra):
+    vertices = points[tetrahedra]
+
+    edges = vertices[:, 1:] - vertices[:, :1]
+
+    volumes = np.abs(np.linalg.det(edges)) / 6
+
+    gradients = np.empty((len(tetrahedra), 4, 3))
+
+    gradients[:, 1:] = np.linalg.inv(edges).transpose(0, 2, 1)
+
+    gradients[:, 0] = -gradients[:, 1:].sum(axis=1)
+
+    return volumes, gradients
+
+
+def boundary_triangles(*, tetrahedra, shape):
+    candidates = np.concatenate(
+        [tetrahedra[:, face] for face in ([0, 1, 2], [0, 1, 3], [0, 2, 3], [1, 2, 3])]
+    )
+
+    unique, counts = np.unique(np.sort(candidates, axis=1), axis=0, return_counts=True)
+
+    triangles = unique[counts == 1]
+
+    indices = np.stack(np.unravel_index(triangles, shape), axis=-1)
+
+    faces = {}
+
+    for axis, name in enumerate("xyz"):
+        faces[f"{name}_min"] = triangles[np.all(indices[..., axis] == 0, axis=1)]
+
+        faces[f"{name}_max"] = triangles[
+            np.all(indices[..., axis] == shape[axis] - 1, axis=1)
+        ]
+
+    return faces
+
+
+def triangle_areas(*, points, triangles):
+    vertices = points[triangles]
+
+    return (
+        np.linalg.norm(
+            np.cross(vertices[:, 1] - vertices[:, 0], vertices[:, 2] - vertices[:, 0]),
+            axis=1,
+        )
+        / 2
+    )
+
+
+def source_load(*, points, triangles, source):
+    """Three-point triangle quadrature for the disk footprint and nodal load."""
+    from .source import SurfaceSource
+
+    barycentric = np.array(
+        [[2 / 3, 1 / 6, 1 / 6], [1 / 6, 2 / 3, 1 / 6], [1 / 6, 1 / 6, 2 / 3]]
+    )
+
+    quadrature = np.einsum("qa,tad->tqd", barycentric, points[triangles])
+
+    areas = triangle_areas(points=points, triangles=triangles)
+
+    selected = np.ones(quadrature.shape[:2], dtype=bool)
+
+    if isinstance(source, SurfaceSource):
+        axis = "xyz".index(source.face[0])
+
+        in_plane = [i for i in range(3) if i != axis]
+
+        displacement = (
+            quadrature[..., in_plane] - source.position.to("m").magnitude[in_plane]
+        )
+
+        selected = (
+            np.linalg.norm(displacement, axis=-1) <= source.radius.to("m").magnitude
+        )
+
+    sampled_area = np.sum(areas[:, None] * selected / 3)
+
+    if sampled_area == 0:
+        raise ValueError("The mesh does not resolve the source footprint; refine it.")
+
+    irradiance = source.optical_power.to("W").magnitude / sampled_area
+
+    local_load = (
+        irradiance * areas[:, None] * np.einsum("tq,qa->ta", selected / 3, barycentric)
+    )
+
+    return local_load, sampled_area