mbsolver 0.3.1__tar.gz → 0.5.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mbsolver-0.5.0/PKG-INFO +272 -0
- mbsolver-0.5.0/README.md +240 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/pyproject.toml +5 -2
- {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/__init__.py +1 -1
- {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/constants.py +3 -0
- mbsolver-0.5.0/src/mbsolver/three_level/__init__.py +176 -0
- mbsolver-0.5.0/src/mbsolver/three_level/_kernel_1d.py +140 -0
- mbsolver-0.5.0/src/mbsolver/three_level/sample.py +85 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/two_level/__init__.py +66 -7
- mbsolver-0.5.0/src/mbsolver/two_level/_kernel_adiabatic_1d.py +100 -0
- mbsolver-0.5.0/src/mbsolver.egg-info/PKG-INFO +272 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver.egg-info/SOURCES.txt +7 -1
- mbsolver-0.5.0/tests/test_three_level.py +113 -0
- mbsolver-0.5.0/tests/test_two_level_adiabatic.py +59 -0
- mbsolver-0.3.1/PKG-INFO +0 -161
- mbsolver-0.3.1/README.md +0 -130
- mbsolver-0.3.1/src/mbsolver.egg-info/PKG-INFO +0 -161
- {mbsolver-0.3.1 → mbsolver-0.5.0}/LICENSE +0 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/setup.cfg +0 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/grids.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/profiles.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/sample.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/two_level/_kernel_1d.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver.egg-info/dependency_links.txt +0 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver.egg-info/requires.txt +0 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver.egg-info/top_level.txt +0 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/tests/test_profiles.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/tests/test_sample.py +0 -0
- {mbsolver-0.3.1 → mbsolver-0.5.0}/tests/test_two_level.py +0 -0
mbsolver-0.5.0/PKG-INFO
ADDED
|
@@ -0,0 +1,272 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mbsolver
|
|
3
|
+
Version: 0.5.0
|
|
4
|
+
Summary: Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation
|
|
5
|
+
Author: Toktam Rashidi
|
|
6
|
+
Author-email: Vahid Anari <vahid.anari8@gmail.com>
|
|
7
|
+
License-Expression: MIT
|
|
8
|
+
Project-URL: Homepage, https://github.com/vahid-anari/mbsolver
|
|
9
|
+
Project-URL: Repository, https://github.com/vahid-anari/mbsolver
|
|
10
|
+
Project-URL: Issues, https://github.com/vahid-anari/mbsolver/issues
|
|
11
|
+
Keywords: maxwell-bloch,maser,superradiance,physics,astrophysics,numba,simulation
|
|
12
|
+
Classifier: Development Status :: 3 - Alpha
|
|
13
|
+
Classifier: Intended Audience :: Science/Research
|
|
14
|
+
Classifier: Operating System :: OS Independent
|
|
15
|
+
Classifier: Programming Language :: Python :: 3
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
17
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
18
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
20
|
+
Classifier: Topic :: Scientific/Engineering :: Physics
|
|
21
|
+
Classifier: Topic :: Scientific/Engineering :: Astronomy
|
|
22
|
+
Requires-Python: >=3.10
|
|
23
|
+
Description-Content-Type: text/markdown
|
|
24
|
+
License-File: LICENSE
|
|
25
|
+
Requires-Dist: numpy>=1.24
|
|
26
|
+
Requires-Dist: numba>=0.58
|
|
27
|
+
Provides-Extra: dev
|
|
28
|
+
Requires-Dist: build; extra == "dev"
|
|
29
|
+
Requires-Dist: twine; extra == "dev"
|
|
30
|
+
Requires-Dist: pytest; extra == "dev"
|
|
31
|
+
Dynamic: license-file
|
|
32
|
+
|
|
33
|
+
# mbsolver
|
|
34
|
+
|
|
35
|
+
[](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml)
|
|
36
|
+
[](https://pypi.org/project/mbsolver/)
|
|
37
|
+
[](https://pypi.org/project/mbsolver/)
|
|
38
|
+
[](https://doi.org/10.5281/zenodo.23407483)
|
|
39
|
+

|
|
40
|
+
|
|
41
|
+
Fast Maxwell-Bloch solvers in Python (numpy + numba) for astrophysical masers,
|
|
42
|
+
superradiance and coherent pulse propagation. Use them from scripts,
|
|
43
|
+
notebooks or cluster jobs; the
|
|
44
|
+
[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio)
|
|
45
|
+
desktop app runs on the same code.
|
|
46
|
+
|
|
47
|
+
## Installation
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
pip install mbsolver
|
|
51
|
+
```
|
|
52
|
+
|
|
53
|
+
Requires Python 3.10+ (numpy and numba are installed with it).
|
|
54
|
+
|
|
55
|
+
## Two-level model in one dimension
|
|
56
|
+
|
|
57
|
+
Dimensionless equations for the population inversion `w`, the coherence `R`
|
|
58
|
+
and the field `A` along a medium `0 ≤ z ≤ 1`:
|
|
59
|
+
|
|
60
|
+
```
|
|
61
|
+
dw/dt = A R − (w − w0) / T1 + Λ(t)
|
|
62
|
+
dR/dt = −A w − (R − R0) / T2
|
|
63
|
+
dA/dz = −η R
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The field `A(t)` entering at `z = 0` is given; population and coherence are
|
|
67
|
+
advanced with fourth-order Runge-Kutta in time, the field step by step in `z`.
|
|
68
|
+
The derivation from the two-level Hamiltonian is in
|
|
69
|
+
[`docs/two_level.pdf`](docs/two_level.pdf).
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
import matplotlib.pyplot as plt
|
|
73
|
+
from mbsolver import Pulse, Steps
|
|
74
|
+
from mbsolver.two_level import solve_1d
|
|
75
|
+
|
|
76
|
+
res = solve_1d(
|
|
77
|
+
t_max=300, nt=3001, nz=121, eta=40.0,
|
|
78
|
+
theta0=0.003, # or w0=..., R0=...
|
|
79
|
+
pump=[Pulse(a=[2e-3, 1e-3], x0=[60, 180], w=[15, 25])],
|
|
80
|
+
field_in=Pulse(a=1e-3, x0=30, w=5), # A(t) at z = 0
|
|
81
|
+
t1=Steps(y=[80, 40, 60], x0=[100, 200], w=[10, 0]),
|
|
82
|
+
t2=5.0,
|
|
83
|
+
n_planes=7, # stored z planes, 0 ... 1
|
|
84
|
+
)
|
|
85
|
+
|
|
86
|
+
plt.plot(res.time, res.intensity[-1]) # intensity leaving the medium
|
|
87
|
+
plt.show()
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
### Arguments
|
|
91
|
+
|
|
92
|
+
| Argument | Meaning |
|
|
93
|
+
|----------|---------|
|
|
94
|
+
| `t_max`, `nt` | time grid from 0 to `t_max` with `nt` points |
|
|
95
|
+
| `nz` | number of z points |
|
|
96
|
+
| `eta` | coupling coefficient η |
|
|
97
|
+
| `theta0`, or `w0` and `R0` | initial state (`w0 = cos θ0`, `R0 = sin θ0`); the medium also relaxes towards it |
|
|
98
|
+
| `t1`, `t2` | relaxation times: a number or `Steps` (> 0, `math.inf` for none) |
|
|
99
|
+
| `pump` | Λ(t): a `Pulse`, a number, or a list of them (summed) |
|
|
100
|
+
| `field_in` | A(t) at z = 0: a `Pulse`, a number, or `None` |
|
|
101
|
+
| `n_planes` | number of evenly spaced z planes returned (default 2: entrance and exit) |
|
|
102
|
+
|
|
103
|
+
### Result
|
|
104
|
+
|
|
105
|
+
`res.time`, `res.z` (positions of the stored planes), `res.intensity` and
|
|
106
|
+
`res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
|
|
107
|
+
|
|
108
|
+
### Adiabatic (rate-equation) limit
|
|
109
|
+
|
|
110
|
+
When `T2` is short compared with the times over which `A` and `w` change, the
|
|
111
|
+
coherence follows its steady state, `R = R0 − T2 A w`, and two equations remain:
|
|
112
|
+
|
|
113
|
+
```
|
|
114
|
+
dw/dt = A R0 − T2 A² w − (w − w0) / T1 + Λ(t)
|
|
115
|
+
dA/dz = −η R0 + η T2 A w
|
|
116
|
+
```
|
|
117
|
+
|
|
118
|
+
`solve_1d_adiabatic` takes the same arguments as `solve_1d` (with a finite
|
|
119
|
+
`t2`) and returns the same result plus `res.R`, so the two can be compared
|
|
120
|
+
directly. The limit differs from the full system during the first few `T2`
|
|
121
|
+
and in bursts faster than `T2`; see the section on it in
|
|
122
|
+
[`docs/two_level.pdf`](docs/two_level.pdf).
|
|
123
|
+
|
|
124
|
+
## Three-level (Λ) model in one dimension
|
|
125
|
+
|
|
126
|
+
Levels 1 and 2 lie below level 3; the transitions 3→1 and 3→2 carry the fields
|
|
127
|
+
`E31` and `E32`. With the population differences `n31 = n3 − n1`,
|
|
128
|
+
`n32 = n3 − n2` and the coherences `R31`, `R32`, `R21` (all real):
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
dn31/dt = −(E31 R31 + ½ E32 R32) − (n31 − n31⁰) / T1_31 + Λ31(t)
|
|
132
|
+
dn32/dt = −(½ E31 R31 + E32 R32) − (n32 − n32⁰) / T1_32 + Λ32(t)
|
|
133
|
+
dR31/dt = E31 n31 − ½ E32 R21 − (R31 − R31⁰) / T2_31
|
|
134
|
+
dR32/dt = E32 n32 − ½ E31 R21 − (R32 − R32⁰) / T2_32
|
|
135
|
+
dR21/dt = ½ (E31 R32 + E32 R31) − (R21 − R21⁰) / T2_21
|
|
136
|
+
dE31/dz = η R31, dE32/dz = R32, η = ω d²
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
with `d = |d31/d32|` and `ω = k31/k32`. Time is in units of the 3→2 time
|
|
140
|
+
scale `T0 = 2ε0ħ / (n0 L k32 |d32|²)`. The initial state comes from the
|
|
141
|
+
population ratios `r1 = n3/n1`, `r2 = n3/n2` and the coherence fractions
|
|
142
|
+
`c_ij`: `R_ij⁰ = c_ij · 2√(n_i n_j)`.
|
|
143
|
+
|
|
144
|
+
```python
|
|
145
|
+
from mbsolver import Pulse
|
|
146
|
+
from mbsolver.three_level import solve_1d
|
|
147
|
+
|
|
148
|
+
res = solve_1d(
|
|
149
|
+
t_max=2500, nt=4000, nz=400, d=0.875, omega=35.95,
|
|
150
|
+
r1=0.94, r2=2.33e19, c31=1e-10, c32=1.0, # c21 = 0 by default
|
|
151
|
+
t1_31=31.3, t1_32=313, t2_31=2.96, t2_32=29.6, # t2_21 = inf by default
|
|
152
|
+
pump32=Pulse(a=5.63e-3, x0=795.5, w=154.8), # pump31, field31_in, field32_in too
|
|
153
|
+
)
|
|
154
|
+
res.intensity32[-1] # 3→2 intensity leaving the medium
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
`t1_*` and `t2_*` take numbers or `Steps`, the pumps and entrance fields
|
|
158
|
+
`Pulse`s, numbers or lists, as in the two-level model. The result holds
|
|
159
|
+
`time`, `z`, the fields `e31`, `e32`, the intensities `intensity31 = (E31/d)²`
|
|
160
|
+
and `intensity32 = E32²` (both in units of the 3→2 scale), `n31`, `n32`,
|
|
161
|
+
`r31`, `r32`, `r21` (shape `(n_planes, nt)`), and the pumps, entrance fields
|
|
162
|
+
and relaxation times on the time grid.
|
|
163
|
+
|
|
164
|
+
`populations(r1, r2)` gives `n1`, `n2`, `n3`, `n31⁰`, `n32⁰` and the largest
|
|
165
|
+
coherences. `scaling(nu31, nu32, d31, d32, l, n0)` (SI units;
|
|
166
|
+
`mbsolver.constants.DEBYE` converts dipoles from debye) gives `d`, `omega`,
|
|
167
|
+
`eta`, `t0`, the field and intensity scales `e0`, `i0` (and `i0_jy` = 10²⁶ `i0`)
|
|
168
|
+
and the pump scale `lambda0 = n0/t0`. By default the decay rate of the 3→2
|
|
169
|
+
line is the Einstein A computed from `d32`; pass `gamma=` to use a measured one.
|
|
170
|
+
|
|
171
|
+
The three-level equations were derived and checked with Toktam Rashidi. The
|
|
172
|
+
derivation, from the Hamiltonian to the dimensionless equations, with the
|
|
173
|
+
initial conditions, physical scales and the S255IR-NIRS3 values, is in
|
|
174
|
+
[`docs/three_level.pdf`](docs/three_level.pdf);
|
|
175
|
+
[`examples/three_level/s255_flare.py`](examples/three_level/s255_flare.py)
|
|
176
|
+
runs the S255IR-NIRS3 flare and plots it with the observed flux (needs
|
|
177
|
+
matplotlib). The observations are from the Toruń 32 m telescope,
|
|
178
|
+
[Szymczak et al. 2018, A&A 617, A80](https://doi.org/10.1051/0004-6361/201833443).
|
|
179
|
+
|
|
180
|
+
## From physical values: `scaling` (two-level)
|
|
181
|
+
|
|
182
|
+
The solvers take dimensionless parameters. `mbsolver.scaling` computes them for the two-level model from the
|
|
183
|
+
physical sample values (SI units): transition frequency `nu` (Hz), spontaneous
|
|
184
|
+
decay rate `gamma` (s⁻¹), time unit `t0` (s), length `l` (m) and inverted
|
|
185
|
+
population density `n0` (m⁻³).
|
|
186
|
+
|
|
187
|
+
```python
|
|
188
|
+
import math
|
|
189
|
+
import mbsolver
|
|
190
|
+
from mbsolver.two_level import solve_1d
|
|
191
|
+
|
|
192
|
+
s = mbsolver.scaling(nu=6.67e9, gamma=1.56e-9, t0=86400, l=7.5e12, n0=5.3e-7)
|
|
193
|
+
res = solve_1d(t_max=2000, nt=20001, nz=101, eta=s["eta"], theta0=s["theta0"],
|
|
194
|
+
t1=math.inf, t2=math.inf)
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
Besides `eta` (η = T₀/T_R) and `theta0` (θ₀ = 2/√N), the result holds `t_r`,
|
|
198
|
+
`N`, `omega`, `lambda`, `k`, `lambda0` (Λ₀ = 1/T₀) and the field, polarization
|
|
199
|
+
and intensity scales for an electric dipole (`d`, `e0`, `p0`, `i0_electric`)
|
|
200
|
+
and a magnetic dipole (`mu`, `b0`, `m0`, `i0_magnetic`). Times in the solver
|
|
201
|
+
are in units of `t0`.
|
|
202
|
+
|
|
203
|
+
## Profiles
|
|
204
|
+
|
|
205
|
+
`Pulse(a, x0, w)` is a sum of sech² pulses, `a_i sech²((t − x0_i) / w_i)`.
|
|
206
|
+
Give `wl` and `wr` instead of `w` for a different width on each side.
|
|
207
|
+
|
|
208
|
+
`Steps(y, x0, w)` goes from level `y[0]` to `y[1]` around `x0[0]`, then to
|
|
209
|
+
`y[2]` around `x0[1]`, and so on, each step smoothed as `(1 + tanh)/2` with
|
|
210
|
+
width `w` (0 for a sharp step). `x0` and `w` have one value fewer than `y`.
|
|
211
|
+
|
|
212
|
+
A zero width gives a single point (pulse) or a sharp step; an infinite width
|
|
213
|
+
a constant. `profile.evaluate(t)` returns the values on any grid.
|
|
214
|
+
|
|
215
|
+
## Development
|
|
216
|
+
|
|
217
|
+
```
|
|
218
|
+
pip install -e ".[dev]"
|
|
219
|
+
pytest
|
|
220
|
+
```
|
|
221
|
+
|
|
222
|
+
The tests include a reference run that must match the solver of the Maxwell
|
|
223
|
+
Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
|
|
224
|
+
entrance, relaxation balance, uncoupled propagation). The three-level model
|
|
225
|
+
matches the 2025 three-level solver exactly for the S255IR-NIRS3 case. `scaling`
|
|
226
|
+
is checked against the values of Maxwell Bloch Studio.
|
|
227
|
+
|
|
228
|
+
The model documents `docs/two_level.pdf` and `docs/three_level.pdf` are built
|
|
229
|
+
from their LaTeX sources with `sh tools/build_docs.sh` (needs LaTeX with
|
|
230
|
+
`latexmk`); commit the rebuilt PDFs with the sources.
|
|
231
|
+
|
|
232
|
+
What changed in each version is in [`CHANGELOG.md`](CHANGELOG.md). Pushing a
|
|
233
|
+
tag `vX.Y.Z` publishes a GitHub Release with that version's section of the
|
|
234
|
+
changelog, and Zenodo gives it a DOI; update `version` and `date-released` in
|
|
235
|
+
`CITATION.cff` before tagging.
|
|
236
|
+
|
|
237
|
+
## Earlier name
|
|
238
|
+
|
|
239
|
+
Up to 0.1.0 this package was called `maxbloch`; 0.2.0 is the same code under
|
|
240
|
+
the new name. `maxbloch` stays on PyPI unchanged (0.1.1 only adds a
|
|
241
|
+
deprecation warning) but gets no updates; change `maxbloch` to `mbsolver` in
|
|
242
|
+
your imports.
|
|
243
|
+
|
|
244
|
+
## Citing
|
|
245
|
+
|
|
246
|
+
If you use mbsolver in published work, please cite it:
|
|
247
|
+
|
|
248
|
+
> Anari, V., & Rashidi, T. *mbsolver: Fast Maxwell-Bloch solvers for masers, superradiance and
|
|
249
|
+
> coherent pulse propagation*. Zenodo. https://doi.org/10.5281/zenodo.23407483
|
|
250
|
+
|
|
251
|
+
This DOI always points to the latest version. Each release also has its own
|
|
252
|
+
DOI (for 0.3.1: [10.5281/zenodo.23407484](https://doi.org/10.5281/zenodo.23407484));
|
|
253
|
+
cite the version you used, which you find under *Versions* on the Zenodo page.
|
|
254
|
+
GitHub's **Cite this repository** button gives the same in BibTeX and APA.
|
|
255
|
+
|
|
256
|
+
## License
|
|
257
|
+
|
|
258
|
+
MIT License. See [LICENSE](LICENSE).
|
|
259
|
+
|
|
260
|
+
## Authors
|
|
261
|
+
|
|
262
|
+
Vahid Anari ·
|
|
263
|
+
[GitHub](https://github.com/vahid-anari) ·
|
|
264
|
+
[LinkedIn](https://www.linkedin.com/in/vahid-anari/)
|
|
265
|
+
|
|
266
|
+
Toktam Rashidi ·
|
|
267
|
+
[GitHub](https://github.com/ToktamS) ·
|
|
268
|
+
[LinkedIn](https://www.linkedin.com/in/toktam-r-71951996/)
|
|
269
|
+
|
|
270
|
+
Related projects: [sciwidgets](https://github.com/vahid-anari/sciwidgets) ·
|
|
271
|
+
[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio) ·
|
|
272
|
+
[linecat](https://github.com/vahid-anari/linecat)
|
mbsolver-0.5.0/README.md
ADDED
|
@@ -0,0 +1,240 @@
|
|
|
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
|
+
The derivation from the two-level Hamiltonian is in
|
|
37
|
+
[`docs/two_level.pdf`](docs/two_level.pdf).
|
|
38
|
+
|
|
39
|
+
```python
|
|
40
|
+
import matplotlib.pyplot as plt
|
|
41
|
+
from mbsolver import Pulse, Steps
|
|
42
|
+
from mbsolver.two_level import solve_1d
|
|
43
|
+
|
|
44
|
+
res = solve_1d(
|
|
45
|
+
t_max=300, nt=3001, nz=121, eta=40.0,
|
|
46
|
+
theta0=0.003, # or w0=..., R0=...
|
|
47
|
+
pump=[Pulse(a=[2e-3, 1e-3], x0=[60, 180], w=[15, 25])],
|
|
48
|
+
field_in=Pulse(a=1e-3, x0=30, w=5), # A(t) at z = 0
|
|
49
|
+
t1=Steps(y=[80, 40, 60], x0=[100, 200], w=[10, 0]),
|
|
50
|
+
t2=5.0,
|
|
51
|
+
n_planes=7, # stored z planes, 0 ... 1
|
|
52
|
+
)
|
|
53
|
+
|
|
54
|
+
plt.plot(res.time, res.intensity[-1]) # intensity leaving the medium
|
|
55
|
+
plt.show()
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
### Arguments
|
|
59
|
+
|
|
60
|
+
| Argument | Meaning |
|
|
61
|
+
|----------|---------|
|
|
62
|
+
| `t_max`, `nt` | time grid from 0 to `t_max` with `nt` points |
|
|
63
|
+
| `nz` | number of z points |
|
|
64
|
+
| `eta` | coupling coefficient η |
|
|
65
|
+
| `theta0`, or `w0` and `R0` | initial state (`w0 = cos θ0`, `R0 = sin θ0`); the medium also relaxes towards it |
|
|
66
|
+
| `t1`, `t2` | relaxation times: a number or `Steps` (> 0, `math.inf` for none) |
|
|
67
|
+
| `pump` | Λ(t): a `Pulse`, a number, or a list of them (summed) |
|
|
68
|
+
| `field_in` | A(t) at z = 0: a `Pulse`, a number, or `None` |
|
|
69
|
+
| `n_planes` | number of evenly spaced z planes returned (default 2: entrance and exit) |
|
|
70
|
+
|
|
71
|
+
### Result
|
|
72
|
+
|
|
73
|
+
`res.time`, `res.z` (positions of the stored planes), `res.intensity` and
|
|
74
|
+
`res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
|
|
75
|
+
|
|
76
|
+
### Adiabatic (rate-equation) limit
|
|
77
|
+
|
|
78
|
+
When `T2` is short compared with the times over which `A` and `w` change, the
|
|
79
|
+
coherence follows its steady state, `R = R0 − T2 A w`, and two equations remain:
|
|
80
|
+
|
|
81
|
+
```
|
|
82
|
+
dw/dt = A R0 − T2 A² w − (w − w0) / T1 + Λ(t)
|
|
83
|
+
dA/dz = −η R0 + η T2 A w
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
`solve_1d_adiabatic` takes the same arguments as `solve_1d` (with a finite
|
|
87
|
+
`t2`) and returns the same result plus `res.R`, so the two can be compared
|
|
88
|
+
directly. The limit differs from the full system during the first few `T2`
|
|
89
|
+
and in bursts faster than `T2`; see the section on it in
|
|
90
|
+
[`docs/two_level.pdf`](docs/two_level.pdf).
|
|
91
|
+
|
|
92
|
+
## Three-level (Λ) model in one dimension
|
|
93
|
+
|
|
94
|
+
Levels 1 and 2 lie below level 3; the transitions 3→1 and 3→2 carry the fields
|
|
95
|
+
`E31` and `E32`. With the population differences `n31 = n3 − n1`,
|
|
96
|
+
`n32 = n3 − n2` and the coherences `R31`, `R32`, `R21` (all real):
|
|
97
|
+
|
|
98
|
+
```
|
|
99
|
+
dn31/dt = −(E31 R31 + ½ E32 R32) − (n31 − n31⁰) / T1_31 + Λ31(t)
|
|
100
|
+
dn32/dt = −(½ E31 R31 + E32 R32) − (n32 − n32⁰) / T1_32 + Λ32(t)
|
|
101
|
+
dR31/dt = E31 n31 − ½ E32 R21 − (R31 − R31⁰) / T2_31
|
|
102
|
+
dR32/dt = E32 n32 − ½ E31 R21 − (R32 − R32⁰) / T2_32
|
|
103
|
+
dR21/dt = ½ (E31 R32 + E32 R31) − (R21 − R21⁰) / T2_21
|
|
104
|
+
dE31/dz = η R31, dE32/dz = R32, η = ω d²
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
with `d = |d31/d32|` and `ω = k31/k32`. Time is in units of the 3→2 time
|
|
108
|
+
scale `T0 = 2ε0ħ / (n0 L k32 |d32|²)`. The initial state comes from the
|
|
109
|
+
population ratios `r1 = n3/n1`, `r2 = n3/n2` and the coherence fractions
|
|
110
|
+
`c_ij`: `R_ij⁰ = c_ij · 2√(n_i n_j)`.
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
from mbsolver import Pulse
|
|
114
|
+
from mbsolver.three_level import solve_1d
|
|
115
|
+
|
|
116
|
+
res = solve_1d(
|
|
117
|
+
t_max=2500, nt=4000, nz=400, d=0.875, omega=35.95,
|
|
118
|
+
r1=0.94, r2=2.33e19, c31=1e-10, c32=1.0, # c21 = 0 by default
|
|
119
|
+
t1_31=31.3, t1_32=313, t2_31=2.96, t2_32=29.6, # t2_21 = inf by default
|
|
120
|
+
pump32=Pulse(a=5.63e-3, x0=795.5, w=154.8), # pump31, field31_in, field32_in too
|
|
121
|
+
)
|
|
122
|
+
res.intensity32[-1] # 3→2 intensity leaving the medium
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
`t1_*` and `t2_*` take numbers or `Steps`, the pumps and entrance fields
|
|
126
|
+
`Pulse`s, numbers or lists, as in the two-level model. The result holds
|
|
127
|
+
`time`, `z`, the fields `e31`, `e32`, the intensities `intensity31 = (E31/d)²`
|
|
128
|
+
and `intensity32 = E32²` (both in units of the 3→2 scale), `n31`, `n32`,
|
|
129
|
+
`r31`, `r32`, `r21` (shape `(n_planes, nt)`), and the pumps, entrance fields
|
|
130
|
+
and relaxation times on the time grid.
|
|
131
|
+
|
|
132
|
+
`populations(r1, r2)` gives `n1`, `n2`, `n3`, `n31⁰`, `n32⁰` and the largest
|
|
133
|
+
coherences. `scaling(nu31, nu32, d31, d32, l, n0)` (SI units;
|
|
134
|
+
`mbsolver.constants.DEBYE` converts dipoles from debye) gives `d`, `omega`,
|
|
135
|
+
`eta`, `t0`, the field and intensity scales `e0`, `i0` (and `i0_jy` = 10²⁶ `i0`)
|
|
136
|
+
and the pump scale `lambda0 = n0/t0`. By default the decay rate of the 3→2
|
|
137
|
+
line is the Einstein A computed from `d32`; pass `gamma=` to use a measured one.
|
|
138
|
+
|
|
139
|
+
The three-level equations were derived and checked with Toktam Rashidi. The
|
|
140
|
+
derivation, from the Hamiltonian to the dimensionless equations, with the
|
|
141
|
+
initial conditions, physical scales and the S255IR-NIRS3 values, is in
|
|
142
|
+
[`docs/three_level.pdf`](docs/three_level.pdf);
|
|
143
|
+
[`examples/three_level/s255_flare.py`](examples/three_level/s255_flare.py)
|
|
144
|
+
runs the S255IR-NIRS3 flare and plots it with the observed flux (needs
|
|
145
|
+
matplotlib). The observations are from the Toruń 32 m telescope,
|
|
146
|
+
[Szymczak et al. 2018, A&A 617, A80](https://doi.org/10.1051/0004-6361/201833443).
|
|
147
|
+
|
|
148
|
+
## From physical values: `scaling` (two-level)
|
|
149
|
+
|
|
150
|
+
The solvers take dimensionless parameters. `mbsolver.scaling` computes them for the two-level model from the
|
|
151
|
+
physical sample values (SI units): transition frequency `nu` (Hz), spontaneous
|
|
152
|
+
decay rate `gamma` (s⁻¹), time unit `t0` (s), length `l` (m) and inverted
|
|
153
|
+
population density `n0` (m⁻³).
|
|
154
|
+
|
|
155
|
+
```python
|
|
156
|
+
import math
|
|
157
|
+
import mbsolver
|
|
158
|
+
from mbsolver.two_level import solve_1d
|
|
159
|
+
|
|
160
|
+
s = mbsolver.scaling(nu=6.67e9, gamma=1.56e-9, t0=86400, l=7.5e12, n0=5.3e-7)
|
|
161
|
+
res = solve_1d(t_max=2000, nt=20001, nz=101, eta=s["eta"], theta0=s["theta0"],
|
|
162
|
+
t1=math.inf, t2=math.inf)
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
Besides `eta` (η = T₀/T_R) and `theta0` (θ₀ = 2/√N), the result holds `t_r`,
|
|
166
|
+
`N`, `omega`, `lambda`, `k`, `lambda0` (Λ₀ = 1/T₀) and the field, polarization
|
|
167
|
+
and intensity scales for an electric dipole (`d`, `e0`, `p0`, `i0_electric`)
|
|
168
|
+
and a magnetic dipole (`mu`, `b0`, `m0`, `i0_magnetic`). Times in the solver
|
|
169
|
+
are in units of `t0`.
|
|
170
|
+
|
|
171
|
+
## Profiles
|
|
172
|
+
|
|
173
|
+
`Pulse(a, x0, w)` is a sum of sech² pulses, `a_i sech²((t − x0_i) / w_i)`.
|
|
174
|
+
Give `wl` and `wr` instead of `w` for a different width on each side.
|
|
175
|
+
|
|
176
|
+
`Steps(y, x0, w)` goes from level `y[0]` to `y[1]` around `x0[0]`, then to
|
|
177
|
+
`y[2]` around `x0[1]`, and so on, each step smoothed as `(1 + tanh)/2` with
|
|
178
|
+
width `w` (0 for a sharp step). `x0` and `w` have one value fewer than `y`.
|
|
179
|
+
|
|
180
|
+
A zero width gives a single point (pulse) or a sharp step; an infinite width
|
|
181
|
+
a constant. `profile.evaluate(t)` returns the values on any grid.
|
|
182
|
+
|
|
183
|
+
## Development
|
|
184
|
+
|
|
185
|
+
```
|
|
186
|
+
pip install -e ".[dev]"
|
|
187
|
+
pytest
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
The tests include a reference run that must match the solver of the Maxwell
|
|
191
|
+
Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
|
|
192
|
+
entrance, relaxation balance, uncoupled propagation). The three-level model
|
|
193
|
+
matches the 2025 three-level solver exactly for the S255IR-NIRS3 case. `scaling`
|
|
194
|
+
is checked against the values of Maxwell Bloch Studio.
|
|
195
|
+
|
|
196
|
+
The model documents `docs/two_level.pdf` and `docs/three_level.pdf` are built
|
|
197
|
+
from their LaTeX sources with `sh tools/build_docs.sh` (needs LaTeX with
|
|
198
|
+
`latexmk`); commit the rebuilt PDFs with the sources.
|
|
199
|
+
|
|
200
|
+
What changed in each version is in [`CHANGELOG.md`](CHANGELOG.md). Pushing a
|
|
201
|
+
tag `vX.Y.Z` publishes a GitHub Release with that version's section of the
|
|
202
|
+
changelog, and Zenodo gives it a DOI; update `version` and `date-released` in
|
|
203
|
+
`CITATION.cff` before tagging.
|
|
204
|
+
|
|
205
|
+
## Earlier name
|
|
206
|
+
|
|
207
|
+
Up to 0.1.0 this package was called `maxbloch`; 0.2.0 is the same code under
|
|
208
|
+
the new name. `maxbloch` stays on PyPI unchanged (0.1.1 only adds a
|
|
209
|
+
deprecation warning) but gets no updates; change `maxbloch` to `mbsolver` in
|
|
210
|
+
your imports.
|
|
211
|
+
|
|
212
|
+
## Citing
|
|
213
|
+
|
|
214
|
+
If you use mbsolver in published work, please cite it:
|
|
215
|
+
|
|
216
|
+
> Anari, V., & Rashidi, T. *mbsolver: Fast Maxwell-Bloch solvers for masers, superradiance and
|
|
217
|
+
> coherent pulse propagation*. Zenodo. https://doi.org/10.5281/zenodo.23407483
|
|
218
|
+
|
|
219
|
+
This DOI always points to the latest version. Each release also has its own
|
|
220
|
+
DOI (for 0.3.1: [10.5281/zenodo.23407484](https://doi.org/10.5281/zenodo.23407484));
|
|
221
|
+
cite the version you used, which you find under *Versions* on the Zenodo page.
|
|
222
|
+
GitHub's **Cite this repository** button gives the same in BibTeX and APA.
|
|
223
|
+
|
|
224
|
+
## License
|
|
225
|
+
|
|
226
|
+
MIT License. See [LICENSE](LICENSE).
|
|
227
|
+
|
|
228
|
+
## Authors
|
|
229
|
+
|
|
230
|
+
Vahid Anari ·
|
|
231
|
+
[GitHub](https://github.com/vahid-anari) ·
|
|
232
|
+
[LinkedIn](https://www.linkedin.com/in/vahid-anari/)
|
|
233
|
+
|
|
234
|
+
Toktam Rashidi ·
|
|
235
|
+
[GitHub](https://github.com/ToktamS) ·
|
|
236
|
+
[LinkedIn](https://www.linkedin.com/in/toktam-r-71951996/)
|
|
237
|
+
|
|
238
|
+
Related projects: [sciwidgets](https://github.com/vahid-anari/sciwidgets) ·
|
|
239
|
+
[Maxwell Bloch Studio](https://github.com/vahid-anari/maxwell-bloch-studio) ·
|
|
240
|
+
[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.5.0"
|
|
8
8
|
description = "Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation"
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
requires-python = ">=3.10"
|
|
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
|
|