mbsolver 0.6.1__tar.gz → 0.7.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. {mbsolver-0.6.1/src/mbsolver.egg-info → mbsolver-0.7.0}/PKG-INFO +68 -50
  2. {mbsolver-0.6.1 → mbsolver-0.7.0}/README.md +67 -49
  3. {mbsolver-0.6.1 → mbsolver-0.7.0}/pyproject.toml +1 -1
  4. mbsolver-0.7.0/src/mbsolver/three_level/__init__.py +260 -0
  5. mbsolver-0.7.0/src/mbsolver/three_level/_kernel_1d.py +170 -0
  6. mbsolver-0.7.0/src/mbsolver/three_level/sample.py +79 -0
  7. {mbsolver-0.6.1 → mbsolver-0.7.0/src/mbsolver.egg-info}/PKG-INFO +68 -50
  8. {mbsolver-0.6.1 → mbsolver-0.7.0}/src/mbsolver.egg-info/SOURCES.txt +1 -0
  9. mbsolver-0.7.0/tests/test_small_signal_gain.py +61 -0
  10. mbsolver-0.7.0/tests/test_three_level.py +236 -0
  11. mbsolver-0.6.1/src/mbsolver/three_level/__init__.py +0 -176
  12. mbsolver-0.6.1/src/mbsolver/three_level/_kernel_1d.py +0 -140
  13. mbsolver-0.6.1/src/mbsolver/three_level/sample.py +0 -85
  14. mbsolver-0.6.1/tests/test_three_level.py +0 -113
  15. {mbsolver-0.6.1 → mbsolver-0.7.0}/LICENSE +0 -0
  16. {mbsolver-0.6.1 → mbsolver-0.7.0}/setup.cfg +0 -0
  17. {mbsolver-0.6.1 → mbsolver-0.7.0}/src/mbsolver/__init__.py +0 -0
  18. {mbsolver-0.6.1 → mbsolver-0.7.0}/src/mbsolver/constants.py +0 -0
  19. {mbsolver-0.6.1 → mbsolver-0.7.0}/src/mbsolver/grids.py +0 -0
  20. {mbsolver-0.6.1 → mbsolver-0.7.0}/src/mbsolver/profiles.py +0 -0
  21. {mbsolver-0.6.1 → mbsolver-0.7.0}/src/mbsolver/sample.py +0 -0
  22. {mbsolver-0.6.1 → mbsolver-0.7.0}/src/mbsolver/two_level/__init__.py +0 -0
  23. {mbsolver-0.6.1 → mbsolver-0.7.0}/src/mbsolver/two_level/_kernel_1d.py +0 -0
  24. {mbsolver-0.6.1 → mbsolver-0.7.0}/src/mbsolver/two_level/_kernel_adiabatic_1d.py +0 -0
  25. {mbsolver-0.6.1 → mbsolver-0.7.0}/src/mbsolver.egg-info/dependency_links.txt +0 -0
  26. {mbsolver-0.6.1 → mbsolver-0.7.0}/src/mbsolver.egg-info/requires.txt +0 -0
  27. {mbsolver-0.6.1 → mbsolver-0.7.0}/src/mbsolver.egg-info/top_level.txt +0 -0
  28. {mbsolver-0.6.1 → mbsolver-0.7.0}/tests/test_profiles.py +0 -0
  29. {mbsolver-0.6.1 → mbsolver-0.7.0}/tests/test_sample.py +0 -0
  30. {mbsolver-0.6.1 → mbsolver-0.7.0}/tests/test_two_level.py +0 -0
  31. {mbsolver-0.6.1 → mbsolver-0.7.0}/tests/test_two_level_adiabatic.py +0 -0
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: mbsolver
3
- Version: 0.6.1
3
+ Version: 0.7.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>
@@ -41,9 +41,8 @@ Dynamic: license-file
41
41
 
42
42
  Fast Maxwell-Bloch solvers in Python (numpy + numba) for astrophysical masers,
43
43
  superradiance and coherent pulse propagation. Use them from scripts,
44
- notebooks or cluster jobs; the
45
- [Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio)
46
- desktop app runs on the same code.
44
+ notebooks or cluster jobs; the Maxwell Bloch Studio desktop app runs on
45
+ the same code.
47
46
 
48
47
  ## Installation
49
48
 
@@ -123,61 +122,66 @@ directly. The limit differs from the full system during the first few `T2`
123
122
  and in bursts faster than `T2`; see the section on it in
124
123
  [`docs/two_level.pdf`](docs/two_level.pdf).
125
124
 
126
- ## Three-level (Λ) model in one dimension
125
+ ## Three-level model in one dimension
127
126
 
128
- Levels 1 and 2 lie below level 3; the transitions 3→1 and 3→2 carry the fields
129
- `E31` and `E32`. With the population differences `n31 = n3 − n1`,
130
- `n32 = n3 − n2` and the coherences `R31`, `R32`, `R21` (all real):
127
+ Levels are ordered by energy, `E1 < E2 < E3`. Two of the three transitions
128
+ are dipole allowed and carry fields; the third is forbidden:
129
+
130
+ | `config` | allowed | forbidden |
131
+ |------------|-------------|-----------|
132
+ | `"lambda"` | 3→1, 3→2 | 2↔1 |
133
+ | `"v"` | 2→1, 3→1 | 3↔2 |
134
+ | `"ladder"` | 2→1, 3→2 | 3↔1 |
135
+
136
+ With `n_ij = n_i − n_j`, `W_ij = ½ E_ij R_ij` and fields as Rabi frequencies,
137
+ the dimensionless equations along `0 ≤ z ≤ 1` are
131
138
 
