mbsolver 0.4.0__tar.gz → 0.5.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 (26) hide show
  1. {mbsolver-0.4.0/src/mbsolver.egg-info → mbsolver-0.5.0}/PKG-INFO +31 -5
  2. {mbsolver-0.4.0 → mbsolver-0.5.0}/README.md +30 -4
  3. {mbsolver-0.4.0 → mbsolver-0.5.0}/pyproject.toml +1 -1
  4. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver/two_level/__init__.py +66 -7
  5. mbsolver-0.5.0/src/mbsolver/two_level/_kernel_adiabatic_1d.py +100 -0
  6. {mbsolver-0.4.0 → mbsolver-0.5.0/src/mbsolver.egg-info}/PKG-INFO +31 -5
  7. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver.egg-info/SOURCES.txt +3 -1
  8. mbsolver-0.5.0/tests/test_two_level_adiabatic.py +59 -0
  9. {mbsolver-0.4.0 → mbsolver-0.5.0}/LICENSE +0 -0
  10. {mbsolver-0.4.0 → mbsolver-0.5.0}/setup.cfg +0 -0
  11. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver/__init__.py +0 -0
  12. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver/constants.py +0 -0
  13. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver/grids.py +0 -0
  14. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver/profiles.py +0 -0
  15. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver/sample.py +0 -0
  16. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver/three_level/__init__.py +0 -0
  17. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver/three_level/_kernel_1d.py +0 -0
  18. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver/three_level/sample.py +0 -0
  19. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver/two_level/_kernel_1d.py +0 -0
  20. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver.egg-info/dependency_links.txt +0 -0
  21. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver.egg-info/requires.txt +0 -0
  22. {mbsolver-0.4.0 → mbsolver-0.5.0}/src/mbsolver.egg-info/top_level.txt +0 -0
  23. {mbsolver-0.4.0 → mbsolver-0.5.0}/tests/test_profiles.py +0 -0
  24. {mbsolver-0.4.0 → mbsolver-0.5.0}/tests/test_sample.py +0 -0
  25. {mbsolver-0.4.0 → mbsolver-0.5.0}/tests/test_three_level.py +0 -0
  26. {mbsolver-0.4.0 → mbsolver-0.5.0}/tests/test_two_level.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: mbsolver
3
- Version: 0.4.0
3
+ Version: 0.5.0
4
4
  Summary: Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation
5
5
  Author: Toktam Rashidi
6
6
  Author-email: Vahid Anari <vahid.anari8@gmail.com>
@@ -65,6 +65,8 @@ dA/dz = −η R
65
65
 
66
66
  The field `A(t)` entering at `z = 0` is given; population and coherence are
67
67
  advanced with fourth-order Runge-Kutta in time, the field step by step in `z`.
68
+ The derivation from the two-level Hamiltonian is in
69
+ [`docs/two_level.pdf`](docs/two_level.pdf).
68
70
 
69
71
  ```python
70
72
  import matplotlib.pyplot as plt
@@ -103,6 +105,22 @@ plt.show()
103
105
  `res.time`, `res.z` (positions of the stored planes), `res.intensity` and
104
106
  `res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
105
107
 
108
+ ### Adiabatic (rate-equation) limit
109
+
110
+ When `T2` is short compared with the times over which `A` and `w` change, the
111
+ coherence follows its steady state, `R = R0 − T2 A w`, and two equations remain:
112
+
113
+ ```
114
+ dw/dt = A R0 − T2 A² w − (w − w0) / T1 + Λ(t)
115
+ dA/dz = −η R0 + η T2 A w
116
+ ```
117
+
118
+ `solve_1d_adiabatic` takes the same arguments as `solve_1d` (with a finite
119
+ `t2`) and returns the same result plus `res.R`, so the two can be compared
120
+ directly. The limit differs from the full system during the first few `T2`
121
+ and in bursts faster than `T2`; see the section on it in
122
+ [`docs/two_level.pdf`](docs/two_level.pdf).
123
+
106
124
  ## Three-level (Λ) model in one dimension
