radphen-iadpython 0.7.0__tar.gz

radphen_iadpython-0.7.0/CHANGELOG.rst

@@ -0,0 +1,124 @@
+Changelog for `iadpython` package
+=================================
+
+0.8.0 (unreleased, fork)
+------------------------
+* add ``Layer`` class and ``Sample(layers=[...])`` API for explicit multilayer
+  structure; each layer carries its own a, b, g, n, d, and phase function
+* support refractive-index mismatched layers exactly (Snell-invariant master
+  grid with per-channel total internal reflection at internal interfaces)
+* support per-layer phase functions, mixing Henyey-Greenstein and TABULATED
+  layers freely within one stack
+* support wavelength-dependent layer properties (arrays inside Layer
+  attributes; one ``pf_data`` column per wavelength); scalar layers broadcast
+  across the sweep
+* exact analytic unscattered (ballistic) reflection/transmission for
+  multilayer stacks, including mismatched indices and absorbing slides
+* BREAKING: flat arrays on ``a``/``b``/``g`` now always mean wavelengths;
+  the old form where arrays passed to ``rt_matrices()`` meant layers was
+  removed (use ``Sample(layers=...)``); array-valued ``n`` on a flat sample
+  now raises
+* make ``mu_a()``/``mu_s()``/``mu_sp()`` and zero-thickness collapse handling
+  array-safe
+
+0.7.0
+-----
+* align build, packaging, CI, and docs infrastructure with miepython patterns
+* move JupyterLite configuration into package-managed location
+* integrate adaptive AGrid warm starts for inverse-search acceleration
+* align `iadcommand` behavior more closely with legacy `iad` CLI
+* improve wavelength handling to match legacy `iad` behavior
+* add and expand round-trip coverage (including one-sphere workflows)
+* increase minimum supported Python version to 3.10
+* improve linting quality and add/expand pylint checks
+* port two-sphere integrating-sphere gain and normalization equations from CWEB/C into `DoubleSphere`
+* wire two-sphere forward measurement path into `Experiment.measured_rt()` for `num_spheres == 2`
+* fix `DoubleSphere.do_one_photon()` return contract to return two values by default
+* expand two-sphere tests to cover CWEB-equation parity, normalization anchors, and experiment wiring
+
+0.6.0
+------
+* fully support single integrating spheres
+* add command-line support
+* add Monte Carlo sphere simulations
+* add Port class for Sphere class
+* change entrance port to empty port
+* improve sphere-single.ipynb
+* add sphere-random.ipynb
+* improve single sphere testing
+* add port testing
+* add notebook on measurements
+* rearrange documentation
+
+
+0.5.3
+------
+* add github actions
+* add citation with zenodo DOI
+* add copyright to docs
+* add conda support
+* improve badges
+* add github auto testing
+* lint files
+* start fixing math in docstrings
+* remove tox
+
+v0.5.2
+------
+* fix search, one-sphere round-trips now
+* fix packaging
+* fix html generation
+* linting
+
+v0.5.1
+------
+* inverse calculation works for 0 spheres
+* much more testing
+* basic multiple layers support
+* single location for version number
+* revert to sphinx_rtd_theme
+
+v0.4.0
+------
+* forward adding-doubling calculation is pure python now
+* create pure python packages
+* include wheel file
+* package as python3 only
+* use sphinx_book_theme for docs
+
+v0.3.0
+------
+* improve packaging
+* improve documentation with Sphinx
+* use tox
+* add better diagnostics for finding libiad library
+
+v0.2.5
+------
+* add doc files to distribution
+* promise only python 3 and non-zip
+* improve long description
+
+v0.2.4
+* fix bugs found by C Regan
+* (unreleased??)
+
+v0.2.3
+------
+* fix __init__.py so "import iadpython" works
+
+v0.2.2
+------
+* necessary because setup.py version did not get updated
+
+v0.2.1
+------
+* remove ctypes as a requirement
+
+v0.2.0
+------
+* initial checkin
+* Convert to markdown format
+* update to correct contents
+* add ctypes as dependancy, fix test path
+* update my notes on how to cut a release

radphen_iadpython-0.7.0/CITATION.cff

