mbsolver 0.2.0__tar.gz → 0.3.0__tar.gz

{mbsolver-0.2.0/src/mbsolver.egg-info → mbsolver-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mbsolver
-Version: 0.2.0
+Version: 0.3.0
 Summary: Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation
 Author-email: Vahid Anari <vahid.anari8@gmail.com>
 License-Expression: MIT
@@ -92,6 +92,29 @@ plt.show()
 `res.time`, `res.z` (positions of the stored planes), `res.intensity` and
 `res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
 
+## From physical values: `scaling`
+
+The solvers take dimensionless parameters. `scaling` computes them from the
+physical sample values (SI units): transition frequency `nu` (Hz), spontaneous
+decay rate `gamma` (s⁻¹), time unit `t0` (s), length `l` (m) and inverted
+population density `n0` (m⁻³).
+
+```python
+import math
+import mbsolver
+from mbsolver.two_level import solve_1d
+
+s = mbsolver.scaling(nu=6.67e9, gamma=1.56e-9, t0=86400, l=7.5e12, n0=5.3e-7)
+res = solve_1d(t_max=2000, nt=20001, nz=101, eta=s["eta"], theta0=s["theta0"],
+               t1=math.inf, t2=math.inf)
+```
+
+Besides `eta` (η = T₀/T_R) and `theta0` (θ₀ = 2/√N), the result holds `t_r`,
+`N`, `omega`, `lambda`, `k`, `lambda0` (Λ₀ = 1/T₀) and the field, polarization
+and intensity scales for an electric dipole (`d`, `e0`, `p0`, `i0_electric`)
+and a magnetic dipole (`mu`, `b0`, `m0`, `i0_magnetic`). Times in the solver
+are in units of `t0`.
+
 ## Profiles
 
 `Pulse(a, x0, w)` is a sum of sech² pulses, `a_i sech²((t − x0_i) / w_i)`.
@@ -113,7 +136,8 @@ pytest
 
 The tests include a reference run that must match the solver of the Maxwell
 Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
-entrance, relaxation balance, uncoupled propagation).
+entrance, relaxation balance, uncoupled propagation). `scaling` is checked
+against the values of Maxwell Bloch Studio.
 
 ## Earlier name
 

{mbsolver-0.2.0 → mbsolver-0.3.0}/README.md

@@ -61,6 +61,29 @@ plt.show()
 `res.time`, `res.z` (positions of the stored planes), `res.intensity` and
 `res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
 
+## From physical values: `scaling`
+
+The solvers take dimensionless parameters. `scaling` computes them from the
+physical sample values (SI units): transition frequency `nu` (Hz), spontaneous
+decay rate `gamma` (s⁻¹), time unit `t0` (s), length `l` (m) and inverted
+population density `n0` (m⁻³).
+
+```python
+import math
+import mbsolver
+from mbsolver.two_level import solve_1d
+
+s = mbsolver.scaling(nu=6.67e9, gamma=1.56e-9, t0=86400, l=7.5e12, n0=5.3e-7)
+res = solve_1d(t_max=2000, nt=20001, nz=101, eta=s["eta"], theta0=s["theta0"],
+               t1=math.inf, t2=math.inf)
+```
+
+Besides `eta` (η = T₀/T_R) and `theta0` (θ₀ = 2/√N), the result holds `t_r`,
+`N`, `omega`, `lambda`, `k`, `lambda0` (Λ₀ = 1/T₀) and the field, polarization
+and intensity scales for an electric dipole (`d`, `e0`, `p0`, `i0_electric`)
+and a magnetic dipole (`mu`, `b0`, `m0`, `i0_magnetic`). Times in the solver
+are in units of `t0`.
+
 ## Profiles
 
 `Pulse(a, x0, w)` is a sum of sech² pulses, `a_i sech²((t − x0_i) / w_i)`.
@@ -82,7 +105,8 @@ pytest
 
 The tests include a reference run that must match the solver of the Maxwell
 Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
-entrance, relaxation balance, uncoupled propagation).
+entrance, relaxation balance, uncoupled propagation). `scaling` is checked
+against the values of Maxwell Bloch Studio.
 
 ## Earlier name
 

