BornSim 0.5.10__tar.gz → 0.6.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 (136) hide show
  1. {bornsim-0.5.10 → bornsim-0.6.0}/.zenodo.json +1 -1
  2. {bornsim-0.5.10 → bornsim-0.6.0/BornSim.egg-info}/PKG-INFO +1 -1
  3. {bornsim-0.5.10 → bornsim-0.6.0}/BornSim.egg-info/SOURCES.txt +3 -0
  4. {bornsim-0.5.10 → bornsim-0.6.0}/CITATION.cff +1 -1
  5. {bornsim-0.5.10/BornSim.egg-info → bornsim-0.6.0}/PKG-INFO +1 -1
  6. bornsim-0.6.0/bornsim/_version.py +1 -0
  7. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/material.py +2 -1
  8. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/results.py +22 -2
  9. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/series.py +14 -1
  10. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/solver.py +16 -0
  11. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/volume.py +31 -0
  12. {bornsim-0.5.10 → bornsim-0.6.0}/conda.recipe/meta.yaml +1 -1
  13. bornsim-0.6.0/docs/examples/born_orders/absorbing_random_medium.py +143 -0
  14. bornsim-0.6.0/docs/source/absorption.rst +61 -0
  15. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/index.rst +1 -0
  16. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/research.rst +1 -1
  17. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/theory.rst +3 -2
  18. {bornsim-0.5.10 → bornsim-0.6.0}/pyproject.toml +1 -1
  19. bornsim-0.6.0/tests/numerical/test_absorption.py +77 -0
  20. bornsim-0.5.10/bornsim/_version.py +0 -1
  21. {bornsim-0.5.10 → bornsim-0.6.0}/.coveragerc +0 -0
  22. {bornsim-0.5.10 → bornsim-0.6.0}/.pre-commit-config.yaml +0 -0
  23. {bornsim-0.5.10 → bornsim-0.6.0}/BornSim.egg-info/dependency_links.txt +0 -0
  24. {bornsim-0.5.10 → bornsim-0.6.0}/BornSim.egg-info/requires.txt +0 -0
  25. {bornsim-0.5.10 → bornsim-0.6.0}/BornSim.egg-info/top_level.txt +0 -0
  26. {bornsim-0.5.10 → bornsim-0.6.0}/CONTRIBUTING.md +0 -0
  27. {bornsim-0.5.10 → bornsim-0.6.0}/LICENSE +0 -0
  28. {bornsim-0.5.10 → bornsim-0.6.0}/MANIFEST.in +0 -0
  29. {bornsim-0.5.10 → bornsim-0.6.0}/README.rst +0 -0
  30. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/__init__.py +0 -0
  31. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/angular_data.py +0 -0
  32. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/api.py +0 -0
  33. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/directions.py +0 -0
  34. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/ensemble.py +0 -0
  35. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/ensemble_sampling.py +0 -0
  36. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/geometry.py +0 -0
  37. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/green.py +0 -0
  38. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/grid.py +0 -0
  39. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/__init__.py +0 -0
  40. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/base.py +0 -0
  41. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/particles/__init__.py +0 -0
  42. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/particles/core_shell.py +0 -0
  43. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/particles/cylinder.py +0 -0
  44. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/particles/ellipsoid.py +0 -0
  45. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/particles/spheres.py +0 -0
  46. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/random/__init__.py +0 -0
  47. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/random/fields.py +0 -0
  48. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/random_medium.py +0 -0
  49. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/random_spheres.py +0 -0
  50. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/structured/__init__.py +0 -0
  51. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/structured/composite.py +0 -0
  52. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/medium/structured/periodic.py +0 -0
  53. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/rotation.py +0 -0
  54. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/sampling.py +0 -0
  55. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/source.py +0 -0
  56. {bornsim-0.5.10 → bornsim-0.6.0}/bornsim/units.py +0 -0
  57. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/README.rst +0 -0
  58. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/born_orders/README.rst +0 -0
  59. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/born_orders/born_interference.py +0 -0
  60. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/born_orders/compare_orders.py +0 -0
  61. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/random_media/README.rst +0 -0
  62. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/random_media/covariance_models.py +0 -0
  63. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/random_media/phase_function.py +0 -0
  64. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/random_media/random_medium.py +0 -0
  65. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/random_media/random_spheres.py +0 -0
  66. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/random_media/theory_random_fields.py +0 -0
  67. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/random_media/wavelength_dependence.py +0 -0
  68. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/results/README.rst +0 -0
  69. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/results/result_plots.py +0 -0
  70. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/results/save_load_results.py +0 -0
  71. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/structured_media/README.rst +0 -0
  72. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/structured_media/antenna_rods.py +0 -0
  73. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/structured_media/dielectric_sphere.py +0 -0
  74. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/structured_media/particle_families.py +0 -0
  75. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/structured_media/periodic_array.py +0 -0
  76. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/structured_media/structured_media.py +0 -0
  77. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/structured_media/theory_directional_interference.py +0 -0
  78. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/validation/README.rst +0 -0
  79. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/validation/angular_convergence.py +0 -0
  80. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/validation/ensemble_sampling.py +0 -0
  81. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/validation/finite_size_comparison.py +0 -0
  82. {bornsim-0.5.10 → bornsim-0.6.0}/docs/examples/validation/grid_refinement.py +0 -0
  83. {bornsim-0.5.10 → bornsim-0.6.0}/docs/images/bornsim_medium_opacity_3d.png +0 -0
  84. {bornsim-0.5.10 → bornsim-0.6.0}/docs/images/bornsim_spf_surface_3d.png +0 -0
  85. {bornsim-0.5.10 → bornsim-0.6.0}/docs/images/branding-prompts.rst +0 -0
  86. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/_static/favicon.png +0 -0
  87. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/_static/favicon.svg +0 -0
  88. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/_static/icon.png +0 -0
  89. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/_static/logo.png +0 -0
  90. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/_static/logo.svg +0 -0
  91. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/_static/phase_function.svg +0 -0
  92. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/api.rst +0 -0
  93. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/conf.py +0 -0
  94. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/development.rst +0 -0
  95. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/examples.rst +0 -0
  96. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/gallery_config.py +0 -0
  97. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/getting_started.rst +0 -0
  98. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/guide.rst +0 -0
  99. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/medium_visualization.rst +0 -0
  100. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/overview.rst +0 -0
  101. {bornsim-0.5.10 → bornsim-0.6.0}/docs/source/resources.rst +0 -0
  102. {bornsim-0.5.10 → bornsim-0.6.0}/makefile +0 -0
  103. {bornsim-0.5.10 → bornsim-0.6.0}/pytest.ini +0 -0
  104. {bornsim-0.5.10 → bornsim-0.6.0}/setup.cfg +0 -0
  105. {bornsim-0.5.10 → bornsim-0.6.0}/tests/analytical/reference.py +0 -0
  106. {bornsim-0.5.10 → bornsim-0.6.0}/tests/analytical/test_model.py +0 -0
  107. {bornsim-0.5.10 → bornsim-0.6.0}/tests/analytical/test_numerical_reference.py +0 -0
  108. {bornsim-0.5.10 → bornsim-0.6.0}/tests/conftest.py +0 -0
  109. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_api.py +0 -0
  110. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_api_keywords.py +0 -0
  111. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_api_ownership.py +0 -0
  112. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_api_scope.py +0 -0
  113. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_configuration.py +0 -0
  114. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_directional_api.py +0 -0
  115. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_directions.py +0 -0
  116. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_engine.py +0 -0
  117. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_explicit_physics.py +0 -0
  118. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_geometry.py +0 -0
  119. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_media.py +0 -0
  120. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_medium_composition.py +0 -0
  121. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_medium_families.py +0 -0
  122. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_medium_metadata.py +0 -0
  123. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_plot_contract.py +0 -0
  124. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_random_spheres.py +0 -0
  125. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_result.py +0 -0
  126. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_result_contract.py +0 -0
  127. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_rotation.py +0 -0
  128. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_series.py +0 -0
  129. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_unit_contract.py +0 -0
  130. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_units.py +0 -0
  131. {bornsim-0.5.10 → bornsim-0.6.0}/tests/numerical/test_volume_plotting.py +0 -0
  132. {bornsim-0.5.10 → bornsim-0.6.0}/tests/packaging/test_release_tools.py +0 -0
  133. {bornsim-0.5.10 → bornsim-0.6.0}/tools/check_release.py +0 -0
  134. {bornsim-0.5.10 → bornsim-0.6.0}/tools/check_wheel.py +0 -0
  135. {bornsim-0.5.10 → bornsim-0.6.0}/tools/next_release_version.py +0 -0
  136. {bornsim-0.5.10 → bornsim-0.6.0}/tools/release_tag.py +0 -0
