mbsolver 0.3.1__tar.gz → 0.4.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.
- {mbsolver-0.3.1/src/mbsolver.egg-info → mbsolver-0.4.0}/PKG-INFO +95 -10
- mbsolver-0.4.0/README.md +214 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/pyproject.toml +5 -2
- {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/__init__.py +1 -1
- {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/constants.py +3 -0
- mbsolver-0.4.0/src/mbsolver/three_level/__init__.py +176 -0
- mbsolver-0.4.0/src/mbsolver/three_level/_kernel_1d.py +140 -0
- mbsolver-0.4.0/src/mbsolver/three_level/sample.py +85 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0/src/mbsolver.egg-info}/PKG-INFO +95 -10
- {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver.egg-info/SOURCES.txt +4 -0
- mbsolver-0.4.0/tests/test_three_level.py +113 -0
- mbsolver-0.3.1/README.md +0 -130
- {mbsolver-0.3.1 → mbsolver-0.4.0}/LICENSE +0 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/setup.cfg +0 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/grids.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/profiles.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/sample.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/two_level/__init__.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/two_level/_kernel_1d.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver.egg-info/dependency_links.txt +0 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver.egg-info/requires.txt +0 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver.egg-info/top_level.txt +0 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/tests/test_profiles.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/tests/test_sample.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.4.0}/tests/test_two_level.py +0 -0
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: mbsolver
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.4.0
|
|
4
4
|
Summary: Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation
|
|
5
|
+
Author: Toktam Rashidi
|
|
5
6
|
Author-email: Vahid Anari <vahid.anari8@gmail.com>
|
|
6
7
|
License-Expression: MIT
|
|
7
8
|
Project-URL: Homepage, https://github.com/vahid-anari/mbsolver
|
|
@@ -34,6 +35,8 @@ Dynamic: license-file
|
|
|
34
35
|
[](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml)
|
|
35
36
|
[](https://pypi.org/project/mbsolver/)
|
|
36
37
|
[](https://pypi.org/project/mbsolver/)
|
|
38
|
+
[](https://doi.org/10.5281/zenodo.23407483)
|
|
39
|
+

|
|
37
40
|
|
|
38
41
|
Fast Maxwell-Bloch solvers in Python (numpy + numba) for astrophysical masers,
|
|
39
42
|
superradiance and coherent pulse propagation. Use them from scripts,
|
|
@@ -41,10 +44,14 @@ notebooks or cluster jobs; the
|
|
|
41
44
|
[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio)
|
|
42
45
|
desktop app runs on the same code.
|
|
43
46
|
|
|
47
|
+
## Installation
|
|
48
|
+
|
|
44
49
|
```
|
|
45
50
|
pip install mbsolver
|
|
46
51
|
```
|
|
47
52
|
|
|
53
|
+
Requires Python 3.10+ (numpy and numba are installed with it).
|
|
54
|
+
|
|
48
55
|
## Two-level model in one dimension
|
|
49
56
|
|
|
50
57
|
Dimensionless equations for the population inversion `w`, the coherence `R`
|
|
@@ -96,9 +103,63 @@ plt.show()
|
|
|
96
103
|
`res.time`, `res.z` (positions of the stored planes), `res.intensity` and
|
|
97
104
|
`res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
|
|
98
105
|
|
|
99
|
-
##
|
|
106
|
+
## Three-level (Λ) model in one dimension
|
|
107
|
+
|
|
108
|
+
Levels 1 and 2 lie below level 3; the transitions 3→1 and 3→2 carry the fields
|
|
109
|
+
`E31` and `E32`. With the population differences `n31 = n3 − n1`,
|
|
110
|
+
`n32 = n3 − n2` and the coherences `R31`, `R32`, `R21` (all real):
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
dn31/dt = −(E31 R31 + ½ E32 R32) − (n31 − n31⁰) / T1_31 + Λ31(t)
|
|
114
|
+
dn32/dt = −(½ E31 R31 + E32 R32) − (n32 − n32⁰) / T1_32 + Λ32(t)
|
|
115
|
+
dR31/dt = E31 n31 − ½ E32 R21 − (R31 − R31⁰) / T2_31
|
|
116
|
+
dR32/dt = E32 n32 − ½ E31 R21 − (R32 − R32⁰) / T2_32
|
|
117
|
+
dR21/dt = ½ (E31 R32 + E32 R31) − (R21 − R21⁰) / T2_21
|
|
118
|
+
dE31/dz = η R31, dE32/dz = R32, η = ω d²
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
with `d = |d31/d32|` and `ω = k31/k32`. Time is in units of the 3→2 time
|
|
122
|
+
scale `T0 = 2ε0ħ / (n0 L k32 |d32|²)`. The initial state comes from the
|
|
123
|
+
population ratios `r1 = n3/n1`, `r2 = n3/n2` and the coherence fractions
|
|
124
|
+
`c_ij`: `R_ij⁰ = c_ij · 2√(n_i n_j)`.
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
from mbsolver import Pulse
|
|
128
|
+
from mbsolver.three_level import solve_1d
|
|
129
|
+
|
|
130
|
+
res = solve_1d(
|
|
131
|
+
t_max=2500, nt=4000, nz=400, d=0.875, omega=35.95,
|
|
132
|
+
r1=0.94, r2=2.33e19, c31=1e-10, c32=1.0, # c21 = 0 by default
|
|
133
|
+
t1_31=31.3, t1_32=313, t2_31=2.96, t2_32=29.6, # t2_21 = inf by default
|
|
134
|
+
pump32=Pulse(a=5.63e-3, x0=795.5, w=154.8), # pump31, field31_in, field32_in too
|
|
135
|
+
)
|
|
136
|
+
res.intensity32[-1] # 3→2 intensity leaving the medium
|
|
137
|
+
```
|
|
100
138
|
|
|
101
|
-
|
|
139
|
+
`t1_*` and `t2_*` take numbers or `Steps`, the pumps and entrance fields
|
|
140
|
+
`Pulse`s, numbers or lists, as in the two-level model. The result holds
|
|
141
|
+
`time`, `z`, the fields `e31`, `e32`, the intensities `intensity31 = (E31/d)²`
|
|
142
|
+
and `intensity32 = E32²` (both in units of the 3→2 scale), `n31`, `n32`,
|
|
143
|
+
`r31`, `r32`, `r21` (shape `(n_planes, nt)`), and the pumps, entrance fields
|
|
144
|
+
and relaxation times on the time grid.
|
|
145
|
+
|
|
146
|
+
`populations(r1, r2)` gives `n1`, `n2`, `n3`, `n31⁰`, `n32⁰` and the largest
|
|
147
|
+
coherences. `scaling(nu31, nu32, d31, d32, l, n0)` (SI units;
|
|
148
|
+
`mbsolver.constants.DEBYE` converts dipoles from debye) gives `d`, `omega`,
|
|
149
|
+
`eta`, `t0`, the field and intensity scales `e0`, `i0` (and `i0_jy` = 10²⁶ `i0`)
|
|
150
|
+
and the pump scale `lambda0 = n0/t0`. By default the decay rate of the 3→2
|
|
151
|
+
line is the Einstein A computed from `d32`; pass `gamma=` to use a measured one.
|
|
152
|
+
|
|
153
|
+
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/);
|
|
156
|
+
[`examples/three_level/s255_flare.py`](examples/three_level/s255_flare.py)
|
|
157
|
+
runs the S255IR-NIRS3 flare and plots it with the observed flux (needs
|
|
158
|
+
matplotlib).
|
|
159
|
+
|
|
160
|
+
## From physical values: `scaling` (two-level)
|
|
161
|
+
|
|
162
|
+
The solvers take dimensionless parameters. `mbsolver.scaling` computes them for the two-level model from the
|
|
102
163
|
physical sample values (SI units): transition frequency `nu` (Hz), spontaneous
|
|
103
164
|
decay rate `gamma` (s⁻¹), time unit `t0` (s), length `l` (m) and inverted
|
|
104
165
|
population density `n0` (m⁻³).
|
|
@@ -131,7 +192,7 @@ width `w` (0 for a sharp step). `x0` and `w` have one value fewer than `y`.
|
|
|
131
192
|
A zero width gives a single point (pulse) or a sharp step; an infinite width
|
|
132
193
|
a constant. `profile.evaluate(t)` returns the values on any grid.
|
|
133
194
|
|
|
134
|
-
##
|
|
195
|
+
## Development
|
|
135
196
|
|
|
136
197
|
```
|
|
137
198
|
pip install -e ".[dev]"
|
|
@@ -140,8 +201,14 @@ pytest
|
|
|
140
201
|
|
|
141
202
|
The tests include a reference run that must match the solver of the Maxwell
|
|
142
203
|
Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
|
|
143
|
-
entrance, relaxation balance, uncoupled propagation).
|
|
144
|
-
|
|
204
|
+
entrance, relaxation balance, uncoupled propagation). The three-level model
|
|
205
|
+
matches the 2025 three-level solver exactly for the S255IR-NIRS3 case. `scaling`
|
|
206
|
+
is checked against the values of Maxwell Bloch Studio.
|
|
207
|
+
|
|
208
|
+
What changed in each version is in [`CHANGELOG.md`](CHANGELOG.md). Pushing a
|
|
209
|
+
tag `vX.Y.Z` publishes a GitHub Release with that version's section of the
|
|
210
|
+
changelog, and Zenodo gives it a DOI; update `version` and `date-released` in
|
|
211
|
+
`CITATION.cff` before tagging.
|
|
145
212
|
|
|
146
213
|
## Earlier name
|
|
147
214
|
|
|
@@ -152,10 +219,28 @@ your imports.
|
|
|
152
219
|
|
|
153
220
|
## Citing
|
|
154
221
|
|
|
155
|
-
If you use mbsolver in published work, please cite it
|
|
156
|
-
|
|
157
|
-
|
|
222
|
+
If you use mbsolver in published work, please cite it:
|
|
223
|
+
|
|
224
|
+
> Anari, V., & Rashidi, T. *mbsolver: Fast Maxwell-Bloch solvers for masers, superradiance and
|
|
225
|
+
> coherent pulse propagation*. Zenodo. https://doi.org/10.5281/zenodo.23407483
|
|
226
|
+
|
|
227
|
+
This DOI always points to the latest version. Each release also has its own
|
|
228
|
+
DOI (for 0.3.1: [10.5281/zenodo.23407484](https://doi.org/10.5281/zenodo.23407484));
|
|
229
|
+
cite the version you used, which you find under *Versions* on the Zenodo page.
|
|
230
|
+
GitHub's **Cite this repository** button gives the same in BibTeX and APA.
|
|
158
231
|
|
|
159
232
|
## License
|
|
160
233
|
|
|
161
|
-
MIT
|
|
234
|
+
MIT License. See [LICENSE](LICENSE).
|
|
235
|
+
|
|
236
|
+
## Authors
|
|
237
|
+
|
|
238
|
+
Vahid Anari ·
|
|
239
|
+
[GitHub](https://github.com/vahid-anari) ·
|
|
240
|
+
[LinkedIn](https://www.linkedin.com/in/vahid-anari/)
|
|
241
|
+
|
|
242
|
+
Toktam Rashidi (three-level model)
|
|
243
|
+
|
|
244
|
+
Related projects: [sciwidgets](https://github.com/vahid-anari/sciwidgets) ·
|
|
245
|
+
[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio) ·
|
|
246
|
+
[linecat](https://github.com/vahid-anari/linecat)
|
mbsolver-0.4.0/README.md
ADDED
|
@@ -0,0 +1,214 @@
|
|
|
1
|
+
# mbsolver
|
|
2
|
+
|
|
3
|
+
[](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml)
|
|
4
|
+
[](https://pypi.org/project/mbsolver/)
|
|
5
|
+
[](https://pypi.org/project/mbsolver/)
|
|
6
|
+
[](https://doi.org/10.5281/zenodo.23407483)
|
|
7
|
+

|
|
8
|
+
|
|
9
|
+
Fast Maxwell-Bloch solvers in Python (numpy + numba) for astrophysical masers,
|
|
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.
|
|
14
|
+
|
|
15
|
+
## Installation
|
|
16
|
+
|
|
17
|
+
```
|
|
18
|
+
pip install mbsolver
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
Requires Python 3.10+ (numpy and numba are installed with it).
|
|
22
|
+
|
|
23
|
+
## Two-level model in one dimension
|
|
24
|
+
|
|
25
|
+
Dimensionless equations for the population inversion `w`, the coherence `R`
|
|
26
|
+
and the field `A` along a medium `0 ≤ z ≤ 1`:
|
|
27
|
+
|
|
28
|
+
```
|
|
29
|
+
dw/dt = A R − (w − w0) / T1 + Λ(t)
|
|
30
|
+
dR/dt = −A w − (R − R0) / T2
|
|
31
|
+
dA/dz = −η R
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
The field `A(t)` entering at `z = 0` is given; population and coherence are
|
|
35
|
+
advanced with fourth-order Runge-Kutta in time, the field step by step in `z`.
|
|
36
|
+
|
|
37
|
+
```python
|
|
38
|
+
import matplotlib.pyplot as plt
|
|
39
|
+
from mbsolver import Pulse, Steps
|
|
40
|
+
from mbsolver.two_level import solve_1d
|
|
41
|
+
|
|
42
|
+
res = solve_1d(
|
|
43
|
+
t_max=300, nt=3001, nz=121, eta=40.0,
|
|
44
|
+
theta0=0.003, # or w0=..., R0=...
|
|
45
|
+
pump=[Pulse(a=[2e-3, 1e-3], x0=[60, 180], w=[15, 25])],
|
|
46
|
+
field_in=Pulse(a=1e-3, x0=30, w=5), # A(t) at z = 0
|
|
47
|
+
t1=Steps(y=[80, 40, 60], x0=[100, 200], w=[10, 0]),
|
|
48
|
+
t2=5.0,
|
|
49
|
+
n_planes=7, # stored z planes, 0 ... 1
|
|
50
|
+
)
|
|
51
|
+
|
|
52
|
+
plt.plot(res.time, res.intensity[-1]) # intensity leaving the medium
|
|
53
|
+
plt.show()
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
### Arguments
|
|
57
|
+
|
|
58
|
+
| Argument | Meaning |
|
|
59
|
+
|----------|---------|
|
|
60
|
+
| `t_max`, `nt` | time grid from 0 to `t_max` with `nt` points |
|
|
61
|
+
| `nz` | number of z points |
|
|
62
|
+
| `eta` | coupling coefficient η |
|
|
63
|
+
| `theta0`, or `w0` and `R0` | initial state (`w0 = cos θ0`, `R0 = sin θ0`); the medium also relaxes towards it |
|
|
64
|
+
| `t1`, `t2` | relaxation times: a number or `Steps` (> 0, `math.inf` for none) |
|
|
65
|
+
| `pump` | Λ(t): a `Pulse`, a number, or a list of them (summed) |
|
|
66
|
+
| `field_in` | A(t) at z = 0: a `Pulse`, a number, or `None` |
|
|
67
|
+
| `n_planes` | number of evenly spaced z planes returned (default 2: entrance and exit) |
|
|
68
|
+
|
|
69
|
+
### Result
|
|
70
|
+
|
|
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
|
+
|
|
74
|
+
## Three-level (Λ) model in one dimension
|
|
75
|
+
|
|
76
|
+
Levels 1 and 2 lie below level 3; the transitions 3→1 and 3→2 carry the fields
|
|
77
|
+
`E31` and `E32`. With the population differences `n31 = n3 − n1`,
|
|
78
|
+
`n32 = n3 − n2` and the coherences `R31`, `R32`, `R21` (all real):
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
dn31/dt = −(E31 R31 + ½ E32 R32) − (n31 − n31⁰) / T1_31 + Λ31(t)
|
|
82
|
+
dn32/dt = −(½ E31 R31 + E32 R32) − (n32 − n32⁰) / T1_32 + Λ32(t)
|
|
83
|
+
dR31/dt = E31 n31 − ½ E32 R21 − (R31 − R31⁰) / T2_31
|
|
84
|
+
dR32/dt = E32 n32 − ½ E31 R21 − (R32 − R32⁰) / T2_32
|
|
85
|
+
dR21/dt = ½ (E31 R32 + E32 R31) − (R21 − R21⁰) / T2_21
|
|
86
|
+
dE31/dz = η R31, dE32/dz = R32, η = ω d²
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
with `d = |d31/d32|` and `ω = k31/k32`. Time is in units of the 3→2 time
|
|
90
|
+
scale `T0 = 2ε0ħ / (n0 L k32 |d32|²)`. The initial state comes from the
|
|
91
|
+
population ratios `r1 = n3/n1`, `r2 = n3/n2` and the coherence fractions
|
|
92
|
+
`c_ij`: `R_ij⁰ = c_ij · 2√(n_i n_j)`.
|
|
93
|
+
|
|
94
|
+
```python
|
|
95
|
+
from mbsolver import Pulse
|
|
96
|
+
from mbsolver.three_level import solve_1d
|
|
97
|
+
|
|
98
|
+
res = solve_1d(
|
|
99
|
+
t_max=2500, nt=4000, nz=400, d=0.875, omega=35.95,
|
|
100
|
+
r1=0.94, r2=2.33e19, c31=1e-10, c32=1.0, # c21 = 0 by default
|
|
101
|
+
t1_31=31.3, t1_32=313, t2_31=2.96, t2_32=29.6, # t2_21 = inf by default
|
|
102
|
+
pump32=Pulse(a=5.63e-3, x0=795.5, w=154.8), # pump31, field31_in, field32_in too
|
|
103
|
+
)
|
|
104
|
+
res.intensity32[-1] # 3→2 intensity leaving the medium
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
`t1_*` and `t2_*` take numbers or `Steps`, the pumps and entrance fields
|
|
108
|
+
`Pulse`s, numbers or lists, as in the two-level model. The result holds
|
|
109
|
+
`time`, `z`, the fields `e31`, `e32`, the intensities `intensity31 = (E31/d)²`
|
|
110
|
+
and `intensity32 = E32²` (both in units of the 3→2 scale), `n31`, `n32`,
|
|
111
|
+
`r31`, `r32`, `r21` (shape `(n_planes, nt)`), and the pumps, entrance fields
|
|
112
|
+
and relaxation times on the time grid.
|
|
113
|
+
|
|
114
|
+
`populations(r1, r2)` gives `n1`, `n2`, `n3`, `n31⁰`, `n32⁰` and the largest
|
|
115
|
+
coherences. `scaling(nu31, nu32, d31, d32, l, n0)` (SI units;
|
|
116
|
+
`mbsolver.constants.DEBYE` converts dipoles from debye) gives `d`, `omega`,
|
|
117
|
+
`eta`, `t0`, the field and intensity scales `e0`, `i0` (and `i0_jy` = 10²⁶ `i0`)
|
|
118
|
+
and the pump scale `lambda0 = n0/t0`. By default the decay rate of the 3→2
|
|
119
|
+
line is the Einstein A computed from `d32`; pass `gamma=` to use a measured one.
|
|
120
|
+
|
|
121
|
+
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/);
|
|
124
|
+
[`examples/three_level/s255_flare.py`](examples/three_level/s255_flare.py)
|
|
125
|
+
runs the S255IR-NIRS3 flare and plots it with the observed flux (needs
|
|
126
|
+
matplotlib).
|
|
127
|
+
|
|
128
|
+
## From physical values: `scaling` (two-level)
|
|
129
|
+
|
|
130
|
+
The solvers take dimensionless parameters. `mbsolver.scaling` computes them for the two-level model from the
|
|
131
|
+
physical sample values (SI units): transition frequency `nu` (Hz), spontaneous
|
|
132
|
+
decay rate `gamma` (s⁻¹), time unit `t0` (s), length `l` (m) and inverted
|
|
133
|
+
population density `n0` (m⁻³).
|
|
134
|
+
|
|
135
|
+
```python
|
|
136
|
+
import math
|
|
137
|
+
import mbsolver
|
|
138
|
+
from mbsolver.two_level import solve_1d
|
|
139
|
+
|
|
140
|
+
s = mbsolver.scaling(nu=6.67e9, gamma=1.56e-9, t0=86400, l=7.5e12, n0=5.3e-7)
|
|
141
|
+
res = solve_1d(t_max=2000, nt=20001, nz=101, eta=s["eta"], theta0=s["theta0"],
|
|
142
|
+
t1=math.inf, t2=math.inf)
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
Besides `eta` (η = T₀/T_R) and `theta0` (θ₀ = 2/√N), the result holds `t_r`,
|
|
146
|
+
`N`, `omega`, `lambda`, `k`, `lambda0` (Λ₀ = 1/T₀) and the field, polarization
|
|
147
|
+
and intensity scales for an electric dipole (`d`, `e0`, `p0`, `i0_electric`)
|
|
148
|
+
and a magnetic dipole (`mu`, `b0`, `m0`, `i0_magnetic`). Times in the solver
|
|
149
|
+
are in units of `t0`.
|
|
150
|
+
|
|
151
|
+
## Profiles
|
|
152
|
+
|
|
153
|
+
`Pulse(a, x0, w)` is a sum of sech² pulses, `a_i sech²((t − x0_i) / w_i)`.
|
|
154
|
+
Give `wl` and `wr` instead of `w` for a different width on each side.
|
|
155
|
+
|
|
156
|
+
`Steps(y, x0, w)` goes from level `y[0]` to `y[1]` around `x0[0]`, then to
|
|
157
|
+
`y[2]` around `x0[1]`, and so on, each step smoothed as `(1 + tanh)/2` with
|
|
158
|
+
width `w` (0 for a sharp step). `x0` and `w` have one value fewer than `y`.
|
|
159
|
+
|
|
160
|
+
A zero width gives a single point (pulse) or a sharp step; an infinite width
|
|
161
|
+
a constant. `profile.evaluate(t)` returns the values on any grid.
|
|
162
|
+
|
|
163
|
+
## Development
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
pip install -e ".[dev]"
|
|
167
|
+
pytest
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
The tests include a reference run that must match the solver of the Maxwell
|
|
171
|
+
Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
|
|
172
|
+
entrance, relaxation balance, uncoupled propagation). The three-level model
|
|
173
|
+
matches the 2025 three-level solver exactly for the S255IR-NIRS3 case. `scaling`
|
|
174
|
+
is checked against the values of Maxwell Bloch Studio.
|
|
175
|
+
|
|
176
|
+
What changed in each version is in [`CHANGELOG.md`](CHANGELOG.md). Pushing a
|
|
177
|
+
tag `vX.Y.Z` publishes a GitHub Release with that version's section of the
|
|
178
|
+
changelog, and Zenodo gives it a DOI; update `version` and `date-released` in
|
|
179
|
+
`CITATION.cff` before tagging.
|
|
180
|
+
|
|
181
|
+
## Earlier name
|
|
182
|
+
|
|
183
|
+
Up to 0.1.0 this package was called `maxbloch`; 0.2.0 is the same code under
|
|
184
|
+
the new name. `maxbloch` stays on PyPI unchanged (0.1.1 only adds a
|
|
185
|
+
deprecation warning) but gets no updates; change `maxbloch` to `mbsolver` in
|
|
186
|
+
your imports.
|
|
187
|
+
|
|
188
|
+
## Citing
|
|
189
|
+
|
|
190
|
+
If you use mbsolver in published work, please cite it:
|
|
191
|
+
|
|
192
|
+
> Anari, V., & Rashidi, T. *mbsolver: Fast Maxwell-Bloch solvers for masers, superradiance and
|
|
193
|
+
> coherent pulse propagation*. Zenodo. https://doi.org/10.5281/zenodo.23407483
|
|
194
|
+
|
|
195
|
+
This DOI always points to the latest version. Each release also has its own
|
|
196
|
+
DOI (for 0.3.1: [10.5281/zenodo.23407484](https://doi.org/10.5281/zenodo.23407484));
|
|
197
|
+
cite the version you used, which you find under *Versions* on the Zenodo page.
|
|
198
|
+
GitHub's **Cite this repository** button gives the same in BibTeX and APA.
|
|
199
|
+
|
|
200
|
+
## License
|
|
201
|
+
|
|
202
|
+
MIT License. See [LICENSE](LICENSE).
|
|
203
|
+
|
|
204
|
+
## Authors
|
|
205
|
+
|
|
206
|
+
Vahid Anari ·
|
|
207
|
+
[GitHub](https://github.com/vahid-anari) ·
|
|
208
|
+
[LinkedIn](https://www.linkedin.com/in/vahid-anari/)
|
|
209
|
+
|
|
210
|
+
Toktam Rashidi (three-level model)
|
|
211
|
+
|
|
212
|
+
Related projects: [sciwidgets](https://github.com/vahid-anari/sciwidgets) ·
|
|
213
|
+
[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio) ·
|
|
214
|
+
[linecat](https://github.com/vahid-anari/linecat)
|
|
@@ -4,13 +4,16 @@ build-backend = "setuptools.build_meta"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "mbsolver"
|
|
7
|
-
version = "0.
|
|
7
|
+
version = "0.4.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"
|
|
11
11
|
license = "MIT"
|
|
12
12
|
license-files = ["LICENSE"]
|
|
13
|
-
authors = [
|
|
13
|
+
authors = [
|
|
14
|
+
{ name = "Vahid Anari", email = "vahid.anari8@gmail.com" },
|
|
15
|
+
{ name = "Toktam Rashidi" },
|
|
16
|
+
]
|
|
14
17
|
keywords = [
|
|
15
18
|
"maxwell-bloch", "maser", "superradiance", "physics",
|
|
16
19
|
"astrophysics", "numba", "simulation",
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
|
|
3
3
|
Profiles (pump pulses, boundary fields, relaxation-time schedules) are built
|
|
4
4
|
with :class:`Pulse` and :class:`Steps`; the solvers live in model subpackages,
|
|
5
|
-
e.g. ``mbsolver.two_level.solve_1d``. :func:`scaling` turns the physical
|
|
5
|
+
e.g. ``mbsolver.two_level.solve_1d`` and ``mbsolver.three_level.solve_1d``. :func:`scaling` turns the physical
|
|
6
6
|
sample values into the solvers' ``eta`` and ``theta0``.
|
|
7
7
|
"""
|
|
8
8
|
|
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
"""Λ-type three-level Maxwell-Bloch model.
|
|
2
|
+
|
|
3
|
+
Levels 1 and 2 lie below level 3; the transitions 3→1 and 3→2 carry the
|
|
4
|
+
fields ``E31`` and ``E32``. Dimensionless equations along a 1-D medium
|
|
5
|
+
``0 <= z <= 1`` (all quantities real)::
|
|
6
|
+
|
|
7
|
+
dn31/dt = -(E31 R31 + ½ E32 R32) - (n31 - n31⁰) / T1_31 + Λ31(t)
|
|
8
|
+
dn32/dt = -(½ E31 R31 + E32 R32) - (n32 - n32⁰) / T1_32 + Λ32(t)
|
|
9
|
+
dR31/dt = E31 n31 - ½ E32 R21 - (R31 - R31⁰) / T2_31
|
|
10
|
+
dR32/dt = E32 n32 - ½ E31 R21 - (R32 - R32⁰) / T2_32
|
|
11
|
+
dR21/dt = ½ (E31 R32 + E32 R31) - (R21 - R21⁰) / T2_21
|
|
12
|
+
dE31/dz = η R31, dE32/dz = R32, η = ω d²
|
|
13
|
+
|
|
14
|
+
with ``d = |d31/d32|``, ``ω = k31/k32`` and the fields at ``z = 0`` given.
|
|
15
|
+
The initial state comes from ``r1 = n3/n1``, ``r2 = n3/n2`` and the
|
|
16
|
+
coherence fractions ``c_ij``: ``R_ij⁰ = c_ij · 2√(n_i n_j)``.
|
|
17
|
+
|
|
18
|
+
The equations were derived and checked with Toktam Rashidi.
|
|
19
|
+
"""
|
|
20
|
+
|
|
21
|
+
from __future__ import annotations
|
|
22
|
+
|
|
23
|
+
import math
|
|
24
|
+
from dataclasses import dataclass
|
|
25
|
+
from typing import Sequence, Union
|
|
26
|
+
|
|
27
|
+
import numpy as np
|
|
28
|
+
|
|
29
|
+
from mbsolver.grids import grids_1d
|
|
30
|
+
from mbsolver.profiles import Pulse, Steps, evaluate
|
|
31
|
+
from mbsolver.three_level._kernel_1d import solve_kernel
|
|
32
|
+
from mbsolver.three_level.sample import populations, scaling
|
|
33
|
+
|
|
34
|
+
__all__ = ["Result", "solve_1d", "populations", "scaling"]
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass(frozen=True)
|
|
38
|
+
class Result:
|
|
39
|
+
"""Output of :func:`solve_1d`.
|
|
40
|
+
|
|
41
|
+
Arrays on the stored planes have shape ``(n_planes, nt)``.
|
|
42
|
+
|
|
43
|
+
Attributes:
|
|
44
|
+
time: Time grid, shape ``(nt,)``.
|
|
45
|
+
z: Positions of the stored planes, shape ``(n_planes,)``, from 0 to 1.
|
|
46
|
+
e31, e32: Fields.
|
|
47
|
+
intensity31, intensity32: ``(E31/d)²`` and ``E32²``, both in units of the 3→2 scale.
|
|
48
|
+
n31, n32: Population differences ``n3 - n1`` and ``n3 - n2``.
|
|
49
|
+
r31, r32, r21: Coherences.
|
|
50
|
+
pump31, pump32: Pumps ``Λ31(t)``, ``Λ32(t)``.
|
|
51
|
+
field31_in, field32_in: Fields at ``z = 0``.
|
|
52
|
+
t1_31, t1_32, t2_31, t2_32, t2_21: Relaxation times on the time grid.
|
|
53
|
+
"""
|
|
54
|
+
|
|
55
|
+
time: np.ndarray
|
|
56
|
+
z: np.ndarray
|
|
57
|
+
e31: np.ndarray
|
|
58
|
+
e32: np.ndarray
|
|
59
|
+
intensity31: np.ndarray
|
|
60
|
+
intensity32: np.ndarray
|
|
61
|
+
n31: np.ndarray
|
|
62
|
+
n32: np.ndarray
|
|
63
|
+
r31: np.ndarray
|
|
64
|
+
r32: np.ndarray
|
|
65
|
+
r21: np.ndarray
|
|
66
|
+
pump31: np.ndarray
|
|
67
|
+
pump32: np.ndarray
|
|
68
|
+
field31_in: np.ndarray
|
|
69
|
+
field32_in: np.ndarray
|
|
70
|
+
t1_31: np.ndarray
|
|
71
|
+
t1_32: np.ndarray
|
|
72
|
+
t2_31: np.ndarray
|
|
73
|
+
t2_32: np.ndarray
|
|
74
|
+
t2_21: np.ndarray
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
Profile = Union[None, float, Pulse, Steps]
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _sum(profile, t):
|
|
81
|
+
"""A profile or a list of profiles (summed) on ``t``."""
|
|
82
|
+
items = profile if isinstance(profile, (list, tuple)) else [profile]
|
|
83
|
+
total = np.zeros_like(t)
|
|
84
|
+
for p in items:
|
|
85
|
+
total = total + evaluate(p, t)
|
|
86
|
+
return total
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def solve_1d(
|
|
90
|
+
*,
|
|
91
|
+
t_max: float,
|
|
92
|
+
nt: int,
|
|
93
|
+
nz: int,
|
|
94
|
+
d: float,
|
|
95
|
+
omega: float,
|
|
96
|
+
r1: float,
|
|
97
|
+
r2: float,
|
|
98
|
+
c31: float,
|
|
99
|
+
c32: float,
|
|
100
|
+
t1_31: Union[float, Steps],
|
|
101
|
+
t1_32: Union[float, Steps],
|
|
102
|
+
t2_31: Union[float, Steps],
|
|
103
|
+
t2_32: Union[float, Steps],
|
|
104
|
+
t2_21: Union[float, Steps] = math.inf,
|
|
105
|
+
c21: float = 0.0,
|
|
106
|
+
pump31: Union[Profile, Sequence[Profile]] = None,
|
|
107
|
+
pump32: Union[Profile, Sequence[Profile]] = None,
|
|
108
|
+
field31_in: Profile = None,
|
|
109
|
+
field32_in: Profile = None,
|
|
110
|
+
n_planes: int = 2,
|
|
111
|
+
) -> Result:
|
|
112
|
+
"""Solve the Λ-type three-level Maxwell-Bloch equations in one dimension.
|
|
113
|
+
|
|
114
|
+
Args:
|
|
115
|
+
t_max: Duration; the time grid runs from 0 to ``t_max``.
|
|
116
|
+
nt: Number of time points (>= 2).
|
|
117
|
+
nz: Number of z points (>= 2).
|
|
118
|
+
d: Dipole ratio ``|d31/d32|`` (> 0).
|
|
119
|
+
omega: Wave-number ratio ``k31/k32`` (> 0); the 3→1 coupling is ``η = ω d²``.
|
|
120
|
+
r1, r2: Population ratios ``n3/n1`` and ``n3/n2`` (>= 0).
|
|
121
|
+
c31, c32, c21: Initial coherences as fractions of their largest values.
|
|
122
|
+
t1_31, t1_32: Population relaxation times, numbers or :class:`Steps` (> 0; ``inf`` = none).
|
|
123
|
+
t2_31, t2_32, t2_21: Coherence relaxation times, the same way.
|
|
124
|
+
pump31, pump32: Pumps of ``n31`` and ``n32``: a :class:`Pulse`, a number,
|
|
125
|
+
or a list of them (summed).
|
|
126
|
+
field31_in, field32_in: Fields entering at ``z = 0``: a :class:`Pulse`, a number or ``None``.
|
|
127
|
+
n_planes: Number of evenly spaced z planes to return, from 0 to 1 (<= ``nz``).
|
|
128
|
+
|
|
129
|
+
Returns:
|
|
130
|
+
A :class:`Result`.
|
|
131
|
+
|
|
132
|
+
Example:
|
|
133
|
+
>>> res = solve_1d(t_max=2500, nt=4000, nz=400, d=0.875, omega=35.95,
|
|
134
|
+
... r1=0.94, r2=2.33e19, c31=1e-10, c32=1.0,
|
|
135
|
+
... t1_31=31.3, t1_32=313, t2_31=2.96, t2_32=29.6,
|
|
136
|
+
... pump32=Pulse(a=5.63e-3, x0=795.5, w=154.8))
|
|
137
|
+
>>> exit_intensity = res.intensity32[-1]
|
|
138
|
+
"""
|
|
139
|
+
nt, nz, n_planes = int(nt), int(nz), int(n_planes)
|
|
140
|
+
if nt < 2 or nz < 2:
|
|
141
|
+
raise ValueError("nt and nz must be at least 2")
|
|
142
|
+
if not 1 <= n_planes <= nz:
|
|
143
|
+
raise ValueError(f"n_planes must be between 1 and nz ({nz}), got {n_planes}")
|
|
144
|
+
if not t_max > 0:
|
|
145
|
+
raise ValueError("t_max must be positive")
|
|
146
|
+
if not (d > 0 and omega > 0):
|
|
147
|
+
raise ValueError("d and omega must be positive")
|
|
148
|
+
|
|
149
|
+
pops = populations(float(r1), float(r2))
|
|
150
|
+
init = np.array([pops["n31"], pops["n32"], c31 * pops["r31"], c32 * pops["r32"],
|
|
151
|
+
c21 * pops["r21"]], dtype=np.float64)
|
|
152
|
+
|
|
153
|
+
t, dt, z, dz = grids_1d(float(t_max), nt, nz)
|
|
154
|
+
pump31_t, pump32_t = _sum(pump31, t), _sum(pump32, t)
|
|
155
|
+
field31_t, field32_t = evaluate(field31_in, t), evaluate(field32_in, t)
|
|
156
|
+
times = {}
|
|
157
|
+
for name, value in (("t1_31", t1_31), ("t1_32", t1_32), ("t2_31", t2_31),
|
|
158
|
+
("t2_32", t2_32), ("t2_21", t2_21)):
|
|
159
|
+
times[name] = evaluate(value, t)
|
|
160
|
+
if np.any(times[name] <= 0):
|
|
161
|
+
raise ValueError(f"{name} must be positive")
|
|
162
|
+
|
|
163
|
+
eta = float(omega) * float(d) * float(d)
|
|
164
|
+
v, E = solve_kernel(t, dt, z, dz, n_planes, init, field31_t, field32_t,
|
|
165
|
+
pump31_t, pump32_t, times["t1_31"], times["t1_32"],
|
|
166
|
+
times["t2_31"], times["t2_32"], times["t2_21"], eta)
|
|
167
|
+
|
|
168
|
+
e31, e32 = E[:, 0], E[:, 1]
|
|
169
|
+
planes = z[np.rint(np.linspace(0.0, 1.0, n_planes) * (nz - 1)).astype(np.int64)]
|
|
170
|
+
return Result(
|
|
171
|
+
time=t, z=planes, e31=e31, e32=e32,
|
|
172
|
+
intensity31=e31 ** 2 / float(d) ** 2, intensity32=e32 ** 2,
|
|
173
|
+
n31=v[:, 0], n32=v[:, 1], r31=v[:, 2], r32=v[:, 3], r21=v[:, 4],
|
|
174
|
+
pump31=pump31_t, pump32=pump32_t, field31_in=field31_t, field32_in=field32_t,
|
|
175
|
+
**times,
|
|
176
|
+
)
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
"""Λ-type three-level Maxwell-Bloch equations in one dimension (numba kernel).
|
|
2
|
+
|
|
3
|
+
Moved from the three-level solver of 2025 (``maxwell_bloch_three_level_v2.py``)
|
|
4
|
+
with the same arithmetic: RK4 in time for populations and coherences,
|
|
5
|
+
explicit step in z for the fields. All quantities are real.
|
|
6
|
+
|
|
7
|
+
dn31/dτ = -(E1 R31 + ½ E2 R32) - (n31 - n31⁰) / τ31⁽¹⁾ + Λ31
|
|
8
|
+
dn32/dτ = -(½ E1 R31 + E2 R32) - (n32 - n32⁰) / τ32⁽¹⁾ + Λ32
|
|
9
|
+
dR31/dτ = E1 n31 - ½ E2 R21 - (R31 - R31⁰) / τ31⁽²⁾
|
|
10
|
+
dR32/dτ = E2 n32 - ½ E1 R21 - (R32 - R32⁰) / τ32⁽²⁾
|
|
11
|
+
dR21/dτ = ½ (E1 R32 + E2 R31) - (R21 - R21⁰) / τ21⁽²⁾
|
|
12
|
+
dE1/dξ = η R31, dE2/dξ = R32
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
from __future__ import annotations
|
|
16
|
+
|
|
17
|
+
import numpy as np
|
|
18
|
+
from numba import njit
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
@njit(inline="always", nogil=True, cache=True)
|
|
22
|
+
def _derivs(n31, n32, R31, R32, R21, kn31, kn32, kR31, kR32, kR21,
|
|
23
|
+
n31_0, n32_0, R31_0, R32_0, R21_0, E31, E32,
|
|
24
|
+
pump31, pump32, t1_31, t1_32, t2_31, t2_32, t2_21):
|
|
25
|
+
"""Right-hand sides for one RK stage."""
|
|
26
|
+
return (
|
|
27
|
+
-(E31 * (R31 + kR31) + 0.5 * E32 * (R32 + kR32)) - (n31 + kn31 - n31_0) / t1_31 + pump31,
|
|
28
|
+
-(0.5 * E31 * (R31 + kR31) + E32 * (R32 + kR32)) - (n32 + kn32 - n32_0) / t1_32 + pump32,
|
|
29
|
+
E31 * (n31 + kn31) - 0.5 * E32 * (R21 + kR21) - (R31 + kR31 - R31_0) / t2_31,
|
|
30
|
+
E32 * (n32 + kn32) - 0.5 * E31 * (R21 + kR21) - (R32 + kR32 - R32_0) / t2_32,
|
|
31
|
+
0.5 * (E31 * (R32 + kR32) + E32 * (R31 + kR31)) - (R21 + kR21 - R21_0) / t2_21,
|
|
32
|
+
)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
@njit(inline="always", nogil=True, cache=True)
|
|
36
|
+
def _rk4_sum(n31, n32, R31, R32, R21, n31_0, n32_0, R31_0, R32_0, R21_0, E31, E32,
|
|
37
|
+
pump31, pump32, t1_31, t1_32, t2_31, t2_32, t2_21, dt):
|
|
38
|
+
"""``k1 + 2 k2 + 2 k3 + k4`` for the five variables."""
|
|
39
|
+
h = 0.5 * dt
|
|
40
|
+
a1, b1, c1, d1, e1 = _derivs(n31, n32, R31, R32, R21, 0.0, 0.0, 0.0, 0.0, 0.0,
|
|
41
|
+
n31_0, n32_0, R31_0, R32_0, R21_0, E31, E32,
|
|
42
|
+
pump31, pump32, t1_31, t1_32, t2_31, t2_32, t2_21)
|
|
43
|
+
a2, b2, c2, d2, e2 = _derivs(n31, n32, R31, R32, R21,
|
|
44
|
+
h * a1, h * b1, h * c1, h * d1, h * e1,
|
|
45
|
+
n31_0, n32_0, R31_0, R32_0, R21_0, E31, E32,
|
|
46
|
+
pump31, pump32, t1_31, t1_32, t2_31, t2_32, t2_21)
|
|
47
|
+
a3, b3, c3, d3, e3 = _derivs(n31, n32, R31, R32, R21,
|
|
48
|
+
h * a2, h * b2, h * c2, h * d2, h * e2,
|
|
49
|
+
n31_0, n32_0, R31_0, R32_0, R21_0, E31, E32,
|
|
50
|
+
pump31, pump32, t1_31, t1_32, t2_31, t2_32, t2_21)
|
|
51
|
+
a4, b4, c4, d4, e4 = _derivs(n31, n32, R31, R32, R21,
|
|
52
|
+
dt * a3, dt * b3, dt * c3, dt * d3, dt * e3,
|
|
53
|
+
n31_0, n32_0, R31_0, R32_0, R21_0, E31, E32,
|
|
54
|
+
pump31, pump32, t1_31, t1_32, t2_31, t2_32, t2_21)
|
|
55
|
+
return (a1 + 2.0 * a2 + 2.0 * a3 + a4,
|
|
56
|
+
b1 + 2.0 * b2 + 2.0 * b3 + b4,
|
|
57
|
+
c1 + 2.0 * c2 + 2.0 * c3 + c4,
|
|
58
|
+
d1 + 2.0 * d2 + 2.0 * d3 + d4,
|
|
59
|
+
e1 + 2.0 * e2 + 2.0 * e3 + e4)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
@njit(nogil=True, cache=True)
|
|
63
|
+
def _slice(v, E31, E32, init, pump31, pump32, t1_31, t1_32, t2_31, t2_32, t2_21, dt):
|
|
64
|
+
"""Advance one z slice in time; ``v`` is ``(5, nt)`` with column 0 set."""
|
|
65
|
+
nt = v.shape[1]
|
|
66
|
+
dt6 = dt / 6.0
|
|
67
|
+
n31_0, n32_0, R31_0, R32_0, R21_0 = init[0], init[1], init[2], init[3], init[4]
|
|
68
|
+
for j in range(1, nt):
|
|
69
|
+
i = j - 1
|
|
70
|
+
s0, s1, s2, s3, s4 = _rk4_sum(
|
|
71
|
+
v[0, i], v[1, i], v[2, i], v[3, i], v[4, i],
|
|
72
|
+
n31_0, n32_0, R31_0, R32_0, R21_0, E31[i], E32[i],
|
|
73
|
+
pump31[i], pump32[i], t1_31[i], t1_32[i], t2_31[i], t2_32[i], t2_21[i], dt)
|
|
74
|
+
v[0, j] = v[0, i] + dt6 * s0
|
|
75
|
+
v[1, j] = v[1, i] + dt6 * s1
|
|
76
|
+
v[2, j] = v[2, i] + dt6 * s2
|
|
77
|
+
v[3, j] = v[3, i] + dt6 * s3
|
|
78
|
+
v[4, j] = v[4, i] + dt6 * s4
|
|
79
|
+
|
|
80
|
+
|
|
81
|
+
@njit(nogil=True, cache=True)
|
|
82
|
+
def solve_kernel(t, dt, z, dz, n_z_planes, init, field31_in, field32_in, pump31, pump32,
|
|
83
|
+
t1_31, t1_32, t2_31, t2_32, t2_21, eta):
|
|
84
|
+
"""Advance the system over the grid.
|
|
85
|
+
|
|
86
|
+
Args:
|
|
87
|
+
t, dt: Time grid and step.
|
|
88
|
+
z, dz: Spatial grid and step.
|
|
89
|
+
n_z_planes: Number of evenly spaced z planes to store (<= len(z)).
|
|
90
|
+
init: Initial (and equilibrium) ``(n31, n32, R31, R32, R21)``, the same at every z.
|
|
91
|
+
field31_in, field32_in: Fields at z = 0 on the time grid.
|
|
92
|
+
pump31, pump32: Pumps on the time grid.
|
|
93
|
+
t1_31, t1_32, t2_31, t2_32, t2_21: Relaxation times on the time grid (> 0, may be inf).
|
|
94
|
+
eta: Coupling coefficient of the 3→1 field (that of 3→2 is 1).
|
|
95
|
+
|
|
96
|
+
Returns:
|
|
97
|
+
``(v, E)``: ``v`` of shape ``(n_z_planes, 5, len(t))`` holding
|
|
98
|
+
``n31, n32, R31, R32, R21``; ``E`` of shape ``(n_z_planes, 2, len(t))``
|
|
99
|
+
holding ``E31, E32``.
|
|
100
|
+
"""
|
|
101
|
+
nt = len(t)
|
|
102
|
+
nz = len(z)
|
|
103
|
+
z_planes = np.linspace(0.0, 1.0, n_z_planes)
|
|
104
|
+
z_plane_indices = np.rint(z_planes * (nz - 1)).astype(np.int64)
|
|
105
|
+
|
|
106
|
+
v_old = np.empty((5, nt), dtype=np.float64)
|
|
107
|
+
v_new = np.empty((5, nt), dtype=np.float64)
|
|
108
|
+
E31_old = field31_in.copy()
|
|
109
|
+
E32_old = field32_in.copy()
|
|
110
|
+
E31_new = np.empty(nt, dtype=np.float64)
|
|
111
|
+
E32_new = np.empty(nt, dtype=np.float64)
|
|
112
|
+
|
|
113
|
+
v_result = np.empty((n_z_planes, 5, nt), dtype=np.float64)
|
|
114
|
+
E_result = np.empty((n_z_planes, 2, nt), dtype=np.float64)
|
|
115
|
+
|
|
116
|
+
v_old[:, 0] = init
|
|
117
|
+
_slice(v_old, E31_old, E32_old, init, pump31, pump32, t1_31, t1_32, t2_31, t2_32, t2_21, dt)
|
|
118
|
+
v_result[0] = v_old
|
|
119
|
+
E_result[0, 0] = E31_old
|
|
120
|
+
E_result[0, 1] = E32_old
|
|
121
|
+
i = 1
|
|
122
|
+
|
|
123
|
+
for z_idx in range(1, nz):
|
|
124
|
+
for j in range(nt):
|
|
125
|
+
E31_new[j] = E31_old[j] + eta * v_old[2, j] * dz
|
|
126
|
+
E32_new[j] = E32_old[j] + 1.0 * v_old[3, j] * dz
|
|
127
|
+
v_new[:, 0] = init
|
|
128
|
+
_slice(v_new, E31_new, E32_new, init, pump31, pump32, t1_31, t1_32, t2_31, t2_32, t2_21, dt)
|
|
129
|
+
|
|
130
|
+
if i < n_z_planes and z_plane_indices[i] == z_idx:
|
|
131
|
+
v_result[i] = v_new
|
|
132
|
+
E_result[i, 0] = E31_new
|
|
133
|
+
E_result[i, 1] = E32_new
|
|
134
|
+
i += 1
|
|
135
|
+
|
|
136
|
+
v_old, v_new = v_new, v_old
|
|
137
|
+
E31_old, E31_new = E31_new, E31_old
|
|
138
|
+
E32_old, E32_new = E32_new, E32_old
|
|
139
|
+
|
|
140
|
+
return v_result, E_result
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
"""Initial populations and scales of the three-level model.
|
|
2
|
+
|
|
3
|
+
:func:`populations` gives the level populations and population differences
|
|
4
|
+
from the ratios ``r1 = n3/n1`` and ``r2 = n3/n2``; :func:`scaling` turns
|
|
5
|
+
the physical values of the two transitions into the solver's ``d`` and
|
|
6
|
+
``omega`` and the time, field, intensity and pump scales.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import math
|
|
12
|
+
from typing import Dict, Optional
|
|
13
|
+
|
|
14
|
+
from mbsolver.constants import C, EPSILON_0, H_BAR, PI
|
|
15
|
+
|
|
16
|
+
__all__ = ["populations", "scaling"]
|
|
17
|
+
|
|
18
|
+
|
|
19
|
+
def populations(r1: float, r2: float) -> Dict[str, float]:
|
|
20
|
+
"""Level populations from ``r1 = n3/n1`` and ``r2 = n3/n2`` (``n1 + n2 + n3 = 1``).
|
|
21
|
+
|
|
22
|
+
Returns:
|
|
23
|
+
Mapping with ``n1``, ``n2``, ``n3``, the differences ``n31 = n3 - n1``
|
|
24
|
+
and ``n32 = n3 - n2``, and the largest coherences
|
|
25
|
+
``r31 = 2√(n3 n1)``, ``r32 = 2√(n3 n2)``, ``r21 = 2√(n2 n1)``
|
|
26
|
+
(the solver's initial coherences are ``c_ij`` times these).
|
|
27
|
+
"""
|
|
28
|
+
if r1 < 0 or r2 < 0:
|
|
29
|
+
raise ValueError("r1 and r2 must not be negative")
|
|
30
|
+
c = r1 + r2 + r1 * r2
|
|
31
|
+
if c == 0.0:
|
|
32
|
+
return {"n1": 0.5, "n2": 0.5, "n3": 0.0, "n31": -0.5, "n32": -0.5,
|
|
33
|
+
"r31": 0.0, "r32": 0.0, "r21": 1.0}
|
|
34
|
+
return {
|
|
35
|
+
"n1": r2 / c, "n2": r1 / c, "n3": r1 * r2 / c,
|
|
36
|
+
"n31": r2 * (r1 - 1) / c, "n32": r1 * (r2 - 1) / c,
|
|
37
|
+
"r31": 2.0 * r2 * math.sqrt(r1) / c,
|
|
38
|
+
"r32": 2.0 * r1 * math.sqrt(r2) / c,
|
|
39
|
+
"r21": 2.0 * math.sqrt(r1 * r2) / c,
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
def scaling(nu31: float, nu32: float, d31: float, d32: float, l: float, n0: float,
|
|
44
|
+
gamma: Optional[float] = None) -> Dict[str, float]:
|
|
45
|
+
"""Compute the solver parameters and scales from the physical values (SI units).
|
|
46
|
+
|
|
47
|
+
The time unit is ``T0 = 2 ε0 ħ / (n0 L k32 |d32|²)``. This equals
|
|
48
|
+
``8π / (3 Γ n0 L λ32²)`` with ``Γ`` the Einstein A of the 3→2 line
|
|
49
|
+
computed from ``d32``; ``gamma`` replaces that ``Γ`` by a given rate.
|
|
50
|
+
|
|
51
|
+
Args:
|
|
52
|
+
nu31, nu32: Frequencies of the 3→1 and 3→2 transitions in Hz.
|
|
53
|
+
d31, d32: Dipole moments in C·m (``mbsolver.constants.DEBYE`` converts from debye).
|
|
54
|
+
l: Length of the medium L in m.
|
|
55
|
+
n0: Density scale n₀ in m⁻³.
|
|
56
|
+
gamma: Decay rate Γ of the 3→2 line in s⁻¹; by default the Einstein A from ``d32``.
|
|
57
|
+
|
|
58
|
+
Returns:
|
|
59
|
+
Mapping:
|
|
60
|
+
|
|
61
|
+
- ``d`` = |d31/d32| and ``omega`` = k31/k32 (the solver's ``d`` and ``omega``),
|
|
62
|
+
``eta`` = ω d² (the coupling of the 3→1 field),
|
|
63
|
+
- ``k31``, ``k32``, ``lambda31``, ``lambda32``: wave numbers and wavelengths,
|
|
64
|
+
- ``gamma``: the decay rate used, ``t0``: time unit T₀ in s,
|
|
65
|
+
- ``e0`` = ħ / (T₀ d32): field scale in V/m,
|
|
66
|
+
- ``i0`` = ½ ε₀ c E₀²: intensity scale in W/m², ``i0_jy`` = 10²⁶ ``i0``,
|
|
67
|
+
- ``lambda0`` = n₀ / T₀: pump scale in m⁻³ s⁻¹.
|
|
68
|
+
"""
|
|
69
|
+
k31 = 2 * PI * nu31 / C
|
|
70
|
+
k32 = 2 * PI * nu32 / C
|
|
71
|
+
if gamma is None:
|
|
72
|
+
gamma = k32**3 * d32**2 / (3 * PI * EPSILON_0 * H_BAR)
|
|
73
|
+
t0 = 2.0 * EPSILON_0 * H_BAR / (n0 * l * k32 * d32**2)
|
|
74
|
+
else:
|
|
75
|
+
t0 = 2.0 * k32**2 / (3.0 * PI * gamma * n0 * l)
|
|
76
|
+
d = abs(d31 / d32)
|
|
77
|
+
omega = k31 / k32
|
|
78
|
+
e0 = H_BAR / (t0 * d32)
|
|
79
|
+
i0 = 0.5 * EPSILON_0 * C * e0**2
|
|
80
|
+
return {
|
|
81
|
+
"d": d, "omega": omega, "eta": omega * d**2,
|
|
82
|
+
"k31": k31, "k32": k32, "lambda31": C / nu31, "lambda32": C / nu32,
|
|
83
|
+
"gamma": gamma, "t0": t0, "e0": e0, "i0": i0, "i0_jy": i0 * 1e26,
|
|
84
|
+
"lambda0": n0 / t0,
|
|
85
|
+
}
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: mbsolver
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.4.0
|
|
4
4
|
Summary: Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation
|
|
5
|
+
Author: Toktam Rashidi
|
|
5
6
|
Author-email: Vahid Anari <vahid.anari8@gmail.com>
|
|
6
7
|
License-Expression: MIT
|
|
7
8
|
Project-URL: Homepage, https://github.com/vahid-anari/mbsolver
|
|
@@ -34,6 +35,8 @@ Dynamic: license-file
|
|
|
34
35
|
[](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml)
|
|
35
36
|
[](https://pypi.org/project/mbsolver/)
|
|
36
37
|
[](https://pypi.org/project/mbsolver/)
|
|
38
|
+
[](https://doi.org/10.5281/zenodo.23407483)
|
|
39
|
+

|
|
37
40
|
|
|
38
41
|
Fast Maxwell-Bloch solvers in Python (numpy + numba) for astrophysical masers,
|
|
39
42
|
superradiance and coherent pulse propagation. Use them from scripts,
|
|
@@ -41,10 +44,14 @@ notebooks or cluster jobs; the
|
|
|
41
44
|
[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio)
|
|
42
45
|
desktop app runs on the same code.
|
|
43
46
|
|
|
47
|
+
## Installation
|
|
48
|
+
|
|
44
49
|
```
|
|
45
50
|
pip install mbsolver
|
|
46
51
|
```
|
|
47
52
|
|
|
53
|
+
Requires Python 3.10+ (numpy and numba are installed with it).
|
|
54
|
+
|
|
48
55
|
## Two-level model in one dimension
|
|
49
56
|
|
|
50
57
|
Dimensionless equations for the population inversion `w`, the coherence `R`
|
|
@@ -96,9 +103,63 @@ plt.show()
|
|
|
96
103
|
`res.time`, `res.z` (positions of the stored planes), `res.intensity` and
|
|
97
104
|
`res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
|
|
98
105
|
|
|
99
|
-
##
|
|
106
|
+
## Three-level (Λ) model in one dimension
|
|
107
|
+
|
|
108
|
+
Levels 1 and 2 lie below level 3; the transitions 3→1 and 3→2 carry the fields
|
|
109
|
+
`E31` and `E32`. With the population differences `n31 = n3 − n1`,
|
|
110
|
+
`n32 = n3 − n2` and the coherences `R31`, `R32`, `R21` (all real):
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
dn31/dt = −(E31 R31 + ½ E32 R32) − (n31 − n31⁰) / T1_31 + Λ31(t)
|
|
114
|
+
dn32/dt = −(½ E31 R31 + E32 R32) − (n32 − n32⁰) / T1_32 + Λ32(t)
|
|
115
|
+
dR31/dt = E31 n31 − ½ E32 R21 − (R31 − R31⁰) / T2_31
|
|
116
|
+
dR32/dt = E32 n32 − ½ E31 R21 − (R32 − R32⁰) / T2_32
|
|
117
|
+
dR21/dt = ½ (E31 R32 + E32 R31) − (R21 − R21⁰) / T2_21
|
|
118
|
+
dE31/dz = η R31, dE32/dz = R32, η = ω d²
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
with `d = |d31/d32|` and `ω = k31/k32`. Time is in units of the 3→2 time
|
|
122
|
+
scale `T0 = 2ε0ħ / (n0 L k32 |d32|²)`. The initial state comes from the
|
|
123
|
+
population ratios `r1 = n3/n1`, `r2 = n3/n2` and the coherence fractions
|
|
124
|
+
`c_ij`: `R_ij⁰ = c_ij · 2√(n_i n_j)`.
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
from mbsolver import Pulse
|
|
128
|
+
from mbsolver.three_level import solve_1d
|
|
129
|
+
|
|
130
|
+
res = solve_1d(
|
|
131
|
+
t_max=2500, nt=4000, nz=400, d=0.875, omega=35.95,
|
|
132
|
+
r1=0.94, r2=2.33e19, c31=1e-10, c32=1.0, # c21 = 0 by default
|
|
133
|
+
t1_31=31.3, t1_32=313, t2_31=2.96, t2_32=29.6, # t2_21 = inf by default
|
|
134
|
+
pump32=Pulse(a=5.63e-3, x0=795.5, w=154.8), # pump31, field31_in, field32_in too
|
|
135
|
+
)
|
|
136
|
+
res.intensity32[-1] # 3→2 intensity leaving the medium
|
|
137
|
+
```
|
|
100
138
|
|
|
101
|
-
|
|
139
|
+
`t1_*` and `t2_*` take numbers or `Steps`, the pumps and entrance fields
|
|
140
|
+
`Pulse`s, numbers or lists, as in the two-level model. The result holds
|
|
141
|
+
`time`, `z`, the fields `e31`, `e32`, the intensities `intensity31 = (E31/d)²`
|
|
142
|
+
and `intensity32 = E32²` (both in units of the 3→2 scale), `n31`, `n32`,
|
|
143
|
+
`r31`, `r32`, `r21` (shape `(n_planes, nt)`), and the pumps, entrance fields
|
|
144
|
+
and relaxation times on the time grid.
|
|
145
|
+
|
|
146
|
+
`populations(r1, r2)` gives `n1`, `n2`, `n3`, `n31⁰`, `n32⁰` and the largest
|
|
147
|
+
coherences. `scaling(nu31, nu32, d31, d32, l, n0)` (SI units;
|
|
148
|
+
`mbsolver.constants.DEBYE` converts dipoles from debye) gives `d`, `omega`,
|
|
149
|
+
`eta`, `t0`, the field and intensity scales `e0`, `i0` (and `i0_jy` = 10²⁶ `i0`)
|
|
150
|
+
and the pump scale `lambda0 = n0/t0`. By default the decay rate of the 3→2
|
|
151
|
+
line is the Einstein A computed from `d32`; pass `gamma=` to use a measured one.
|
|
152
|
+
|
|
153
|
+
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/);
|
|
156
|
+
[`examples/three_level/s255_flare.py`](examples/three_level/s255_flare.py)
|
|
157
|
+
runs the S255IR-NIRS3 flare and plots it with the observed flux (needs
|
|
158
|
+
matplotlib).
|
|
159
|
+
|
|
160
|
+
## From physical values: `scaling` (two-level)
|
|
161
|
+
|
|
162
|
+
The solvers take dimensionless parameters. `mbsolver.scaling` computes them for the two-level model from the
|
|
102
163
|
physical sample values (SI units): transition frequency `nu` (Hz), spontaneous
|
|
103
164
|
decay rate `gamma` (s⁻¹), time unit `t0` (s), length `l` (m) and inverted
|
|
104
165
|
population density `n0` (m⁻³).
|
|
@@ -131,7 +192,7 @@ width `w` (0 for a sharp step). `x0` and `w` have one value fewer than `y`.
|
|
|
131
192
|
A zero width gives a single point (pulse) or a sharp step; an infinite width
|
|
132
193
|
a constant. `profile.evaluate(t)` returns the values on any grid.
|
|
133
194
|
|
|
134
|
-
##
|
|
195
|
+
## Development
|
|
135
196
|
|
|
136
197
|
```
|
|
137
198
|
pip install -e ".[dev]"
|
|
@@ -140,8 +201,14 @@ pytest
|
|
|
140
201
|
|
|
141
202
|
The tests include a reference run that must match the solver of the Maxwell
|
|
142
203
|
Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
|
|
143
|
-
entrance, relaxation balance, uncoupled propagation).
|
|
144
|
-
|
|
204
|
+
entrance, relaxation balance, uncoupled propagation). The three-level model
|
|
205
|
+
matches the 2025 three-level solver exactly for the S255IR-NIRS3 case. `scaling`
|
|
206
|
+
is checked against the values of Maxwell Bloch Studio.
|
|
207
|
+
|
|
208
|
+
What changed in each version is in [`CHANGELOG.md`](CHANGELOG.md). Pushing a
|
|
209
|
+
tag `vX.Y.Z` publishes a GitHub Release with that version's section of the
|
|
210
|
+
changelog, and Zenodo gives it a DOI; update `version` and `date-released` in
|
|
211
|
+
`CITATION.cff` before tagging.
|
|
145
212
|
|
|
146
213
|
## Earlier name
|
|
147
214
|
|
|
@@ -152,10 +219,28 @@ your imports.
|
|
|
152
219
|
|
|
153
220
|
## Citing
|
|
154
221
|
|
|
155
|
-
If you use mbsolver in published work, please cite it
|
|
156
|
-
|
|
157
|
-
|
|
222
|
+
If you use mbsolver in published work, please cite it:
|
|
223
|
+
|
|
224
|
+
> Anari, V., & Rashidi, T. *mbsolver: Fast Maxwell-Bloch solvers for masers, superradiance and
|
|
225
|
+
> coherent pulse propagation*. Zenodo. https://doi.org/10.5281/zenodo.23407483
|
|
226
|
+
|
|
227
|
+
This DOI always points to the latest version. Each release also has its own
|
|
228
|
+
DOI (for 0.3.1: [10.5281/zenodo.23407484](https://doi.org/10.5281/zenodo.23407484));
|
|
229
|
+
cite the version you used, which you find under *Versions* on the Zenodo page.
|
|
230
|
+
GitHub's **Cite this repository** button gives the same in BibTeX and APA.
|
|
158
231
|
|
|
159
232
|
## License
|
|
160
233
|
|
|
161
|
-
MIT
|
|
234
|
+
MIT License. See [LICENSE](LICENSE).
|
|
235
|
+
|
|
236
|
+
## Authors
|
|
237
|
+
|
|
238
|
+
Vahid Anari ·
|
|
239
|
+
[GitHub](https://github.com/vahid-anari) ·
|
|
240
|
+
[LinkedIn](https://www.linkedin.com/in/vahid-anari/)
|
|
241
|
+
|
|
242
|
+
Toktam Rashidi (three-level model)
|
|
243
|
+
|
|
244
|
+
Related projects: [sciwidgets](https://github.com/vahid-anari/sciwidgets) ·
|
|
245
|
+
[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio) ·
|
|
246
|
+
[linecat](https://github.com/vahid-anari/linecat)
|
|
@@ -11,8 +11,12 @@ src/mbsolver.egg-info/SOURCES.txt
|
|
|
11
11
|
src/mbsolver.egg-info/dependency_links.txt
|
|
12
12
|
src/mbsolver.egg-info/requires.txt
|
|
13
13
|
src/mbsolver.egg-info/top_level.txt
|
|
14
|
+
src/mbsolver/three_level/__init__.py
|
|
15
|
+
src/mbsolver/three_level/_kernel_1d.py
|
|
16
|
+
src/mbsolver/three_level/sample.py
|
|
14
17
|
src/mbsolver/two_level/__init__.py
|
|
15
18
|
src/mbsolver/two_level/_kernel_1d.py
|
|
16
19
|
tests/test_profiles.py
|
|
17
20
|
tests/test_sample.py
|
|
21
|
+
tests/test_three_level.py
|
|
18
22
|
tests/test_two_level.py
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
"""Tests for mbsolver.three_level."""
|
|
2
|
+
|
|
3
|
+
import json
|
|
4
|
+
import math
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
|
|
7
|
+
import numpy as np
|
|
8
|
+
import pytest
|
|
9
|
+
|
|
10
|
+
from mbsolver import Pulse
|
|
11
|
+
from mbsolver.constants import DEBYE
|
|
12
|
+
from mbsolver.three_level import populations, scaling, solve_1d
|
|
13
|
+
|
|
14
|
+
DATA = Path(__file__).parent / "data"
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
def test_matches_three_level_solver_2025():
|
|
18
|
+
"""Same results as the 2025 three-level solver (v7) for the S255IR-NIRS3 case."""
|
|
19
|
+
p = json.loads((DATA / "reference_three_level_params.json").read_text())
|
|
20
|
+
ref = np.load(DATA / "reference_three_level.npz")
|
|
21
|
+
a, x0, w = p.pop("pump32")
|
|
22
|
+
res = solve_1d(**p, pump32=Pulse(a=a, x0=x0, w=w))
|
|
23
|
+
for name in ("time", "pump31", "pump32"):
|
|
24
|
+
np.testing.assert_allclose(getattr(res, name), ref[name], rtol=1e-12, atol=0, err_msg=name)
|
|
25
|
+
for name in ("e31", "e32", "intensity31", "intensity32", "n31", "n32", "r31", "r32", "r21"):
|
|
26
|
+
np.testing.assert_allclose(getattr(res, name)[-1], ref[name], rtol=1e-12, atol=0,
|
|
27
|
+
err_msg=name)
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
BASE = dict(t_max=50, nt=501, nz=11, d=0.9, omega=2.0, r1=0.9, r2=5.0, c31=1e-3, c32=1e-2,
|
|
31
|
+
t1_31=10, t1_32=20, t2_31=5, t2_32=8)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def test_no_coupling_leaves_fields_unchanged():
|
|
35
|
+
"""With η = 0 for 3→1 and no medium for 3→2 the entrance fields pass unchanged."""
|
|
36
|
+
res = solve_1d(**{**BASE, "r1": 1.0, "r2": 1.0, "c31": 0.0, "c32": 0.0},
|
|
37
|
+
field31_in=Pulse(a=0.05, x0=20, w=5), n_planes=4)
|
|
38
|
+
for plane in res.e31:
|
|
39
|
+
np.testing.assert_allclose(plane, res.field31_in, rtol=0, atol=1e-15)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def test_relaxation_and_pump_balance():
|
|
43
|
+
"""Without fields, n relaxes to n⁰ + T1 · Λ for a constant pump."""
|
|
44
|
+
pops = populations(BASE["r1"], BASE["r2"])
|
|
45
|
+
res = solve_1d(**{**BASE, "c31": 0.0, "c32": 0.0, "t_max": 400, "nt": 4001, "nz": 2},
|
|
46
|
+
pump31=1e-3, pump32=2e-3)
|
|
47
|
+
assert res.n31[-1, -1] == pytest.approx(pops["n31"] + 10 * 1e-3, rel=1e-6)
|
|
48
|
+
assert res.n32[-1, -1] == pytest.approx(pops["n32"] + 20 * 2e-3, rel=1e-6)
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
def test_entrance_follows_the_bloch_equations():
|
|
52
|
+
"""At z = 0 a weak 3→2 field rotates R32 like a two-level system (n32 nearly fixed)."""
|
|
53
|
+
res = solve_1d(**{**BASE, "c31": 0.0, "c32": 0.0, "t1_31": math.inf, "t1_32": math.inf,
|
|
54
|
+
"t2_31": math.inf, "t2_32": math.inf, "nt": 4001, "nz": 2},
|
|
55
|
+
field32_in=Pulse(a=1e-4, x0=20, w=5))
|
|
56
|
+
dt = res.time[1] - res.time[0]
|
|
57
|
+
area = np.concatenate(([0.0], np.cumsum(res.field32_in[:-1]) * dt))
|
|
58
|
+
n32 = populations(BASE["r1"], BASE["r2"])["n32"]
|
|
59
|
+
np.testing.assert_allclose(res.r32[0], n32 * area, rtol=1e-3, atol=1e-12)
|
|
60
|
+
|
|
61
|
+
|
|
62
|
+
def test_result_shapes_and_planes():
|
|
63
|
+
res = solve_1d(**{**BASE, "nz": 21}, n_planes=5)
|
|
64
|
+
for name in ("e31", "e32", "intensity31", "intensity32", "n31", "n32", "r31", "r32", "r21"):
|
|
65
|
+
assert getattr(res, name).shape == (5, 501), name
|
|
66
|
+
np.testing.assert_allclose(res.z, [0, 0.25, 0.5, 0.75, 1.0])
|
|
67
|
+
np.testing.assert_allclose(res.intensity31, res.e31 ** 2 / BASE["d"] ** 2)
|
|
68
|
+
|
|
69
|
+
|
|
70
|
+
@pytest.mark.parametrize("kwargs, message", [
|
|
71
|
+
(dict(nt=1), "nt and nz"),
|
|
72
|
+
(dict(n_planes=50), "n_planes"),
|
|
73
|
+
(dict(d=0.0), "d and omega"),
|
|
74
|
+
(dict(t2_21=0.0), "t2_21 must be positive"),
|
|
75
|
+
(dict(r1=-1.0), "must not be negative"),
|
|
76
|
+
(dict(pump32="x"), "expected None"),
|
|
77
|
+
])
|
|
78
|
+
def test_invalid_input(kwargs, message):
|
|
79
|
+
with pytest.raises((ValueError, TypeError), match=message):
|
|
80
|
+
solve_1d(**{**BASE, **kwargs})
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def test_populations():
|
|
84
|
+
p = populations(0.94, 2.33e19)
|
|
85
|
+
assert p["n1"] + p["n2"] + p["n3"] == pytest.approx(1.0, rel=1e-15)
|
|
86
|
+
assert p["n31"] == pytest.approx(p["n3"] - p["n1"], abs=1e-15)
|
|
87
|
+
assert p["n32"] == pytest.approx(p["n3"] - p["n2"], abs=1e-15)
|
|
88
|
+
assert p["r31"] == pytest.approx(2 * math.sqrt(p["n3"] * p["n1"]), rel=1e-12)
|
|
89
|
+
# values in the paper's S255IR-NIRS3 case
|
|
90
|
+
assert p["n31"] == pytest.approx(-0.0309, abs=1e-4)
|
|
91
|
+
assert p["n32"] == pytest.approx(0.4845, abs=1e-4)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
# S255IR-NIRS3 values of the 2025 plotting script
|
|
95
|
+
S255 = dict(nu31=239_746.219e6, nu32=6_668.564e6, d31=0.59425 * DEBYE, d32=0.67936 * DEBYE,
|
|
96
|
+
l=2.1e13, n0=1.17e-6 * (1 / 0.94 + 1))
|
|
97
|
+
|
|
98
|
+
|
|
99
|
+
def test_scaling_paper_values():
|
|
100
|
+
s = scaling(**S255)
|
|
101
|
+
assert s["d"] == pytest.approx(0.59425 / 0.67936, rel=1e-15)
|
|
102
|
+
assert s["omega"] == pytest.approx(239_746.219 / 6_668.564, rel=1e-15)
|
|
103
|
+
assert s["eta"] == pytest.approx(27.51, abs=0.01)
|
|
104
|
+
assert s["t0"] == pytest.approx(5.13e4, rel=1e-3)
|
|
105
|
+
assert scaling(**S255, gamma=1.56e-9)["t0"] == pytest.approx(5.24e4, rel=1e-3)
|
|
106
|
+
|
|
107
|
+
|
|
108
|
+
def test_scaling_gamma_from_d32_gives_the_same_t0():
|
|
109
|
+
"""With Γ = Einstein A from d32, both forms of T0 agree."""
|
|
110
|
+
s = scaling(**S255)
|
|
111
|
+
assert scaling(**S255, gamma=s["gamma"])["t0"] == pytest.approx(s["t0"], rel=1e-13)
|
|
112
|
+
assert s["lambda0"] == pytest.approx(S255["n0"] / s["t0"], rel=1e-15)
|
|
113
|
+
assert s["i0_jy"] == pytest.approx(1e26 * s["i0"], rel=1e-15)
|
mbsolver-0.3.1/README.md
DELETED
|
@@ -1,130 +0,0 @@
|
|
|
1
|
-
# mbsolver
|
|
2
|
-
|
|
3
|
-
[](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml)
|
|
4
|
-
[](https://pypi.org/project/mbsolver/)
|
|
5
|
-
[](https://pypi.org/project/mbsolver/)
|
|
6
|
-
|
|
7
|
-
Fast Maxwell-Bloch solvers in Python (numpy + numba) for astrophysical masers,
|
|
8
|
-
superradiance and coherent pulse propagation. Use them from scripts,
|
|
9
|
-
notebooks or cluster jobs; the
|
|
10
|
-
[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio)
|
|
11
|
-
desktop app runs on the same code.
|
|
12
|
-
|
|
13
|
-
```
|
|
14
|
-
pip install mbsolver
|
|
15
|
-
```
|
|
16
|
-
|
|
17
|
-
## Two-level model in one dimension
|
|
18
|
-
|
|
19
|
-
Dimensionless equations for the population inversion `w`, the coherence `R`
|
|
20
|
-
and the field `A` along a medium `0 ≤ z ≤ 1`:
|
|
21
|
-
|
|
22
|
-
```
|
|
23
|
-
dw/dt = A R − (w − w0) / T1 + Λ(t)
|
|
24
|
-
dR/dt = −A w − (R − R0) / T2
|
|
25
|
-
dA/dz = −η R
|
|
26
|
-
```
|
|
27
|
-
|
|
28
|
-
The field `A(t)` entering at `z = 0` is given; population and coherence are
|
|
29
|
-
advanced with fourth-order Runge-Kutta in time, the field step by step in `z`.
|
|
30
|
-
|
|
31
|
-
```python
|
|
32
|
-
import matplotlib.pyplot as plt
|
|
33
|
-
from mbsolver import Pulse, Steps
|
|
34
|
-
from mbsolver.two_level import solve_1d
|
|
35
|
-
|
|
36
|
-
res = solve_1d(
|
|
37
|
-
t_max=300, nt=3001, nz=121, eta=40.0,
|
|
38
|
-
theta0=0.003, # or w0=..., R0=...
|
|
39
|
-
pump=[Pulse(a=[2e-3, 1e-3], x0=[60, 180], w=[15, 25])],
|
|
40
|
-
field_in=Pulse(a=1e-3, x0=30, w=5), # A(t) at z = 0
|
|
41
|
-
t1=Steps(y=[80, 40, 60], x0=[100, 200], w=[10, 0]),
|
|
42
|
-
t2=5.0,
|
|
43
|
-
n_planes=7, # stored z planes, 0 ... 1
|
|
44
|
-
)
|
|
45
|
-
|
|
46
|
-
plt.plot(res.time, res.intensity[-1]) # intensity leaving the medium
|
|
47
|
-
plt.show()
|
|
48
|
-
```
|
|
49
|
-
|
|
50
|
-
### Arguments
|
|
51
|
-
|
|
52
|
-
| Argument | Meaning |
|
|
53
|
-
|----------|---------|
|
|
54
|
-
| `t_max`, `nt` | time grid from 0 to `t_max` with `nt` points |
|
|
55
|
-
| `nz` | number of z points |
|
|
56
|
-
| `eta` | coupling coefficient η |
|
|
57
|
-
| `theta0`, or `w0` and `R0` | initial state (`w0 = cos θ0`, `R0 = sin θ0`); the medium also relaxes towards it |
|
|
58
|
-
| `t1`, `t2` | relaxation times: a number or `Steps` (> 0, `math.inf` for none) |
|
|
59
|
-
| `pump` | Λ(t): a `Pulse`, a number, or a list of them (summed) |
|
|
60
|
-
| `field_in` | A(t) at z = 0: a `Pulse`, a number, or `None` |
|
|
61
|
-
| `n_planes` | number of evenly spaced z planes returned (default 2: entrance and exit) |
|
|
62
|
-
|
|
63
|
-
### Result
|
|
64
|
-
|
|
65
|
-
`res.time`, `res.z` (positions of the stored planes), `res.intensity` and
|
|
66
|
-
`res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
|
|
67
|
-
|
|
68
|
-
## From physical values: `scaling`
|
|
69
|
-
|
|
70
|
-
The solvers take dimensionless parameters. `scaling` computes them from the
|
|
71
|
-
physical sample values (SI units): transition frequency `nu` (Hz), spontaneous
|
|
72
|
-
decay rate `gamma` (s⁻¹), time unit `t0` (s), length `l` (m) and inverted
|
|
73
|
-
population density `n0` (m⁻³).
|
|
74
|
-
|
|
75
|
-
```python
|
|
76
|
-
import math
|
|
77
|
-
import mbsolver
|
|
78
|
-
from mbsolver.two_level import solve_1d
|
|
79
|
-
|
|
80
|
-
s = mbsolver.scaling(nu=6.67e9, gamma=1.56e-9, t0=86400, l=7.5e12, n0=5.3e-7)
|
|
81
|
-
res = solve_1d(t_max=2000, nt=20001, nz=101, eta=s["eta"], theta0=s["theta0"],
|
|
82
|
-
t1=math.inf, t2=math.inf)
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
Besides `eta` (η = T₀/T_R) and `theta0` (θ₀ = 2/√N), the result holds `t_r`,
|
|
86
|
-
`N`, `omega`, `lambda`, `k`, `lambda0` (Λ₀ = 1/T₀) and the field, polarization
|
|
87
|
-
and intensity scales for an electric dipole (`d`, `e0`, `p0`, `i0_electric`)
|
|
88
|
-
and a magnetic dipole (`mu`, `b0`, `m0`, `i0_magnetic`). Times in the solver
|
|
89
|
-
are in units of `t0`.
|
|
90
|
-
|
|
91
|
-
## Profiles
|
|
92
|
-
|
|
93
|
-
`Pulse(a, x0, w)` is a sum of sech² pulses, `a_i sech²((t − x0_i) / w_i)`.
|
|
94
|
-
Give `wl` and `wr` instead of `w` for a different width on each side.
|
|
95
|
-
|
|
96
|
-
`Steps(y, x0, w)` goes from level `y[0]` to `y[1]` around `x0[0]`, then to
|
|
97
|
-
`y[2]` around `x0[1]`, and so on, each step smoothed as `(1 + tanh)/2` with
|
|
98
|
-
width `w` (0 for a sharp step). `x0` and `w` have one value fewer than `y`.
|
|
99
|
-
|
|
100
|
-
A zero width gives a single point (pulse) or a sharp step; an infinite width
|
|
101
|
-
a constant. `profile.evaluate(t)` returns the values on any grid.
|
|
102
|
-
|
|
103
|
-
## Tests
|
|
104
|
-
|
|
105
|
-
```
|
|
106
|
-
pip install -e ".[dev]"
|
|
107
|
-
pytest
|
|
108
|
-
```
|
|
109
|
-
|
|
110
|
-
The tests include a reference run that must match the solver of the Maxwell
|
|
111
|
-
Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
|
|
112
|
-
entrance, relaxation balance, uncoupled propagation). `scaling` is checked
|
|
113
|
-
against the values of Maxwell Bloch Studio.
|
|
114
|
-
|
|
115
|
-
## Earlier name
|
|
116
|
-
|
|
117
|
-
Up to 0.1.0 this package was called `maxbloch`; 0.2.0 is the same code under
|
|
118
|
-
the new name. `maxbloch` stays on PyPI unchanged (0.1.1 only adds a
|
|
119
|
-
deprecation warning) but gets no updates; change `maxbloch` to `mbsolver` in
|
|
120
|
-
your imports.
|
|
121
|
-
|
|
122
|
-
## Citing
|
|
123
|
-
|
|
124
|
-
If you use mbsolver in published work, please cite it. The GitHub page has a
|
|
125
|
-
**Cite this repository** button (from [`CITATION.cff`](https://github.com/vahid-anari/mbsolver/blob/main/CITATION.cff)),
|
|
126
|
-
and each release has its own DOI on Zenodo; cite the version you used.
|
|
127
|
-
|
|
128
|
-
## License
|
|
129
|
-
|
|
130
|
-
MIT
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|