107
125
 
108
126
  Levels 1 and 2 lie below level 3; the transitions 3→1 and 3→2 carry the fields
@@ -151,11 +169,13 @@ and the pump scale `lambda0 = n0/t0`. By default the decay rate of the 3→2
151
169
  line is the Einstein A computed from `d32`; pass `gamma=` to use a measured one.
152
170
 
153
171
  The three-level equations were derived and checked with Toktam Rashidi. The
154
- derivation, the final dimensionless equations, the initial conditions and the
155
- CH₃OH data are in [`docs/three_level/`](docs/three_level/);
172
+ derivation, from the Hamiltonian to the dimensionless equations, with the
173
+ initial conditions, physical scales and the S255IR-NIRS3 values, is in
174
+ [`docs/three_level.pdf`](docs/three_level.pdf);
156
175
  [`examples/three_level/s255_flare.py`](examples/three_level/s255_flare.py)
157
176
  runs the S255IR-NIRS3 flare and plots it with the observed flux (needs
158
- matplotlib).
177
+ matplotlib). The observations are from the Toruń 32 m telescope,
178
+ [Szymczak et al. 2018, A&A 617, A80](https://doi.org/10.1051/0004-6361/201833443).
159
179
 
160
180
  ## From physical values: `scaling` (two-level)
161
181
 
@@ -205,6 +225,10 @@ entrance, relaxation balance, uncoupled propagation). The three-level model
205
225
  matches the 2025 three-level solver exactly for the S255IR-NIRS3 case. `scaling`
206
226
  is checked against the values of Maxwell Bloch Studio.
207
227
 
228
+ The model documents `docs/two_level.pdf` and `docs/three_level.pdf` are built
229
+ from their LaTeX sources with `sh tools/build_docs.sh` (needs LaTeX with
230
+ `latexmk`); commit the rebuilt PDFs with the sources.
231
+
208
232
  What changed in each version is in [`CHANGELOG.md`](CHANGELOG.md). Pushing a
209
233
  tag `vX.Y.Z` publishes a GitHub Release with that version's section of the
210
234
  changelog, and Zenodo gives it a DOI; update `version` and `date-released` in