132
139
  ```
133
- dn31/dt = −(E31 R31 + ½ E32 R32) − (n31 − n31⁰) / T1_31 + Λ31(t)
134
- dn32/dt = −(½ E31 R31 + E32 R32) − (n32 − n32⁰) / T1_32 + Λ32(t)
135
- dR31/dt = E31 n31 − ½ E32 R21 − (R31 − R31⁰) / T2_31
136
- dR32/dt = E32 n32 − ½ E31 R21 − (R32 − R32⁰) / T2_32
137
- dR21/dt = ½ (E31 R32 + E32 R31) − (R21 − R21⁰) / T2_21
138
- dE31/dz = η R31, dE32/dz = R32, η = ω d²
140
+ dn1/dt = W21 + W31, dn2/dt = W32 − W21, dn3/dt = −W31 − W32
141
+ dR21/dt = E21 n21 + ½ (E31 R32 + E32 R31) − (R21 − R21⁰) / T2_21
142
+ dR31/dt = E31 n31 + ½ (E21 R32 − E32 R21) − (R31 − R31⁰) / T2_31
143
+ dR32/dt = E32 n32 − ½ (E21 R31 + E31 R21) − (R32 − R32⁰) / T2_32
144
+ dE_ij/dz = η_ij R_ij
139
145
  ```
140
146
 
141
- with `d = |d31/d32|` and `ω = k31/k32`. Time is in units of the 3→2 time
142
- scale `T0 = 2ε0ħ / (n0 L k32 |d32|²)`. The initial state comes from the
143
- population ratios `r1 = n3/n1`, `r2 = n3/n2` and the coherence fractions
144
- `c_ij`: `R_ij⁰ = c_ij · 2√(n_i n_j)`.
147
+ The field of the forbidden transition is zero. The population differences of
148
+ the two allowed transitions relax with their `T1` and are pumped. In Λ and V
149
+ the two transitions compete for the shared level; in the ladder, emission on
150
+ the upper step raises the inversion of the lower one (a cascade).
145
151
 
146
152
  ```python
147
- from mbsolver import Pulse
153
+ import math
148
154
  from mbsolver.three_level import solve_1d
149
155
 
150
156
  res = solve_1d(
151
- t_max=2500, nt=4000, nz=400, d=0.875, omega=35.95,
152
- r1=0.94, r2=2.33e19, c31=1e-10, c32=1.0, # c21 = 0 by default
153
- t1_31=31.3, t1_32=313, t2_31=2.96, t2_32=29.6, # t2_21 = inf by default
154
- pump32=Pulse(a=5.63e-3, x0=795.5, w=154.8), # pump31, field31_in, field32_in too
157
+ config="ladder", t_max=200, nt=2001, nz=101,
158
+ n_init=(0.05, 0.05, 0.9), # (n1, n2, n3), summing to 1
159
+ eta21=10.0, eta32=10.0, # couplings of the allowed transitions
160
+ c21=1e-3, c32=1e-3, # seeds: R_ij⁰ = c_ij · 2√(n_i n_j)
161
+ t1_21=math.inf, t1_32=math.inf,
162
+ t2_21=math.inf, t2_32=math.inf, # t2 of the forbidden pair: inf by default
155
163
  )
156
- res.intensity32[-1] # 3→2 intensity leaving the medium
164
+ res.e32[-1], res.e21[-1] # upper step bursts first, then the lower one
157
165
  ```
158
166
 
159
- `t1_*` and `t2_*` take numbers or `Steps`, the pumps and entrance fields
160
- `Pulse`s, numbers or lists, as in the two-level model. The result holds
161
- `time`, `z`, the fields `e31`, `e32`, the intensities `intensity31 = (E31/d)²`
162
- and `intensity32 = E32²` (both in units of the 3→2 scale), `n31`, `n32`,
163
- `r31`, `r32`, `r21` (shape `(n_planes, nt)`), and the pumps, entrance fields
164
- and relaxation times on the time grid.
167
+ `eta_ij`, `t1_ij`, `pump_ij` and `field_ij_in` are given only for the allowed
168
+ transitions; `t2_ij` and `c_ij` exist for all three coherences. Relaxation
169
+ times take numbers or `Steps`, pumps and entrance fields `Pulse`s, numbers or
170
+ lists, as in the two-level model. The result holds `time`, `z`, the fields
171
+ `e21`, `e31`, `e32`, the differences `n21`, `n31`, `n32` and the coherences
172
+ `r21`, `r31`, `r32` (shape `(n_planes, nt)`), and the inputs on the time grid.
165
173
 
