BornSim 0.6.0__tar.gz → 0.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (144) hide show
  1. {bornsim-0.6.0 → bornsim-0.7.0}/.zenodo.json +2 -2
  2. {bornsim-0.6.0 → bornsim-0.7.0/BornSim.egg-info}/PKG-INFO +5 -1
  3. {bornsim-0.6.0 → bornsim-0.7.0}/BornSim.egg-info/SOURCES.txt +8 -0
  4. {bornsim-0.6.0 → bornsim-0.7.0}/CITATION.cff +1 -1
  5. {bornsim-0.6.0/BornSim.egg-info → bornsim-0.7.0}/PKG-INFO +5 -1
  6. {bornsim-0.6.0 → bornsim-0.7.0}/README.rst +4 -0
  7. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/__init__.py +2 -0
  8. bornsim-0.7.0/bornsim/_version.py +1 -0
  9. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/api.py +2 -0
  10. bornsim-0.7.0/bornsim/convergence.py +116 -0
  11. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/ensemble.py +19 -0
  12. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/material.py +16 -3
  13. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/random/fields.py +4 -1
  14. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/structured/composite.py +13 -0
  15. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/results.py +62 -8
  16. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/series.py +5 -1
  17. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/solver.py +6 -0
  18. {bornsim-0.6.0 → bornsim-0.7.0}/conda.recipe/meta.yaml +1 -1
  19. bornsim-0.7.0/docs/examples/results/coherent_diffuse.py +93 -0
  20. bornsim-0.7.0/docs/examples/validation/absorbing_sphere_balance.py +83 -0
  21. bornsim-0.7.0/docs/examples/validation/convergence_reports.py +106 -0
  22. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/absorption.rst +4 -3
  23. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/api.rst +3 -0
  24. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/index.rst +1 -0
  25. bornsim-0.7.0/docs/source/reliability.rst +106 -0
  26. {bornsim-0.6.0 → bornsim-0.7.0}/pyproject.toml +2 -2
  27. bornsim-0.7.0/tests/analytical/mie_reference.py +58 -0
  28. bornsim-0.7.0/tests/analytical/test_absorbing_mie.py +73 -0
  29. bornsim-0.7.0/tests/numerical/test_reliability.py +134 -0
  30. bornsim-0.6.0/bornsim/_version.py +0 -1
  31. {bornsim-0.6.0 → bornsim-0.7.0}/.coveragerc +0 -0
  32. {bornsim-0.6.0 → bornsim-0.7.0}/.pre-commit-config.yaml +0 -0
  33. {bornsim-0.6.0 → bornsim-0.7.0}/BornSim.egg-info/dependency_links.txt +0 -0
  34. {bornsim-0.6.0 → bornsim-0.7.0}/BornSim.egg-info/requires.txt +0 -0
  35. {bornsim-0.6.0 → bornsim-0.7.0}/BornSim.egg-info/top_level.txt +0 -0
  36. {bornsim-0.6.0 → bornsim-0.7.0}/CONTRIBUTING.md +0 -0
  37. {bornsim-0.6.0 → bornsim-0.7.0}/LICENSE +0 -0
  38. {bornsim-0.6.0 → bornsim-0.7.0}/MANIFEST.in +0 -0
  39. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/angular_data.py +0 -0
  40. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/directions.py +0 -0
  41. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/ensemble_sampling.py +0 -0
  42. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/geometry.py +0 -0
  43. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/green.py +0 -0
  44. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/grid.py +0 -0
  45. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/__init__.py +0 -0
  46. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/base.py +0 -0
  47. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/particles/__init__.py +0 -0
  48. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/particles/core_shell.py +0 -0
  49. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/particles/cylinder.py +0 -0
  50. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/particles/ellipsoid.py +0 -0
  51. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/particles/spheres.py +0 -0
  52. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/random/__init__.py +0 -0
  53. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/random_medium.py +0 -0
  54. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/random_spheres.py +0 -0
  55. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/structured/__init__.py +0 -0
  56. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/medium/structured/periodic.py +0 -0
  57. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/rotation.py +0 -0
  58. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/sampling.py +0 -0
  59. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/source.py +0 -0
  60. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/units.py +0 -0
  61. {bornsim-0.6.0 → bornsim-0.7.0}/bornsim/volume.py +0 -0
  62. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/README.rst +0 -0
  63. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/born_orders/README.rst +0 -0
  64. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/born_orders/absorbing_random_medium.py +0 -0
  65. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/born_orders/born_interference.py +0 -0
  66. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/born_orders/compare_orders.py +0 -0
  67. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/random_media/README.rst +0 -0
  68. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/random_media/covariance_models.py +0 -0
  69. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/random_media/phase_function.py +0 -0
  70. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/random_media/random_medium.py +0 -0
  71. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/random_media/random_spheres.py +0 -0
  72. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/random_media/theory_random_fields.py +0 -0
  73. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/random_media/wavelength_dependence.py +0 -0
  74. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/results/README.rst +0 -0
  75. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/results/result_plots.py +0 -0
  76. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/results/save_load_results.py +0 -0
  77. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/structured_media/README.rst +0 -0
  78. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/structured_media/antenna_rods.py +0 -0
  79. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/structured_media/dielectric_sphere.py +0 -0
  80. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/structured_media/particle_families.py +0 -0
  81. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/structured_media/periodic_array.py +0 -0
  82. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/structured_media/structured_media.py +0 -0
  83. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/structured_media/theory_directional_interference.py +0 -0
  84. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/validation/README.rst +0 -0
  85. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/validation/angular_convergence.py +0 -0
  86. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/validation/ensemble_sampling.py +0 -0
  87. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/validation/finite_size_comparison.py +0 -0
  88. {bornsim-0.6.0 → bornsim-0.7.0}/docs/examples/validation/grid_refinement.py +0 -0
  89. {bornsim-0.6.0 → bornsim-0.7.0}/docs/images/bornsim_medium_opacity_3d.png +0 -0
  90. {bornsim-0.6.0 → bornsim-0.7.0}/docs/images/bornsim_spf_surface_3d.png +0 -0
  91. {bornsim-0.6.0 → bornsim-0.7.0}/docs/images/branding-prompts.rst +0 -0
  92. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/_static/favicon.png +0 -0
  93. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/_static/favicon.svg +0 -0
  94. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/_static/icon.png +0 -0
  95. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/_static/logo.png +0 -0
  96. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/_static/logo.svg +0 -0
  97. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/_static/phase_function.svg +0 -0
  98. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/conf.py +0 -0
  99. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/development.rst +0 -0
  100. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/examples.rst +0 -0
  101. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/gallery_config.py +0 -0
  102. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/getting_started.rst +0 -0
  103. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/guide.rst +0 -0
  104. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/medium_visualization.rst +0 -0
  105. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/overview.rst +0 -0
  106. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/research.rst +0 -0
  107. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/resources.rst +0 -0
  108. {bornsim-0.6.0 → bornsim-0.7.0}/docs/source/theory.rst +0 -0
  109. {bornsim-0.6.0 → bornsim-0.7.0}/makefile +0 -0
  110. {bornsim-0.6.0 → bornsim-0.7.0}/pytest.ini +0 -0
  111. {bornsim-0.6.0 → bornsim-0.7.0}/setup.cfg +0 -0
  112. {bornsim-0.6.0 → bornsim-0.7.0}/tests/analytical/reference.py +0 -0
  113. {bornsim-0.6.0 → bornsim-0.7.0}/tests/analytical/test_model.py +0 -0
  114. {bornsim-0.6.0 → bornsim-0.7.0}/tests/analytical/test_numerical_reference.py +0 -0
  115. {bornsim-0.6.0 → bornsim-0.7.0}/tests/conftest.py +0 -0
  116. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_absorption.py +0 -0
  117. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_api.py +0 -0
  118. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_api_keywords.py +0 -0
  119. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_api_ownership.py +0 -0
  120. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_api_scope.py +0 -0
  121. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_configuration.py +0 -0
  122. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_directional_api.py +0 -0
  123. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_directions.py +0 -0
  124. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_engine.py +0 -0
  125. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_explicit_physics.py +0 -0
  126. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_geometry.py +0 -0
  127. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_media.py +0 -0
  128. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_medium_composition.py +0 -0
  129. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_medium_families.py +0 -0
  130. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_medium_metadata.py +0 -0
  131. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_plot_contract.py +0 -0
  132. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_random_spheres.py +0 -0
  133. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_result.py +0 -0
  134. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_result_contract.py +0 -0
  135. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_rotation.py +0 -0
  136. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_series.py +0 -0
  137. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_unit_contract.py +0 -0
  138. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_units.py +0 -0
  139. {bornsim-0.6.0 → bornsim-0.7.0}/tests/numerical/test_volume_plotting.py +0 -0
  140. {bornsim-0.6.0 → bornsim-0.7.0}/tests/packaging/test_release_tools.py +0 -0
  141. {bornsim-0.6.0 → bornsim-0.7.0}/tools/check_release.py +0 -0
  142. {bornsim-0.6.0 → bornsim-0.7.0}/tools/check_wheel.py +0 -0
  143. {bornsim-0.6.0 → bornsim-0.7.0}/tools/next_release_version.py +0 -0
  144. {bornsim-0.6.0 → bornsim-0.7.0}/tools/release_tag.py +0 -0
