radphen-iadpython 0.7.0__py3-none-any.whl

iadpython/layer.py

@@ -0,0 +1,241 @@
+"""One layer of a multilayer sample.
+
+A :class:`Layer` bundles the optical properties of one slab in a stack.  The
+two independent axes of a simulation are kept structurally distinct:
+
+* **layer axis** -- the position of the ``Layer`` in the ``layers`` list passed
+  to :class:`iadpython.Sample`;
+* **wavelength axis** -- arrays *inside* each ``Layer`` attribute (``a``,
+  ``b``, ``g``, ``n`` may each be a scalar or a 1-D array over wavelengths;
+  a ``TABULATED`` phase function carries one ``pf_data`` column per
+  wavelength).
+
+A scalar attribute is automatically held constant (broadcast) across all
+wavelengths of the sweep, so layers with constant properties can be freely
+mixed with wavelength-dependent ones.
+
+Example::
+
+    >>> import iadpython as iad
+    >>> l0 = iad.Layer(a=0.95, b=0.84, g=0.20, n=1.35, d=0.10)
+    >>> l1 = iad.Layer(a=0.81, b=0.31, g=0.85, n=2.00, d=0.05)
+    >>> s = iad.Sample(layers=[l0, l1], quad_pts=16)
+    >>> ur1, ut1, uru, utu = s.rt()
+"""
+
+import numpy as np
+
+__all__ = ("Layer",)
+
+_PF_TYPES = ("HG", "TABULATED", "MOMENTS")
+
+
+def _as_scalar_or_1d(value, name):
+    """Return ``value`` unchanged if scalar, else as a 1-D float array.
+
+    Lists/tuples are converted to numpy arrays so downstream code can rely on
+    numpy semantics.  Anything with more than one dimension is rejected --
+    the wavelength axis is the only in-attribute axis a ``Layer`` carries.
+    """
+    if value is None or np.isscalar(value):
+        return value
+    arr = np.asarray(value)
+    if arr.ndim == 0:
+        return arr.item()
+    if arr.ndim > 1:
+        raise ValueError(
+            "Layer.%s must be a scalar or 1-D wavelength array, got shape %s"
+            % (name, arr.shape)
+        )
+    return arr
+
+
+def _fmt(value):
+    """Compact scalar-or-range formatting for repr (no iadpython imports)."""
+    if value is None:
+        return "None"
+    if np.isscalar(value) or np.ndim(value) == 0:
+        return "%.3f" % np.real(value)
+    arr = np.asarray(value)
+    return "%.3f..%.3f[%d]" % (np.real(arr.min()), np.real(arr.max()), arr.size)
+
+
+class Layer:
+    """Optical properties of one slab in a multilayer sample.
+
+    Attributes:
+        a: single-scattering albedo (scalar or wavelength array)
+        b: optical thickness (scalar or wavelength array)
+        g: scattering anisotropy, used when ``pf_type == 'HG'``
+           (scalar or wavelength array)
+        d: physical thickness [mm] (scalar; informational -- the radiative
+           transfer solve consumes ``b``, not ``d``)
+        n: refractive index (scalar or wavelength array)
+        pf_type: ``'HG'`` (Henyey-Greenstein, from ``g``), ``'TABULATED'``
+           (from ``pf_data``), or ``'MOMENTS'`` (from ``pf_data``)
+        pf_data: for ``'TABULATED'``, a pandas ``DataFrame`` indexed by
+           mu = cos(theta) with one column per wavelength (a single column
+           is broadcast across the sweep). For ``'MOMENTS'``, a plain
+           ndarray of Legendre moments a_l -- 1-D ``(n_mom,)`` (broadcast
+           across the sweep) or 2-D ``(n_mom, n_wavelength)`` -- supplied
+           directly instead of a tabulated phase function, bypassing the
+           spline+quadrature step ``'TABULATED'`` requires. Required when
+           ``pf_type`` is ``'TABULATED'`` or ``'MOMENTS'``.
+
+    Cross-layer consistency (matching wavelength counts, physical ranges) is
+    checked at solve time by ``validate_layers`` so partially built layers can
+    be edited freely before use.
+
+    Note on ``pf_type='MOMENTS'`` in a mismatched-refractive-index stack:
+    unlike ``'TABULATED'`` (a continuous curve that can be re-integrated to
+    any order on demand), a MOMENTS array is a fixed, finite set of
+    precomputed numbers. The mismatched-index solver's internal master grid
+    may need a *larger* effective quadrature order for some sub-layers than
+    the Sample's own ``quad_pts`` -- so a MOMENTS array sized only for the
+    nominal ``quad_pts`` can raise "needs at least N moments" partway
+    through a solve. Supply generously more moments than ``2*quad_pts+1``
+    when index-mismatched layers are involved.
+    """
+
+    def __init__(self, a=0, b=1, g=0, d=1, n=1, pf_type="HG", pf_data=None):
+        """Create one layer; see class docstring for attribute meanings."""
+        self.a = _as_scalar_or_1d(a, "a")
+        self.b = _as_scalar_or_1d(b, "b")
+        self.g = _as_scalar_or_1d(g, "g")
+        self.n = _as_scalar_or_1d(n, "n")
+        self.d = d
+
+        self.pf_type = str(pf_type).upper()
+        if self.pf_type not in _PF_TYPES:
+            raise ValueError(
+                "Layer pf_type must be one of %s, got %r" % (_PF_TYPES, pf_type)
+            )
+        if self.pf_type == "TABULATED":
+            # duck-typed DataFrame check to keep this module pandas-free
+            if pf_data is None or not hasattr(pf_data, "iloc"):
+                raise TypeError(
+                    "pf_type='TABULATED' requires pf_data to be a pandas "
+                    "DataFrame (index = cos(theta), one column per wavelength)"
+                )
+        elif self.pf_type == "MOMENTS":
+            # Legendre moments a_l, bypassing TABULATED's spline+quadrature.
+            # Explicitly reject DataFrame-like input -- np.asarray(df) would
+            # otherwise silently coerce it instead of failing loudly.
+            if pf_data is None or hasattr(pf_data, "iloc"):
+                raise TypeError(
+                    "pf_type='MOMENTS' requires pf_data to be a plain array "
+                    "of Legendre moments (1-D), or a 2-D array (n_mom, "
+                    "n_wavelength) for a wavelength sweep -- not a DataFrame"
+                )
+            pf_data = np.asarray(pf_data, dtype=float)
+            if pf_data.ndim not in (1, 2):
+                raise ValueError(
+                    "MOMENTS pf_data must be 1-D (n_mom,) or 2-D (n_mom, "
+                    "n_wavelength), got shape %s" % (pf_data.shape,)
+                )
+        self.pf_data = pf_data
+
+    def n_wavelengths(self):
+        """Number of wavelengths this layer's own data spans (1 if scalar)."""
+        counts = [1]
+        for value in (self.a, self.b, self.g, self.n):
+            if not (value is None or np.isscalar(value) or np.ndim(value) == 0):
+                counts.append(len(value))
+        if self.pf_type == "TABULATED" and self.pf_data is not None:
+            counts.append(self.pf_data.shape[1])
+        if self.pf_type == "MOMENTS" and self.pf_data is not None and self.pf_data.ndim == 2:
+            counts.append(self.pf_data.shape[1])
+        return max(counts)
+
+    def __repr__(self):
+        """Compact one-line description."""
+        s = "Layer(a=%s, b=%s, g=%s, n=%s, d=%s, pf=%s" % (
+            _fmt(self.a),
+            _fmt(self.b),
+            _fmt(self.g),
+            _fmt(self.n),
+            _fmt(self.d),
+            self.pf_type,
+        )
+        if self.pf_type == "TABULATED" and self.pf_data is not None:
+            s += "[%d col]" % self.pf_data.shape[1]
+        if self.pf_type == "MOMENTS" and self.pf_data is not None:
+            if self.pf_data.ndim == 2:
+                s += "[%d mom x %d col]" % self.pf_data.shape
+            else:
+                s += "[%d mom]" % self.pf_data.shape[0]
+        return s + ")"
+
+
+def validate_layers(layers):
+    """Check a list of layers for cross-layer consistency.
+
+    Determines the wavelength count of the sweep as the maximum over every
+    layer's array lengths and ``pf_data`` column counts, then verifies that
+    each per-layer axis is compatible with it (length 1 broadcasts).
+
+    Args:
+        layers: sequence of :class:`Layer` objects (at least one)
+
+    Returns:
+        n_wavelengths: the number of wavelengths of the sweep (>= 1)
+
+    Raises:
+        RuntimeError: on empty input, non-Layer entries, conflicting
+            wavelength counts, or out-of-range ``a``/``b`` values.
+    """
+    if layers is None or len(layers) == 0:
+        raise RuntimeError("Sample(layers=...) needs at least one Layer")
+
+    for k, layer in enumerate(layers):
+        if not isinstance(layer, Layer):
+            raise RuntimeError(
+                "layers[%d] is %s, expected iadpython.Layer" % (k, type(layer).__name__)
+            )
+
+    n_wave = max(layer.n_wavelengths() for layer in layers)
+
+    for k, layer in enumerate(layers):
+        for name in ("a", "b", "g", "n"):
+            value = getattr(layer, name)
+            if value is None or np.isscalar(value) or np.ndim(value) == 0:
+                continue
+            if len(value) not in (1, n_wave):
+                raise RuntimeError(
+                    "layers[%d].%s has %d wavelengths but the stack sweep "
+                    "has %d (lengths must be 1 or match)"
+                    % (k, name, len(value), n_wave)
+                )
+
+        if not (np.isscalar(layer.d) or np.ndim(layer.d) == 0):
+            raise RuntimeError(
+                "layers[%d].d must be a scalar physical thickness "
+                "(wavelength-dependent d is not meaningful)" % k
+            )
+
+        if layer.pf_type == "TABULATED":
+            ncols = layer.pf_data.shape[1]
+            if ncols not in (1, n_wave):
+                raise RuntimeError(
+                    "layers[%d].pf_data has %d columns but the stack sweep "
+                    "has %d wavelengths (columns must be 1 or match)"
+                    % (k, ncols, n_wave)
+                )
+
+        if layer.pf_type == "MOMENTS" and layer.pf_data.ndim == 2:
+            ncols = layer.pf_data.shape[1]
+            if ncols not in (1, n_wave):
+                raise RuntimeError(
+                    "layers[%d].pf_data has %d columns but the stack sweep "
+                    "has %d wavelengths (columns must be 1 or match)"
+                    % (k, ncols, n_wave)
+                )
+
+        a_arr = np.atleast_1d(layer.a).astype(float)
+        b_arr = np.atleast_1d(layer.b).astype(float)
+        if np.any(a_arr < 0) or np.any(a_arr > 1):
+            raise RuntimeError("layers[%d].a must lie in [0, 1]" % k)
+        if np.any(b_arr < 0):
+            raise RuntimeError("layers[%d].b must be non-negative" % k)
+
+    return n_wave