@@ -239,7 +263,9 @@ Vahid Anari ·
239
263
  [GitHub](https://github.com/vahid-anari) ·
240
264
  [LinkedIn](https://www.linkedin.com/in/vahid-anari/)
241
265
 
242
- Toktam Rashidi (three-level model)
266
+ Toktam Rashidi ·
267
+ [GitHub](https://github.com/ToktamS) ·
268
+ [LinkedIn](https://www.linkedin.com/in/toktam-r-71951996/)
243
269
 
244
270
  Related projects: [sciwidgets](https://github.com/vahid-anari/sciwidgets) ·
245
271
  [Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio) ·
@@ -33,6 +33,8 @@ dA/dz = −η R
33
33
 
34
34
  The field `A(t)` entering at `z = 0` is given; population and coherence are
35
35
  advanced with fourth-order Runge-Kutta in time, the field step by step in `z`.
36
+ The derivation from the two-level Hamiltonian is in
37
+ [`docs/two_level.pdf`](docs/two_level.pdf).
36
38
 
37
39
  ```python
38
40
  import matplotlib.pyplot as plt
@@ -71,6 +73,22 @@ plt.show()
71
73
  `res.time`, `res.z` (positions of the stored planes), `res.intensity` and
72
74
  `res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
73
75
 
76
+ ### Adiabatic (rate-equation) limit
77
+
78
+ When `T2` is short compared with the times over which `A` and `w` change, the
79
+ coherence follows its steady state, `R = R0 − T2 A w`, and two equations remain:
80
+
81
+ ```
82
+ dw/dt = A R0 − T2 A² w − (w − w0) / T1 + Λ(t)
83
+ dA/dz = −η R0 + η T2 A w
84
+ ```
85
+
86
+ `solve_1d_adiabatic` takes the same arguments as `solve_1d` (with a finite
87
+ `t2`) and returns the same result plus `res.R`, so the two can be compared
88
+ directly. The limit differs from the full system during the first few `T2`
89
+ and in bursts faster than `T2`; see the section on it in
90
+ [`docs/two_level.pdf`](docs/two_level.pdf).
91
+
74
92
  ## Three-level (Λ) model in one dimension
75
93
 
76
94
  Levels 1 and 2 lie below level 3; the transitions 3→1 and 3→2 carry the fields
@@ -119,11 +137,13 @@ and the pump scale `lambda0 = n0/t0`. By default the decay rate of the 3→2
119
137
  line is the Einstein A computed from `d32`; pass `gamma=` to use a measured one.
120
138
 
121
139
  The three-level equations were derived and checked with Toktam Rashidi. The
122
- derivation, the final dimensionless equations, the initial conditions and the
123
- CH₃OH data are in [`docs/three_level/`](docs/three_level/);
140
+ derivation, from the Hamiltonian to the dimensionless equations, with the
141
+ initial conditions, physical scales and the S255IR-NIRS3 values, is in
142
+ [`docs/three_level.pdf`](docs/three_level.pdf);
124
143
  [`examples/three_level/s255_flare.py`](examples/three_level/s255_flare.py)
125
144
  runs the S255IR-NIRS3 flare and plots it with the observed flux (needs
126
- matplotlib).
145
+ matplotlib). The observations are from the Toruń 32 m telescope,
146
+ [Szymczak et al. 2018, A&A 617, A80](https://doi.org/10.1051/0004-6361/201833443).
127
147
 
128
148
  ## From physical values: `scaling` (two-level)
129
149
 
@@ -173,6 +193,10 @@ entrance, relaxation balance, uncoupled propagation). The three-level model
173
193
  matches the 2025 three-level solver exactly for the S255IR-NIRS3 case. `scaling`
174
194
  is checked against the values of Maxwell Bloch Studio.
175
195
 
196
+ The model documents `docs/two_level.pdf` and `docs/three_level.pdf` are built
197
+ from their LaTeX sources with `sh tools/build_docs.sh` (needs LaTeX with
198
+ `latexmk`); commit the rebuilt PDFs with the sources.
199
+
176
200
  What changed in each version is in [`CHANGELOG.md`](CHANGELOG.md). Pushing a
177
201
  tag `vX.Y.Z` publishes a GitHub Release with that version's section of the
178
202
  changelog, and Zenodo gives it a DOI; update `version` and `date-released` in
@@ -207,7 +231,9 @@ Vahid Anari ·
207
231
  [GitHub](https://github.com/vahid-anari) ·
208
232
  [LinkedIn](https://www.linkedin.com/in/vahid-anari/)
209
233
 
210
- Toktam Rashidi (three-level model)
234
+ Toktam Rashidi ·
235
+ [GitHub](https://github.com/ToktamS) ·
236
+ [LinkedIn](https://www.linkedin.com/in/toktam-r-71951996/)
211
237
 
212
238
  Related projects: [sciwidgets](https://github.com/vahid-anari/sciwidgets) ·
213
239
  [Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio) ·
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "mbsolver"
7
- version = "0.4.0"
7
+ version = "0.5.0"
8
8
  description = "Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation"
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -7,7 +7,8 @@ field ``A`` along a 1-D medium ``0 <= z <= 1``::
7
7
  dR/dt = -A w - (R - R0) / T2
8
8
  dA/dz = -η R
9
9
 
10
- with the field ``A(t, z=0)`` given at the entrance.
10
+ with the field ``A(t, z=0)`` given at the entrance (:func:`solve_1d`), and their adiabatic
11
+ limit ``R = R0 - T2 A w`` (:func:`solve_1d_adiabatic`).
11
12
  """
12
13
 
13
14
  from __future__ import annotations
@@ -21,8 +22,9 @@ import numpy as np
21
22
  from mbsolver.grids import grids_1d
22
23
  from mbsolver.profiles import Pulse, Steps, evaluate
23
24
  from mbsolver.two_level._kernel_1d import solve_kernel
25
+ from mbsolver.two_level._kernel_adiabatic_1d import solve_kernel as _solve_kernel_adiabatic
24
26
 
25
- __all__ = ["Result", "solve_1d"]
27
+ __all__ = ["Result", "solve_1d", "solve_1d_adiabatic"]
26
28
 
27
29
 
28
30
  @dataclass(frozen=True)
@@ -37,6 +39,8 @@ class Result:
37
39
  pump: Total pump ``Λ(t)``.
38
40
  field_in: Boundary field ``A(t, z=0)``.
39
41
  t1, t2: Relaxation times on the time grid.
42
+ R: Coherence on the stored planes, shape ``(n_planes, nt)``; only from
43
+ :func:`solve_1d_adiabatic` (``None`` from :func:`solve_1d`).
40
44
  """
41
45
 
42
46
  time: np.ndarray
@@ -47,6 +51,7 @@ class Result:
47
51
  field_in: np.ndarray
48
52
  t1: np.ndarray
49
53
  t2: np.ndarray
54
+ R: Optional[np.ndarray] = None
50
55
 
51
56
 
52
57
  Profile = Union[None, float, Pulse, Steps]
@@ -91,6 +96,63 @@ def solve_1d(
91
96
  ... t1=1.0, t2=0.5, pump=Pulse(a=0.1, x0=50, w=10))
92
97
  >>> exit_intensity = res.intensity[-1]
93
98
  """
99
+ g = _prepare(t_max=t_max, nt=nt, nz=nz, t1=t1, t2=t2, theta0=theta0, w0=w0, R0=R0,
100
+ pump=pump, field_in=field_in, n_planes=n_planes)
101
+ w, intensity = solve_kernel(g["t"], g["dt"], g["z"], g["dz"], g["n_planes"], g["w_z"], g["R_z"],
102
+ g["field_t"], g["pump_t"], g["t1_t"], g["t2_t"], float(eta))
103
+ return Result(time=g["t"], z=g["planes"], intensity=intensity, w=w, pump=g["pump_t"],
104
+ field_in=g["field_t"], t1=g["t1_t"], t2=g["t2_t"])
105
+
106
+
107
+ def solve_1d_adiabatic(
108
+ *,
109
+ t_max: float,
110
+ nt: int,
111
+ nz: int,
112
+ eta: float,
113
+ t1: Union[float, Steps],
114
+ t2: Union[float, Steps],
115
+ theta0: Optional[float] = None,
116
+ w0: Optional[float] = None,
117
+ R0: Optional[float] = None,
118
+ pump: Union[Profile, Sequence[Profile]] = None,
119
+ field_in: Profile = None,
120
+ n_planes: int = 2,
121
+ ) -> Result:
122
+ """Solve the adiabatic (rate-equation) limit of the two-level equations.
123
+
124
+ Sets ``dR/dt = 0``, so ``R = R0 - T2 A w`` and only two equations are solved::
125
+
126
+ dw/dt = A R0 - T2 A² w - (w - w0) / T1 + Λ(t)
127
+ dA/dz = -η R0 + η T2 A w
128
+
129
+ The limit holds when ``T2`` is short compared with the times over which ``A`` and ``w``
130
+ change; it differs from :func:`solve_1d` during the first few ``T2`` and in bursts faster
131
+ than ``T2``. Same arguments and grids as :func:`solve_1d`, so the two can be compared
132
+ directly; ``t2`` must be finite. The result also carries ``R``. Derivation and numerical
133
+ scheme: ``docs/two_level.pdf``, section "Adiabatic (Rate-Equation) Limit".
134
+
135
+ Raises:
136
+ ValueError: As :func:`solve_1d`, and if ``t2`` is infinite anywhere.
137
+
138
+ Example:
139
+ >>> res = solve_1d_adiabatic(t_max=200, nt=4000, nz=200, eta=5.0, theta0=0.01,
140
+ ... t1=1.0, t2=0.5, pump=Pulse(a=0.1, x0=50, w=10))
141
+ >>> exit_intensity, exit_coherence = res.intensity[-1], res.R[-1]
142
+ """
143
+ g = _prepare(t_max=t_max, nt=nt, nz=nz, t1=t1, t2=t2, theta0=theta0, w0=w0, R0=R0,
144
+ pump=pump, field_in=field_in, n_planes=n_planes)
145
+ if not np.all(np.isfinite(g["t2_t"])):
146
+ raise ValueError("t2 must be finite in the adiabatic limit")
147
+ w, intensity, R = _solve_kernel_adiabatic(
148
+ g["t"], g["dt"], g["z"], g["dz"], g["n_planes"], g["w_z"], g["R_z"],
149
+ g["field_t"], g["pump_t"], g["t1_t"], g["t2_t"], float(eta))
150
+ return Result(time=g["t"], z=g["planes"], intensity=intensity, w=w, pump=g["pump_t"],
151
+ field_in=g["field_t"], t1=g["t1_t"], t2=g["t2_t"], R=R)
152
+
153
+
154
+ def _prepare(*, t_max, nt, nz, t1, t2, theta0, w0, R0, pump, field_in, n_planes):
155
+ """Validate the arguments and build grids and profiles (shared by both solvers)."""
94
156
  nt, nz, n_planes = int(nt), int(nz), int(n_planes)
95
157
  if nt < 2 or nz < 2:
96
158
  raise ValueError("nt and nz must be at least 2")
@@ -123,9 +185,6 @@ def solve_1d(
123
185
 
124
186
  w_z = np.full_like(z, w_init)
125
187
  R_z = np.full_like(z, R_init)
126
- w, intensity = solve_kernel(t, dt, z, dz, n_planes, w_z, R_z, field_t, pump_t,
127
- t1_t, t2_t, float(eta))
128
-
129
188
  planes = z[np.rint(np.linspace(0.0, 1.0, n_planes) * (nz - 1)).astype(np.int64)]
130
- return Result(time=t, z=planes, intensity=intensity, w=w, pump=pump_t,
131
- field_in=field_t, t1=t1_t, t2=t2_t)
189
+ return dict(t=t, dt=dt, z=z, dz=dz, n_planes=n_planes, w_z=w_z, R_z=R_z, field_t=field_t,
190
+ pump_t=pump_t, t1_t=t1_t, t2_t=t2_t, planes=planes)
@@ -0,0 +1,100 @@
1
+ """Two-level Maxwell-Bloch equations, adiabatic (rate-equation) limit, one dimension.
2
+
3
+ With dR/dt = 0 the coherence follows the field and the population::
4
+
5
+ R = R0 - T2 A w
6
+
7
+ so only two equations remain::
8
+
9
+ dw/dt = A R0 - T2 A² w - (w - w0) / T1 + Λ
10
+ dA/dz = -η R = -η R0 + η T2 A w
11
+
12
+ Same grids and z step as ``_kernel_1d`` (explicit step in z for the field using ``R`` of the
13
+ previous plane; ``A``, ``T1``, ``T2`` and ``Λ`` held at the start of each time step). In time,
14
+ ``w`` is advanced by the exact solution of its (then linear) equation instead of RK4, because
15
+ ``T2 A²`` makes the equation stiff when the field is strong.
16
+ """
17
+
18
+ from __future__ import annotations
19
+
20
+ import numpy as np
21
+ from numba import njit
22
+
23
+
24
+ @njit(inline="always", nogil=True, cache=True)
25
+ def _step_w(w, A, inv_t1, t2, w0, R0, lambda_n, dt):
26
+ """Exact step of the linear equation dw/dt = a - b w (coefficients frozen over the step).
27
+
28
+ ``b = T2 A² + 1/T1`` can be large for a strong field (stiff), so an explicit RK4 step
29
+ would blow up; this step is stable for any ``dt``.
30
+ """
31
+ a = A * R0 + w0 * inv_t1 + lambda_n
32
+ b = t2 * A * A + inv_t1
33
+ bdt = b * dt
34
+ if bdt < 1e-12:
35
+ return w + (a - b * w) * dt
36
+ return w + (a - b * w) * (-np.expm1(-bdt)) / b
37
+
38
+
39
+ @njit(nogil=True, cache=True)
40
+ def _march_plane(w, R, A, w0, R0, inv_t1, t2, lambda_n, dt):
41
+ """Fill ``w`` and ``R`` on one z plane for the field ``A`` already known there."""
42
+ nt = len(w)
43
+ w[0] = w0
44
+ R[0] = R0 - t2[0] * A[0] * w[0]
45
+ for t_idx in range(1, nt):
46
+ w[t_idx] = _step_w(w[t_idx - 1], A[t_idx - 1], inv_t1[t_idx - 1], t2[t_idx - 1], w0, R0,
47
+ lambda_n[t_idx - 1], dt)
48
+ R[t_idx] = R0 - t2[t_idx] * A[t_idx] * w[t_idx]
49
+
50
+
51
+ @njit(nogil=True, cache=True)
52
+ def solve_kernel(t, dt, z, dz, n_z_planes, w0, R0, A0, lambda_n, t1, t2, eta):
53
+ """Advance the system over the grid (same arguments as ``_kernel_1d.solve_kernel``).
54
+
55
+ ``t2`` must be finite.
56
+
57
+ Returns:
58
+ ``(w, I, R)``, each of shape ``(n_z_planes, len(t))``.
59
+ """
60
+ nt = len(t)
61
+ nz = len(z)
62
+ z_planes = np.linspace(0.0, 1.0, n_z_planes)
63
+ z_plane_indices = np.rint(z_planes * (nz - 1)).astype(np.int64)
64
+
65
+ inv_t1 = 1.0 / t1
66
+
67
+ w_old = np.empty(nt, dtype=np.float64)
68
+ R_old = np.empty(nt, dtype=np.float64)
69
+ A_old = A0.copy()
70
+
71
+ w_new = np.empty_like(w_old)
72
+ R_new = np.empty_like(R_old)
73
+ A_new = np.empty_like(A_old)
74
+
75
+ w_result = np.empty((n_z_planes, nt), dtype=np.float64)
76
+ I_result = np.empty((n_z_planes, nt), dtype=np.float64)
77
+ R_result = np.empty((n_z_planes, nt), dtype=np.float64)
78
+
79
+ _march_plane(w_old, R_old, A_old, w0[0], R0[0], inv_t1, t2, lambda_n, dt)
80
+ w_result[0, :] = w_old
81
+ I_result[0, :] = A_old * A_old
82
+ R_result[0, :] = R_old
83
+ i = 1
84
+
85
+ for z_idx in range(1, nz):
86
+ for t_idx in range(nt):
87
+ A_new[t_idx] = A_old[t_idx] - eta * R_old[t_idx] * dz
88
+ _march_plane(w_new, R_new, A_new, w0[z_idx], R0[z_idx], inv_t1, t2, lambda_n, dt)
89
+
90
+ if i < n_z_planes and z_plane_indices[i] == z_idx:
91
+ w_result[i, :] = w_new
92
+ I_result[i, :] = A_new * A_new
93
+ R_result[i, :] = R_new
94
+ i += 1
95
+
96
+ w_old, w_new = w_new, w_old
97
+ R_old, R_new = R_new, R_old
98
+ A_old, A_new = A_new, A_old
99
+
100
+ return w_result, I_result, R_result
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: mbsolver
3
- Version: 0.4.0
3
+ Version: 0.5.0
4
4
  Summary: Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation
5
5
  Author: Toktam Rashidi
6
6
  Author-email: Vahid Anari <vahid.anari8@gmail.com>
@@ -65,6 +65,8 @@ dA/dz = −η R
65
65
 
66
66
  The field `A(t)` entering at `z = 0` is given; population and coherence are
67
67
  advanced with fourth-order Runge-Kutta in time, the field step by step in `z`.
68
+ The derivation from the two-level Hamiltonian is in
69
+ [`docs/two_level.pdf`](docs/two_level.pdf).
68
70
 
69
71
  ```python
70
72
  import matplotlib.pyplot as plt
@@ -103,6 +105,22 @@ plt.show()
103
105
  `res.time`, `res.z` (positions of the stored planes), `res.intensity` and
104
106
  `res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
105
107
 
108
+ ### Adiabatic (rate-equation) limit
109
+
110
+ When `T2` is short compared with the times over which `A` and `w` change, the
111
+ coherence follows its steady state, `R = R0 − T2 A w`, and two equations remain:
112
+
113
+ ```
114
+ dw/dt = A R0 − T2 A² w − (w − w0) / T1 + Λ(t)
115
+ dA/dz = −η R0 + η T2 A w
116
+ ```
117
+
118
+ `solve_1d_adiabatic` takes the same arguments as `solve_1d` (with a finite
119
+ `t2`) and returns the same result plus `res.R`, so the two can be compared
120
+ directly. The limit differs from the full system during the first few `T2`
121
+ and in bursts faster than `T2`; see the section on it in
122
+ [`docs/two_level.pdf`](docs/two_level.pdf).
123
+
106
124
  ## Three-level (Λ) model in one dimension
107
125
 
108
126
  Levels 1 and 2 lie below level 3; the transitions 3→1 and 3→2 carry the fields
@@ -151,11 +169,13 @@ and the pump scale `lambda0 = n0/t0`. By default the decay rate of the 3→2
151
169
  line is the Einstein A computed from `d32`; pass `gamma=` to use a measured one.
152
170
 
153
171
  The three-level equations were derived and checked with Toktam Rashidi. The
154
- derivation, the final dimensionless equations, the initial conditions and the
155
- CH₃OH data are in [`docs/three_level/`](docs/three_level/);
172
+ derivation, from the Hamiltonian to the dimensionless equations, with the
173
+ initial conditions, physical scales and the S255IR-NIRS3 values, is in
174
+ [`docs/three_level.pdf`](docs/three_level.pdf);
156
175
  [`examples/three_level/s255_flare.py`](examples/three_level/s255_flare.py)
157
176
  runs the S255IR-NIRS3 flare and plots it with the observed flux (needs
158
- matplotlib).
177
+ matplotlib). The observations are from the Toruń 32 m telescope,
178
+ [Szymczak et al. 2018, A&A 617, A80](https://doi.org/10.1051/0004-6361/201833443).
159
179
 
160
180
  ## From physical values: `scaling` (two-level)
161
181
 
@@ -205,6 +225,10 @@ entrance, relaxation balance, uncoupled propagation). The three-level model
205
225
  matches the 2025 three-level solver exactly for the S255IR-NIRS3 case. `scaling`
206
226
  is checked against the values of Maxwell Bloch Studio.
207
227
 
228
+ The model documents `docs/two_level.pdf` and `docs/three_level.pdf` are built
229
+ from their LaTeX sources with `sh tools/build_docs.sh` (needs LaTeX with
230
+ `latexmk`); commit the rebuilt PDFs with the sources.
231
+
208
232
  What changed in each version is in [`CHANGELOG.md`](CHANGELOG.md). Pushing a
209
233
  tag `vX.Y.Z` publishes a GitHub Release with that version's section of the
210
234
  changelog, and Zenodo gives it a DOI; update `version` and `date-released` in
@@ -239,7 +263,9 @@ Vahid Anari ·
239
263
  [GitHub](https://github.com/vahid-anari) ·
240
264
  [LinkedIn](https://www.linkedin.com/in/vahid-anari/)
241
265
 
242
- Toktam Rashidi (three-level model)
266
+ Toktam Rashidi ·
267
+ [GitHub](https://github.com/ToktamS) ·
268
+ [LinkedIn](https://www.linkedin.com/in/toktam-r-71951996/)
243
269
 
244
270
  Related projects: [sciwidgets](https://github.com/vahid-anari/sciwidgets) ·
245
271
  [Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio) ·
@@ -16,7 +16,9 @@ src/mbsolver/three_level/_kernel_1d.py
16
16
  src/mbsolver/three_level/sample.py
17
17
  src/mbsolver/two_level/__init__.py
18
18
  src/mbsolver/two_level/_kernel_1d.py
19
+ src/mbsolver/two_level/_kernel_adiabatic_1d.py
19
20
  tests/test_profiles.py
20
21
  tests/test_sample.py
21
22
  tests/test_three_level.py
22
- tests/test_two_level.py
23
+ tests/test_two_level.py
24
+ tests/test_two_level_adiabatic.py
@@ -0,0 +1,59 @@
1
+ """Tests for mbsolver.two_level.solve_1d_adiabatic (rate-equation limit)."""
2
+
3
+ import math
4
+
5
+ import numpy as np
6
+ import pytest
7
+
8
+ from mbsolver import Pulse
9
+ from mbsolver.two_level import solve_1d, solve_1d_adiabatic
10
+
11
+ CASE = dict(t_max=300, nt=6001, nz=201, eta=40.0, theta0=0.003, t1=50.0,
12
+ pump=Pulse(a=2e-3, x0=100, w=20), n_planes=2)
13
+
14
+
15
+ def test_short_t2_matches_full_solver():
16
+ """With T2 much shorter than every other time scale, R follows its steady state.
17
+
18
+ Only the start-up transient (a few T2, while the full solver builds R) differs.
19
+ """
20
+ full = solve_1d(**CASE, t2=0.05)
21
+ adiabatic = solve_1d_adiabatic(**CASE, t2=0.05)
22
+ later = full.time > 1.0
23
+ np.testing.assert_allclose(adiabatic.w[:, later], full.w[:, later], atol=2e-3)
24
+ np.testing.assert_allclose(adiabatic.intensity[-1, later], full.intensity[-1, later], rtol=2e-2)
25
+
26
+
27
+ @pytest.mark.parametrize("t2", [0.5, 5.0])
28
+ def test_late_times_match_full_solver(t2):
29
+ """Once the transients are over, both solvers reach the same state."""
30
+ full = solve_1d(**CASE, t2=t2)
31
+ adiabatic = solve_1d_adiabatic(**CASE, t2=t2)
32
+ np.testing.assert_allclose(adiabatic.intensity[-1, -1], full.intensity[-1, -1], rtol=1e-3)
33
+ np.testing.assert_allclose(adiabatic.w[-1, -1], full.w[-1, -1], rtol=1e-3, atol=1e-6)
34
+
35
+
36
+ def test_coherence_is_the_steady_state():
37
+ """R returned is R0 - T2 A w on every stored plane."""
38
+ res = solve_1d_adiabatic(t_max=50, nt=501, nz=11, eta=2.0, w0=0.9, R0=0.01, t1=10.0, t2=0.3,
39
+ field_in=Pulse(a=0.05, x0=20, w=5), n_planes=11)
40
+ a = np.sqrt(res.intensity[0])
41
+ np.testing.assert_allclose(res.R[0], 0.01 - 0.3 * res.field_in * res.w[0], rtol=1e-12, atol=1e-15)
42
+ np.testing.assert_allclose(a, np.abs(res.field_in), rtol=1e-12)
43
+ assert res.R.shape == res.w.shape == (11, 501)
44
+
45
+
46
+ def test_stable_for_a_strong_field():
47
+ """T2 A² dt far beyond the explicit limit still gives finite, bounded populations."""
48
+ res = solve_1d_adiabatic(t_max=20, nt=201, nz=5, eta=1.0, w0=1.0, R0=0.0, t1=math.inf, t2=1.0,
49
+ field_in=50.0)
50
+ assert np.all(np.isfinite(res.w)) and np.all(np.abs(res.w) <= 1.0 + 1e-12)
51
+
52
+
53
+ def test_full_solver_returns_no_coherence():
54
+ assert solve_1d(**CASE, t2=0.5).R is None
55
+
56
+
57
+ def test_infinite_t2_is_refused():
58
+ with pytest.raises(ValueError, match="t2 must be finite"):
59
+ solve_1d_adiabatic(**CASE, t2=math.inf)
File without changes
File without changes
File without changes
File without changes