@@ -8,11 +8,11 @@
8
8
  }
9
9
  ],
10
10
  "license": "mit",
11
- "version": "0.6.0",
11
+ "version": "0.7.0",
12
12
  "keywords": [
13
13
  "Born approximation",
14
14
  "light scattering",
15
15
  "random media"
16
16
  ],
17
- "publication_date": "2026-10-22"
17
+ "publication_date": "2026-10-23"
18
18
  }
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: BornSim
3
- Version: 0.6.0
3
+ Version: 0.7.0
4
4
  Summary: Vector Born-series scattering from continuous random dielectric media
5
5
  Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
6
6
  License-Expression: MIT
@@ -147,6 +147,10 @@ What BornSim models
147
147
  * **Results:** differential scattering, full directional phase functions,
148
148
  cross sections, uncertainty estimates, saved provenance, and Matplotlib or
149
149
  Plotly visualizations.
150
+ * **Reliability:** integral-equation residuals, explicit refinement reports,
151
+ and weak-contrast absorbing-sphere validation against Mie theory.
152
+ * **Absorption and ensembles:** passive absorbing materials and random fields,
153
+ absorption uncertainty, and coherent/diffuse scattering decomposition.
150
154
  * **Units:** explicit physical units for wavelengths, lengths, angles, and
151
155
  scattering coefficients through ``bornsim.units.ureg``.
