radphen-iadpython 0.7.0__py3-none-any.whl

iadpython/iad.py

@@ -0,0 +1,615 @@
+"""Class for doing inverse adding-doubling calculations for a sample.
+
+Example::
+
+    >>> import iadpython as iad
+
+    >>> exp = iad.Experiment(0.5,0.1,0.01)
+    >>> a, b, g = exp.invert()
+    >>> print("a = %7.3f" % a)
+    >>> print("b = %7.3f" % b)
+    >>> print("g = %7.3f" % g)
+
+    >>> s = iad.Sample(0.5,0.1,0.01,n=1.4, n_top=1.5, n_bottom=1.5)
+    >>> exp = iad.Experiment(s)
+    >>> a, b, g = exp.invert()
+    >>> print("a = %7.3f" % a)
+    >>> print("b = %7.3f" % b)
+    >>> print("g = %7.3f" % g)
+"""
+
+import sys
+import copy
+import numpy as np
+import scipy.optimize
+import iadpython as iad
+
+G_BOUND_EPS = 1e-6
+
+
+class Experiment:
+    """Container class for details of an experiment."""
+
+    def __init__(
+        self,
+        r=None,
+        t=None,
+        u=None,
+        sample=None,
+        r_sphere=None,
+        t_sphere=None,
+        num_spheres=0,
+        default_a=None,
+        default_b=None,
+        default_g=None,
+    ):
+        """Object initialization."""
+        if sample is None:
+            self.sample = iad.Sample()
+        else:
+            self.sample = sample
+
+        self.r_sphere = r_sphere
+        self.t_sphere = t_sphere
+        self.num_spheres = num_spheres
+
+        self.m_r = r
+        self.m_t = t
+        self.m_u = u
+        self.lambda0 = None
+
+        # these will have to be eventually supported
+        self.d_beam = 1
+        self.lambda0 = None
+
+        self.flip_sample = False
+        self.fraction_of_rc_in_mr = 1
+        self.fraction_of_tc_in_mt = 1
+        self.f_r = 0.0
+
+        self.ur1_lost = 0
+        self.uru_lost = 0
+        self.ut1_lost = 0
+        self.utu_lost = 0
+
+        self.default_a = default_a
+        self.default_b = default_b
+        self.default_g = default_g
+        self.default_ba = None
+        self.default_bs = None
+        self.default_mua = None
+        self.default_mus = None
+
+        self.search = "unknown"
+        self.metric = 1
+        self.tolerance = 0.0001
+        self.MC_tolerance = 0.01
+        self.final_distance = 1
+        self.iterations = 1
+        self.error = 1
+        self.num_measurements = 0
+        self.grid = None
+        self.method = "unknown"
+        self.debug_level = 0
+        self.max_mc_iterations = 19
+        self.n_photons = 100000
+        self.use_adaptive_grid = True
+        self.adaptive_grid_tol = 0.03
+        self.adaptive_grid_max_depth = 6
+        self.counter = 0
+        self.include_measurements = True
+
+    def __str__(self):
+        """Return basic details as a string for printing."""
+        s = "---------------- Sample ---------------\n"
+        s += self.sample.__str__()
+        s += "\n--------------- Spheres ---------------\n"
+        if not np.isscalar(self.num_spheres):
+            s += "number of spheres range (%s)\n" % iad.stringify("%d", self.num_spheres)
+        elif self.num_spheres == 0:
+            s += "No spheres used.\n"
+        elif self.num_spheres == 1:
+            s += "A single integrating sphere was used.\n"
+        elif self.num_spheres == 2:
+            s += "Double integrating spheres were used.\n"
+        if self.r_sphere is not None:
+            s += "Reflectance Sphere--------\n"
+            s += self.r_sphere.__str__()
+        if self.t_sphere is not None:
+            s += "Transmission Sphere--------\n"
+            s += self.t_sphere.__str__()
+
+        if self.include_measurements:
+            s += "\n------------- Measurements ------------\n"
+            s += "   Reflection               = "
+            s += iad.stringify("%.5f", self.m_r) + "\n"
+            s += "   Transmission             = "
+            s += iad.stringify("%.5f", self.m_t) + "\n"
+            s += "   Unscattered Transmission = "
+            s += iad.stringify("%.5f", self.m_u) + "\n"
+        return s
+
+    def check_measurements(self):
+        """Make sure measurements are sane."""
+        between = " Must be between 0 and 1."
+        if (
+            not (self.m_r is None or np.isscalar(self.m_r))
+            or not (self.m_t is None or np.isscalar(self.m_t))
+            or not (self.m_u is None or np.isscalar(self.m_u))
+        ):
+            raise ValueError("invert_scalar_rt() is only for scalar m_r, m_t, m_u")
+
+        if self.m_r is not None:
+            if self.m_r < 0 or self.m_r > 1:
+                raise ValueError("Invalid refl. %.4f" % self.m_r + between)
+
+        if self.m_t is not None:
+            if self.m_t < 0 or self.m_t > 1:
+                raise ValueError("Invalid trans. %.4f" % self.m_t + between)
+
+        if self.m_u is not None:
+            if self.m_u < 0 or self.m_u > 1:
+                raise ValueError("Invalid unscattered trans. %.4f." % self.m_u + between)
+
+    def useful_measurements(self):
+        """Count the number of useful measurements."""
+        self.num_measurements = 0
+        if self.m_r is not None:
+            self.num_measurements += 1
+        if self.m_t is not None:
+            self.num_measurements += 1
+        if self.m_u is not None:
+            self.num_measurements += 1
+
+    def determine_one_parameter_search(self):
+        """Establish proper search when only one measurement is available."""
+        # default case
+        self.search = "find_a"
+
+        # albedo is known
+        if self.default_a is not None:
+            if self.default_b is None:
+                self.search = "find_b"
+            else:
+                self.search = "find_g"
+
+        # optical thickness is known
+        elif self.default_b is not None:
+            self.search = "find_a"
+
+        # anisotropy is known
+        elif self.default_g is not None:
+            self.search = "find_a"
+
+        # scattering coefficient is known
+        elif self.default_bs is not None:
+            self.search = "find_ba"
+
+        # absorption coefficient is known
+        elif self.default_ba is not None:
+            self.search = "find_bs"
+
+    def determine_two_parameter_search(self):
+        """Establish proper search when 2 or 3 measurements are available."""
+        # albedo is known
+        if self.default_a is not None:
+            self.search = "find_bg"
+
+        # optical thickness is known
+        elif self.default_b is not None:
+            self.search = "find_ag"
+
+        # anisotropy is known
+        elif self.default_g is not None:
+            self.search = "find_ab"
+
+        # scattering coefficient is known
+        elif self.default_bs is not None:
+            self.search = "find_bag"
+
+        # absorption coefficient is known
+        elif self.default_ba is not None:
+            self.search = "find_bsg"
+
+        # by this point, assume that M_R, M_T, and M_U are known
+        else:
+            if self.m_u is None or self.m_u <= 0:
+                self.search = "find_ab"
+            else:
+                self.search = "find_ag"
+
+    def determine_search(self):
+        """Determine type of search to do."""
+        if self.num_measurements == 0:
+            self.search = "unknown"
+
+        if self.num_measurements == 1:
+            self.determine_one_parameter_search()
+
+        else:
+            self.determine_two_parameter_search()
+
+    def invert_scalar_rt(self, verbose = False):
+        """Find a,b,g for a single experimental measurement.
+
+        This routine assumes that `m_r`, `m_t`, and `m_u` are scalars.
+
+        Parameters:
+            verbose: if True, print progress. Default is True.
+
+        Returns:
+            - `a` is the single scattering albedo of the slab
+            - `b` is the optical thickness of the slab
+            - `g` is the anisotropy of single scattering
+        """
+        self.check_measurements()
+        self.useful_measurements()
+        self.determine_search()
+
+        if self.m_r is None and self.m_t is None and self.m_u is None:
+            return None, None, None
+
+        # assign default values
+        self.sample.a = self.default_a or 0
+        self.sample.b = self.default_b or self.what_is_b()
+        self.sample.g = self.default_g or 0
+
+        #        print('search is', self.search)
+        #        print('     a = ', self.sample.a)
+        #        print('     b = ', self.sample.b)
+        #        print('     g = ', self.sample.g)
+
+        if self.search == "find_a":
+            _ = scipy.optimize.minimize_scalar(afun, args=(self), bounds=(0, 1), method="bounded")
+
+        if self.search == "find_b":
+            _ = scipy.optimize.minimize_scalar(bfun, args=(self), method="brent")
+
+        if self.search == "find_g":
+            _ = scipy.optimize.minimize_scalar(
+                gfun,
+                args=(self),
+                bounds=(-1 + G_BOUND_EPS, 1 - G_BOUND_EPS),
+                method="bounded",
+            )
+
+        if self.search in ["find_ab", "find_ag", "find_bg"]:
+
+            if self.grid is None:
+                if self.use_adaptive_grid:
+                    self.grid = iad.AGrid(tol=self.adaptive_grid_tol, max_depth=self.adaptive_grid_max_depth)
+                else:
+                    self.grid = iad.Grid()
+
+            if self.use_adaptive_grid and not isinstance(self.grid, iad.AGrid):
+                self.grid = iad.AGrid(tol=self.adaptive_grid_tol, max_depth=self.adaptive_grid_max_depth)
+            if not self.use_adaptive_grid and isinstance(self.grid, iad.AGrid):
+                self.grid = iad.Grid()
+
+            # the grids are two-dimensional, one value is held constant
+            grid_constant = None
+            if self.search == "find_ag":
+                grid_constant = self.sample.b
+            if self.search == "find_bg":
+                grid_constant = self.sample.a
+            if self.search == "find_ab":
+                grid_constant = self.sample.g
+
+            if isinstance(self.grid, iad.AGrid):
+                if self.grid.is_stale(grid_constant, search=self.search):
+                    self.grid.calc(self, default=grid_constant, search=self.search)
+            else:
+                if self.grid.is_stale(grid_constant):
+                    self.grid.calc(self, grid_constant)
+
+            a, b, g = self.grid.min_abg(self.m_r, self.m_t)
+            if verbose:
+                print('grid constant %8.5f' % grid_constant)
+
+                print('grid start a=%8.5f' % a)
+                print('grid start b=%8.5f' % b)
+                print('grid start g=%8.5f' % g)
+
+        if self.search == 'find_ab':
+            x = scipy.optimize.Bounds(np.array([0, 0]), np.array([1, np.inf]))
+            result = scipy.optimize.minimize(abfun, [a, b], args=(self), bounds=x, method="Nelder-Mead")
+            self._refine_two_parameter_fit(result.x, ("a", "b"), x)
+
+        if self.search == "find_ag":
+            x = scipy.optimize.Bounds(
+                np.array([0, -1 + G_BOUND_EPS]),
+                np.array([1, 1 - G_BOUND_EPS]),
+            )
+            result = scipy.optimize.minimize(agfun, [a, g], args=(self), bounds=x, method="Nelder-Mead")
+            self._refine_two_parameter_fit(result.x, ("a", "g"), x)
+
+        if self.search == "find_bg":
+            x = scipy.optimize.Bounds(
+                np.array([0, -1 + G_BOUND_EPS]),
+                np.array([np.inf, 1 - G_BOUND_EPS]),
+            )
+            result = scipy.optimize.minimize(bgfun, [b, g], args=(self), bounds=x, method="Nelder-Mead")
+            self._refine_two_parameter_fit(result.x, ("b", "g"), x)
+
+        return self.sample.a, self.sample.b, self.sample.g
+
+    def _refine_two_parameter_fit(self, values, names, bounds):
+        """Refine a stalled L1 fit, retaining only a smaller measured residual.
+
+        At conservative-albedo boundaries, R+T is constant and the L1
+        objective can have a flat plateau. A bounded residual-vector fit can
+        leave that plateau even when Nelder-Mead reports successful convergence.
+        Always restore the selected parameters after optimizer trial evaluations.
+        """
+        def residual(parameters):
+            for name, value in zip(names, parameters):
+                setattr(self.sample, name, value)
+            measured = self.measured_rt()
+            return np.asarray(measured) - np.asarray((self.m_r, self.m_t))
+
+        selected = np.asarray(values, dtype=float).copy()
+        distance = np.sum(np.abs(residual(selected)))
+        if distance > self.tolerance:
+            candidate = scipy.optimize.least_squares(
+                residual, selected, bounds=(bounds.lb, bounds.ub)
+            )
+            if np.all(np.isfinite(candidate.x)):
+                candidate_distance = np.sum(np.abs(residual(candidate.x)))
+                if np.isfinite(candidate_distance) and candidate_distance < distance:
+                    selected = candidate.x
+
+        for name, value in zip(names, selected):
+            setattr(self.sample, name, value)
+
+    def print_dot(self):
+        """Print a character for each datapoint during analysis."""
+        self.counter += 1
+        if self.counter % 50 == 0:
+            print(file=sys.stderr)
+        print(".", end="", file=sys.stderr)
+        sys.stderr.flush()
+
+    def invert_rt(self, verbose=False):
+        """Find a,b,g for experimental measurements.
+
+        This method works if `m_r`, `m_t`, and `m_u` are scalars or arrays.
+
+        Parameters:
+            verbose: if True, print progress. Default is True.
+
+        Returns:
+            - `a` is the single scattering albedo of the slab
+            - `b` is the optical thickness of the slab
+            - `g` is the anisotropy of single scattering
+        """
+        if self.m_r is None and self.m_t is None and self.m_u is None:
+            return self.invert_scalar_rt()
+
+        # any scalar measurement indicates a single data point
+        if np.isscalar(self.m_r) or np.isscalar(self.m_t) or np.isscalar(self.m_u):
+            return self.invert_scalar_rt()
+
+        # figure out the number of points that we need to invert
+        if self.m_r is not None:
+            N = len(self.m_r)
+        elif self.m_t is not None:
+            N = len(self.m_t)
+        else:
+            N = len(self.m_u)
+
+        a = np.zeros(N)
+        b = np.zeros(N)
+        g = np.zeros(N)
+
+        x = copy.deepcopy(self)
+        x.m_r = None
+        x.m_t = None
+        x.m_u = None
+
+        for i in range(N):
+            if self.m_r is not None:
+                x.m_r = self.m_r[i]
+            if self.m_t is not None:
+                x.m_t = self.m_t[i]
+            if self.m_u is not None:
+                x.m_u = self.m_u[i]
+            a[i], b[i], g[i] = x.invert_scalar_rt(verbose = verbose)
+            if verbose:
+                self.print_dot()
+
+        print(file=sys.stderr)
+        return a, b, g
+
+    def what_is_b(self):
+        """Find optical thickness using unscattered transmission."""
+        s = self.sample
+        t_u = self.m_u or 0
+        n_boundary = getattr(s, "n_sample_boundary", s.n)
+        n_outer_above = getattr(s, "n_outer_above", 1.0)
+        n_outer_below = getattr(s, "n_outer_below", 1.0)
+
+        r1, t1 = iad.absorbing_glass_RT(n_outer_above, s.n_above, n_boundary, s.nu_0, s.b_above)
+
+        mu = iad.cos_snell(iad.fresnel._transport_index(n_outer_above), s.nu_0, s.n)
+
+        r2, t2 = iad.absorbing_glass_RT(n_boundary, s.n_below, n_outer_below, mu, s.b_below)
+
+        if t_u <= 0:
+            return np.inf
+
+        if t_u >= t1 * t2 / (1 - r1 * r2):
+            return 0.001
+
+        tt = t1 * t2
+
+        if r1 == 0 or r2 == 0:
+            ratio = tt / t_u
+        else:
+            ratio = (tt + np.sqrt(tt**2 + 4 * t_u**2 * r1 * r2)) / (2 * t_u)
+
+        return s.nu_0 * np.log(ratio)
+
+    def measured_rt(self):
+        r"""Calculate measured reflection and transmission.
+
+        The direct incident power is :math:`(1-f_u)P`. The reflected power will
+        be :math:`(1-f_u)R_{direct} P`.  Since baffles ensure that the light cannot
+        reach the detector, we must bounce the light off the sphere walls to
+        use to above gain formulas.  The contribution will then be
+
+        .. math:: (1-f_u)R_{direct} (1-a_e) r_w P.
+
+        The measured power will be
+
+        .. math:: P_d = a_d (1-a_e) r_w [(1-f_u) r_{direct} + f_u r_w] P ⋅ G(r_s)
+
+        Similarly the power falling on the detector measuring transmitted light is
+
+        .. math:: P_d'= a_d' t_{direct} r_w' (1-a_e') P ⋅ G'(r_s)
+
+        when the empty port in the transmission sphere is closed,
+        :math:`a_e'=0`.
+
+        The normalized sphere measurements are
+
+        .. math:: M_R = r_{std}⋅\frac{R(r_{direct},r_s)-R(0,0)}{R(r_{std},r_{std})-R(0,0)}
+
+        and
+
+        .. math:: M_T = t_{std}⋅\frac{T(t_{direct},r_s)-T(0,0)}{T(t_{std},r_{std})-T(0,0)}
+
+        Args:
+            ur1: reflection for collimated incidence
+            ut1: transmission for collimated incidence
+            uru: reflection for diffuse incidence
+            utu: transmission for diffuse incidence
+
+        Returns:
+            [float, float]: measured reflection and transmission
+        """
+        s = self.sample
+        ur1, ut1, uru, utu = s.rt()
+
+        # find the unscattered reflection and transmission
+        r_u, t_u = iad.specular_rt(
+            s.n_above,
+            getattr(s, "n_sample_boundary", s.n),
+            s.n_below,
+            s.b,
+            s.nu_0,
+            n_outer_top=getattr(s, "n_outer_above", 1.0),
+            n_outer_bot=getattr(s, "n_outer_below", 1.0),
+            n_slab_transport=s.n,
+        )
+
+        # correct for lost light
+        ur1_actual = ur1 - self.ur1_lost
+        ut1_actual = ut1 - self.ut1_lost
+        uru_actual = uru - self.uru_lost
+        utu_actual = utu - self.utu_lost
+
+        # correct for fraction not collected
+        m_r = ur1_actual - (1.0 - self.fraction_of_rc_in_mr) * r_u
+        m_t = ut1_actual - (1.0 - self.fraction_of_tc_in_mt) * t_u
+
+        if self.num_spheres == 2:
+            if self.r_sphere is None or self.t_sphere is None:
+                raise ValueError("Double sphere mode requires both reflection and transmission spheres.")
+
+            # Match CWEB/C correction path in iad_calc.c before two-sphere formulas
+            uru_calc = max(uru_actual, 0.0)
+            utu_calc = max(utu_actual, 0.0)
+            ur1_calc = max(ur1 - (1.0 - self.fraction_of_rc_in_mr) * r_u - self.ur1_lost, 0.0)
+            ut1_calc = max(ut1 - (1.0 - self.fraction_of_tc_in_mt) * t_u - self.ut1_lost, 0.0)
+
+            d_spheres = iad.DoubleSphere(self.r_sphere, self.t_sphere)
+            d_spheres.f_r = self.f_r
+            m_r, m_t = d_spheres.measured_rt(ur1_calc, uru_calc, ut1_calc, utu_calc)
+            return m_r, m_t
+
+        if self.num_spheres == 1:
+            if self.method in ("comparison", 1):
+                return m_r, m_t
+
+            if self.r_sphere is not None:
+                f_u = self.fraction_of_rc_in_mr
+                m_r = self.r_sphere.MR(ur1, uru, R_u=r_u, f_u=f_u, f_w=self.f_r)
+
+            if self.t_sphere is not None:
+                m_t = self.t_sphere.MT(ut1, uru, T_u=t_u, f_u=self.fraction_of_tc_in_mt)
+
+        return m_r, m_t
+
+
+def afun(x, *args):
+    """Vary the albedo."""
+    exp = args[0]
+    exp.sample.a = x
+    m_r, m_t = exp.measured_rt()
+
+    result = 0
+    if exp.m_r is not None:
+        result += np.abs(m_r - exp.m_r)
+    if exp.m_t is not None:
+        result += np.abs(m_t - exp.m_t)
+    return result
+
+
+def bfun(x, *args):
+    """Vary the optical thickness."""
+    exp = args[0]
+    exp.sample.b = x
+    m_r, m_t = exp.measured_rt()
+
+    result = 0
+    if exp.m_r is not None:
+        result += np.abs(m_r - exp.m_r)
+    if exp.m_t is not None:
+        result += np.abs(m_t - exp.m_t)
+    return result
+
+
+def gfun(x, *args):
+    """Vary the anisotropy."""
+    exp = args[0]
+    exp.sample.g = x
+    m_r, m_t = exp.measured_rt()
+
+    result = 0
+    if exp.m_r is not None:
+        result += np.abs(m_r - exp.m_r)
+    if exp.m_t is not None:
+        result += np.abs(m_t - exp.m_t)
+    return result
+
+
+def abfun(x, *args):
+    """Vary the ab."""
+    exp = args[0]
+    exp.sample.a = x[0]
+    exp.sample.b = x[1]
+    m_r, m_t = exp.measured_rt()
+    delta = np.abs(m_r - exp.m_r) + np.abs(m_t - exp.m_t)
+    #    print("%7.4f %7.4f %7.4f %7.4f %7.4f" % (exp.sample.a, exp.sample.b, m_r, m_t, delta))
+    return delta
+
+
+def bgfun(x, *args):
+    """Vary the bg."""
+    exp = args[0]
+    exp.sample.b = x[0]
+    exp.sample.g = x[1]
+    m_r, m_t = exp.measured_rt()
+    delta = np.abs(m_r - exp.m_r) + np.abs(m_t - exp.m_t)
+    return delta
+
+
+def agfun(x, *args):
+    """Vary the ag."""
+    exp = args[0]
+    exp.sample.a = x[0]
+    exp.sample.g = x[1]
+    m_r, m_t = exp.measured_rt()
+    delta = np.abs(m_r - exp.m_r) + np.abs(m_t - exp.m_t)
+    #    print("%9.7f %8.5f %8.5f %8.5f %8.5f" % (delta, x[0], x[1], m_r, m_t))
+    return delta