solprop 0.1.0__py3-none-any.whl

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 (233) hide show
  1. solprop/__init__.py +121 -0
  2. solprop/_display.py +361 -0
  3. solprop/_helpers.py +223 -0
  4. solprop/_host.py +264 -0
  5. solprop/_interrupts.py +210 -0
  6. solprop/_numba_cache.py +557 -0
  7. solprop/_process.py +574 -0
  8. solprop/adiabatic.py +820 -0
  9. solprop/backends/__init__.py +35 -0
  10. solprop/backends/adams_core.py +557 -0
  11. solprop/backends/batch.py +596 -0
  12. solprop/backends/bodies.py +2123 -0
  13. solprop/backends/driver.py +2555 -0
  14. solprop/backends/exponential.py +714 -0
  15. solprop/backends/low_storage.py +727 -0
  16. solprop/backends/memory.py +2255 -0
  17. solprop/backends/mlx_gpu/__init__.py +21 -0
  18. solprop/backends/mlx_gpu/arithmetic.py +710 -0
  19. solprop/backends/mlx_gpu/backend.py +1598 -0
  20. solprop/backends/mlx_gpu/batch.py +78 -0
  21. solprop/backends/mlx_gpu/envelope.py +374 -0
  22. solprop/backends/mlx_gpu/passes.py +720 -0
  23. solprop/backends/multistep.py +4082 -0
  24. solprop/backends/multistep_general.py +455 -0
  25. solprop/backends/numba_cpu/__init__.py +20 -0
  26. solprop/backends/numba_cpu/backend.py +5238 -0
  27. solprop/backends/numba_cpu/batch.py +185 -0
  28. solprop/backends/numba_cpu/coupled_flow.py +1086 -0
  29. solprop/backends/numba_cpu/dispersive.py +1644 -0
  30. solprop/backends/numba_cpu/dispersive_general.py +451 -0
  31. solprop/backends/numba_cpu/dispersive_spatial.py +539 -0
  32. solprop/backends/numba_cpu/envelope_plasma.py +471 -0
  33. solprop/backends/numba_cpu/fft.py +1465 -0
  34. solprop/backends/numba_cpu/field_plasma.py +375 -0
  35. solprop/backends/numba_cpu/general_modal.py +981 -0
  36. solprop/backends/numba_cpu/kernels.py +2036 -0
  37. solprop/backends/numba_cpu/low_storage.py +1305 -0
  38. solprop/backends/numba_cpu/multistep.py +1937 -0
  39. solprop/backends/numba_cpu/openmp.py +349 -0
  40. solprop/backends/numba_cpu/pass_timers.py +162 -0
  41. solprop/backends/numba_cpu/planar.py +420 -0
  42. solprop/backends/numba_cpu/spatial.py +1202 -0
  43. solprop/backends/numba_cpu/tables.py +108 -0
  44. solprop/backends/numpy_ref/__init__.py +65 -0
  45. solprop/backends/numpy_ref/admission.py +717 -0
  46. solprop/backends/numpy_ref/backend.py +3825 -0
  47. solprop/backends/numpy_ref/batch.py +213 -0
  48. solprop/backends/numpy_ref/envelope_plasma.py +180 -0
  49. solprop/backends/numpy_ref/general_modal.py +1151 -0
  50. solprop/backends/numpy_ref/passes.py +2230 -0
  51. solprop/backends/numpy_ref/single.py +1288 -0
  52. solprop/backends/numpy_ref/tdse.py +1026 -0
  53. solprop/backends/numpy_ref/transforms.py +208 -0
  54. solprop/backends/populations.py +295 -0
  55. solprop/backends/protocol.py +787 -0
  56. solprop/backends/registry.py +653 -0
  57. solprop/backends/spatial.py +1152 -0
  58. solprop/boundaries.py +1204 -0
  59. solprop/constants.py +124 -0
  60. solprop/coupling/__init__.py +135 -0
  61. solprop/coupling/coupler.py +2906 -0
  62. solprop/coupling/elements.py +3244 -0
  63. solprop/coupling/envelopes.py +273 -0
  64. solprop/coupling/models.py +941 -0
  65. solprop/coupling/outcouple.py +226 -0
  66. solprop/coupling/plane.py +1847 -0
  67. solprop/coupling/port.py +412 -0
  68. solprop/coupling/remap.py +555 -0
  69. solprop/coupling/transport.py +517 -0
  70. solprop/driver/__init__.py +60 -0
  71. solprop/driver/_scan_batch.py +449 -0
  72. solprop/driver/_scan_context.py +24 -0
  73. solprop/driver/_scan_model.py +327 -0
  74. solprop/driver/_scan_run.py +899 -0
  75. solprop/driver/batch.py +423 -0
  76. solprop/driver/executors/__init__.py +38 -0
  77. solprop/driver/executors/_queue_state.py +208 -0
  78. solprop/driver/executors/_request.py +36 -0
  79. solprop/driver/executors/batch.py +73 -0
  80. solprop/driver/executors/local.py +33 -0
  81. solprop/driver/executors/pool.py +604 -0
  82. solprop/driver/executors/queue.py +706 -0
  83. solprop/driver/executors/slurm.py +365 -0
  84. solprop/driver/interface.py +1797 -0
  85. solprop/driver/material_output.py +986 -0
  86. solprop/driver/memory.py +822 -0
  87. solprop/driver/mixtures.py +382 -0
  88. solprop/driver/run.py +1489 -0
  89. solprop/driver/scaffold.py +259 -0
  90. solprop/driver/scan.py +91 -0
  91. solprop/driver/simulation.py +11064 -0
  92. solprop/driver/summary.py +847 -0
  93. solprop/driver/tdse.py +3172 -0
  94. solprop/driver/tdse_consistency.py +1219 -0
  95. solprop/exceptions.py +349 -0
  96. solprop/fourier.py +1025 -0
  97. solprop/gasflow.py +2087 -0
  98. solprop/grid.py +2341 -0
  99. solprop/hankel.py +198 -0
  100. solprop/linear.py +612 -0
  101. solprop/log.py +1541 -0
  102. solprop/modes/__init__.py +195 -0
  103. solprop/modes/_stepindex_vector.py +394 -0
  104. solprop/modes/antiresonant.py +1144 -0
  105. solprop/modes/base.py +475 -0
  106. solprop/modes/capillary.py +3806 -0
  107. solprop/modes/collection.py +1048 -0
  108. solprop/modes/connection.py +989 -0
  109. solprop/modes/fill.py +733 -0
  110. solprop/modes/graded_index.py +1272 -0
  111. solprop/modes/guide.py +2795 -0
  112. solprop/modes/material.py +806 -0
  113. solprop/modes/protocol.py +568 -0
  114. solprop/modes/quadrature.py +1732 -0
  115. solprop/modes/rectangular.py +887 -0
  116. solprop/modes/slab.py +1306 -0
  117. solprop/modes/stepindex.py +1630 -0
  118. solprop/modes/tabulated.py +1032 -0
  119. solprop/modes/vector.py +431 -0
  120. solprop/monitor.py +1018 -0
  121. solprop/noise.py +515 -0
  122. solprop/nonlinear/__init__.py +114 -0
  123. solprop/nonlinear/envelope_plasma.py +814 -0
  124. solprop/nonlinear/gnlse.py +2699 -0
  125. solprop/nonlinear/ionisation.py +795 -0
  126. solprop/nonlinear/mixtures.py +730 -0
  127. solprop/nonlinear/normalisation.py +462 -0
  128. solprop/nonlinear/optmat_raman.py +1686 -0
  129. solprop/nonlinear/optmat_rates.py +1312 -0
  130. solprop/nonlinear/raman.py +2705 -0
  131. solprop/nonlinear/responses.py +1611 -0
  132. solprop/nonlinear/tdse.py +890 -0
  133. solprop/optics.py +2078 -0
  134. solprop/output/__init__.py +110 -0
  135. solprop/output/_file_lock.py +97 -0
  136. solprop/output/_scan_lock.py +122 -0
  137. solprop/output/_writer_lock.py +79 -0
  138. solprop/output/capability.py +335 -0
  139. solprop/output/hdf5.py +2134 -0
  140. solprop/output/memory.py +668 -0
  141. solprop/output/scan.py +867 -0
  142. solprop/output/scan_artifacts.py +136 -0
  143. solprop/output/schema.py +4465 -0
  144. solprop/output/snapshots.py +968 -0
  145. solprop/output/tdse_archive.py +2307 -0
  146. solprop/physdata/__init__.py +190 -0
  147. solprop/physdata/_optmat.py +833 -0
  148. solprop/physdata/data/mirrors/HD120.csv +2408 -0
  149. solprop/physdata/data/mirrors/HD59_GDD.dat +2485 -0
  150. solprop/physdata/data/mirrors/NOTICE +26 -0
  151. solprop/physdata/data/mirrors/PC147.txt +2409 -0
  152. solprop/physdata/data/mirrors/PC1611.txt +2409 -0
  153. solprop/physdata/data/mirrors/PC1821.txt +2408 -0
  154. solprop/physdata/data/mirrors/PC70_GDD.csv +2408 -0
  155. solprop/physdata/data/mirrors/PC70_R.csv +2795 -0
  156. solprop/physdata/data/mirrors/UCxx-15FS_GD.csv +233 -0
  157. solprop/physdata/data/mirrors/UCxx-15FS_R.csv +1380 -0
  158. solprop/physdata/equation_of_state.py +255 -0
  159. solprop/physdata/gases.py +118 -0
  160. solprop/physdata/glasses.py +1771 -0
  161. solprop/physdata/metals.py +70 -0
  162. solprop/physdata/mixtures.py +1535 -0
  163. solprop/physdata/nonlinear_data.py +1209 -0
  164. solprop/physdata/raman_types.py +664 -0
  165. solprop/physdata/selection.py +1106 -0
  166. solprop/physdata/sellmeier.py +1279 -0
  167. solprop/physdata/species.py +1082 -0
  168. solprop/physdata/transport.py +395 -0
  169. solprop/plotting/__init__.py +75 -0
  170. solprop/plotting/propagation.py +724 -0
  171. solprop/plotting/spectrograms.py +229 -0
  172. solprop/plotting/statistics.py +247 -0
  173. solprop/plotting/style.py +625 -0
  174. solprop/polarisation.py +351 -0
  175. solprop/processing/__init__.py +172 -0
  176. solprop/processing/_examples.py +467 -0
  177. solprop/processing/axes.py +658 -0
  178. solprop/processing/coherence.py +275 -0
  179. solprop/processing/compression.py +1737 -0
  180. solprop/processing/fields.py +769 -0
  181. solprop/processing/mixtures.py +423 -0
  182. solprop/processing/modal.py +1248 -0
  183. solprop/processing/planes.py +570 -0
  184. solprop/processing/scans.py +962 -0
  185. solprop/processing/spectra.py +373 -0
  186. solprop/processing/time.py +934 -0
  187. solprop/profiles.py +3988 -0
  188. solprop/pulses.py +2445 -0
  189. solprop/py.typed +0 -0
  190. solprop/scan.py +189 -0
  191. solprop/sol.py +527 -0
  192. solprop/spatial.py +3096 -0
  193. solprop/stats.py +2966 -0
  194. solprop/stepper/__init__.py +74 -0
  195. solprop/stepper/controller.py +780 -0
  196. solprop/stepper/low_storage.py +155 -0
  197. solprop/stepper/multistep.py +963 -0
  198. solprop/stepper/runge_kutta.py +70 -0
  199. solprop/stepper/schedule.py +1070 -0
  200. solprop/stepper/tableau.py +797 -0
  201. solprop/tools.py +2860 -0
  202. solprop/translate/__init__.py +152 -0
  203. solprop/translate/chebyshev.py +2108 -0
  204. solprop/translate/coupled.py +3249 -0
  205. solprop/translate/coupling.py +384 -0
  206. solprop/translate/envelope_plasma.py +713 -0
  207. solprop/translate/expansion.py +1213 -0
  208. solprop/translate/flux.py +408 -0
  209. solprop/translate/free.py +269 -0
  210. solprop/translate/general.py +2302 -0
  211. solprop/translate/ionisation.py +729 -0
  212. solprop/translate/linop.py +3124 -0
  213. solprop/translate/masks.py +484 -0
  214. solprop/translate/modal.py +881 -0
  215. solprop/translate/modal_path.py +1149 -0
  216. solprop/translate/modal_tables.py +2365 -0
  217. solprop/translate/planar.py +442 -0
  218. solprop/translate/plasma_integration.py +369 -0
  219. solprop/translate/plasma_source.py +128 -0
  220. solprop/translate/precision.py +733 -0
  221. solprop/translate/problem.py +6728 -0
  222. solprop/translate/radial.py +717 -0
  223. solprop/translate/raman.py +749 -0
  224. solprop/translate/responses.py +3803 -0
  225. solprop/translate/spatial.py +1052 -0
  226. solprop/translate/stage.py +955 -0
  227. solprop/translate/tdse.py +1570 -0
  228. solprop/translate/tdse_source.py +313 -0
  229. solprop-0.1.0.dist-info/METADATA +201 -0
  230. solprop-0.1.0.dist-info/RECORD +233 -0
  231. solprop-0.1.0.dist-info/WHEEL +4 -0
  232. solprop-0.1.0.dist-info/licenses/LICENSE +674 -0
  233. solprop-0.1.0.dist-info/licenses/src/solprop/physdata/data/mirrors/NOTICE +26 -0