166
- `populations(r1, r2)` gives `n1`, `n2`, `n3`, `n31⁰`, `n32⁰` and the largest
167
- coherences. `scaling(nu31, nu32, d31, d32, l, n0)` (SI units;
168
- `mbsolver.constants.DEBYE` converts dipoles from debye) gives `d`, `omega`,
169
- `eta`, `t0`, the field and intensity scales `e0`, `i0` (and `i0_jy` = 10²⁶ `i0`)
170
- and the pump scale `lambda0 = n0/t0`. By default the decay rate of the 3→2
171
- line is the Einstein A computed from `d32`; pass `gamma=` to use a measured one.
174
+ Time is in units of a free time unit `T0`; each transition has
175
+ `η_ij = T0 / T_R` with the cooperation time `T_R = 2ε0ħ / (n0 L k_ij |d_ij|²)`.
176
+ `mbsolver.three_level.scaling(t0=, l=, n0=, nu31=, d31=, ...)` computes, for
177
+ each transition given by its frequency and its dipole moment (or Einstein
178
+ coefficient `gamma_ij`), `eta_ij`, `t_r_ij` and the field and intensity scales
179
+ `e0_ij`, `i0_ij`; `mbsolver.constants.DEBYE` converts dipoles from debye.
172
180
 
173
181
  The three-level equations were derived and checked with Toktam Rashidi. The
174
182
  derivation, from the Hamiltonian to the dimensionless equations, with the
