mbsolver 0.4.0__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 (26) hide show
  1. {mbsolver-0.4.0/src/mbsolver.egg-info → mbsolver-0.6.0}/PKG-INFO +33 -7
  2. {mbsolver-0.4.0 → mbsolver-0.6.0}/README.md +32 -6
  3. {mbsolver-0.4.0 → mbsolver-0.6.0}/pyproject.toml +1 -1
  4. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver/two_level/__init__.py +67 -8
  5. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver/two_level/_kernel_1d.py +6 -2
  6. mbsolver-0.6.0/src/mbsolver/two_level/_kernel_adiabatic_1d.py +100 -0
  7. {mbsolver-0.4.0 → mbsolver-0.6.0/src/mbsolver.egg-info}/PKG-INFO +33 -7
  8. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver.egg-info/SOURCES.txt +3 -1
  9. {mbsolver-0.4.0 → mbsolver-0.6.0}/tests/test_two_level.py +1 -0
  10. mbsolver-0.6.0/tests/test_two_level_adiabatic.py +60 -0
  11. {mbsolver-0.4.0 → mbsolver-0.6.0}/LICENSE +0 -0
  12. {mbsolver-0.4.0 → mbsolver-0.6.0}/setup.cfg +0 -0
  13. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver/__init__.py +0 -0
  14. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver/constants.py +0 -0
  15. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver/grids.py +0 -0
  16. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver/profiles.py +0 -0
  17. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver/sample.py +0 -0
  18. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver/three_level/__init__.py +0 -0
  19. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver/three_level/_kernel_1d.py +0 -0
  20. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver/three_level/sample.py +0 -0
  21. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver.egg-info/dependency_links.txt +0 -0
  22. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver.egg-info/requires.txt +0 -0
  23. {mbsolver-0.4.0 → mbsolver-0.6.0}/src/mbsolver.egg-info/top_level.txt +0 -0
  24. {mbsolver-0.4.0 → mbsolver-0.6.0}/tests/test_profiles.py +0 -0
  25. {mbsolver-0.4.0 → mbsolver-0.6.0}/tests/test_sample.py +0 -0
  26. {mbsolver-0.4.0 → mbsolver-0.6.0}/tests/test_three_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.6.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
@@ -100,8 +102,24 @@ plt.show()
100
102
 
101
103
  ### Result
102
104
 
103
- `res.time`, `res.z` (positions of the stored planes), `res.intensity` and
104
- `res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
105
+ `res.time`, `res.z` (positions of the stored planes), `res.intensity`,
106
+ `res.w` and `res.R` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
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 (`res.R` included, as from `solve_1d`), 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).
105
123
 
106
124
  ## Three-level (Λ) model in one dimension
107
125
 
@@ -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
@@ -68,8 +70,24 @@ plt.show()
68
70
 
69
71
  ### Result
70
72
 
71
- `res.time`, `res.z` (positions of the stored planes), `res.intensity` and
72
- `res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
73
+ `res.time`, `res.z` (positions of the stored planes), `res.intensity`,
74
+ `res.w` and `res.R` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
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 (`res.R` included, as from `solve_1d`), 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).
73
91
 
74
92
  ## Three-level (Λ) model in one dimension
75
93
 