iadpython/nist.py

@@ -0,0 +1,114 @@
+"""Module for importing reflection spectra from NIST database.
+
+Example::
+
+    >>> import numpy as np
+    >>> import matplotlib.pyplot as plt
+    >>> import iadpython as iad
+
+    >>> # Retrieve and plot subject 5
+
+    >>> subject_number = 5
+    >>> lambda0, R = iad.subject_average_reflectance(subject_number)
+    >>> plt.plot(lambda0, R)
+    >>> plt.xlabel("Wavelength (nm)")
+    >>> plt.ylabel("Total Reflectance")
+    >>> plt.title("Subject #%d" % subject_number)
+    >>> plt.show()
+
+    >>> # Retrieve and plot all subjects
+
+    >>> lambda0, R = iad.all_average_reflectances()
+    >>> for i in range(100):
+    >>>     plt.plot(lambda0, R[:, i])
+    >>> plt.xlabel("Wavelength (nm)")
+    >>> plt.ylabel("Total Reflectance")
+    >>> plt.title("All Subjects")
+    >>> plt.show()
+
+Reference:
+    <https://nvlpubs.nist.gov/nistpubs/jres/122/jres.122.026.pdf>
+    nist_db = 'https://doi.org/10.18434/M38597'
+"""
+
+import os
+import numpy as np
+
+__all__ = (
+    "subject_reflectances",
+    "subject_average_reflectance",
+    "all_average_reflectances",
+)
+
+
+def get_subject_data(cols):
+    """
+    Load and return data from a CSV file based on specified columns.
+
+    This function reads data from a CSV file located in the 'data' directory relative
+    to the script's location and allows you to specify the columns to extract.
+
+    Args:
+        cols: A tuple of column indices to extract from the CSV file.
+
+    Returns:
+        An array containing the requested data.
+
+    Example:
+        To extract columns 1 and 2 from the CSV file, you can call the function like this:
+        >>> cols_to_extract = (1, 2)
+        >>> data = get_subject_data(cols_to_extract)
+    """
+    script_dir = os.path.dirname(__file__)  # Path to directory of this file
+    data_file_path = os.path.join(script_dir, "data", "M38597.csv")
+    data = np.loadtxt(data_file_path, skiprows=8, usecols=cols, delimiter=",", encoding="latin1")
+    return data
+
+
+def subject_reflectances(subject_number):
+    """Extract all reflection data for one subject."""
+    if subject_number <= 0 or subject_number > 100:
+        raise ValueError("subject_number must be 1 to 100")
+
+    col = (subject_number - 1) * 4 + 1
+
+    cols = (0, col, col + 1, col + 2, col + 3)
+
+    data = get_subject_data(cols)
+
+    lambda0 = data[:, 0]
+    r_1 = data[:, 1]
+    r_2 = data[:, 2]
+    r_3 = data[:, 3]
+    r_ave = data[:, 4]
+
+    return lambda0, r_1, r_2, r_3, r_ave
+
+
+def subject_average_reflectance(subject_number):
+    """Extract average reflection for one subject."""
+    if subject_number <= 0 or subject_number > 100:
+        raise ValueError("subject_number must be 1 to 100")
+
+    col = (subject_number - 1) * 4 + 4
+
+    cols = (0, col)
+
+    data = get_subject_data(cols)
+
+    lambda0 = data[:, 0]
+    r_ave = data[:, 1]
+
+    return lambda0, r_ave
+
+
+def all_average_reflectances():
+    """Extract average reflectance for all subjects."""
+    cols = [4 * i for i in range(101)]
+
+    data = get_subject_data(cols)
+
+    lambda0 = data[:, 0]
+    r_ave = data[:, 1:]
+
+    return lambda0, r_ave