175
- initial conditions, physical scales and the S255IR-NIRS3 values, is in
176
- [`docs/three_level.pdf`](docs/three_level.pdf);
177
- [`examples/three_level/s255_flare.py`](examples/three_level/s255_flare.py)
178
- runs the S255IR-NIRS3 flare and plots it with the observed flux (needs
179
- matplotlib). The observations are from the Toruń 32 m telescope,
180
- [Szymczak et al. 2018, A&A 617, A80](https://doi.org/10.1051/0004-6361/201833443).
183
+ three configurations, initial conditions and physical scales, is in
184
+ [`docs/three_level.pdf`](docs/three_level.pdf).
181
185
 
182
186
  ## From physical values: `scaling` (two-level)
183
187
 
@@ -191,8 +195,8 @@ import math
191
195
  import mbsolver
192
196
  from mbsolver.two_level import solve_1d
193
197
 
194
- s = mbsolver.scaling(nu=6.67e9, gamma=1.56e-9, t0=86400, l=7.5e12, n0=5.3e-7)
195
- res = solve_1d(t_max=2000, nt=20001, nz=101, eta=s["eta"], theta0=s["theta0"],
198
+ s = mbsolver.scaling(nu=1.0e9, gamma=1.0e-8, t0=1.0e4, l=1.0e12, n0=1.0e-5) # η ≈ 10.7
199
+ res = solve_1d(t_max=100, nt=20001, nz=101, eta=s["eta"], theta0=s["theta0"],
196
200
  t1=math.inf, t2=math.inf)
197
201
  ```
198
202
 
@@ -202,6 +206,17 @@ and intensity scales for an electric dipole (`d`, `e0`, `p0`, `i0_electric`)
202
206
  and a magnetic dipole (`mu`, `b0`, `m0`, `i0_magnetic`). Times in the solver
203
207
  are in units of `t0`.
204
208
 
209
+ ## Examples
210
+
211
+ Two short scripts in [`examples/`](examples) (in the repository, not in the
212
+ PyPI package; they need matplotlib):
213
+
214
+ - [`examples/two_level/burst.py`](examples/two_level/burst.py): superradiant
215
+ bursts of a fully inverted two-level medium for three couplings η.
216
+ - [`examples/three_level/configurations.py`](examples/three_level/configurations.py):
217
+ the Λ, V and ladder configurations side by side, showing the competition for
218
+ a shared level and the ladder's cascade.
219
+
205
220
  ## Profiles
206
221
 
207
222
  `Pulse(a, x0, w)` is a sum of sech² pulses, `a_i sech²((t − x0_i) / w_i)`.
@@ -223,8 +238,10 @@ pytest
223
238
 
224
239
  The tests include a reference run that must match the solver of the Maxwell
225
240
  Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
226
- entrance, relaxation balance, uncoupled propagation). The three-level model
227
- matches the 2025 three-level solver exactly for the S255IR-NIRS3 case. `scaling`
241
+ entrance, relaxation balance, uncoupled propagation, small-signal gain). The three-level
242
+ Λ case must match a stored run of the earlier Λ-only solver; all three configurations
243
+ are checked for purity conservation, Bloch rotation and the reduction to the two-level
244
+ model. `scaling`
228
245
  is checked against the values of Maxwell Bloch Studio.
229
246
 
230
247
  The model documents `docs/two_level.pdf` and `docs/three_level.pdf` are built
@@ -263,12 +280,13 @@ MIT License. See [LICENSE](LICENSE).
263
280
 
264
281
  Vahid Anari ·
265
282
  [GitHub](https://github.com/vahid-anari) ·
266
- [LinkedIn](https://www.linkedin.com/in/vahid-anari/)
283
+ [LinkedIn](https://www.linkedin.com/in/vahid-anari/) ·
284
+ [ORCID](https://orcid.org/0000-0002-2464-3989)
267
285
 
268
286
  Toktam Rashidi ·
269
- [GitHub](https://github.com/ToktamS) ·
270
- [LinkedIn](https://www.linkedin.com/in/toktam-r-71951996/)
287
+ [GitHub](https://github.com/toktamrashidi) ·
288
+ [LinkedIn](https://www.linkedin.com/in/toktam-r-71951996/) ·
289
+ [ORCID](https://orcid.org/0009-0007-2978-7985)
271
290
 
272
291
  Related projects: [sciwidgets](https://github.com/vahid-anari/sciwidgets) ·
273
- [Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio) ·
274
292
  [linecat](https://github.com/vahid-anari/linecat)
@@ -8,9 +8,8 @@
8
8
 
9
9
  Fast Maxwell-Bloch solvers in Python (numpy + numba) for astrophysical masers,
10
10
  superradiance and coherent pulse propagation. Use them from scripts,
11
- notebooks or cluster jobs; the
12
- [Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio)
13
- desktop app runs on the same code.
11
+ notebooks or cluster jobs; the Maxwell Bloch Studio desktop app runs on
12
+ the same code.
14
13
 
15
14
  ## Installation
16
15
 
@@ -90,61 +89,66 @@ directly. The limit differs from the full system during the first few `T2`
90
89
  and in bursts faster than `T2`; see the section on it in
91
90
  [`docs/two_level.pdf`](docs/two_level.pdf).
92
91
 
93
- ## Three-level (Λ) model in one dimension
92
+ ## Three-level model in one dimension
94
93
 
95
- Levels 1 and 2 lie below level 3; the transitions 3→1 and 3→2 carry the fields
96
- `E31` and `E32`. With the population differences `n31 = n3 − n1`,
97
- `n32 = n3 − n2` and the coherences `R31`, `R32`, `R21` (all real):
94
+ Levels are ordered by energy, `E1 < E2 < E3`. Two of the three transitions
95
+ are dipole allowed and carry fields; the third is forbidden:
96
+
97
+ | `config` | allowed | forbidden |
98
+ |------------|-------------|-----------|
99
+ | `"lambda"` | 3→1, 3→2 | 2↔1 |
100
+ | `"v"` | 2→1, 3→1 | 3↔2 |
101
+ | `"ladder"` | 2→1, 3→2 | 3↔1 |
102
+
103
+ With `n_ij = n_i − n_j`, `W_ij = ½ E_ij R_ij` and fields as Rabi frequencies,
104
+ the dimensionless equations along `0 ≤ z ≤ 1` are
98
105
 
99
106
  ```
100
- dn31/dt = −(E31 R31 + ½ E32 R32) − (n31 − n31⁰) / T1_31 + Λ31(t)
101
- dn32/dt = −(½ E31 R31 + E32 R32) − (n32 − n32⁰) / T1_32 + Λ32(t)
102
- dR31/dt = E31 n31 − ½ E32 R21 − (R31 − R31⁰) / T2_31
103
- dR32/dt = E32 n32 − ½ E31 R21 − (R32 − R32⁰) / T2_32
104
- dR21/dt = ½ (E31 R32 + E32 R31) − (R21 − R21⁰) / T2_21
105
- dE31/dz = η R31, dE32/dz = R32, η = ω d²
107
+ dn1/dt = W21 + W31, dn2/dt = W32 − W21, dn3/dt = −W31 − W32
108
+ dR21/dt = E21 n21 + ½ (E31 R32 + E32 R31) − (R21 − R21⁰) / T2_21
109
+ dR31/dt = E31 n31 + ½ (E21 R32 − E32 R21) − (R31 − R31⁰) / T2_31
110
+ dR32/dt = E32 n32 − ½ (E21 R31 + E31 R21) − (R32 − R32⁰) / T2_32
111
+ dE_ij/dz = η_ij R_ij
106
112
  ```
107
113
 
108
- with `d = |d31/d32|` and `ω = k31/k32`. Time is in units of the 3→2 time
109
- scale `T0 = 2ε0ħ / (n0 L k32 |d32|²)`. The initial state comes from the
110
- population ratios `r1 = n3/n1`, `r2 = n3/n2` and the coherence fractions
111
- `c_ij`: `R_ij⁰ = c_ij · 2√(n_i n_j)`.
114
+ The field of the forbidden transition is zero. The population differences of
115
+ the two allowed transitions relax with their `T1` and are pumped. In Λ and V
116
+ the two transitions compete for the shared level; in the ladder, emission on
117
+ the upper step raises the inversion of the lower one (a cascade).
112
118
 
113
119
  ```python
114
- from mbsolver import Pulse
120
+ import math
115
121
  from mbsolver.three_level import solve_1d
116
122
 
117
123
  res = solve_1d(
118
- t_max=2500, nt=4000, nz=400, d=0.875, omega=35.95,
119
- r1=0.94, r2=2.33e19, c31=1e-10, c32=1.0, # c21 = 0 by default
120
- t1_31=31.3, t1_32=313, t2_31=2.96, t2_32=29.6, # t2_21 = inf by default
121
- pump32=Pulse(a=5.63e-3, x0=795.5, w=154.8), # pump31, field31_in, field32_in too
124
+ config="ladder", t_max=200, nt=2001, nz=101,
125
+ n_init=(0.05, 0.05, 0.9), # (n1, n2, n3), summing to 1
126
+ eta21=10.0, eta32=10.0, # couplings of the allowed transitions
127
+ c21=1e-3, c32=1e-3, # seeds: R_ij⁰ = c_ij · 2√(n_i n_j)
128
+ t1_21=math.inf, t1_32=math.inf,
129
+ t2_21=math.inf, t2_32=math.inf, # t2 of the forbidden pair: inf by default
122
130
  )
123
- res.intensity32[-1] # 3→2 intensity leaving the medium
131
+ res.e32[-1], res.e21[-1] # upper step bursts first, then the lower one
124
132
  ```
125
133
 
126
- `t1_*` and `t2_*` take numbers or `Steps`, the pumps and entrance fields
127
- `Pulse`s, numbers or lists, as in the two-level model. The result holds
128
- `time`, `z`, the fields `e31`, `e32`, the intensities `intensity31 = (E31/d)²`
129
- and `intensity32 = E32²` (both in units of the 3→2 scale), `n31`, `n32`,
130
- `r31`, `r32`, `r21` (shape `(n_planes, nt)`), and the pumps, entrance fields
131
- and relaxation times on the time grid.
134
+ `eta_ij`, `t1_ij`, `pump_ij` and `field_ij_in` are given only for the allowed
135
+ transitions; `t2_ij` and `c_ij` exist for all three coherences. Relaxation
136
+ times take numbers or `Steps`, pumps and entrance fields `Pulse`s, numbers or
137
+ lists, as in the two-level model. The result holds `time`, `z`, the fields
138
+ `e21`, `e31`, `e32`, the differences `n21`, `n31`, `n32` and the coherences
139
+ `r21`, `r31`, `r32` (shape `(n_planes, nt)`), and the inputs on the time grid.
132
140
 
133
- `populations(r1, r2)` gives `n1`, `n2`, `n3`, `n31⁰`, `n32⁰` and the largest
134
- coherences. `scaling(nu31, nu32, d31, d32, l, n0)` (SI units;
135
- `mbsolver.constants.DEBYE` converts dipoles from debye) gives `d`, `omega`,
136
- `eta`, `t0`, the field and intensity scales `e0`, `i0` (and `i0_jy` = 10²⁶ `i0`)
137
- and the pump scale `lambda0 = n0/t0`. By default the decay rate of the 3→2
138
- line is the Einstein A computed from `d32`; pass `gamma=` to use a measured one.
141
+ Time is in units of a free time unit `T0`; each transition has
142
+ `η_ij = T0 / T_R` with the cooperation time `T_R = 2ε0ħ / (n0 L k_ij |d_ij|²)`.
143
+ `mbsolver.three_level.scaling(t0=, l=, n0=, nu31=, d31=, ...)` computes, for
144
+ each transition given by its frequency and its dipole moment (or Einstein
145
+ coefficient `gamma_ij`), `eta_ij`, `t_r_ij` and the field and intensity scales
146
+ `e0_ij`, `i0_ij`; `mbsolver.constants.DEBYE` converts dipoles from debye.
139
147
 
140
148
  The three-level equations were derived and checked with Toktam Rashidi. The
141
149
  derivation, from the Hamiltonian to the dimensionless equations, with the
142
- initial conditions, physical scales and the S255IR-NIRS3 values, is in
143
- [`docs/three_level.pdf`](docs/three_level.pdf);
144
- [`examples/three_level/s255_flare.py`](examples/three_level/s255_flare.py)
145
- runs the S255IR-NIRS3 flare and plots it with the observed flux (needs
146
- matplotlib). The observations are from the Toruń 32 m telescope,
147
- [Szymczak et al. 2018, A&A 617, A80](https://doi.org/10.1051/0004-6361/201833443).
150
+ three configurations, initial conditions and physical scales, is in
151
+ [`docs/three_level.pdf`](docs/three_level.pdf).
148
152
 
149
153
  ## From physical values: `scaling` (two-level)
150
154
 
@@ -158,8 +162,8 @@ import math
158
162
  import mbsolver
159
163
  from mbsolver.two_level import solve_1d
160
164
 
161
- s = mbsolver.scaling(nu=6.67e9, gamma=1.56e-9, t0=86400, l=7.5e12, n0=5.3e-7)
162
- res = solve_1d(t_max=2000, nt=20001, nz=101, eta=s["eta"], theta0=s["theta0"],
165
+ s = mbsolver.scaling(nu=1.0e9, gamma=1.0e-8, t0=1.0e4, l=1.0e12, n0=1.0e-5) # η ≈ 10.7
166
+ res = solve_1d(t_max=100, nt=20001, nz=101, eta=s["eta"], theta0=s["theta0"],
163
167
  t1=math.inf, t2=math.inf)
164
168
  ```
165
169
 
@@ -169,6 +173,17 @@ and intensity scales for an electric dipole (`d`, `e0`, `p0`, `i0_electric`)
169
173
  and a magnetic dipole (`mu`, `b0`, `m0`, `i0_magnetic`). Times in the solver
170
174
  are in units of `t0`.
171
175
 
176
+ ## Examples
177
+
178
+ Two short scripts in [`examples/`](examples) (in the repository, not in the
179
+ PyPI package; they need matplotlib):
180
+
181
+ - [`examples/two_level/burst.py`](examples/two_level/burst.py): superradiant
182
+ bursts of a fully inverted two-level medium for three couplings η.
183
+ - [`examples/three_level/configurations.py`](examples/three_level/configurations.py):
184
+ the Λ, V and ladder configurations side by side, showing the competition for
185
+ a shared level and the ladder's cascade.
186
+
172
187
  ## Profiles
173
188
 
174
189
  `Pulse(a, x0, w)` is a sum of sech² pulses, `a_i sech²((t − x0_i) / w_i)`.
@@ -190,8 +205,10 @@ pytest
190
205
 
191
206
  The tests include a reference run that must match the solver of the Maxwell
192
207
  Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
193
- entrance, relaxation balance, uncoupled propagation). The three-level model
194
- matches the 2025 three-level solver exactly for the S255IR-NIRS3 case. `scaling`
208
+ entrance, relaxation balance, uncoupled propagation, small-signal gain). The three-level
209
+ Λ case must match a stored run of the earlier Λ-only solver; all three configurations
210
+ are checked for purity conservation, Bloch rotation and the reduction to the two-level
211
+ model. `scaling`
195
212
  is checked against the values of Maxwell Bloch Studio.