@@ -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.6.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)`` (from both solvers;
43
+ ``None`` only for a hand-built result).
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]
@@ -89,8 +94,65 @@ def solve_1d(
89
94
  Example:
90
95
  >>> res = solve_1d(t_max=200, nt=4000, nz=200, eta=5.0, theta0=0.01,
91
96
  ... t1=1.0, t2=0.5, pump=Pulse(a=0.1, x0=50, w=10))
92
- >>> exit_intensity = res.intensity[-1]
97
+ >>> exit_intensity, exit_coherence = res.intensity[-1], res.R[-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, R = 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"], R=R)
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. 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)
@@ -2,6 +2,7 @@
2
2
 
3
3
  Moved unchanged from MB Solver 8.13 (``solver/maxwell_bloch.py``):
4
4
  RK4 in time for the population and coherence, explicit step in z for the field.
5
+ From 0.6.0 the coherence R is also stored on the returned planes (numerics unchanged).
5
6
 
6
7
  dw/dt = A R - (w - w0) / T1 + Λ
7
8
  dR/dt = -A w - (R - R0) / T2
@@ -68,7 +69,7 @@ def solve_kernel(t, dt, z, dz, n_z_planes, w0, R0, A0, lambda_n, t1, t2, eta):
68
69
  eta: Coupling coefficient.
69
70
 
70
71
  Returns:
71
- ``(w, I)``, each of shape ``(n_z_planes, len(t))``.
72
+ ``(w, I, R)``, each of shape ``(n_z_planes, len(t))``.
72
73
  """
73
74
  nt = len(t)
74
75
  nz = len(z)
@@ -90,6 +91,7 @@ def solve_kernel(t, dt, z, dz, n_z_planes, w0, R0, A0, lambda_n, t1, t2, eta):
90
91
 
91
92
  w_result = np.empty((n_z_planes, nt), dtype=np.float64)
92
93
  I_result = np.empty((n_z_planes, nt), dtype=np.float64)
94
+ R_result = np.empty((n_z_planes, nt), dtype=np.float64)
93
95
 
94
96
  w_old[0], R_old[0] = w0[0], R0[0]
95
97
  A_old[0] = A0[0]
@@ -108,6 +110,7 @@ def solve_kernel(t, dt, z, dz, n_z_planes, w0, R0, A0, lambda_n, t1, t2, eta):
108
110
 
109
111
  w_result[0, :] = w_old
110
112
  I_result[0, :] = A_old * A_old
113
+ R_result[0, :] = R_old
111
114
  i = 1
112
115
 
113
116
  for z_idx in range(1, nz):
@@ -129,10 +132,11 @@ def solve_kernel(t, dt, z, dz, n_z_planes, w0, R0, A0, lambda_n, t1, t2, eta):
129
132
  if i < n_z_planes and z_plane_indices[i] == z_idx:
130
133
  w_result[i, :] = w_new
131
134
  I_result[i, :] = A_new * A_new
135
+ R_result[i, :] = R_new
132
136
  i += 1
133
137
 
134
138
  w_old, w_new = w_new, w_old
135
139
  R_old, R_new = R_new, R_old
136
140
  A_old, A_new = A_new, A_old
137
141
 
138
- return w_result, I_result
142
+ return w_result, I_result, R_result
@@ -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.6.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
@@ -100,8 +102,24 @@ plt.show()
100
102
 
101
103
  ### Result
102
104
 
103
- `res.time`, `res.z` (positions of the stored planes), `res.intensity` and
104
- `res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
105
+ `res.time`, `res.z` (positions of the stored planes), `res.intensity`,
106
+ `res.w` and `res.R` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
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 (`res.R` included, as from `solve_1d`), 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).
105
123
 
106
124
  ## Three-level (Λ) model in one dimension
107
125
 
@@ -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
@@ -54,6 +54,7 @@ def test_entrance_is_a_bloch_rotation():
54
54
  dt = res.time[1] - res.time[0]
55
55
  area = np.concatenate(([0.0], np.cumsum(res.field_in[:-1]) * dt))
56
56
  np.testing.assert_allclose(res.w[0], np.cos(theta0 - area), atol=1e-9)
57
+ np.testing.assert_allclose(res.R[0], np.sin(theta0 - area), atol=1e-9)
57
58
 
58
59
 
59
60
  def test_no_coupling_leaves_field_unchanged():
@@ -0,0 +1,60 @@
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_coherence():
54
+ res = solve_1d(**CASE, t2=0.5)
55
+ assert res.R is not None and res.R.shape == res.w.shape
56
+
57
+
58
+ def test_infinite_t2_is_refused():
59
+ with pytest.raises(ValueError, match="t2 must be finite"):
60
+ solve_1d_adiabatic(**CASE, t2=math.inf)
File without changes
File without changes
File without changes
File without changes