MomentRT 0.1.0__py3-none-any.whl

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/_version.py

@@ -0,0 +1,3 @@
+"""Package version shared with release metadata."""
+
+__version__ = version = "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/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/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

MomentRT/fields.py

@@ -0,0 +1,139 @@
+"""Unit-bearing nodal scalar fields with mesh-aware visualization."""
+
+import numpy as np
+
+from .units import ureg
+
+
+class ScalarField:
+    def __init__(self, *, mesh, values, name, metadata=None):
+        if not isinstance(values, ureg.Quantity):
+            raise TypeError("values must carry units.")
+
+        if values.shape != mesh.shape or not np.all(np.isfinite(values.magnitude)):
+            raise ValueError("Field values must be finite and match the mesh shape.")
+
+        self.mesh = mesh
+
+        self.values = values
+
+        self.name = name
+
+        self.metadata = dict(metadata or {})
+
+    def to_pyvista(self, *, length_unit="mm"):
+        grid = self.mesh.to_pyvista(length_unit=length_unit)
+
+        grid.point_data[self.name] = self.values.magnitude.ravel(order="F")
+
+        grid.field_data["value_units"] = [str(self.values.units)]
+
+        grid.field_data["coordinate_units"] = [length_unit]
+
+        grid.field_data["association"] = ["point"]
+
+        for key, value in self.metadata.items():
+            grid.field_data[key] = [str(value)]
+
+        return grid
+
+    def export(self, *, path, length_unit="mm"):
+        from pathlib import Path
+
+        if Path(path).suffix != ".vti":
+            raise ValueError("Cartesian fields must be exported with a .vti extension.")
+
+        grid = self.to_pyvista(length_unit=length_unit)
+
+        grid.save(path)
+
+    def plot(
+        self,
+        *,
+        view="slices",
+        scale="linear",
+        length_unit="mm",
+        show=True,
+    ):
+        from .plotting import plot_field
+
+        return plot_field(
+            field=self,
+            view=view,
+            scale=scale,
+            length_unit=length_unit,
+            show=show,
+        )
+
+
+class VectorField:
+    """Element-centered vectors, without smoothing across material interfaces."""
+
+    def __init__(self, *, positions, values, name):
+        from .units import validate_units
+
+        validate_units(value=positions, unit="m", name="positions")
+
+        if positions.ndim != 2 or positions.shape[1] != 3 or len(positions) == 0:
+            raise ValueError("positions must have shape (N, 3).")
+
+        if (
+            not isinstance(values, ureg.Quantity)
+            or values.shape != positions.shape
+            or not np.all(np.isfinite(values.magnitude))
+        ):
+            raise ValueError(
+                "values must be finite unit-bearing vectors matching positions."
+            )
+
+        self.positions = positions
+
+        self.values = values
+
+        self.name = name
+
+    def plot(self, *, max_vectors=500, length_unit="mm", show=True):
+        from .plotting import make_figure, require_plotly
+
+        if (
+            isinstance(max_vectors, bool)
+            or not isinstance(max_vectors, (int, np.integer))
+            or max_vectors < 1
+        ):
+            raise ValueError("max_vectors must be a positive integer.")
+
+        go = require_plotly()
+
+        selection = np.linspace(
+            0, len(self.values) - 1, min(max_vectors, len(self.values)), dtype=int
+        )
+
+        points = self.positions.to(length_unit).magnitude[selection]
+
+        vectors = self.values.magnitude[selection]
+
+        figure = make_figure(length_unit=length_unit)
+
+        figure.add_trace(
+            go.Cone(
+                x=points[:, 0],
+                y=points[:, 1],
+                z=points[:, 2],
+                u=vectors[:, 0],
+                v=vectors[:, 1],
+                w=vectors[:, 2],
+                colorscale="Viridis",
+                sizemode="scaled",
+                sizeref=0.25,
+                colorbar={"title": {"text": f"{self.name} [{self.values.units:~}]"}},
+            )
+        )
+
+        figure.update_layout(
+            title=f"{self.name} (element centers; relative arrow lengths)"
+        )
+
+        if show:
+            figure.show()
+
+        return figure