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.
Files changed (25) hide show
  1. {mbsolver-0.3.1/src/mbsolver.egg-info → mbsolver-0.4.0}/PKG-INFO +95 -10
  2. mbsolver-0.4.0/README.md +214 -0
  3. {mbsolver-0.3.1 → mbsolver-0.4.0}/pyproject.toml +5 -2
  4. {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/__init__.py +1 -1
  5. {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/constants.py +3 -0
  6. mbsolver-0.4.0/src/mbsolver/three_level/__init__.py +176 -0
  7. mbsolver-0.4.0/src/mbsolver/three_level/_kernel_1d.py +140 -0
  8. mbsolver-0.4.0/src/mbsolver/three_level/sample.py +85 -0
  9. {mbsolver-0.3.1 → mbsolver-0.4.0/src/mbsolver.egg-info}/PKG-INFO +95 -10
  10. {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver.egg-info/SOURCES.txt +4 -0
  11. mbsolver-0.4.0/tests/test_three_level.py +113 -0
  12. mbsolver-0.3.1/README.md +0 -130
  13. {mbsolver-0.3.1 → mbsolver-0.4.0}/LICENSE +0 -0
  14. {mbsolver-0.3.1 → mbsolver-0.4.0}/setup.cfg +0 -0
  15. {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/grids.py +0 -0
  16. {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/profiles.py +0 -0
  17. {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/sample.py +0 -0
  18. {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/two_level/__init__.py +0 -0
  19. {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver/two_level/_kernel_1d.py +0 -0
  20. {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver.egg-info/dependency_links.txt +0 -0
  21. {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver.egg-info/requires.txt +0 -0
  22. {mbsolver-0.3.1 → mbsolver-0.4.0}/src/mbsolver.egg-info/top_level.txt +0 -0
  23. {mbsolver-0.3.1 → mbsolver-0.4.0}/tests/test_profiles.py +0 -0
  24. {mbsolver-0.3.1 → mbsolver-0.4.0}/tests/test_sample.py +0 -0
  25. {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.1
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
  [![tests](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml/badge.svg)](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml)
35
36
  [![PyPI](https://img.shields.io/pypi/v/mbsolver)](https://pypi.org/project/mbsolver/)
36
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)
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
- ## From physical values: `scaling`
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
- The solvers take dimensionless parameters. `scaling` computes them from the
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
- ## Tests
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). `scaling` is checked
144
- against the values of Maxwell Bloch Studio.
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. The GitHub page has a
156
- **Cite this repository** button (from [`CITATION.cff`](https://github.com/vahid-anari/mbsolver/blob/main/CITATION.cff)),
157
- and each release has its own DOI on Zenodo; cite the version you used.
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)
@@ -0,0 +1,214 @@
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
+
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.3.1"
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 = [{ 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."""
@@ -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.1
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
  [![tests](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml/badge.svg)](https://github.com/vahid-anari/mbsolver/actions/workflows/tests.yml)
35
36
  [![PyPI](https://img.shields.io/pypi/v/mbsolver)](https://pypi.org/project/mbsolver/)
36
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)
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
- ## From physical values: `scaling`
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
- The solvers take dimensionless parameters. `scaling` computes them from the
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
- ## Tests
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). `scaling` is checked
144
- against the values of Maxwell Bloch Studio.
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. The GitHub page has a
156
- **Cite this repository** button (from [`CITATION.cff`](https://github.com/vahid-anari/mbsolver/blob/main/CITATION.cff)),
157
- and each release has its own DOI on Zenodo; cite the version you used.
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
- [![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
-
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