196
213
 
197
214
  The model documents `docs/two_level.pdf` and `docs/three_level.pdf` are built
@@ -230,12 +247,13 @@ MIT License. See [LICENSE](LICENSE).
230
247
 
231
248
  Vahid Anari ·
232
249
  [GitHub](https://github.com/vahid-anari) ·
233
- [LinkedIn](https://www.linkedin.com/in/vahid-anari/)
250
+ [LinkedIn](https://www.linkedin.com/in/vahid-anari/) ·
251
+ [ORCID](https://orcid.org/0000-0002-2464-3989)
234
252
 
235
253
  Toktam Rashidi ·
236
- [GitHub](https://github.com/ToktamS) ·
237
- [LinkedIn](https://www.linkedin.com/in/toktam-r-71951996/)
254
+ [GitHub](https://github.com/toktamrashidi) ·
255
+ [LinkedIn](https://www.linkedin.com/in/toktam-r-71951996/) ·
256
+ [ORCID](https://orcid.org/0009-0007-2978-7985)
238
257
 
239
258
  Related projects: [sciwidgets](https://github.com/vahid-anari/sciwidgets) ·
240
- [Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio) ·
241
259
  [linecat](https://github.com/vahid-anari/linecat)
@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
4
4
 
5
5
  [project]
6
6
  name = "mbsolver"
7
- version = "0.6.1"
7
+ version = "0.7.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"
@@ -0,0 +1,260 @@
1
+ """Three-level Maxwell-Bloch model: Λ, V and ladder configurations.
2
+
3
+ Levels are ordered by energy, ``E1 < E2 < E3``. Two of the three transitions
4
+ are dipole allowed and carry fields; the third is forbidden:
5
+
6
+ ========= =================== =========
7
+ config allowed forbidden
8
+ ========= =================== =========
9
+ "lambda" 3→1, 3→2 2↔1
10
+ "v" 2→1, 3→1 3↔2
11
+ "ladder" 2→1, 3→2 3↔1
12
+ ========= =================== =========
13
+
14
+ Dimensionless equations along a 1-D medium ``0 <= z <= 1`` (all quantities
15
+ real; fields are Rabi frequencies, ``W_ij = ½ E_ij R_ij``, ``n_ij = n_i - n_j``)::
16
+
17
+ dn1/dt = W21 + W31, dn2/dt = W32 - W21, dn3/dt = -W31 - W32
18
+ dR21/dt = E21 n21 + ½ (E31 R32 + E32 R31) - (R21 - R21⁰) / T2_21
19
+ dR31/dt = E31 n31 + ½ (E21 R32 - E32 R21) - (R31 - R31⁰) / T2_31
20
+ dR32/dt = E32 n32 - ½ (E21 R31 + E31 R21) - (R32 - R32⁰) / T2_32
21
+ dE_ij/dz = η_ij R_ij
22
+
23
+ The population differences of the two allowed transitions relax with their
24
+ ``T1`` and are pumped; the field of the forbidden transition is zero. The
25
+ derivation is in ``docs/three_level.pdf``.
26
+
27
+ The equations were derived and checked with Toktam Rashidi.
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ import math
33
+ from dataclasses import dataclass
34
+ from typing import Optional, Sequence, Tuple, Union
35
+
36
+ import numpy as np
37
+
38
+ from mbsolver.grids import grids_1d
39
+ from mbsolver.profiles import Pulse, Steps, evaluate
40
+ from mbsolver.three_level._kernel_1d import LADDER, LAMBDA, V, solve_kernel
41
+ from mbsolver.three_level.sample import scaling
42
+
43
+ __all__ = ["CONFIGS", "Result", "solve_1d", "scaling"]
44
+
45
+ #: Allowed transitions of each configuration, as ``(a, b)``.
46
+ CONFIGS = {"lambda": ("31", "32"), "v": ("21", "31"), "ladder": ("21", "32")}
47
+ _CODES = {"lambda": LAMBDA, "v": V, "ladder": LADDER}
48
+ _PAIRS = ("21", "31", "32")
49
+
50
+
51
+ @dataclass(frozen=True)
52
+ class Result:
53
+ """Output of :func:`solve_1d`.
54
+
55
+ Arrays on the stored planes have shape ``(n_planes, nt)``. Inputs that
56
+ belong only to the allowed transitions (``pump``, ``field_in``, ``t1``)
57
+ are ``None`` for the forbidden one.
58
+
59
+ Attributes:
60
+ config: ``"lambda"``, ``"v"`` or ``"ladder"``.
61
+ time: Time grid, shape ``(nt,)``.
62
+ z: Positions of the stored planes, shape ``(n_planes,)``, from 0 to 1.
63
+ e21, e31, e32: Fields (Rabi frequencies); zeros for the forbidden transition.
64
+ n21, n31, n32: Population differences ``n2 - n1``, ``n3 - n1``, ``n3 - n2``.
65
+ r21, r31, r32: Coherences.
66
+ pump21, pump31, pump32: Pumps on the time grid.
67
+ field21_in, field31_in, field32_in: Fields at ``z = 0``.
68
+ t1_21, t1_31, t1_32: Population relaxation times on the time grid.
69
+ t2_21, t2_31, t2_32: Coherence relaxation times on the time grid.
70
+ """
71
+
72
+ config: str
73
+ time: np.ndarray
74
+ z: np.ndarray
75
+ e21: np.ndarray
76
+ e31: np.ndarray
77
+ e32: np.ndarray
78
+ n21: np.ndarray
79
+ n31: np.ndarray
80
+ n32: np.ndarray
81
+ r21: np.ndarray
82
+ r31: np.ndarray
83
+ r32: np.ndarray
84
+ pump21: Optional[np.ndarray]
85
+ pump31: Optional[np.ndarray]
86
+ pump32: Optional[np.ndarray]
87
+ field21_in: Optional[np.ndarray]
88
+ field31_in: Optional[np.ndarray]
89
+ field32_in: Optional[np.ndarray]
90
+ t1_21: Optional[np.ndarray]
91
+ t1_31: Optional[np.ndarray]
92
+ t1_32: Optional[np.ndarray]
93
+ t2_21: np.ndarray
94
+ t2_31: np.ndarray
95
+ t2_32: np.ndarray
96
+
97
+
98
+ Profile = Union[None, float, Pulse, Steps]
99
+ Time = Union[None, float, Steps]
100
+
101
+
102
+ def _sum(profile, t):
103
+ """A profile or a list of profiles (summed) on ``t``."""
104
+ items = profile if isinstance(profile, (list, tuple)) else [profile]
105
+ total = np.zeros_like(t)
106
+ for p in items:
107
+ total = total + evaluate(p, t)
108
+ return total
109
+
110
+
111
+ def _times(name, value, t):
112
+ """A relaxation time on ``t``, checked to be positive."""
113
+ out = evaluate(value, t)
114
+ if np.any(out <= 0):
115
+ raise ValueError(f"{name} must be positive")
116
+ return out
117
+
118
+
119
+ def solve_1d(
120
+ *,
121
+ config: str,
122
+ t_max: float,
123
+ nt: int,
124
+ nz: int,
125
+ n_init: Tuple[float, float, float],
126
+ eta21: Optional[float] = None,
127
+ eta31: Optional[float] = None,
128
+ eta32: Optional[float] = None,
129
+ c21: float = 0.0,
130
+ c31: float = 0.0,
131
+ c32: float = 0.0,
132
+ t1_21: Time = None,
133
+ t1_31: Time = None,
134
+ t1_32: Time = None,
135
+ t2_21: Time = None,
136
+ t2_31: Time = None,
137
+ t2_32: Time = None,
138
+ pump21: Union[Profile, Sequence[Profile]] = None,
139
+ pump31: Union[Profile, Sequence[Profile]] = None,
140
+ pump32: Union[Profile, Sequence[Profile]] = None,
141
+ field21_in: Profile = None,
142
+ field31_in: Profile = None,
143
+ field32_in: Profile = None,
144
+ n_planes: int = 2,
145
+ ) -> Result:
146
+ """Solve the three-level Maxwell-Bloch equations in one dimension.
147
+
148
+ Parameters named ``…ij`` belong to the transition ``i→j``. ``eta``,
149
+ ``t1``, ``pump`` and ``field_in`` are given only for the two allowed
150
+ transitions of ``config`` (``eta`` and ``t1`` are required there);
151
+ ``t2`` is required for the two allowed coherences and defaults to
152
+ ``inf`` for the forbidden one.
153
+
154
+ Args:
155
+ config: ``"lambda"`` (allowed 3→1, 3→2), ``"v"`` (2→1, 3→1) or ``"ladder"`` (2→1, 3→2).
156
+ t_max: Duration; the time grid runs from 0 to ``t_max``.
157
+ nt: Number of time points (>= 2).
158
+ nz: Number of z points (>= 2).
159
+ n_init: Initial populations ``(n1, n2, n3)``, not negative, summing to 1.
160
+ eta21, eta31, eta32: Couplings ``η_ij = T0 / T_R`` of the allowed transitions (>= 0).
161
+ c21, c31, c32: Initial coherences as fractions of their largest values ``2√(n_i n_j)``.
162
+ t1_21, t1_31, t1_32: Relaxation times of the population differences, numbers or
163
+ :class:`Steps` (> 0; ``inf`` = none).
164
+ t2_21, t2_31, t2_32: Relaxation times of the coherences, the same way.
165
+ pump21, pump31, pump32: Pumps of the population differences: a :class:`Pulse`,
166
+ a number, or a list of them (summed).
167
+ field21_in, field31_in, field32_in: Fields entering at ``z = 0``: a :class:`Pulse`,
168
+ a number or ``None``.
169
+ n_planes: Number of evenly spaced z planes to return, from 0 to 1 (<= ``nz``).
170
+
171
+ Returns:
172
+ A :class:`Result`.
173
+
174
+ Example:
175
+ >>> res = solve_1d(config="ladder", t_max=200, nt=2001, nz=101,
176
+ ... n_init=(0.05, 0.05, 0.9), eta21=10.0, eta32=10.0,
177
+ ... c21=1e-3, c32=1e-3, t1_21=math.inf, t1_32=math.inf,
178
+ ... t2_21=math.inf, t2_32=math.inf)
179
+ >>> lower_step_exit = res.e21[-1]
180
+ """
181
+ if config not in CONFIGS:
182
+ raise ValueError(f"config must be one of {sorted(CONFIGS)}, got {config!r}")
183
+ nt, nz, n_planes = int(nt), int(nz), int(n_planes)
184
+ if nt < 2 or nz < 2:
185
+ raise ValueError("nt and nz must be at least 2")
186
+ if not 1 <= n_planes <= nz:
187
+ raise ValueError(f"n_planes must be between 1 and nz ({nz}), got {n_planes}")
188
+ if not t_max > 0:
189
+ raise ValueError("t_max must be positive")
190
+
191
+ allowed = CONFIGS[config]
192
+ forbidden = next(p for p in _PAIRS if p not in allowed)
193
+ given = {
194
+ "eta": {"21": eta21, "31": eta31, "32": eta32},
195
+ "t1_": {"21": t1_21, "31": t1_31, "32": t1_32},
196
+ "pump": {"21": pump21, "31": pump31, "32": pump32},
197
+ "field_in": {"21": field21_in, "31": field31_in, "32": field32_in},
198
+ }
199
+ for prefix, values in given.items():
200
+ if values[forbidden] is not None:
201
+ name = f"field{forbidden}_in" if prefix == "field_in" else f"{prefix}{forbidden}"
202
+ raise ValueError(f"{name} is not allowed for config={config!r} "
203
+ f"({forbidden[0]}↔{forbidden[1]} is forbidden)")
204
+ t2s = {"21": t2_21, "31": t2_31, "32": t2_32}
205
+ for p in allowed:
206
+ for prefix, values in (("eta", given["eta"]), ("t1_", given["t1_"]), ("t2_", t2s)):
207
+ if values[p] is None:
208
+ raise ValueError(f"{prefix}{p} is required for config={config!r}")
209
+ if not given["eta"][p] >= 0:
210
+ raise ValueError(f"eta{p} must not be negative")
211
+ if t2s[forbidden] is None:
212
+ t2s[forbidden] = math.inf
213
+
214
+ n = np.asarray(n_init, dtype=np.float64)
215
+ if n.shape != (3,) or np.any(n < 0) or abs(n.sum() - 1.0) > 1e-12:
216
+ raise ValueError("n_init must be three non-negative populations (n1, n2, n3) summing to 1")
217
+ n1, n2, n3 = float(n[0]), float(n[1]), float(n[2])
218
+ diff = {"21": n2 - n1, "31": n3 - n1, "32": n3 - n2}
219
+ pops = {"1": n1, "2": n2, "3": n3}
220
+ c = {"21": c21, "31": c31, "32": c32}
221
+ r0 = {p: c[p] * 2.0 * math.sqrt(pops[p[0]] * pops[p[1]]) for p in _PAIRS}
222
+ a, b = allowed
223
+ init = np.array([diff[a], diff[b], r0["21"], r0["31"], r0["32"]], dtype=np.float64)
224
+
225
+ t, dt, z, dz = grids_1d(float(t_max), nt, nz)
226
+ pumps = {p: (_sum(given["pump"][p], t) if p in allowed else None) for p in _PAIRS}
227
+ fields = {p: (evaluate(given["field_in"][p], t) if p in allowed else None) for p in _PAIRS}
228
+ t1 = {p: (_times(f"t1_{p}", given["t1_"][p], t) if p in allowed else None) for p in _PAIRS}
229
+ t2 = {p: _times(f"t2_{p}", t2s[p], t) for p in _PAIRS}
230
+
231
+ zeros = np.zeros_like(t)
232
+ field_in = np.array([fields[p] if p in allowed else zeros for p in _PAIRS])
233
+ t2_arr = np.array([t2[p] for p in _PAIRS])
234
+ eta = np.array([float(given["eta"][p]) if p in allowed else 0.0 for p in _PAIRS])
235
+
236
+ v, E = solve_kernel(_CODES[config], t, dt, z, dz, n_planes, init, field_in,
237
+ pumps[a], pumps[b], t1[a], t1[b], t2_arr, eta)
238
+
239
+ na, nb = v[:, 0], v[:, 1]
240
+ if config == "lambda":
241
+ n31, n32 = na, nb
242
+ n21 = n31 - n32
243
+ elif config == "v":
244
+ n21, n31 = na, nb
245
+ n32 = n31 - n21
246
+ else:
247
+ n21, n32 = na, nb
248
+ n31 = n21 + n32
249
+
250
+ planes = z[np.rint(np.linspace(0.0, 1.0, n_planes) * (nz - 1)).astype(np.int64)]
251
+ return Result(
252
+ config=config, time=t, z=planes,
253
+ e21=E[:, 0], e31=E[:, 1], e32=E[:, 2],
254
+ n21=n21, n31=n31, n32=n32,
255
+ r21=v[:, 2], r31=v[:, 3], r32=v[:, 4],
256
+ pump21=pumps["21"], pump31=pumps["31"], pump32=pumps["32"],
257
+ field21_in=fields["21"], field31_in=fields["31"], field32_in=fields["32"],
258
+ t1_21=t1["21"], t1_31=t1["31"], t1_32=t1["32"],
259
+ t2_21=t2["21"], t2_31=t2["31"], t2_32=t2["32"],
260
+ )