152
156
 
@@ -18,6 +18,7 @@ bornsim/__init__.py
18
18
  bornsim/_version.py
19
19
  bornsim/angular_data.py
20
20
  bornsim/api.py
21
+ bornsim/convergence.py
21
22
  bornsim/directions.py
22
23
  bornsim/ensemble.py
23
24
  bornsim/ensemble_sampling.py
@@ -61,6 +62,7 @@ docs/examples/random_media/random_spheres.py
61
62
  docs/examples/random_media/theory_random_fields.py
62
63
  docs/examples/random_media/wavelength_dependence.py
63
64
  docs/examples/results/README.rst
65
+ docs/examples/results/coherent_diffuse.py
64
66
  docs/examples/results/result_plots.py
65
67
  docs/examples/results/save_load_results.py
66
68
  docs/examples/structured_media/README.rst
@@ -71,7 +73,9 @@ docs/examples/structured_media/periodic_array.py
71
73
  docs/examples/structured_media/structured_media.py
72
74
  docs/examples/structured_media/theory_directional_interference.py
73
75
  docs/examples/validation/README.rst
76
+ docs/examples/validation/absorbing_sphere_balance.py
74
77
  docs/examples/validation/angular_convergence.py
78
+ docs/examples/validation/convergence_reports.py
75
79
  docs/examples/validation/ensemble_sampling.py
76
80
  docs/examples/validation/finite_size_comparison.py
77
81
  docs/examples/validation/grid_refinement.py
@@ -89,6 +93,7 @@ docs/source/guide.rst
89
93
  docs/source/index.rst
90
94
  docs/source/medium_visualization.rst
91
95
  docs/source/overview.rst
96
+ docs/source/reliability.rst
92
97
  docs/source/research.rst
93
98
  docs/source/resources.rst
94
99
  docs/source/theory.rst
@@ -99,7 +104,9 @@ docs/source/_static/logo.png
99
104
  docs/source/_static/logo.svg
100
105
  docs/source/_static/phase_function.svg
101
106
  tests/conftest.py
107
+ tests/analytical/mie_reference.py
102
108
  tests/analytical/reference.py
109
+ tests/analytical/test_absorbing_mie.py
103
110
  tests/analytical/test_model.py
104
111
  tests/analytical/test_numerical_reference.py
105
112
  tests/numerical/test_absorption.py
@@ -119,6 +126,7 @@ tests/numerical/test_medium_families.py
119
126
  tests/numerical/test_medium_metadata.py
120
127
  tests/numerical/test_plot_contract.py
121
128
  tests/numerical/test_random_spheres.py
129
+ tests/numerical/test_reliability.py
122
130
  tests/numerical/test_result.py
123
131
  tests/numerical/test_result_contract.py
124
132
  tests/numerical/test_rotation.py
@@ -2,7 +2,7 @@ cff-version: 1.2.0
2
2
  message: "If you use BornSim in research, please cite the software version used."
3
3
  title: "BornSim"
4
4
  type: software
5
- version: "0.6.0"
5
+ version: "0.7.0"
6
6
  authors:
7
7
  - family-names: "Poinsinet de Sivry-Houle"
8
8
  given-names: "Martin"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: BornSim
3
- Version: 0.6.0
3
+ Version: 0.7.0
4
4
  Summary: Vector Born-series scattering from continuous random dielectric media
5
5
  Author-email: Martin Poinsinet de Sivry-Houle <martin.poinsinet.de.sivry@gmail.com>
6
6
  License-Expression: MIT
@@ -147,6 +147,10 @@ What BornSim models
147
147
  * **Results:** differential scattering, full directional phase functions,
148
148
  cross sections, uncertainty estimates, saved provenance, and Matplotlib or
149
149
  Plotly visualizations.
150
+ * **Reliability:** integral-equation residuals, explicit refinement reports,
151
+ and weak-contrast absorbing-sphere validation against Mie theory.
152
+ * **Absorption and ensembles:** passive absorbing materials and random fields,
153
+ absorption uncertainty, and coherent/diffuse scattering decomposition.
150
154
  * **Units:** explicit physical units for wavelengths, lengths, angles, and
151
155
  scattering coefficients through ``bornsim.units.ureg``.
152
156
 
@@ -107,6 +107,10 @@ What BornSim models
107
107
  * **Results:** differential scattering, full directional phase functions,
108
108
  cross sections, uncertainty estimates, saved provenance, and Matplotlib or
109
109
  Plotly visualizations.
110
+ * **Reliability:** integral-equation residuals, explicit refinement reports,
111
+ and weak-contrast absorbing-sphere validation against Mie theory.
112
+ * **Absorption and ensembles:** passive absorbing materials and random fields,
113
+ absorption uncertainty, and coherent/diffuse scattering decomposition.
110
114
  * **Units:** explicit physical units for wavelengths, lengths, angles, and
111
115
  scattering coefficients through ``bornsim.units.ureg``.
112
116
 