iadpython/port.py

@@ -0,0 +1,242 @@
+# pylint: disable=protected-access)
+"""
+Implementation of container class for an integrating sphere port.
+
+This module defines the Port class, which is integral to the analysis of light properties
+within an integrating sphere. The Port class specifically models a port on the sphere's
+surface, calculating and storing its geometrical properties and its interaction with light.
+
+Classes:
+    Port: Represents a port in an integrating sphere. It holds information about
+    the port's dimensions, position, and optical properties. The class provides
+    methods to calculate the port's geometrical characteristics, such as the
+    area of the spherical cap it forms, its sagitta, and the chord distance from
+    the port's center to its edge. Additionally, it includes functionality to
+    assess whether a given point on the sphere's surface falls within the port's
+    boundaries.
+
+Functions:
+    - cap_area_exact: Calculates the area of the spherical cap formed by the port.
+    - relative_cap_area: Calculates the approximate relative area of the spherical cap.
+    - calculate_sagitta: Determines the sagitta (or height) of the spherical cap.
+    - max_center_chord: Computes the maximum distance from the port's center to its edge.
+    - cap_area_exact: Calculates the exact relative area of the spherical cap.
+    - hit: Checks if a point on the sphere falls within the port's boundaries.
+
+Example:
+    >>> import iadpython as iad
+    >>> sphere = iad.Sphere(200, 20)  # Example of creating a sphere object
+    >>> port = Port(sphere, 20, 0.5, 0, 0, 0)
+    >>> print(port)
+
+See Also:
+    Sphere: Another class/module within the iadpython package that models the entire integrating sphere.
+"""
+
+import random
+import numpy as np
+import iadpython as iad
+
+
+def uniform_disk():
+    """
+    Generate a point uniformly distributed on a unit disk.
+
+    This function generates and returns a point (x, y) that is uniformly distributed
+    over the area of a unit disk centered at the origin (0, 0). The unit disk is
+    defined as the set of all points (x, y) such that x^2 + y^2 <= 1. The method
+    uses rejection sampling, where random points are generated within the square
+    that bounds the unit disk, and only points that fall within the disk are accepted.
+
+    Returns:
+        tuple of (float, float, float): A point (x, y) where x and y are the
+        coordinates of the point uniformly distributed within the unit disk,
+        and s is the square of the distance from the origin to this point.
+    """
+    s = 2
+    while s > 1:
+        x = 2 * random.random() - 1
+        y = 2 * random.random() - 1
+        s = x * x + y * y
+    return x, y, s
+
+
+class Port:
+    """
+    Container class for a port on an integrating sphere.
+
+    A container class for a port in an integrating sphere, which is a structure
+    used to analyze light properties. The class calculates and stores various
+    geometrical properties of the port, such as its diameter, position, and the
+    relative area of the spherical cap it forms on the sphere's surface.
+
+    Attributes:
+        sphere (object): Reference to the sphere the port belongs to.
+        d (float): Diameter of the port in millimeters (mm).
+        uru (float): Diffuse reflectance of diffuse light on the port.
+        x (float): X-coordinate of the port's center on the sphere's surface.
+        y (float): Y-coordinate of the port's center on the sphere's surface.
+        z (float): Z-coordinate of the port's center on the sphere's surface.
+        a (float): Relative area of the port's spherical cap to the sphere's surface.
+        chord2 (float): Square of the distance from the port center to the port edge.
+        sagitta (float): The sagitta (height) of the spherical cap formed by the port.
+
+    Examples:
+        Importing the module and creating a sphere with a port:
+
+        ```python
+        import iadpython as iad
+        s = iad.Sphere(200, 20)
+        print(s.sample)
+    """
+
+    def __init__(self, sphere, d, uru=0, x=0, y=0, z=0):
+        """
+        Initializes a Port object with specified dimensions and position within a sphere.
+
+        The coordinates (x,y,z) indicate the center of the port and must be located
+        on the sphere surface.  They default to the center of the sphere (0,0,0).  The
+        cap location is only used by the `MCSphere` class which uses the `hit()`
+        method.
+
+        Args:
+            sphere: The sphere object to which the port belongs.
+            d: Diameter of the port in millimeters.
+            uru: Diffuse reflectance of diffuse light on the port.
+            x: X-coordinate of the port's center on the sphere's surface.
+            y: Y-coordinate of the port's center on the sphere's surface.
+            z: Z-coordinate of the port's center on the sphere's surface.
+        """
+        self.sphere = sphere
+        self._d = d
+        self.uru = uru
+
+        self.x = x
+        self.y = y
+        self.z = z
+
+        self.a = self.relative_cap_area()
+        self.sagitta = self.calculate_sagitta()
+        self.chord2 = self.max_center_chord() ** 2
+
+    def __repr__(self):
+        """Short string for port."""
+        return "d=%5.1fmm, uru=%s\n" % (
+            self.d,
+            iad.stringify("%5.1f%%", self.uru * 100),
+        )
+
+    def __str__(self):
+        """Return basic details as a string for printing."""
+        s = ""
+        s += "        diameter = %7.2f mm\n" % self.d
+        s += "          radius = %7.2f mm\n" % (self.d / 2)
+        s += "           chord = %7.2f mm\n" % np.sqrt(self.chord2)
+        s += "         sagitta = %7.2f mm\n" % self.sagitta
+        s += "          center = (%6.1f, %6.1f, %6.1f) mm\n" % (self.x, self.y, self.z)
+        s += "   relative area = %7.2f%%\n" % (self.a * 100)
+        s += "             uru = %s\n" % iad.stringify("%5.1f%%", self.uru * 100)
+        return s
+
+    @property
+    def d(self):
+        """float: Gets the diameter of the port."""
+        return self._d
+
+    @d.setter
+    def d(self, value):
+        """
+        Sets the diameter of the port and recalculates geometrical properties.
+
+        Args:
+            value (float): The new diameter of the port.
+
+        Raises:
+            AssertionError: If the new diameter exceeds the diameter of the sphere.
+        """
+        assert self.sphere.d >= value, "Sphere must be bigger than the port."
+        self._d = value
+        self.a = self.relative_cap_area()
+        self.sagitta = self.calculate_sagitta()
+        self.chord2 = self.max_center_chord()
+        self.sphere._a_wall = 1 - self.sphere.sample.a - self.sphere.third.a - self.sphere.detector.a
+
+    def cap_area(self):
+        """Approximate area of spherical cap."""
+        return np.pi * self.d**2 / 4
+
+    def cap_area_exact(self):
+        """Exact area of spherical cap."""
+        R = self.sphere.d / 2
+        r = self.d / 2
+        h = R - np.sqrt(R**2 - r**2)
+        return 2 * np.pi * R * h
+
+    def relative_cap_area(self):
+        """Calculate approx relative area of spherical cap."""
+        R = self.sphere.d / 2
+        r = self.d / 2
+        return r**2 / (4 * R**2)
+
+    def calculate_sagitta(self):
+        """Calculate sagitta of spherical cap."""
+        R = self.sphere.d / 2
+        r = self.d / 2
+        return R - np.sqrt(R**2 - r**2)
+
+    def max_center_chord(self):
+        """Distance of chord from port center (on sphere) to port edge."""
+        r = self.d / 2
+        s = self.sagitta
+        return np.sqrt(r**2 + s**2)
+
+    def relative_cap_area_exact(self):
+        """Calculate relative area of spherical cap."""
+        h = (self.sphere.d - np.sqrt(self.sphere.d**2 - self.d**2)) / 2
+        return h / self.sphere.d
+
+    def hit(self):
+        """Determine if point on the sphere within the port."""
+        r2 = (self.x - self.sphere.x) ** 2
+        r2 += (self.y - self.sphere.y) ** 2
+        r2 += (self.z - self.sphere.z) ** 2
+        #        print('cap center (%7.2f, %7.2f, %7.2f)' % (self.x,self.y,self.z))
+        #        print('pt on sph  (%7.2f, %7.2f, %7.2f)' % (self.sphere.x,self.sphere.y,self.sphere.z))
+        #        print("cap distance %7.2f %7.2f"% (r2, self.chord2))
+        return r2 < self.chord2
+
+    def set_center(self, x, y, z):
+        """Centers the cap at x,y,z."""
+        assert x**2 + y**2 + z**2 - (self.sphere.d / 2) ** 2 < 1e-6, "center not on sphere."
+        self.x = x
+        self.y = y
+        self.z = z
+
+    def uniform(self):
+        """
+        Generate a point uniformly distributed on a spherical cap.
+
+        This function generates points uniformly distributed over a spherical cap,
+        defined by a specified sagitta (height of the cap from its base to the top)
+        and sphere radius. The spherical cap can be positioned either at the top or
+        bottom of the sphere. The method utilizes principles from uniform distribution
+        on a disk and transforms these points to the spherical cap geometry.
+
+        WARNING: The cap assumed to be at the top of a sphere. Nothing is done to rotate
+        the points so they align with the center of the cap!
+
+        The algorithm to generate a random point on a spherical cap is adapted from
+        http://marc-b-reynolds.github.io/distribution/2016/11/28/Uniform.html
+
+        Args:
+            sagitta: The height of the spherical cap from its base to the top.
+            sphere_radius: The radius of the sphere with the cap.
+
+        Returns:
+            A numpy array of a random point on the spherical cap surface.
+        """
+        h = self.sagitta / (self.sphere.d / 2)
+        ux, uy, s = uniform_disk()
+        root = np.sqrt(h * (2 - h * s))
+        point = np.array([ux * root, uy * root, 1 - h * s]) * (self.sphere.d / 2)
+        return point