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.
Files changed (29) hide show
  1. mbsolver-0.5.0/PKG-INFO +272 -0
  2. mbsolver-0.5.0/README.md +240 -0
  3. {mbsolver-0.3.1 → mbsolver-0.5.0}/pyproject.toml +5 -2
  4. {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/__init__.py +1 -1
  5. {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/constants.py +3 -0
  6. mbsolver-0.5.0/src/mbsolver/three_level/__init__.py +176 -0
  7. mbsolver-0.5.0/src/mbsolver/three_level/_kernel_1d.py +140 -0
  8. mbsolver-0.5.0/src/mbsolver/three_level/sample.py +85 -0
  9. {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/two_level/__init__.py +66 -7
  10. mbsolver-0.5.0/src/mbsolver/two_level/_kernel_adiabatic_1d.py +100 -0
  11. mbsolver-0.5.0/src/mbsolver.egg-info/PKG-INFO +272 -0
  12. {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver.egg-info/SOURCES.txt +7 -1
  13. mbsolver-0.5.0/tests/test_three_level.py +113 -0
  14. mbsolver-0.5.0/tests/test_two_level_adiabatic.py +59 -0
  15. mbsolver-0.3.1/PKG-INFO +0 -161
  16. mbsolver-0.3.1/README.md +0 -130
  17. mbsolver-0.3.1/src/mbsolver.egg-info/PKG-INFO +0 -161
  18. {mbsolver-0.3.1 → mbsolver-0.5.0}/LICENSE +0 -0
  19. {mbsolver-0.3.1 → mbsolver-0.5.0}/setup.cfg +0 -0
  20. {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/grids.py +0 -0
  21. {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/profiles.py +0 -0
  22. {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/sample.py +0 -0
  23. {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver/two_level/_kernel_1d.py +0 -0
  24. {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver.egg-info/dependency_links.txt +0 -0
  25. {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver.egg-info/requires.txt +0 -0
  26. {mbsolver-0.3.1 → mbsolver-0.5.0}/src/mbsolver.egg-info/top_level.txt +0 -0
  27. {mbsolver-0.3.1 → mbsolver-0.5.0}/tests/test_profiles.py +0 -0
  28. {mbsolver-0.3.1 → mbsolver-0.5.0}/tests/test_sample.py +0 -0
  29. {mbsolver-0.3.1 → mbsolver-0.5.0}/tests/test_two_level.py +0 -0
@@ -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
+ [![tests](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml/badge.svg)](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml)
36
+ [![PyPI](https://img.shields.io/pypi/v/mbsolver)](https://pypi.org/project/mbsolver/)
37
+ [![Python](https://img.shields.io/pypi/pyversions/mbsolver)](https://pypi.org/project/mbsolver/)
38
+ [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.23407483-blue)](https://doi.org/10.5281/zenodo.23407483)
39
+ ![License](https://img.shields.io/badge/license-MIT-green)
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)
@@ -0,0 +1,240 @@
1
+ # mbsolver
2
+
3
+ [![tests](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml/badge.svg)](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/mbsolver)](https://pypi.org/project/mbsolver/)
5
+ [![Python](https://img.shields.io/pypi/pyversions/mbsolver)](https://pypi.org/project/mbsolver/)
6
+ [![DOI](https://img.shields.io/badge/DOI-10.5281%2Fzenodo.23407483-blue)](https://doi.org/10.5281/zenodo.23407483)
7
+ ![License](https://img.shields.io/badge/license-MIT-green)
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.3.1"
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 = [{ name = "Vahid Anari", email = "vahid.anari8@gmail.com" }]
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
 
@@ -16,3 +16,6 @@ MU_0: float = 4.0 * PI * 1e-7
16
16
 
17
17
  EPSILON_0: float = 1.0 / (MU_0 * C**2)
18
18
  """Vacuum permittivity in farads per meter."""
19
+
20
+ DEBYE: float = 1e-21 / C
21
+ """One debye in coulomb-meters."""