@@ -12,6 +12,7 @@ from .grid import Grid
12
12
  from .directions import Directions
13
13
  from .sampling import AngularSampling
14
14
  from .results import Result
15
+ from .convergence import ConvergenceReport
15
16
  from .angular_data import AngularData
16
17
  from .material import Material
17
18
  from .ensemble_sampling import EnsembleSampling
@@ -19,6 +20,7 @@ from .medium.structured import PeriodicMedium
19
20
  from .medium.particles import CoreShellMedium, EllipsoidMedium, CylinderMedium
20
21
 
21
22
  __all__ = [
23
+ "ConvergenceReport",
22
24
  "PeriodicMedium",
23
25
  "CoreShellMedium",
24
26
  "EllipsoidMedium",
@@ -0,0 +1 @@
1
+ __version__ = version = "0.7.0"
@@ -6,6 +6,7 @@ Implementations live in source.py, solver.py, and results.py.
6
6
  from .source import Source
7
7
  from .solver import Solver
8
8
  from .results import Result
9
+ from .convergence import ConvergenceReport
9
10
  from .grid import Grid
10
11
  from .directions import Directions
11
12
  from .sampling import AngularSampling
@@ -14,6 +15,7 @@ from .material import Material
14
15
  from .ensemble_sampling import EnsembleSampling
15
16
 
16
17
  __all__ = [
18
+ "ConvergenceReport",
17
19
  "Directions",
18
20
  "Material",
19
21
  "EnsembleSampling",
@@ -0,0 +1,116 @@
1
+ """Observable stability comparisons, distinct from physical validity claims."""
2
+
3
+ from dataclasses import dataclass
4
+ from typing import Any
5
+ import numpy as np
6
+
7
+ from .results import Result
8
+
9
+
10
+ @dataclass(frozen=True, kw_only=True)
11
+ class ConvergenceReport:
12
+ """Compare final-order observables across an explicit refinement sequence.
13
+
14
+ Parameters
15
+ ----------
16
+ results : tuple of Result
17
+ At least two full angular results ordered from coarse to fine. Change
18
+ one control at a time: grid, quadrature, sample extent, ensemble size,
19
+ or solver order. The user controls physical equivalence of the cases.
20
+ labels : tuple of str
21
+ One descriptive label per calculation.
22
+ tolerance : float, optional
23
+ Relative tolerance for mu_s and mu_a, absolute tolerance for g.
24
+ Default 0.01. Stability does not certify the Born model's validity.
25
+
26
+ Notes
27
+ -----
28
+ Each row uses the highest order in its result. Relative differences use
29
+ max(abs(previous), abs(current)); two zeros have zero difference. Unknown
30
+ observables are omitted, and unknown residuals remain None. Compare
31
+ ensemble uncertainties separately from discretization errors.
32
+ """
33
+
34
+ results: tuple[Result, ...]
35
+ labels: tuple[str, ...]
36
+ tolerance: float = 0.01
37
+
38
+ def __post_init__(self):
39
+ if len(self.results) < 2 or len(self.labels) != len(self.results):
40
+ raise ValueError("Supply at least two results and one label per result.")
41
+ if not np.isfinite(self.tolerance) or self.tolerance <= 0:
42
+ raise ValueError("tolerance must be finite and positive.")
43
+ if any(not isinstance(result, Result) or result.mu_s is None for result in self.results):
44
+ raise ValueError("Convergence comparisons require full angular Result instances.")
45
+ if any(not isinstance(label, str) for label in self.labels):
46
+ raise ValueError("labels must be strings.")
47
+ object.__setattr__(self, "results", tuple(self.results))
48
+ object.__setattr__(self, "labels", tuple(self.labels))
49
+
50
+ @property
51
+ def rows(self) -> tuple[dict, ...]:
52
+ """Fresh numeric rows: coefficients in m⁻¹, g and residual dimensionless."""
53
+ rows = []
54
+ previous: dict[str, Any] | None = None
55
+ previous_result = None
56
+ for label, result in zip(self.labels, self.results):
57
+ row: dict[str, Any] = {"label": label}
58
+ for name in ("mu_s", "mu_a", "g"):
59
+ value = getattr(result, name)
60
+ row[name] = (
61
+ None
62
+ if value is None
63
+ else float(value.to("dimensionless" if name == "g" else "1 / meter").magnitude[-1])
64
+ )
65
+ row["residual"] = (
66
+ None if result.residual_norms is None else float(np.max(result.residual_norms.magnitude[..., -1]))
67
+ )
68
+ changes: dict[str, float] = {}
69
+ if previous is not None:
70
+ for name in ("mu_s", "mu_a", "g"):
71
+ a, b = previous[name], row[name]
72
+ if a is not None and b is not None and np.isfinite(a) and np.isfinite(b):
73
+ denominator = max(abs(a), abs(b)) if name != "g" else 1.0
74
+ changes[name] = abs(b - a) / denominator if denominator else 0.0
75
+ if previous_result is not None:
76
+ phase_change = self._phase_change(previous=previous_result, current=result)
77
+ if phase_change is not None:
78
+ changes["phase_l1"] = phase_change
79
+ row["changes"] = changes
80
+ row["stable"] = bool(changes) and all(value <= self.tolerance for value in changes.values())
81
+ rows.append(row)
82
+ previous = row
83
+ previous_result = result
84
+ return tuple(rows)
85
+
86
+ @staticmethod
87
+ def _phase_change(*, previous: Result, current: Result) -> float | None:
88
+ """Compare full-polar-range azimuth-averaged phase curves on shared cos(theta)."""
89
+ curves = []
90
+ for result in (previous, current):
91
+ if result.angles is None or result.mu_s.magnitude[-1] == 0:
92
+ return None
93
+ theta = result.angles.to("radian").magnitude
94
+ if len(theta) < 2 or not np.isclose(theta.min(), 0) or not np.isclose(theta.max(), np.pi):
95
+ return None
96
+ phase = result.phase_function.to("1 / steradian").magnitude[-1]
97
+ if phase.ndim == 2:
98
+ phase = phase.mean(axis=-1)
99
+ cosine = np.cos(theta)
100
+ indices = np.argsort(cosine)
101
+ curves.append((cosine[indices], phase[indices]))
102
+ nodes = np.union1d(curves[0][0], curves[1][0])
103
+ difference = np.abs(np.interp(nodes, *curves[0]) - np.interp(nodes, *curves[1]))
104
+ return float(2 * np.pi * np.sum((difference[1:] + difference[:-1]) / 2 * np.diff(nodes)))
105
+
106
+ def summary(self) -> str:
107
+ """Return a compact report without claiming physical convergence."""
108
+ lines = ["Observable stability (not a physical-validity certificate):"]
109
+ for row in self.rows:
110
+ lines.append(
111
+ f"{row['label']}: mu_s={row['mu_s']:.6g} m^-1, "
112
+ f"mu_a={row['mu_a']}, residual={row['residual']}, stable={row['stable']}"
113
+ )
114
+ if row["changes"]:
115
+ lines.append(f" Changes: {row['changes']}")
116
+ return "\n".join(lines)
@@ -87,6 +87,9 @@ def ensemble_scattering(
87
87
  set(),
88
88
  )
89
89
 
90
+ absorption_samples, residual_samples = [], []
91
+ amplitude_sum = None
92
+
90
93
  for sample_seed in ensemble_sampling.seeds:
91
94
  volume = medium.to_volume(
92
95
  grid=grid,
@@ -97,6 +100,12 @@ def ensemble_scattering(
97
100
 
98
101
  sampled = sampling.summarize(result=result)
99
102
 
103
+ assert result.mu_a is not None and result.residual_norms is not None
104
+ absorption_samples.append(result.mu_a)
105
+ residual_samples.append(result.residual_norms)
106
+ cumulative = np.cumsum(sampled["directional_amplitudes"], axis=0)
107
+ amplitude_sum = cumulative.copy() if amplitude_sum is None else amplitude_sum + cumulative
108
+
100
109
  directional_samples.append(sampled["directional_differential"])
101
110
 
102
111
  curve_samples.append(sampled["mean"])
@@ -144,7 +153,17 @@ def ensemble_scattering(
144
153
  else np.full_like(directional[0], np.nan)
145
154
  )
146
155
 
156
+ assert amplitude_sum is not None
147
157
  return {
158
+ "mu_a": np.mean(absorption_samples, axis=0),
159
+ "mu_a_stderr": (
160
+ np.std(absorption_samples, axis=0, ddof=1) / np.sqrt(realizations)
161
+ if realizations > 1
162
+ else np.full(order, np.nan)
163
+ ),
164
+ "residual_norms": np.asarray(residual_samples),
165
+ "coherent_differential": np.sum(np.abs(amplitude_sum / realizations) ** 2, axis=(-1, -2))
166
+ / (2 * float(grid.volume.to("meter**3").magnitude)),
148
167
  "angles": sampling.angles.copy(),
149
168
  "azimuths": sampling.azimuths,
150
169
  "directional_differential": directional.mean(axis=0),
@@ -10,11 +10,14 @@ class Material:
10
10
  """A nondispersive real refractive index shared by any number of shapes.
11
11
 
12
12
  ``refractive_index`` is an absolute positive dimensionless refractive index, not a
13
- contrast. Supply a plain number; quantities are rejected. Attach sample absorption
14
- after voxelization with ``Volume.with_absorption``. Wavelength dispersion is not implemented.
13
+ contrast. Supply plain numbers; quantities are rejected. The nonnegative
14
+ ``extinction_coefficient`` is kappa in n+i*kappa, using exp(-i omega t).
15
+ Voxelization retains absorption within the finite sample; the exterior
16
+ host remains lossless. Wavelength dispersion is not implemented.
15
17
  """
16
18
 
17
19
  refractive_index: float
20
+ extinction_coefficient: float = 0.0
18
21
 
19
22
  def __post_init__(self) -> None:
20
23
  refractive_index = _refractive_index_values(value=self.refractive_index, name="refractive_index", scalar=True)
@@ -24,11 +27,21 @@ class Material:
24
27
 
25
28
  object.__setattr__(self, "refractive_index", refractive_index)
26
29
 
30
+ extinction = _refractive_index_values(
31
+ value=self.extinction_coefficient, name="extinction_coefficient", scalar=True
32
+ )
33
+ if not np.isfinite(extinction) or extinction < 0:
34
+ raise ValueError("extinction_coefficient must be finite and nonnegative.")
35
+ object.__setattr__(self, "extinction_coefficient", extinction)
36
+
27
37
  @property
28
38
  def metadata(self):
29
39
  """Fresh JSON-compatible material description."""
30
40
 
31
- return {"refractive_index": self.refractive_index}
41
+ return {
42
+ "refractive_index": self.refractive_index,
43
+ **({"extinction_coefficient": self.extinction_coefficient} if self.extinction_coefficient else {}),
44
+ }
32
45
 
33
46
  @classmethod
34
47
  def _resolve(cls, *, material=None, refractive_index=None):
@@ -24,6 +24,7 @@ class RandomFieldMedium(Medium):
24
24
  background_refractive_index: float
25
25
  refractive_index_std: float
26
26
  correlation_length: Quantity
27
+ extinction_coefficient: float = 0.0
27
28
 
28
29
  @property
29
30
  @abstractmethod
@@ -43,7 +44,7 @@ class RandomFieldMedium(Medium):
43
44
  if not np.isfinite(self.correlation_length) or self.correlation_length <= 0:
44
45
  raise ValueError("correlation_length must be finite and positive.")
45
46
 
46
- for name in ("background_refractive_index", "refractive_index_std"):
47
+ for name in ("background_refractive_index", "refractive_index_std", "extinction_coefficient"):
47
48
  value = _refractive_index_values(
48
49
  value=getattr(self, name),
49
50
  name=name,
@@ -75,6 +76,7 @@ class RandomFieldMedium(Medium):
75
76
  "correlation_length_m": float(self.correlation_length.to("meter").magnitude),
76
77
  "correlation": self.correlation,
77
78
  "smoothness": getattr(self, "smoothness", None),
79
+ **({"extinction_coefficient": self.extinction_coefficient} if self.extinction_coefficient else {}),
78
80
  }
79
81
 
80
82
  def spectral_weight(self, *, q_squared: Quantity) -> np.ndarray:
@@ -157,6 +159,7 @@ class RandomFieldMedium(Medium):
157
159
 
158
160
  return Volume(
159
161
  delta_refractive_index=synthesized_refractive_index_fluctuations[sample_crop],
162
+ extinction_coefficient=self.extinction_coefficient,
160
163
  grid=grid,
161
164
  background_refractive_index=self.background_refractive_index,
162
165
  medium=self,
@@ -53,6 +53,7 @@ class StructuredMedium(Medium):
53
53
  background_refractive_index: float | None = None
54
54
  overlap: str = "replace"
55
55
  warn_on_clipping: bool = False
56
+ _background_extinction: float = field(default=0.0, init=False, repr=False)
56
57
  _background: RandomFieldMedium | None = field(default=None, init=False, repr=False)
57
58
  _fluctuations: RandomFieldMedium | None = field(default=None, init=False, repr=False)
58
59
 
@@ -85,10 +86,12 @@ class StructuredMedium(Medium):
85
86
  Returns None. Random statistics are copied when added.
86
87
  """
87
88
 
89
+ extinction = 0.0
88
90
  if material is not None:
89
91
  resolved = Material._resolve(material=material, refractive_index=refractive_index)
90
92
 
91
93
  refractive_index = resolved.refractive_index
94
+ extinction = resolved.extinction_coefficient
92
95
 
93
96
  if (refractive_index is None) == (medium is None):
94
97
  raise ValueError("Supply exactly one of refractive_index or medium.")
@@ -117,6 +120,7 @@ class StructuredMedium(Medium):
117
120
  self.background_refractive_index = background_refractive_index
118
121
 
119
122
  self._background = background
123
+ self._background_extinction = extinction
120
124
 
121
125
  def add_fluctuations(self, *, medium):
122
126
  """Set an additive random field applied over the background and all structures.
@@ -203,9 +207,13 @@ class StructuredMedium(Medium):
203
207
 
204
208
  description[key] = list(value) if isinstance(value, tuple) else value
205
209
 
210
+ if region.material.extinction_coefficient:
211
+ description["extinction_coefficient"] = region.material.extinction_coefficient
206
212
  regions.append(description)
207
213
 
208
214
  metadata: dict[str, object] = {**super().metadata, "regions": regions}
215
+ if self._background_extinction:
216
+ metadata["extinction_coefficient"] = self._background_extinction
209
217
 
210
218
  if self.overlap != "replace":
211
219
  metadata["overlap"] = self.overlap
@@ -238,6 +246,7 @@ class StructuredMedium(Medium):
238
246
 
239
247
  if self._background is None:
240
248
  contrast = np.zeros(grid.shape)
249
+ extinction = np.full(grid.shape, self._background_extinction)
241
250
  else:
242
251
  background = self._background.to_volume(
243
252
  grid=grid,
@@ -245,6 +254,7 @@ class StructuredMedium(Medium):
245
254
  )
246
255
 
247
256
  contrast = background.delta_refractive_index.copy()
257
+ extinction = np.array(background.extinction_coefficient, copy=True)
248
258
 
249
259
  occupied = np.zeros(grid.shape, dtype=bool)
250
260
 
@@ -264,6 +274,7 @@ class StructuredMedium(Medium):
264
274
  selected = mask & ~occupied if self.overlap == "preserve" else mask
265
275
 
266
276
  contrast[selected] = region.refractive_index - self.background_refractive_index
277
+ extinction[selected] = region.material.extinction_coefficient
267
278
 
268
279
  occupied |= mask
269
280
 
@@ -274,9 +285,11 @@ class StructuredMedium(Medium):
274
285
  )
275
286
 
276
287
  contrast += fluctuation_field.delta_refractive_index
288
+ extinction += fluctuation_field.extinction_coefficient
277
289
 
278
290
  return Volume(
279
291
  delta_refractive_index=contrast,
292
+ extinction_coefficient=extinction,
280
293
  grid=grid,
281
294
  background_refractive_index=self.background_refractive_index,
282
295
  medium=deepcopy(self) if self._fluctuations is not None else None,
@@ -22,6 +22,16 @@ _ANGULAR_FIELDS = (
22
22
  "sample_volume",
23
23
  )
24
24
 
25
+ _DIAGNOSTIC_FIELDS = (
26
+ "g",
27
+ "mu_s_prime",
28
+ "mu_a",
29
+ "mu_a_stderr",
30
+ "residual_norms",
31
+ "coherent_differential",
32
+ "field_norms",
33
+ )
34
+
25
35
 
26
36
  @dataclass(frozen=True, kw_only=True, repr=False, init=False)
27
37
  class Result:
@@ -68,6 +78,9 @@ class Result:
68
78
  angular: AngularData
69
79
  g: Quantity | None
70
80
  mu_a: Quantity | None
81
+ residual_norms: Quantity | None
82
+ mu_a_stderr: Quantity | None
83
+ coherent_differential: Quantity | None
71
84
  mu_s_prime: Quantity | None
72
85
  field_norms: Quantity | None
73
86
  warnings: tuple
@@ -84,6 +97,9 @@ class Result:
84
97
  "mu_s": "1 / meter",
85
98
  "mu_s_prime": "1 / meter",
86
99
  "mu_a": "1 / meter",
100
+ "mu_a_stderr": "1 / meter",
101
+ "residual_norms": "dimensionless",
102
+ "coherent_differential": "1 / meter / steradian",
87
103
  "g": "dimensionless",
88
104
  "directions": "dimensionless",
89
105
  "field_norms": "dimensionless",
@@ -108,6 +124,9 @@ class Result:
108
124
  g=None,
109
125
  mu_s_prime=None,
110
126
  mu_a=None,
127
+ mu_a_stderr=None,
128
+ residual_norms=None,
129
+ coherent_differential=None,
111
130
  amplitudes=None,
112
131
  term_differential=None,
113
132
  stderr=None,
@@ -131,11 +150,7 @@ class Result:
131
150
  if not isinstance(angular, AngularData):
132
151
  raise TypeError("angular must be an AngularData.")
133
152
 
134
- conflicts = any(
135
- value is not None
136
- for name, value in values.items()
137
- if name not in ("g", "mu_s_prime", "mu_a", "field_norms")
138
- )
153
+ conflicts = any(value is not None for name, value in values.items() if name not in _DIAGNOSTIC_FIELDS)
139
154
 
140
155
  if conflicts or azimuth_averaged:
141
156
  raise ValueError("Supply angular or individual angular fields, not both.")
@@ -204,7 +219,7 @@ class Result:
204
219
  }.items():
205
220
  object.__setattr__(self, name, value)
206
221
 
207
- for name in ("g", "mu_s_prime", "mu_a", "field_norms"):
222
+ for name in _DIAGNOSTIC_FIELDS:
208
223
  value = getattr(state, name)
209
224
 
210
225
  if value is not None:
@@ -233,9 +248,22 @@ class Result:
233
248
  "g": (orders,),
234
249
  "mu_s_prime": (orders,),
235
250
  "mu_a": (orders,),
251
+ "mu_a_stderr": (orders,),
252
+ "residual_norms": (result.realizations, orders) if result.kind == "ensemble" else (orders,),
253
+ "coherent_differential": result.differential.shape,
236
254
  "field_norms": (result.realizations, orders) if result.kind == "ensemble" else (orders,),
237
255
  }
238
256
 
257
+ if result.coherent_differential is not None:
258
+ if result.kind != "ensemble":
259
+ raise ValueError("coherent_differential requires an ensemble.")
260
+ if result.coherent_differential.shape != result.differential.shape:
261
+ raise ValueError("coherent_differential must match differential.")
262
+ total = result.differential.to("1 / meter / steradian").magnitude
263
+ coherent = result.coherent_differential.to("1 / meter / steradian").magnitude
264
+ if np.any(coherent > total + 1e-12 * np.maximum(total, np.finfo(float).tiny)):
265
+ raise ValueError("Coherent intensity cannot exceed total ensemble intensity.")
266
+
239
267
  for name, shape in shapes.items():
240
268
  quantity = getattr(result, name)
241
269
 
@@ -250,7 +278,7 @@ class Result:
250
278
  if not np.issubdtype(values.dtype, np.number) or np.iscomplexobj(values):
251
279
  raise ValueError(f"{name} must contain numeric real values.")
252
280
 
253
- if np.any(np.isinf(values)) or (name != "g" and np.any(~np.isfinite(values))):
281
+ if np.any(np.isinf(values)) or (name not in ("g", "mu_a_stderr") and np.any(~np.isfinite(values))):
254
282
  raise ValueError(f"{name} must be finite, except for documented unknown values.")
255
283
 
256
284
  if name != "g" and np.any(values < 0):
@@ -274,7 +302,10 @@ class Result:
274
302
  if not np.allclose(result.mu_s_prime, expected, rtol=1e-10, atol=0):
275
303
  raise ValueError("mu_s_prime must equal mu_s * (1 - g), with zero at zero scattering.")
276
304
 
277
- for name in ("stderr", "azimuth_stderr"):
305
+ if result.mu_a_stderr is not None and result.kind != "ensemble":
306
+ raise ValueError("mu_a_stderr is only available for ensembles.")
307
+
308
+ for name in ("stderr", "azimuth_stderr", "mu_a_stderr"):
278
309
  errors = getattr(result, name)
279
310
 
280
311
  if result.realizations == 1 and errors is not None and not np.all(np.isnan(errors.magnitude)):
@@ -385,12 +416,34 @@ class Result:
385
416
  g=self.g,
386
417
  mu_s_prime=self.mu_s_prime,
387
418
  mu_a=self.mu_a,
419
+ mu_a_stderr=self.mu_a_stderr,
420
+ residual_norms=self.residual_norms,
421
+ coherent_differential=(
422
+ self.coherent_differential.mean(axis=-1)
423
+ if self.coherent_differential is not None and self.differential.ndim == 3
424
+ else self.coherent_differential
425
+ ),
388
426
  field_norms=self.field_norms,
389
427
  warnings=self.warnings,
390
428
  realizations=self.realizations,
391
429
  provenance=self.provenance,
392
430
  )
393
431
 
432
+ @property
433
+ def diffuse_differential(self):
434
+ """Finite-ensemble mean intensity minus squared mean amplitude (m⁻¹ sr⁻¹).
435
+
436
+ The coherent estimate includes the ensemble-mean scattered field, not
437
+ the direct incident beam. With N samples, this uncorrected diffuse
438
+ estimate has factor (N-1)/N finite-sample bias; it is zero for N=1.
439
+ """
440
+ if self.coherent_differential is None:
441
+ return None
442
+
443
+ values = np.maximum(self.differential - self.coherent_differential, 0 * self.differential.units)
444
+ values.magnitude.setflags(write=False)
445
+ return values
446
+
394
447
  @property
395
448
  def absorption_cross_section(self):
396
449
  """Absorbed power divided by incident irradiance, in area units."""
@@ -1228,3 +1281,4 @@ class BornResult:
1228
1281
  field_norms: np.ndarray # ||E_j|| / ||E_inc||
1229
1282
  warnings: tuple[str, ...]
1230
1283
  mu_a: np.ndarray | None = None
1284
+ residual_norms: np.ndarray | None = None
@@ -1,7 +1,7 @@
1
1
  """Reusable finite-volume vector Born-series engine.
2
2
 
3
3
  Time convention exp(-i omega t). Relative dielectric contrast is linearized
4
- as 2 n0 delta_n at every order. Amplitudes interfere coherently before the
4
+ as 2 n0 (delta_n + i kappa) at every order. Amplitudes interfere coherently before the
5
5
  unpolarized intensity is evaluated.
6
6
  """
7
7
 
@@ -299,4 +299,8 @@ class BornSeries:
299
299
  field_norms=np.array(norms),
300
300
  warnings=tuple(warnings),
301
301
  mu_a=np.array(absorption),
302
+ residual_norms=np.array(
303
+ norms[1:]
304
+ + [float(np.linalg.norm(self.operator.apply(source=contrast[..., None, None] * field)) / incident_norm)]
305
+ ),
302
306
  )
@@ -162,6 +162,7 @@ class Solver:
162
162
  term_differential=result.term_differential * (1 / ureg.meter / ureg.steradian),
163
163
  field_norms=result.field_norms,
164
164
  mu_a=result.mu_a * (1 / ureg.meter),
165
+ residual_norms=result.residual_norms,
165
166
  warnings=result.warnings,
166
167
  provenance=_provenance(
167
168
  order=self.order,
@@ -224,6 +225,7 @@ class Solver:
224
225
  mu_s_prime=integrated[:, 2] * (1 / ureg.meter),
225
226
  field_norms=born.field_norms,
226
227
  mu_a=born.mu_a * (1 / ureg.meter),
228
+ residual_norms=born.residual_norms,
227
229
  warnings=born.warnings,
228
230
  provenance=_provenance(
229
231
  order=self.order,
@@ -302,6 +304,10 @@ class Solver:
302
304
  g=result["g"],
303
305
  mu_s_prime=result["mu_s_prime"] * (1 / ureg.meter),
304
306
  field_norms=result["field_norms"],
307
+ mu_a=result["mu_a"] * (1 / ureg.meter),
308
+ mu_a_stderr=result["mu_a_stderr"] * (1 / ureg.meter),
309
+ residual_norms=result["residual_norms"],
310
+ coherent_differential=result["coherent_differential"] * (1 / ureg.meter / ureg.steradian),
305
311
  warnings=result["warnings"],
306
312
  realizations=result["realizations"],
307
313
  provenance=_provenance(