@@ -0,0 +1,13 @@
+authors:
+- family-names: Prahl
+  given-names: Scott
+  orcid: https://orcid.org/0000-0003-1468-6851
+cff-version: 1.2.0
+date-released: '2023-09-19'
+doi: 10.5281/zenodo.8361415
+message: If you use this software, please cite it as below.
+title: 'iadpython: a python module implementation of adding-doubling.'
+url: https://zenodo.org/badge/latestdoi/102148844
+version: 0.5.3
+
+

radphen_iadpython-0.7.0/LICENSE.txt

@@ -0,0 +1,18 @@
+Copyright 2017-2021 Scott Prahl
+
+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.

radphen_iadpython-0.7.0/MANIFEST.in

@@ -0,0 +1,15 @@
+# Core package files
+include LICENSE.txt
+include README.rst
+include CHANGELOG.rst
+include CITATION.cff
+
+# Package data needed at runtime
+include iadpython/data/*.csv
+
+# Test suite + fixtures for reproducible sdist testing
+recursive-include tests *.py
+recursive-include tests/data *.rxt *.txt
+
+include PROVENANCE.md
+recursive-include tools *.py *.md *.json

radphen_iadpython-0.7.0/PKG-INFO

@@ -0,0 +1,264 @@
+Metadata-Version: 2.4
+Name: radphen-iadpython
+Version: 0.7.0
+Summary: Forward and inverse radiative transport using adding-doubling
+Author-email: Scott Prahl <scott.prahl@oit.edu>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/PanxoPanza/iadpython
+Project-URL: Documentation, https://iadpython.readthedocs.io
+Project-URL: Source, https://github.com/PanxoPanza/iadpython
+Project-URL: Tracker, https://github.com/PanxoPanza/iadpython/issues
+Project-URL: Changelog, https://github.com/PanxoPanza/iadpython/blob/main/docs/CHANGELOG.rst
+Keywords: absorption,scattering,reflection,transmission,optical properties,radiative transport,scattering coefficient,scattering anisotropy
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.10
+Description-Content-Type: text/x-rst
+License-File: LICENSE.txt
+Requires-Dist: scipy>=1.10
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=1.5
+Requires-Dist: matplotlib
+Provides-Extra: docs
+Requires-Dist: Sphinx==8.1.3; extra == "docs"
+Requires-Dist: nbsphinx==0.9.7; extra == "docs"
+Requires-Dist: sphinx_automodapi; extra == "docs"
+Requires-Dist: sphinx_rtd_theme; extra == "docs"
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: imageio; extra == "dev"
+Requires-Dist: requests; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: yamllint; extra == "dev"
+Requires-Dist: rstcheck; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pyroma; extra == "dev"
+Requires-Dist: black[jupyter]; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: check-manifest; extra == "dev"
+Requires-Dist: libarchive-c; extra == "dev"
+Requires-Dist: pyyaml; extra == "dev"
+Requires-Dist: setuptools; extra == "dev"
+Requires-Dist: jupyterlab; extra == "dev"
+Requires-Dist: nbconvert; extra == "dev"
+Requires-Dist: nbformat; extra == "dev"
+Provides-Extra: lite
+Requires-Dist: jupyterlite-core==0.6.4; extra == "lite"
+Requires-Dist: jupyterlite-pyodide-kernel==0.6.1; extra == "lite"
+Dynamic: license-file
+
+radphen-iadpython
+=================
+
+This is the MIT-licensed RadPhen fork of Scott Prahl's iadpython, maintained
+at https://github.com/PanxoPanza/iadpython for empylib. Distribution version
+0.7.0 retains the original ``iadpython`` import namespace and ``iadp``
+command. The distribution name alone is ``radphen-iadpython``.
+
+Install with ``python -m pip install radphen-iadpython``. For example::
+
+    import iadpython as iad
+    sample = iad.Sample(a=0.9, b=1.0, g=0.5)
+    print(sample.rt())
+
+The fork preserves HG, TABULATED and MOMENTS phase functions, complex sample
+and exterior boundary indices, and diffuse-cone transport from the audited
+source. See PROVENANCE.md for the exact source and release procedure.
+Both distributions provide ``iadpython`` and ``iadp``; install this fork in a
+fresh environment without the upstream ``iadpython`` distribution. They cannot
+coexist safely in one environment because their package paths overlap.
+
+Original upstream README (historical attribution)
+=================================================
+
+.. |pypi| image:: https://img.shields.io/pypi/v/iadpython?color=68CA66
+   :target: https://pypi.org/project/iadpython/
+   :alt: pypi
+
+.. |github| image:: https://img.shields.io/github/v/tag/scottprahl/iadpython?label=github&color=68CA66
+   :target: https://github.com/scottprahl/iadpython
+   :alt: github
+
+.. |conda| image:: https://img.shields.io/conda/vn/conda-forge/iadpython?label=conda&color=68CA66
+   :target: https://github.com/conda-forge/iadpython-feedstock
+   :alt: conda
+
+.. |doi| image:: https://zenodo.org/badge/102148844.svg
+   :target: https://zenodo.org/badge/latestdoi/102148844
+   :alt: doi
+
+.. |license| image:: https://img.shields.io/github/license/scottprahl/iadpython?color=68CA66
+   :target: https://github.com/scottprahl/iadpython/blob/main/LICENSE.txt
+   :alt: License
+
+.. |test| image:: https://github.com/scottprahl/iadpython/actions/workflows/test.yaml/badge.svg
+   :target: https://github.com/scottprahl/iadpython/actions/workflows/test.yaml
+   :alt: Testing
+
+.. |docs| image:: https://readthedocs.org/projects/iadpython/badge
+   :target: https://iadpython.readthedocs.io
+   :alt: Docs
+
+.. |downloads| image:: https://img.shields.io/pypi/dm/iadpython?color=68CA66
+   :target: https://pypi.org/project/iadpython/
+   :alt: Downloads
+
+iadpython
+=========
+
+by Scott Prahl
+
+|pypi| |github| |conda| |doi|
+
+|license| |test| |docs| |downloads|
+
+`iadpython` will be a pure Python module to do forward and inverse multiple light
+scattering (radiative transport) in layered materials.  Calculations are done using 
+van de Hulst's adding-doubling technique.
+
+The original adding-doubling algorithm was developed by van de Hulst to model light
+propagation through layered media.  I extended it to handle Fresnel 
+reflection at boundaries as well as interactions with integrating spheres. 
+
+Finally, the code was further extended to handle lost light using
+Monte Carlo techniques for inverse calculations.
+
+Version v0.4.0 started the migration to a pure-python implementation.  This 
+version includes the ability to do forward calculations of light transport through
+layered 1D structures.  
+
+The long-term goal is rewrite the integrating sphere, inverse algorithm, and
+lost light calculations in pure python so that one can do 
+inverse calculations (i.e., reflection and transmission measurements to 
+intrinsic absorption and scattering properties). 
+
+Both inverse and forward calculations are currently possible using the `iadc` framework.
+This is a python interface to the inverse 
+adding-doubling package written in C by Scott Prahl 
+<https://github.com/scottprahl/iad>.  This works now
+but is a nuisance to install and maintain because of its dependence on compiling
+and installing a C library.
+
+See <https://iadpython.readthedocs.io> for full documentation of `iadpython`.
+
+Differences from upstream iadpython (this fork)
+-----------------------------------------------
+
+This fork adds first-class multilayer support and **changes how arrays are
+interpreted** relative to upstream.  If you are migrating code, read this
+section.
+
+**Layer API.**  A multilayer sample is built from explicit ``Layer`` objects;
+each layer may have its own refractive index (large index mismatches between
+layers are handled exactly, including total internal reflection), its own
+Henyey-Greenstein anisotropy *or* tabulated phase function, and its own
+wavelength dependence::
+
+    import numpy as np
+    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)
+    l2 = iad.Layer(a=0.90, b=1.00, n=1.45, pf_type='TABULATED', pf_data=df)
+
+    s = iad.Sample(layers=[l0, l1, l2], n_above=1.5, quad_pts=16)
+    ur1, ut1, uru, utu = s.rt()
+
+**Axis rule.**  The two axes of a simulation are now structurally distinct
+and cannot be confused:
+
+* *layer axis* = position in the ``layers`` list;
+* *wavelength axis* = arrays **inside** each attribute (``a``/``b``/``g``/``n``
+  of a ``Layer`` may each be a scalar or a wavelength array; a ``TABULATED``
+  phase function holds one ``pf_data`` column per wavelength).  Scalar-valued
+  layers are automatically held constant across the sweep.
+
+**Breaking change.**  Upstream allowed ``sample.a = np.array([...])`` followed
+by ``rt_matrices()`` to mean *layers* while the same array passed to ``rt()``
+meant *wavelengths*.  That ambiguity is removed: flat arrays on ``a``/``b``/``g``
+now **always mean wavelengths**, and array-valued ``n`` on a flat sample is an
+error.  Code using the old flat-arrays-as-layers form fails with::
+
+    RuntimeError: array-valued a/b/g now mean wavelengths, not layers; build a
+    multilayer sample with iadpython.Sample(layers=[iadpython.Layer(...), ...])
+
+Classic single-layer usage (scalars, or wavelength arrays with ``rt()``) is
+unchanged, as are all inverse-calculation entry points.
+
+Usage
+-----
+
+The following will do a forward calculation::
+
+    import iadpython as iad
+
+    mu_s = 10  # scattering coefficient [1/mm]
+    mu_a = 0.1 # absorption coefficient [1/mm]
+    g = 0.9    # scattering anisotropy
+    d = 1      # thickness mm
+
+    a = mu_s/(mu_a+mu_s)
+    b = (mu_a+mu_s) * d
+
+    # air / glass / sample / glass / air
+    s = iadpython.Sample(a=a, b=b, g=g, n=1.4, n_above=1.5, n_below=1.5)
+    ur1, ut1, uru, utu = s.rt()
+
+    print('Collimated light incident perpendicular to sample')
+    print('  total reflection = %.5f' % ur1)
+    print('  total transmission = %.5f' % ut1)
+ 
+    print('Diffuse light incident on sample')
+    print('  total reflection = %.5f' % uru)
+    print('  total transmission = %.5f' % utu)
+
+`Sample` also accepts tabulated phase-function data via the ``pf_data``
+keyword. When ``pf_type`` is ``'TABULATED'``, ``pf_data`` may hold one column per
+wavelength and must have the same length as other wavelength-dependent inputs.
+
+
+Installation
+------------
+
+Use ``pip``::
+
+    pip install iadpython
+
+or ``conda``::
+
+    conda install -c conda-forge iadpython
+
+or use immediately by clicking the Google Colaboratory button below
+
+.. image:: https://colab.research.google.com/assets/colab-badge.svg
+  :target: https://colab.research.google.com/github/scottprahl/iadpython/blob/main
+  :alt: Colab
+
+Inverse Calculations
+---------------------
+
+As of version 0.5.3, the forward and inverse calculations work fine as long as you do not need to
+include integrating sphere effects or lost-light calculations.
+
+If you want to do these, then you're probably best served by downloading and compiling
+the C-code (on unix or macos) or the `.exe` file for Windows.  <https://omlc.org/software/iad/>
+
+
+Dependencies
+------------
+
+Required Python modules: numpy, matplotlib, ctypes, scipy
+
+
+License
+-------
+
+`iadpython` is licensed under the terms of the MIT license.

radphen_iadpython-0.7.0/PROVENANCE.md

@@ -0,0 +1,90 @@
+# RadPhen adding-doubling backend
+
+Distribution: **radphen-iadpython 0.7.0**. Import: `iadpython`.
+CLI: `iadp`. This is a maintained fork, not the upstream distribution.
+
+Exact audited source: https://github.com/PanxoPanza/iadpython/tree/687a1b803594075d7f4f8feba9e1f7468827e7f9
+(commit `687a1b803594075d7f4f8feba9e1f7468827e7f9`). That fork derives from
+Scott Prahl's https://github.com/scottprahl/iadpython .
+The original MIT copyright and license remain verbatim in LICENSE.txt and
+are included in wheels and source distributions. Package author and numerical
+code attribution remain Scott Prahl; RadPhen maintains this distribution.
+
+This release changes distribution metadata and release tooling and includes
+three narrowly reviewed source corrections, each audited explicitly against
+the source commit by tools/compare_backend.py:
+
+- `interface_rt` returns analytic R=0, T=1 for identical finite positive-real-part
+  scalar media, including exact grazing incidence.
+- `Sphere.uniform` passes explicit `(0.0, 1.0)` to three `random.gauss` calls,
+  retaining the standard-normal sampling while supporting Python 3.10.
+- Three two-parameter inverse searches retain their Nelder-Mead objectives,
+  then recompute the selected point's L1 residual. Only when it exceeds the
+  existing tolerance does a bounded least-squares residual-vector fit run.
+  A candidate is accepted only for finite parameters and a finite, strictly
+  smaller L1 residual. Selected parameters are explicitly restored after trials.
+  This escapes flat L1 plateaus near conservative albedo; scalar searches,
+  initialization, measurement physics and acceptance tolerance are unchanged.
+
+The remaining 18 executable module ASTs match the source commit. Function
+docstrings clarify the external incident-cosine convention. HG, TABULATED,
+MOMENTS and complex-boundary forward fixtures remain unchanged.
+See tools/README.md for reproducible source and fixture checks.
+
+The original import and CLI are retained. Do not install upstream `iadpython`
+and `radphen-iadpython` together: both own the same `iadpython` package and
+`iadp` command. Use separate clean environments for baseline comparisons.
+
+## Release procedure
+
+1. Recheck the proposed name radphen-iadpython on PyPI immediately before
+   publishing; the repository does not reserve it.
+2. Configure a PyPI Trusted Publisher for the actual GitHub owner/repository,
+   workflow pypi.yaml, environment pypi. Protect the environment with owner
+   approval. No API token is stored in this repository.
+3. Review the source diff and validation, push the fork, and create reviewed
+   tag v0.7.0. Only owner-initiated manual dispatch on that tag can publish.
+   If transferring to an organization, replace the actor ownership condition
+   with the explicitly authorized release owner.
+4. Dispatch the publish workflow. It builds and checks both artifacts before
+   the protected job requests a short-lived PyPI OIDC credential.
+5. Verify installed wheel and iadp --version from PyPI before
+   releasing empylib 0.2.0.
+
+Local build/test commands do not publish packages.
+
+## Resolution of the seven initial baseline failures
+
+The initial audited baseline had seven failing tests. Review separated one
+physical edge-case defect from stale test calls and inputs:
+
+- Three matched-interface Fresnel/glass failures shared the identical-media
+  precision/grazing defect. The new exact matched-media guard fixes that limit.
+  Nearby unequal indices retain the original Fresnel path.
+- Two specular tests converted the incident cosine into the slab, then passed
+  it to an API that takes the cosine in the illuminated external medium.
+  Their inputs now use the original external cosine; expectations are retained.
+  The production specular algorithm is unchanged and its docstrings clarified.
+- Two redistribution tests called the removed `hg_legendre` name. They now
+  call the existing `phase_legendre` API with the same expected matrices.
+
+The reviewed Fresnel/redistribution and new interface/incidence regression
+selection passes 71 tests. No test exclusions or xfails were added. Numerical
+fixtures remain exactly equal for all six cases and 816 recorded values.
+The full inherited suite is a separate required CI gate; the earlier bounded,
+incomplete run is not a passing result. Publication requires that gate to pass.
+
+## Additional findings from the first full GitHub CI
+
+Full CI for initial packaging commit 78d24 found five failing tests on Python
+3.10 (four sphere tests reached zero-argument random.gauss and one inverse
+roundtrip stalled), and one inverse-roundtrip failure on Python 3.14. These
+were additional inherited issues beyond the initial seven targeted failures.
+They motivated the explicit Gaussian-default compatibility correction and
+bounded inverse-fit refinement above, rather than relaxed tolerances or skips.
+The sphere selection passes 13 tests on both Python 3.10 and 3.14. Five new
+inverse boundary/control regressions pass, checking real measured transport at
+g=-0.9, 0 and 0.9, rejection/restoration of a worse candidate, and no fallback
+for an already adequate fit. The unchanged full zero-sphere inverse-roundtrip file also passes all six tests.
+Full CI after these corrections remains required;
+the first failing CI is not evidence of a complete passing release.