@@ -0,0 +1,384 @@
1
+ # SPDX-FileCopyrightText: 2026 John C. Travers and contributors
2
+ #
3
+ # SPDX-License-Identifier: GPL-3.0-or-later
4
+
5
+ """Sample a translated problem's entrance into a coupling port (SEP 31).
6
+
7
+ Two products of the translation layer feed plane exchange. :func:`frame_record` is
8
+ the persisted frame integral of a run: the antiderivatives of the frame quantities
9
+ its linear operator removed, so that any saved plane's reference can be rebuilt
10
+ without the run (SEP 31). :func:`input_port` fills the
11
+ :class:`solprop.coupling.port.InputPort` of a translated problem's entrance: its native
12
+ metric at that plane, the frame it has accumulated there, the entrance medium's
13
+ index, the coupling models it admits and what they need: an ordinary mode set's
14
+ scalar profiles, and for a general guide that does not move its E/H reference at the
15
+ nodes and the weak-guidance contrast of its regions (SEP 31, section 4.3). Both read
16
+ the contract's own leaves, so a port and a saved plane of the same run see the same
17
+ numbers.
18
+ """
19
+
20
+ from collections.abc import Sequence
21
+ from typing import cast
22
+
23
+ import numpy as np
24
+ from jaxtyping import Float
25
+
26
+ from solprop.constants import EPS0, C
27
+ from solprop.coupling import (
28
+ InputPort,
29
+ PlaneBasis,
30
+ PlaneGeometry,
31
+ PlaneKind,
32
+ PlaneMetric,
33
+ PlaneReference,
34
+ ScalarModeBasis,
35
+ reference_at,
36
+ )
37
+ from solprop.exceptions import CouplingError, TranslationError
38
+ from solprop.grid import TimeGrid
39
+ from solprop.modes.guide import ModalGuide, StepIndexProvider
40
+ from solprop.modes.protocol import Mode
41
+ from solprop.spatial import FluxSide, SpatialMedium
42
+ from solprop.translate.chebyshev import PiecewiseChebyshev
43
+ from solprop.translate.coupled import metric_at
44
+ from solprop.translate.linop import LinearOperator
45
+ from solprop.translate.modal_tables import ModalTransformTables
46
+ from solprop.translate.problem import KernelProblem
47
+ from solprop.translate.spatial import axial_admittance
48
+
49
+ __all__ = [
50
+ "frame_record",
51
+ "guide_contrast",
52
+ "input_port",
53
+ "port_metric",
54
+ "step_index_frequency",
55
+ ]
56
+
57
+
58
+ def frame_record(
59
+ linear: LinearOperator, frequency_origin: float
60
+ ) -> dict[str, object] | None:
61
+ r"""Return the persisted frame integral of a run's linear operator.
62
+
63
+ The operator removed :math:`R = \beta_0(z) + \beta_1(z)(\omega - \omega_o)`
64
+ (``docs/dev/conventions.md`` section 2; :class:`solprop.linear.Frame`), with
65
+ :math:`\beta_0` zero where the frame keeps it. The record holds the exact
66
+ Chebyshev antiderivatives :math:`\Phi_0 = \int_0^z\beta_0` and
67
+ :math:`T = \int_0^z\beta_1` of the contract's own frame tables and the frequency
68
+ origin, which is all :func:`solprop.coupling.plane.reference_at` needs.
69
+
70
+ Parameters
71
+ ----------
72
+ linear : solprop.translate.linop.LinearOperator
73
+ The contract's linear operator.
74
+ frequency_origin : float
75
+ :math:`\omega_o` in rad/s: the frame's reference frequency on an envelope
76
+ grid, zero on a field grid.
77
+
78
+ Returns
79
+ -------
80
+ dict or None
81
+ JSON-ready ``frequency_origin`` and the ``phase`` (rad) and ``delay`` (s)
82
+ antiderivatives, each its ``breakpoints`` (m) and per-interval
83
+ ``coefficients``, lowest degree first; None for an operator supplied
84
+ without its frame tables.
85
+ """
86
+ if linear.beta0 is None or linear.beta1 is None:
87
+ return None
88
+ return {
89
+ "frequency_origin": float(frequency_origin),
90
+ "phase": _antiderivative(linear.beta0),
91
+ "delay": _antiderivative(linear.beta1),
92
+ }
93
+
94
+
95
+ def _antiderivative(values: PiecewiseChebyshev) -> dict[str, object]:
96
+ """Return the edges and coefficients of a scalar table's antiderivative.
97
+
98
+ Parameters
99
+ ----------
100
+ values : solprop.translate.chebyshev.PiecewiseChebyshev
101
+ A scalar frame table.
102
+
103
+ Returns
104
+ -------
105
+ dict
106
+ JSON-ready ``breakpoints`` (m) and per-interval ``coefficients``, lowest
107
+ degree first, of the exact antiderivative vanishing at the first edge.
108
+ """
109
+ integral = values.integral()
110
+ coefficients = np.real(integral.coefficients).reshape(integral.degrees.size, -1)
111
+ return {
112
+ "breakpoints": [float(one) for one in integral.breakpoints],
113
+ "coefficients": coefficients.tolist(),
114
+ }
115
+
116
+
117
+ def port_metric(problem: KernelProblem, grid: TimeGrid, z: float) -> PlaneMetric:
118
+ """Return the native metric of a translated problem's state at a plane.
119
+
120
+ Parameters
121
+ ----------
122
+ problem : solprop.translate.problem.KernelProblem
123
+ The translated problem.
124
+ grid : solprop.grid.TimeGrid
125
+ Its temporal grid.
126
+ z : float
127
+ The plane's position, m.
128
+
129
+ Returns
130
+ -------
131
+ solprop.coupling.PlaneMetric
132
+ The axial admittance of a spatial run's plane measure at ``z`` (SEP 34),
133
+ the optics-convention Gram ``conj(W)`` of a modal basis that declares one,
134
+ and the identity for true-power coefficients otherwise.
135
+ """
136
+ geometry = problem.transform.geometry
137
+ if geometry is not None:
138
+ if problem.flux is None:
139
+ msg = "a spatial problem carries its plane measure"
140
+ raise TranslationError(msg)
141
+ admittance = axial_admittance(problem.flux.at(z), grid.omega, slice(None))
142
+ return PlaneMetric(
143
+ "admittance",
144
+ admittance=admittance,
145
+ weights=geometry.spectral_weights,
146
+ scale=1.0 if geometry.kind == "slab" else 0.5 * EPS0 * C,
147
+ )
148
+ matrix = metric_at(problem.linear.modal_metric, z)
149
+ if matrix is None:
150
+ return PlaneMetric("identity")
151
+ # The state is internal-convention; a plane's samples are optics-convention, a
152
+ # conjugation away, so the same quadratic form takes conj(W).
153
+ return PlaneMetric("dense", matrix=np.conj(matrix))
154
+
155
+
156
+ def input_port( # noqa: PLR0913 - the problem and each part of the entrance it does not hold
157
+ problem: KernelProblem,
158
+ grid: TimeGrid,
159
+ *,
160
+ route: PlaneKind,
161
+ basis: PlaneBasis,
162
+ frame: dict[str, object] | None,
163
+ medium: SpatialMedium | None = None,
164
+ tables: ModalTransformTables | None = None,
165
+ side: FluxSide | None = None,
166
+ z: float | None = None,
167
+ modes: Sequence[Mode] = (),
168
+ guide: ModalGuide | None = None,
169
+ ) -> InputPort:
170
+ """Fill the input port of a translated problem's entrance.
171
+
172
+ The models it admits: ``same_basis`` always; ``scalar_paraxial`` for an
173
+ ordinary mode set whose scalar profiles exist (a capillary's HE1m modes, a
174
+ step-index fibre's HE1m modes in the weak-guidance limit), with the core's index
175
+ as the reference; ``vector_paraxial`` for a general guide whose E/H the port
176
+ carries, with its core's index and its regions' contrast.
177
+
178
+ Parameters
179
+ ----------
180
+ problem : solprop.translate.problem.KernelProblem
181
+ The translated problem; its launch position is the entrance.
182
+ grid : solprop.grid.TimeGrid
183
+ Its temporal grid.
184
+ route : {'modal', 'general_modal', 'radial', 'cartesian', 'planar'}
185
+ The receiving representation.
186
+ basis : solprop.coupling.PlaneBasis
187
+ The receiving basis and its identity, as the driver computes it from the
188
+ run's record.
189
+ frame : dict or None
190
+ :func:`frame_record` of the problem; None leaves the entrance frame
191
+ uncalibrated.
192
+ medium : solprop.spatial.SpatialMedium or None, optional
193
+ The bulk medium of a spatial route, for the reference index.
194
+ tables : solprop.translate.modal_tables.ModalTransformTables or None, optional
195
+ The E/H reference of a general guide; sampled into the port when the guide
196
+ does not move.
197
+ side : {'before', 'after'} or None, optional
198
+ Side of a declared jump at the entrance.
199
+ z : float or None, optional
200
+ An interior entrance, m, inside the problem's span; None is its launch
201
+ position.
202
+ modes : sequence of solprop.modes.protocol.Mode, optional
203
+ An ordinary modal run's modes, for their scalar profiles.
204
+ guide : solprop.modes.guide.ModalGuide or None, optional
205
+ A general modal run's guide, for its core index and contrast.
206
+
207
+ Returns
208
+ -------
209
+ solprop.coupling.InputPort
210
+ The port and the models it admits.
211
+ """
212
+ z = float(problem.initial.z) if z is None else float(z)
213
+ record: dict[str, object] = {
214
+ "origin": PlaneReference().record(),
215
+ "frame": frame,
216
+ }
217
+ entrance = reference_at(record, z)
218
+ index = None
219
+ if medium is not None:
220
+ live = grid.omega > 0
221
+ values = np.zeros(grid.n_omega)
222
+ values[live] = np.real(medium.index(grid.omega[live], z))
223
+ index = values
224
+ nodes = weights = electric = magnetic = None
225
+ models: tuple[str, ...] = ("same_basis",)
226
+ profiles = contrast = frequency = None
227
+ if tables is not None:
228
+ synthesis = tables.synthesis
229
+ moves = synthesis is not None and synthesis.shape[0] * synthesis.shape[1] > 1
230
+ if not moves:
231
+ nodes = tables.node_xy[0]
232
+ weights = tables.weights[0]
233
+ # Internal-convention reference, conjugated to the optics convention of
234
+ # a plane's samples.
235
+ electric = np.conj(tables.electric[0])
236
+ magnetic = np.conj(tables.magnetic[0])
237
+ if guide is not None:
238
+ index, contrast = guide_contrast(guide, grid)
239
+ frequency = step_index_frequency(guide, grid, z)
240
+ models = ("same_basis", "vector_paraxial")
241
+ if route == "modal" and modes:
242
+ try:
243
+ profiles = ScalarModeBasis.from_modes(modes, grid, z)
244
+ except CouplingError:
245
+ # A family with angular structure has no scalar profiles; the port then
246
+ # admits only the identity model, and couple names why.
247
+ profiles = None
248
+ if profiles is not None:
249
+ index = np.asarray(profiles.core_index)
250
+ models = ("same_basis", "scalar_paraxial")
251
+ if profiles.family == "step_index":
252
+ contrast = _scalar_contrast(profiles, index)
253
+ shape = cast("tuple[int, int, int]", tuple(int(one) for one in problem.shape[1:]))
254
+ return InputPort(
255
+ route,
256
+ grid,
257
+ basis,
258
+ shape,
259
+ PlaneGeometry(z, side),
260
+ entrance,
261
+ port_metric(problem, grid, z),
262
+ index,
263
+ nodes,
264
+ weights,
265
+ electric,
266
+ magnetic,
267
+ models,
268
+ profiles,
269
+ contrast,
270
+ frequency,
271
+ )
272
+
273
+
274
+ def _scalar_contrast(profiles: ScalarModeBasis, index: np.ndarray) -> np.ndarray:
275
+ """Return a step-index profile set's weak-guidance contrast at each bin.
276
+
277
+ Parameters
278
+ ----------
279
+ profiles : solprop.coupling.ScalarModeBasis
280
+ A step-index LP set, carrying its core and cladding indices.
281
+ index : numpy.ndarray
282
+ The reference index per bin.
283
+
284
+ Returns
285
+ -------
286
+ numpy.ndarray
287
+ ``max |n^2 - n_ref^2| / (2 n_ref^2)`` over core and cladding, zero where
288
+ the reference index is zero, shape ``(n_omega,)``.
289
+ """
290
+ live = index > 0
291
+ contrast = np.zeros(index.shape)
292
+ for values in (profiles.core_index, profiles.cladding_index):
293
+ values = cast("np.ndarray", values)
294
+ contrast[live] = np.maximum(
295
+ contrast[live],
296
+ np.abs(values[live] ** 2 - index[live] ** 2) / (2.0 * index[live] ** 2),
297
+ )
298
+ return contrast
299
+
300
+
301
+ def step_index_frequency(
302
+ guide: ModalGuide, grid: TimeGrid, z: float
303
+ ) -> Float[np.ndarray, " n_omega"] | None:
304
+ r"""Return a step-index guide's normalised frequency at its entrance, per bin.
305
+
306
+ :math:`V = (\omega/c)\,a(z)\sqrt{n_{\rm co}^2 - n_{\rm cl}^2}`, with the core
307
+ radius at the entrance and the real parts of the core's and the cladding's
308
+ declared laws, is what the recorded vector envelope's range
309
+ (:data:`solprop.coupling.envelopes.VECTOR_STEP_INDEX_ENVELOPE`) is stated in.
310
+
311
+ Parameters
312
+ ----------
313
+ guide : solprop.modes.guide.ModalGuide
314
+ The guide.
315
+ grid : solprop.grid.TimeGrid
316
+ The run's grid.
317
+ z : float
318
+ The entrance, m.
319
+
320
+ Returns
321
+ -------
322
+ numpy.ndarray or None
323
+ V at each bin, shape ``(n_omega,)``, zero off the active positive band;
324
+ None for a guide whose provider is not a
325
+ :class:`~solprop.modes.guide.StepIndexProvider`.
326
+ """
327
+ provider = guide.field_provider
328
+ if not isinstance(provider, StepIndexProvider):
329
+ return None
330
+ live = grid.active_mask & (grid.omega > 0)
331
+ omega = grid.omega[live]
332
+ radius = float(provider.modes[0].core_radius(np.asarray([z]))[0])
333
+ core, cladding = (
334
+ np.real(np.asarray(region.material.permittivity(omega)))
335
+ for region in provider.regions
336
+ )
337
+ frequency = np.zeros(grid.n_omega)
338
+ frequency[live] = omega / C * radius * np.sqrt(np.maximum(core - cladding, 0.0))
339
+ return frequency
340
+
341
+
342
+ def guide_contrast(guide: ModalGuide, grid: TimeGrid) -> tuple[np.ndarray, np.ndarray]:
343
+ r"""Return a general guide's core index and weak-guidance contrast at each bin.
344
+
345
+ The core is the region on the axis, whose real phase index is the reference
346
+ :math:`n_{\rm ref}`; the contrast is
347
+ :math:`\Delta = \max|n^2 - n_{\rm ref}^2|/(2n_{\rm ref}^2)` over every region's
348
+ law and, for a radial-law provider, over its core profile sampled at 33 radii
349
+ (SEP 31, section 4.3).
350
+
351
+ Parameters
352
+ ----------
353
+ guide : solprop.modes.guide.ModalGuide
354
+ The guide.
355
+ grid : solprop.grid.TimeGrid
356
+ The run's grid.
357
+
358
+ Returns
359
+ -------
360
+ tuple of numpy.ndarray
361
+ The reference index and the contrast, each shape ``(n_omega,)``, zero off
362
+ the active positive band.
363
+ """
364
+ live = grid.active_mask & (grid.omega > 0)
365
+ omega = grid.omega[live]
366
+ index = np.zeros(grid.n_omega)
367
+ index[live] = np.real(np.sqrt(guide.regions[0].material.permittivity(omega)))
368
+ squares = [
369
+ np.real(np.asarray(region.material.permittivity(omega)))
370
+ for region in guide.regions
371
+ ]
372
+ radial = getattr(guide.field_provider, "permittivity", None)
373
+ if radial is not None and callable(getattr(radial, "permittivity", None)):
374
+ fractions = np.linspace(0.0, 1.0, 33)
375
+ profile = np.array(
376
+ [np.real(radial.permittivity(float(one), fractions)) for one in omega]
377
+ )
378
+ squares.extend([profile.min(axis=1), profile.max(axis=1)])
379
+ reference = index[live] ** 2
380
+ contrast = np.zeros(grid.n_omega)
381
+ contrast[live] = np.max(
382
+ [np.abs(one - reference) / (2.0 * reference) for one in squares], axis=0
383
+ )
384
+ return index, contrast