{mbsolver-0.2.0 → mbsolver-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "mbsolver"
-version = "0.2.0"
+version = "0.3.0"
 description = "Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation"
 readme = "README.md"
 requires-python = ">=3.10"

{mbsolver-0.2.0 → mbsolver-0.3.0}/src/mbsolver/__init__.py

@@ -2,16 +2,18 @@
 
 Profiles (pump pulses, boundary fields, relaxation-time schedules) are built
 with :class:`Pulse` and :class:`Steps`; the solvers live in model subpackages,
-e.g. ``mbsolver.two_level.solve_1d``.
+e.g. ``mbsolver.two_level.solve_1d``. :func:`scaling` turns the physical
+sample values into the solvers' ``eta`` and ``theta0``.
 """
 
 from importlib.metadata import PackageNotFoundError, version
 
 from mbsolver.profiles import Pulse, Steps
+from mbsolver.sample import scaling
 
 try:
     __version__ = version("mbsolver")
 except PackageNotFoundError:  # running from a source tree without install
     __version__ = "0+unknown"
 
-__all__ = ["Pulse", "Steps", "__version__"]
+__all__ = ["Pulse", "Steps", "scaling", "__version__"]

mbsolver-0.3.0/src/mbsolver/constants.py

@@ -0,0 +1,18 @@
+"""Physical constants in SI units, used by :mod:`mbsolver.sample`."""
+
+import math
+
+PI: float = math.pi
+"""Circle constant."""
+
+H_BAR: float = 6.62607015e-34 / (2.0 * PI)
+"""Reduced Planck constant in joule-seconds."""
+
+C: float = 2.99792458e8
+"""Speed of light in meters per second."""
+
+MU_0: float = 4.0 * PI * 1e-7
+"""Vacuum permeability in henries per meter."""
+
+EPSILON_0: float = 1.0 / (MU_0 * C**2)
+"""Vacuum permittivity in farads per meter."""

mbsolver-0.3.0/src/mbsolver/sample.py

@@ -0,0 +1,74 @@
+"""From the physical sample to the solver's dimensionless parameters.
+
+The solvers work in dimensionless units: time in units of ``T0``, the medium
+from ``z = 0`` to ``z = 1``. :func:`scaling` turns the physical values of a
+maser sample into the coupling ``eta`` and initial Bloch angle ``theta0`` the
+solvers take, together with the other derived scales::
+
+    import math
+    import mbsolver
+    from mbsolver.two_level import solve_1d
+
+    s = mbsolver.scaling(nu=6.67e9, gamma=1.56e-9, t0=86400, l=7.5e12, n0=5.3e-7)
+    res = solve_1d(t_max=2000, nt=20001, nz=101, eta=s["eta"], theta0=s["theta0"],
+                   t1=math.inf, t2=math.inf)
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Dict
+
+from mbsolver.constants import C, EPSILON_0, H_BAR, MU_0, PI
+
+__all__ = ["scaling"]
+
+
+def scaling(nu: float, gamma: float, t0: float, l: float, n0: float) -> Dict[str, float]:
+    """Compute the solver parameters and derived scales from the sample values.
+
+    Args:
+        nu: Transition frequency ν in Hz.
+        gamma: Spontaneous decay rate Γ in s⁻¹.
+        t0: Time scale T₀ in s (the solver's unit of time).
+        l: Length of the medium L in m.
+        n0: Inverted population density n₀ in m⁻³.
+
+    Returns:
+        Mapping, all in SI units:
+
+        - ``eta``: coupling coefficient η = T₀ / T_R (the solvers' ``eta``),
+        - ``theta0``: initial Bloch angle θ₀ = 2 / √N (the solvers' ``theta0``),
+        - ``t_r``: superradiance time scale T_R,
+        - ``N``: number of molecules in a column of one wavelength squared,
+        - ``omega``, ``lambda``, ``k``: angular frequency, wavelength, wave number,
+        - ``lambda0``: pump scale Λ₀ = 1 / T₀,
+        - electric dipole: ``d`` (dipole moment), ``e0`` (field scale),
+          ``p0`` (polarization scale), ``i0_electric`` (intensity scale),
+        - magnetic dipole: ``mu``, ``b0``, ``m0``, ``i0_magnetic``.
+    """
+    omega0 = 2 * PI * nu
+    k = omega0 / C
+    _lambda = C / nu
+    t_r = 2.0 * k**2 / (3.0 * PI * gamma * n0 * l)
+    N = n0 * _lambda * l**2
+    eta = t0 / t_r
+    theta0 = 2.0 / math.sqrt(N)
+    lambda0 = 1.0 / t0
+
+    d = math.sqrt(3 * PI * EPSILON_0 * H_BAR * gamma / k**3)
+    p0 = n0 * d
+    e0 = H_BAR / (t0 * d)
+    i0_electric = 0.5 * EPSILON_0 * C * e0**2
+
+    mu = math.sqrt(3 * PI * H_BAR * gamma / (MU_0 * k**3))
+    m0 = n0 * mu
+    b0 = H_BAR / (t0 * mu)
+    i0_magnetic = C / (2.0 * MU_0) * b0**2
+
+    return {
+        "omega": omega0, "lambda": _lambda, "k": k, "t_r": t_r, "eta": eta,
+        "N": N, "theta0": theta0, "lambda0": lambda0,
+        "d": d, "e0": e0, "p0": p0, "i0_electric": i0_electric,
+        "mu": mu, "b0": b0, "m0": m0, "i0_magnetic": i0_magnetic,
+    }

{mbsolver-0.2.0 → mbsolver-0.3.0/src/mbsolver.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mbsolver
-Version: 0.2.0
+Version: 0.3.0
 Summary: Fast Maxwell-Bloch solvers for masers, superradiance and coherent pulse propagation
 Author-email: Vahid Anari <vahid.anari8@gmail.com>
 License-Expression: MIT
@@ -92,6 +92,29 @@ plt.show()
 `res.time`, `res.z` (positions of the stored planes), `res.intensity` and
 `res.w` (shape `(n_planes, nt)`), `res.pump`, `res.field_in`, `res.t1`, `res.t2`.
 
+## From physical values: `scaling`
+
+The solvers take dimensionless parameters. `scaling` computes them from the
+physical sample values (SI units): transition frequency `nu` (Hz), spontaneous
+decay rate `gamma` (s⁻¹), time unit `t0` (s), length `l` (m) and inverted
+population density `n0` (m⁻³).
+
+```python
+import math
+import mbsolver
+from mbsolver.two_level import solve_1d
+
+s = mbsolver.scaling(nu=6.67e9, gamma=1.56e-9, t0=86400, l=7.5e12, n0=5.3e-7)
+res = solve_1d(t_max=2000, nt=20001, nz=101, eta=s["eta"], theta0=s["theta0"],
+               t1=math.inf, t2=math.inf)
+```
+
+Besides `eta` (η = T₀/T_R) and `theta0` (θ₀ = 2/√N), the result holds `t_r`,
+`N`, `omega`, `lambda`, `k`, `lambda0` (Λ₀ = 1/T₀) and the field, polarization
+and intensity scales for an electric dipole (`d`, `e0`, `p0`, `i0_electric`)
+and a magnetic dipole (`mu`, `b0`, `m0`, `i0_magnetic`). Times in the solver
+are in units of `t0`.
+
 ## Profiles
 
 `Pulse(a, x0, w)` is a sum of sech² pulses, `a_i sech²((t − x0_i) / w_i)`.
@@ -113,7 +136,8 @@ pytest
 
 The tests include a reference run that must match the solver of the Maxwell
 Bloch app (version 8.13) exactly, and physics checks (Bloch rotation at the
-entrance, relaxation balance, uncoupled propagation).
+entrance, relaxation balance, uncoupled propagation). `scaling` is checked
+against the values of Maxwell Bloch Studio.
 
 ## Earlier name
 

{mbsolver-0.2.0 → mbsolver-0.3.0}/src/mbsolver.egg-info/SOURCES.txt

@@ -2,8 +2,10 @@ LICENSE
 README.md
 pyproject.toml
 src/mbsolver/__init__.py
+src/mbsolver/constants.py
 src/mbsolver/grids.py
 src/mbsolver/profiles.py
+src/mbsolver/sample.py
 src/mbsolver.egg-info/PKG-INFO
 src/mbsolver.egg-info/SOURCES.txt
 src/mbsolver.egg-info/dependency_links.txt
@@ -12,4 +14,5 @@ src/mbsolver.egg-info/top_level.txt
 src/mbsolver/two_level/__init__.py
 src/mbsolver/two_level/_kernel_1d.py
 tests/test_profiles.py
+tests/test_sample.py
 tests/test_two_level.py

mbsolver-0.3.0/tests/test_sample.py

@@ -0,0 +1,61 @@
+"""Tests for mbsolver.scaling (physical sample -> solver parameters)."""
+
+import math
+
+import pytest
+
+import mbsolver
+from mbsolver.constants import C, PI
+
+SAMPLE = dict(nu=6668.519e6, gamma=1.56e-9, t0=86400.0, l=7.5e12, n0=5.3e-7)
+
+# Values from Maxwell Bloch Studio 10.0.3 (mbstudio.scaling) for SAMPLE.
+REFERENCE = {
+    "N": 1.340262006320294e+18,
+    "b0": 1.8155752119506778e-18,
+    "d": 2.2424742818774253e-30,
+    "e0": 5.442957554745647e-10,
+    "eta": 0.12925265980137085,
+    "i0_electric": 3.9319621867605606e-22,
+    "i0_magnetic": 3.9319621867605615e-22,
+    "k": 139.76182349940206,
+    "lambda": 0.04495637757049204,
+    "lambda0": 1.1574074074074073e-05,
+    "m0": 3.5630674479188363e-28,
+    "mu": 6.722768769658182e-22,
+    "omega": 41899540601.44791,
+    "p0": 1.1885113693950354e-36,
+    "t_r": 668458.1975548919,
+    "theta0": 1.7275679662364094e-09,
+}
+
+
+def test_matches_studio():
+    s = mbsolver.scaling(**SAMPLE)
+    assert sorted(s) == sorted(REFERENCE)
+    for key, value in REFERENCE.items():
+        assert s[key] == pytest.approx(value, rel=1e-13), key
+
+
+def test_relations():
+    s = mbsolver.scaling(**SAMPLE)
+    assert s["eta"] == pytest.approx(SAMPLE["t0"] / s["t_r"], rel=1e-15)
+    assert s["theta0"] == pytest.approx(2.0 / math.sqrt(s["N"]), rel=1e-15)
+    assert s["lambda"] == pytest.approx(C / SAMPLE["nu"], rel=1e-15)
+    assert s["k"] == pytest.approx(2 * PI / s["lambda"], rel=1e-14)
+    # electric and magnetic dipole give the same intensity scale
+    assert s["i0_electric"] == pytest.approx(s["i0_magnetic"], rel=1e-12)
+
+
+def test_eta_scales_with_length_and_density():
+    s1 = mbsolver.scaling(**SAMPLE)
+    s2 = mbsolver.scaling(**{**SAMPLE, "l": 2 * SAMPLE["l"], "n0": 3 * SAMPLE["n0"]})
+    assert s2["eta"] == pytest.approx(6 * s1["eta"], rel=1e-14)
+
+
+def test_feeds_the_solver():
+    from mbsolver.two_level import solve_1d
+
+    s = mbsolver.scaling(**SAMPLE)
+    res = solve_1d(t_max=10, nt=101, nz=11, eta=s["eta"], theta0=s["theta0"], t1=math.inf, t2=math.inf)
+    assert res.intensity.shape == (2, 101)