@@ -8,7 +8,7 @@
8
8
  }
9
9
  ],
10
10
  "license": "mit",
11
- "version": "0.5.10",
11
+ "version": "0.6.0",
12
12
  "keywords": [
13
13
  "Born approximation",
14
14
  "light scattering",
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: BornSim
3
- Version: 0.5.10
3
+ Version: 0.6.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
@@ -50,6 +50,7 @@ bornsim/medium/structured/periodic.py
50
50
  conda.recipe/meta.yaml
51
51
  docs/examples/README.rst
52
52
  docs/examples/born_orders/README.rst
53
+ docs/examples/born_orders/absorbing_random_medium.py
53
54
  docs/examples/born_orders/born_interference.py
54
55
  docs/examples/born_orders/compare_orders.py
55
56
  docs/examples/random_media/README.rst
@@ -77,6 +78,7 @@ docs/examples/validation/grid_refinement.py
77
78
  docs/images/bornsim_medium_opacity_3d.png
78
79
  docs/images/bornsim_spf_surface_3d.png
79
80
  docs/images/branding-prompts.rst
81
+ docs/source/absorption.rst
80
82
  docs/source/api.rst
81
83
  docs/source/conf.py
82
84
  docs/source/development.rst
@@ -100,6 +102,7 @@ tests/conftest.py
100
102
  tests/analytical/reference.py
101
103
  tests/analytical/test_model.py
102
104
  tests/analytical/test_numerical_reference.py
105
+ tests/numerical/test_absorption.py
103
106
  tests/numerical/test_api.py
104
107
  tests/numerical/test_api_keywords.py
105
108
  tests/numerical/test_api_ownership.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.5.10"
5
+ version: "0.6.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.5.10
3
+ Version: 0.6.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
@@ -0,0 +1 @@
1
+ __version__ = version = "0.6.0"
@@ -10,7 +10,8 @@ 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. Absorption and wavelength dispersion are not implemented.
13
+ contrast. Supply a plain number; quantities are rejected. Attach sample absorption
14
+ after voxelization with ``Volume.with_absorption``. Wavelength dispersion is not implemented.
14
15
  """
15
16
 
16
17
  refractive_index: float
@@ -47,6 +47,10 @@ class Result:
47
47
  entire voxel-box volume. ``differential_cross_section`` restores area per
48
48
  steradian using stored sample_volume.
49
49
 
50
+ ``mu_a`` is the finite-sample absorption coefficient, if available. At
51
+ scattering order M it uses the cumulative internal field through M-1.
52
+ ``absorption_cross_section`` restores absorbed-power cross sections.
53
+
50
54
  Source and kind are required. Supply angular or individual differential
51
55
  data, never both. Results are immutable; provenance returns a fresh copy. Other fields describe sampling,
52
56
  isolated terms, integrated moments, uncertainty, diagnostics and provenance.
@@ -63,6 +67,7 @@ class Result:
63
67
  kind: str
64
68
  angular: AngularData
65
69
  g: Quantity | None
70
+ mu_a: Quantity | None
66
71
  mu_s_prime: Quantity | None
67
72
  field_norms: Quantity | None
68
73
  warnings: tuple
@@ -78,6 +83,7 @@ class Result:
78
83
  "amplitudes": "meter",
79
84
  "mu_s": "1 / meter",
80
85
  "mu_s_prime": "1 / meter",
86
+ "mu_a": "1 / meter",
81
87
  "g": "dimensionless",
82
88
  "directions": "dimensionless",
83
89
  "field_norms": "dimensionless",
@@ -101,6 +107,7 @@ class Result:
101
107
  mu_s=None,
102
108
  g=None,
103
109
  mu_s_prime=None,
110
+ mu_a=None,
104
111
  amplitudes=None,
105
112
  term_differential=None,
106
113
  stderr=None,
@@ -125,7 +132,9 @@ class Result:
125
132
  raise TypeError("angular must be an AngularData.")
126
133
 
127
134
  conflicts = any(
128
- value is not None for name, value in values.items() if name not in ("g", "mu_s_prime", "field_norms")
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")
129
138
  )
130
139
 
131
140
  if conflicts or azimuth_averaged:
@@ -195,7 +204,7 @@ class Result:
195
204
  }.items():
196
205
  object.__setattr__(self, name, value)
197
206
 
198
- for name in ("g", "mu_s_prime", "field_norms"):
207
+ for name in ("g", "mu_s_prime", "mu_a", "field_norms"):
199
208
  value = getattr(state, name)
200
209
 
201
210
  if value is not None:
@@ -223,6 +232,7 @@ class Result:
223
232
  shapes = {
224
233
  "g": (orders,),
225
234
  "mu_s_prime": (orders,),
235
+ "mu_a": (orders,),
226
236
  "field_norms": (result.realizations, orders) if result.kind == "ensemble" else (orders,),
227
237
  }
228
238
 
@@ -374,12 +384,21 @@ class Result:
374
384
  angular=angular,
375
385
  g=self.g,
376
386
  mu_s_prime=self.mu_s_prime,
387
+ mu_a=self.mu_a,
377
388
  field_norms=self.field_norms,
378
389
  warnings=self.warnings,
379
390
  realizations=self.realizations,
380
391
  provenance=self.provenance,
381
392
  )
382
393
 
394
+ @property
395
+ def absorption_cross_section(self):
396
+ """Absorbed power divided by incident irradiance, in area units."""
397
+ if self.mu_a is None or self.sample_volume is None:
398
+ return None
399
+
400
+ return self.mu_a * self.sample_volume
401
+
383
402
  @property
384
403
  def differential_cross_section(self):
385
404
  """Finite-sample d-sigma/d-Omega in square metres per steradian."""
@@ -1208,3 +1227,4 @@ class BornResult:
1208
1227
  term_differential: np.ndarray # each term alone, excludes interference
1209
1228
  field_norms: np.ndarray # ||E_j|| / ||E_inc||
1210
1229
  warnings: tuple[str, ...]
1230
+ mu_a: np.ndarray | None = None
@@ -245,11 +245,22 @@ class BornSeries:
245
245
 
246
246
  incident_norm = np.linalg.norm(field)
247
247
 
248
- contrast = 2 * volume.background_refractive_index * volume.delta_refractive_index
248
+ contrast = np.asarray(2 * volume.background_refractive_index * volume.delta_refractive_index, dtype=complex)
249
+
250
+ if np.any(volume.extinction_coefficient):
251
+ contrast = contrast + 2j * volume.background_refractive_index * volume.extinction_coefficient
252
+
253
+ total_field = np.array(field, copy=True)
254
+ absorption = []
255
+ k0 = 2 * np.pi / float(self.wavelength.to("meter").magnitude)
249
256
 
250
257
  amplitude_terms, norms = [], []
251
258
 
252
259
  for _ in range(self.order):
260
+ # P_abs / (incident intensity * box volume), averaged over polarizations.
261
+ absorption.append(
262
+ float(k0 * np.mean(volume.extinction_coefficient * np.sum(np.abs(total_field) ** 2, axis=(-1, -2))))
263
+ )
253
264
  source = contrast[..., None, None] * field
254
265
 
255
266
  amplitude_terms.append(self._far_field(source=source))
@@ -260,6 +271,7 @@ class BornSeries:
260
271
  raise ValueError("Born terms overflowed; reduce contrast or order.")
261
272
 
262
273
  norms.append(float(np.linalg.norm(field) / incident_norm))
274
+ total_field += field
263
275
 
264
276
  amplitudes = np.asarray(amplitude_terms)
265
277
 
@@ -286,4 +298,5 @@ class BornSeries:
286
298
  term_differential=separate,
287
299
  field_norms=np.array(norms),
288
300
  warnings=tuple(warnings),
301
+ mu_a=np.array(absorption),
289
302
  )
@@ -161,6 +161,7 @@ class Solver:
161
161
  amplitudes=result.amplitudes * ureg.meter,
162
162
  term_differential=result.term_differential * (1 / ureg.meter / ureg.steradian),
163
163
  field_norms=result.field_norms,
164
+ mu_a=result.mu_a * (1 / ureg.meter),
164
165
  warnings=result.warnings,
165
166
  provenance=_provenance(
166
167
  order=self.order,
@@ -175,6 +176,13 @@ class Solver:
175
176
  medium=target.medium_metadata,
176
177
  seed=target.seed,
177
178
  coefficient_scope="finite-sample",
179
+ absorption={
180
+ "contrast": "2*n0*(delta_n+i*kappa)",
181
+ "field_order": "M-1 for absorption reported at scattering order M",
182
+ "extinction_coefficient_sha256": hashlib.sha256(
183
+ np.asarray(target.extinction_coefficient, dtype="<f8").tobytes(order="C")
184
+ ).hexdigest(),
185
+ },
178
186
  ),
179
187
  )
180
188
 
@@ -215,6 +223,7 @@ class Solver:
215
223
  g=g,
216
224
  mu_s_prime=integrated[:, 2] * (1 / ureg.meter),
217
225
  field_norms=born.field_norms,
226
+ mu_a=born.mu_a * (1 / ureg.meter),
218
227
  warnings=born.warnings,
219
228
  provenance=_provenance(
220
229
  order=self.order,
@@ -229,6 +238,13 @@ class Solver:
229
238
  medium=volume.medium_metadata,
230
239
  seed=volume.seed,
231
240
  coefficient_scope="finite-sample",
241
+ absorption={
242
+ "contrast": "2*n0*(delta_n+i*kappa)",
243
+ "field_order": "M-1 for absorption reported at scattering order M",
244
+ "extinction_coefficient_sha256": hashlib.sha256(
245
+ np.asarray(volume.extinction_coefficient, dtype="<f8").tobytes(order="C")
246
+ ).hexdigest(),
247
+ },
232
248
  ),
233
249
  )
234
250
 
@@ -41,6 +41,7 @@ class Volume:
41
41
  spacing: Quantity = field(init=False)
42
42
  medium: Medium | None = None
43
43
  seed: int | None = None
44
+ extinction_coefficient: np.ndarray | float = 0.0
44
45
  _medium_metadata: dict[str, object] | None = field(init=False, default=None, repr=False, compare=False)
45
46
 
46
47
  def __post_init__(self) -> None:
@@ -111,6 +112,35 @@ class Volume:
111
112
 
112
113
  object.__setattr__(self, "delta_refractive_index", data)
113
114
 
115
+ absorption = np.array(
116
+ _refractive_index_values(value=self.extinction_coefficient, name="extinction_coefficient"),
117
+ copy=True,
118
+ )
119
+ if absorption.ndim == 0:
120
+ absorption = np.full(grid.shape, float(absorption))
121
+ if absorption.shape != grid.shape or not np.all(np.isfinite(absorption)) or np.any(absorption < 0):
122
+ raise ValueError("extinction_coefficient must be finite, nonnegative and scalar or grid-shaped.")
123
+ absorption.setflags(write=False)
124
+ object.__setattr__(self, "extinction_coefficient", absorption)
125
+
126
+ def with_absorption(self, *, extinction_coefficient) -> Self:
127
+ """Return a sample with passive absorption in a real, lossless host.
128
+
129
+ Parameters
130
+ ----------
131
+ extinction_coefficient : float or array_like
132
+ Unitless nonnegative kappa, scalar or matching the voxel grid.
133
+ Uses exp(-i omega t) and linearized contrast 2*n0*(delta_n+i*kappa).
134
+
135
+ Returns
136
+ -------
137
+ Volume
138
+ Immutable sample retaining its real index field and generation metadata.
139
+ """
140
+ from dataclasses import replace
141
+
142
+ return replace(self, extinction_coefficient=extinction_coefficient)
143
+
114
144
  @classmethod
115
145
  def from_refractive_index(
116
146
  cls,
@@ -246,6 +276,7 @@ class Volume:
246
276
 
247
277
  return Volume(
248
278
  delta_refractive_index=self.delta_refractive_index + other.delta_refractive_index,
279
+ extinction_coefficient=self.extinction_coefficient + other.extinction_coefficient,
249
280
  background_refractive_index=self.background_refractive_index,
250
281
  grid=self.grid,
251
282
  )
@@ -1,6 +1,6 @@
1
1
  package:
2
2
  name: bornsim
3
- version: 0.5.10
3
+ version: 0.6.0
4
4
 
5
5
  source:
6
6
  path: ..
@@ -0,0 +1,143 @@
1
+ """
2
+ Absorbing random medium through fourth Born order
3
+ =================================================
4
+
5
+ Compare exactly the same seeded real-index fluctuations with and without
6
+ absorption. Both calculations retain four coherent scattering orders. The host
7
+ is lossless; absorption is confined to the finite voxel sample. These are
8
+ finite-sample coefficients, not converged infinite-medium transport properties.
9
+ """
10
+
11
+ import matplotlib.pyplot as plt
12
+ import numpy as np
13
+
14
+ from bornsim import AngularSampling, GaussianMedium, Grid, Solver, Source
15
+ from bornsim.units import ureg
16
+
17
+ grid = Grid(
18
+ shape=(8, 8, 8),
19
+ spacing=30 * ureg.nanometer,
20
+ )
21
+
22
+ medium = GaussianMedium(
23
+ background_refractive_index=1.33,
24
+ refractive_index_std=0.002,
25
+ correlation_length=60 * ureg.nanometer,
26
+ )
27
+
28
+ volume = medium.to_volume(
29
+ grid=grid,
30
+ seed=42,
31
+ )
32
+
33
+ extinction_coefficient = 0.001
34
+
35
+ absorbing = volume.with_absorption(extinction_coefficient=extinction_coefficient)
36
+
37
+ source = Source(wavelength=633 * ureg.nanometer)
38
+
39
+ sampling = AngularSampling(
40
+ start=0 * ureg.degree,
41
+ end=180 * ureg.degree,
42
+ n_points=91,
43
+ )
44
+
45
+ solver = Solver(
46
+ source=source,
47
+ sampling=sampling,
48
+ order=4,
49
+ )
50
+
51
+ reference = solver.solve(target=volume)
52
+
53
+ result = solver.solve(target=absorbing)
54
+
55
+ # %%
56
+ # Angular scattering through fourth order
57
+ # ----------------------------------------
58
+ # Sum complex amplitudes before evaluating intensity. The phase function is
59
+ # normalized by scattered power alone; absorbed power is not another direction.
60
+ # Azimuth averaging below is explicit because a finite realization need not be
61
+ # rotationally symmetric.
62
+ averaged = result.azimuth_average()
63
+
64
+ reference_averaged = reference.azimuth_average()
65
+
66
+ angles = result.angles.to("degree").magnitude
67
+
68
+ figure, axes = plt.subplots(1, 2, figsize=(11, 4), layout="constrained")
69
+
70
+ for index in range(4):
71
+ label = f"Through order {index + 1}"
72
+
73
+ axes[0].plot(angles, averaged.differential.to("1 / meter / steradian").magnitude[index], label=label)
74
+
75
+ axes[1].plot(angles, averaged.phase_function.to("1 / steradian").magnitude[index], label=label)
76
+
77
+ axes[0].plot(
78
+ angles,
79
+ reference_averaged.differential.to("1 / meter / steradian").magnitude[-1],
80
+ "k--",
81
+ label="No absorption, order 4",
82
+ )
83
+
84
+ axes[1].plot(
85
+ angles,
86
+ reference_averaged.phase_function.to("1 / steradian").magnitude[-1],
87
+ "k--",
88
+ label="No absorption, order 4",
89
+ )
90
+
91
+ axes[0].set(xlabel="Scattering angle (degrees)", ylabel="Differential coefficient (m⁻¹ sr⁻¹)")
92
+
93
+ axes[1].set(xlabel="Scattering angle (degrees)", ylabel="Phase function (sr⁻¹)")
94
+
95
+ for axis in axes:
96
+ axis.legend(fontsize="small")
97
+
98
+ plt.show()
99
+
100
+ # %%
101
+ # Absorbed power and the incident-field limit
102
+ # --------------------------------------------------
103
+ # At scattering order M, mu_a uses the cumulative internal field through M-1.
104
+ # First order therefore gives 4*pi*kappa/lambda_vacuum for uniform kappa.
105
+ # Subsequent orders include the change in local illumination from rescattering.
106
+ # This dissipation estimate and the truncated scattering calculation need not
107
+ # satisfy the optical theorem exactly at a finite Born order.
108
+ orders = np.arange(1, 5)
109
+
110
+ incident_limit = (4 * np.pi * extinction_coefficient / source.wavelength).to("1 / meter")
111
+
112
+ np.testing.assert_allclose(result.mu_a.magnitude[0], incident_limit.magnitude)
113
+
114
+ np.testing.assert_array_equal(reference.mu_a.magnitude, np.zeros(4))
115
+
116
+ absorption_figure, absorption_axis = plt.subplots(layout="constrained")
117
+
118
+ absorption_axis.plot(orders, result.mu_a.to("1 / meter").magnitude, "o-", label="Internal-field absorption")
119
+
120
+ absorption_axis.axhline(incident_limit.magnitude, color="black", linestyle="--", label="Incident-field limit")
121
+
122
+ absorption_axis.set(
123
+ xlabel="Highest scattering order M",
124
+ ylabel="Finite-sample absorption coefficient (m⁻¹)",
125
+ xticks=orders,
126
+ )
127
+
128
+ absorption_axis.legend()
129
+
130
+ plt.show()
131
+
132
+ for index, coefficient in enumerate(result.mu_a.to("1 / meter").magnitude, start=1):
133
+ print(f"Through scattering order {index}: mu_a = {coefficient:.6g} m⁻¹")
134
+
135
+ # %%
136
+ # Born-term diagnostics
137
+ # ---------------------
138
+ # Decreasing terms alone do not certify accuracy. Refine the grid, angular
139
+ # quadrature and sample size as well as comparing orders. Small differences
140
+ # between the curves are expected for this deliberately weak perturbation.
141
+ result.plot_field_norms()
142
+
143
+ plt.show()
@@ -0,0 +1,61 @@
1
+ Absorbing samples
2
+ =================
3
+
4
+ BornSim supports passive absorption in a finite sample embedded in a real,
5
+ nonabsorbing uniform host. Generate any random or structured volume, then call
6
+ ``volume.with_absorption(extinction_coefficient=kappa)``. The input is a
7
+ nonnegative unitless scalar or an array with the voxel grid's shape. An array
8
+ allows absorption to be restricted to particular particles or regions.
9
+
10
+ .. code-block:: python
11
+
12
+ from bornsim import GaussianMedium, Grid, Solver, Source
13
+ from bornsim.units import ureg
14
+
15
+ grid = Grid(shape=(8, 8, 8), spacing=30 * ureg.nanometer)
16
+ medium = GaussianMedium(
17
+ background_refractive_index=1.33,
18
+ refractive_index_std=0.002,
19
+ correlation_length=60 * ureg.nanometer,
20
+ )
21
+ volume = medium.to_volume(grid=grid, seed=42)
22
+ absorbing = volume.with_absorption(extinction_coefficient=0.001)
23
+ source = Source(wavelength=633 * ureg.nanometer)
24
+ solver = Solver(source=source, order=3)
25
+ result = solver.solve(target=absorbing)
26
+ print(f"Finite-sample absorption coefficient: {result.mu_a}")
27
+ print(f"Absorption cross section: {result.absorption_cross_section}")
28
+
29
+ Model and interpretation
30
+ ------------------------
31
+
32
+ For a runnable comparison through **fourth Born order**, see
33
+ :doc:`auto_examples/born_orders/absorbing_random_medium`. It compares absorbing
34
+ and nonabsorbing samples, plots scattering and phase functions, and checks
35
+ the first-order absorption limit before examining higher orders.
36
+
37
+ With time dependence exp(-i omega t), positive kappa represents loss.
38
+ The solver retains its linearized constitutive model, now with complex contrast
39
+ ``chi = 2*n0*(delta_n + i*kappa)``. It does not use the exact squared complex
40
+ refractive index. Existing real-index plots display the real index field;
41
+ ``volume.extinction_coefficient`` stores the absorption field separately.
42
+
43
+ Absorbed power is evaluated from the local dissipation integral. At reported
44
+ scattering order M, ``mu_a`` uses the cumulative internal field through order
45
+ M-1, matching the field used to form the scattering source at that order.
46
+ It averages the two incident polarizations and divides by the entire voxel-box
47
+ volume, including nonabsorbing voxels. With only the incident field retained,
48
+ a uniform kappa gives ``mu_a = 4*pi*kappa/lambda_vacuum``.
49
+
50
+ The scattering phase function remains normalized by scattered power alone.
51
+ Absorption changes scattering through the complex source and internal field;
52
+ it is not a multiplicative attenuation applied to the final phase function.
53
+ ``mu_a`` is preserved by result archives and azimuth averaging. Existing
54
+ archives without absorption data return ``mu_a=None``.
55
+
56
+ An absorbing exterior host and gain media are not supported. Generated-medium
57
+ ensemble calls currently describe real-index media; for absorbing random media,
58
+ attach absorption to each seeded volume and solve the realizations individually.
59
+ Do not assume a finite Born truncation satisfies the optical theorem exactly.
60
+ Check grid and order convergence before interpreting energy budgets, especially
61
+ for optically thick or strongly absorbing samples.
@@ -53,4 +53,5 @@ refractive-index media.
53
53
  Guide <guide>
54
54
  Examples <examples>
55
55
  API <api>
56
+ Absorption <absorption>
56
57
  Resources <resources>
@@ -149,7 +149,7 @@ The implemented model uses real scalar refractive indices, an unpolarized plane
149
149
  wave along +z, a uniform exterior background, and the linearized dielectric
150
150
  contrast ``2 * background_refractive_index * delta_refractive_index``. Higher Born
151
151
  orders do not restore the omitted quadratic refractive-index term. Strong
152
- contrast, absorption, or more general illumination requires a model beyond
152
+ contrast or more general illumination requires a model beyond
153
153
  these assumptions. See :doc:`theory` for the equations and Green-tensor self-cell
154
154
  convention.
155
155
 
@@ -78,8 +78,9 @@ The constitutive model is deliberately linearized:
78
78
 
79
79
  The quadratic term :math:`\delta n^2` in :math:`(n_0+\delta n)^2` is omitted
80
80
  **at every Born order**. More iterations do not restore it. The implementation
81
- requires positive linearized permittivity and does not model absorption,
82
- magnetic contrast or tensor permittivity. Positive permittivity alone does not
81
+ requires a positive real part of the linearized permittivity. Passive sample
82
+ absorption adds ``2j*n0*kappa`` to this contrast; see :doc:`absorption`.
83
+ Magnetic contrast and tensor permittivity are not supported. Positive permittivity alone does not
83
84
  establish weak-contrast accuracy.
84
85
 
85
86
  Geometry and the finite domain
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "BornSim"
7
- version = "0.5.10"
7
+ version = "0.6.0"
8
8
  description = "Vector Born-series scattering from continuous random dielectric media"
9
9
  readme = "README.rst"
10
10
  license = "MIT"
@@ -0,0 +1,77 @@
1
+ """Passive sample absorption with a lossless propagation background."""
2
+
3
+ import numpy as np
4
+ import pytest
5
+
6
+ from bornsim import Directions, Grid, Result, Solver, Source, Volume
7
+ from bornsim.units import ureg
8
+ from bornsim.series import BornSeries
9
+ from tests.numerical.test_series import independent_matrix
10
+
11
+
12
+ def test_absorption_limit_and_archive(tmp_path):
13
+ grid = Grid(shape=(2, 2, 2), spacing=10 * ureg.nanometer)
14
+ volume = Volume(
15
+ grid=grid,
16
+ background_refractive_index=1.33,
17
+ delta_refractive_index=np.zeros(grid.shape),
18
+ )
19
+ absorbing = volume.with_absorption(extinction_coefficient=0.001)
20
+ source = Source(wavelength=633 * ureg.nanometer)
21
+ directions = Directions(vectors=[[0, 0, 1], [1, 0, 0]])
22
+ solver = Solver(source=source, order=2)
23
+ result = solver.solve(target=absorbing, sampling=directions)
24
+ # Incident-field dissipation gives Beer-Lambert intensity attenuation.
25
+ expected = 4 * np.pi * 0.001 / (633e-9)
26
+ assert result.mu_a.to("1/meter").magnitude[0] == pytest.approx(expected)
27
+ assert np.all(result.mu_a.magnitude > 0)
28
+ assert np.all(result.differential.magnitude >= 0)
29
+ path = result.save(path=tmp_path / "absorbing.npz")
30
+ restored = Result.load(path=path)
31
+ np.testing.assert_array_equal(restored.mu_a.magnitude, result.mu_a.magnitude)
32
+ assert not absorbing.extinction_coefficient.flags.writeable
33
+ assert np.all(volume.extinction_coefficient == 0)
34
+
35
+
36
+ @pytest.mark.parametrize("value", [-0.01, np.nan, np.ones((3, 3, 3))])
37
+ def test_absorption_validation(value):
38
+ grid = Grid(shape=(2, 2, 2), spacing=10 * ureg.nanometer)
39
+ with pytest.raises(ValueError, match="extinction_coefficient"):
40
+ Volume(
41
+ grid=grid,
42
+ background_refractive_index=1.33,
43
+ delta_refractive_index=np.zeros(grid.shape),
44
+ extinction_coefficient=value,
45
+ )
46
+
47
+
48
+ def test_absorbed_power_against_dense_internal_field():
49
+ grid = Grid(shape=(2, 2, 2), spacing=15 * ureg.nanometer)
50
+ kappa = np.arange(8).reshape(grid.shape) * 0.0002
51
+ volume = Volume(
52
+ grid=grid,
53
+ background_refractive_index=1.33,
54
+ delta_refractive_index=np.full(grid.shape, 0.002),
55
+ extinction_coefficient=kappa,
56
+ )
57
+ directions = Directions(vectors=[[0, 0, 1]])
58
+ engine = BornSeries(
59
+ grid=grid,
60
+ background_refractive_index=1.33,
61
+ wavelength=633 * ureg.nanometer,
62
+ directions=directions,
63
+ order=3,
64
+ )
65
+ result = engine.solve(volume=volume)
66
+ matrix = independent_matrix(volume, 633e-9)
67
+ phase = np.exp(2j * np.pi * 1.33 / 633e-9 * grid.positions.to("meter").magnitude[..., 2])
68
+ contrast = 2 * 1.33 * (volume.delta_refractive_index + 1j * kappa)
69
+ expected = np.zeros(3)
70
+ for polarization in ([1, 0, 0], [0, 1, 0]):
71
+ term = phase[..., None] * np.array(polarization)
72
+ total = term.copy()
73
+ for order in range(3):
74
+ expected[order] += (2 * np.pi / 633e-9) * np.mean(kappa * np.sum(abs(total) ** 2, axis=-1))
75
+ term = (matrix @ (contrast[..., None] * term).ravel()).reshape(*grid.shape, 3)
76
+ total += term
77
+ np.testing.assert_allclose(result.mu_a, expected, rtol=1e-9)
@@ -1 +0,0 @@
1
- __version__ = version = "0.5.10"
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes
File without changes