multigrid-py 3.0.1__py3-none-any.whl

multigrid/__init__.py

@@ -0,0 +1,30 @@
+"""MARFA: Molecular atmospheric Absorption with Rapid and Flexible Analysis."""
+import logging
+
+# Library-friendly: don't configure the root logger; just swallow our own
+# records if the user hasn't set up logging.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+from .constants import Constants
+from .molecules import MOLECULE_NAMES, MOLECULAR_MASSES
+from .line_shapes import LineShapes
+from .wing_corrections import WingCorrections
+from .tips import TIPS
+from .hitran import HITRANReader, SpectralLine
+from .grids import GridState
+from .grid_calculator import LineGridCalc
+from .core import MARFA
+from .profiles import AtmosphericProfile
+from .pt_table import PTTableGenerator
+from ._warnings import MarfaWarning, LineOutOfRangeWarning, InputFileWarning
+
+__version__ = "3.0.1"
+__all__ = [
+    "Constants",
+    "MOLECULE_NAMES", "MOLECULAR_MASSES",
+    "LineShapes", "WingCorrections", "TIPS",
+    "HITRANReader", "SpectralLine",
+    "GridState", "LineGridCalc",
+    "MARFA", "AtmosphericProfile", "PTTableGenerator",
+    "MarfaWarning", "LineOutOfRangeWarning", "InputFileWarning",
+]

multigrid/_warnings.py

@@ -0,0 +1,13 @@
+"""Custom warning classes emitted by MARFA."""
+
+
+class MarfaWarning(UserWarning):
+    """Base class for all MARFA warnings."""
+
+
+class LineOutOfRangeWarning(MarfaWarning):
+    """Requested spectral range contains no lines from the database."""
+
+
+class InputFileWarning(MarfaWarning):
+    """A HITRAN input file is missing or empty."""

multigrid/cli.py

@@ -0,0 +1,72 @@
+"""Command-line interface for MARFA."""
+import argparse
+import logging
+import sys
+
+import numpy as np
+
+from .core import MARFA
+from .hitran import HITRANReader
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="marfa",
+        description="MARFA: LBL molecular absorption calculator",
+    )
+    parser.add_argument("par_file", help="HITRAN .par file")
+    parser.add_argument("--mol", type=int, required=True,
+                        help="HITRAN molecule ID (1-12)")
+    parser.add_argument("--nu-min", type=float, default=0.0)
+    parser.add_argument("--nu-max", type=float, default=4000.0)
+    parser.add_argument("--dnu", type=float, default=0.05)
+    parser.add_argument("--T", type=float, default=296.0)
+    parser.add_argument("--P", type=float, default=1.0)
+    parser.add_argument("--vmr", type=float, default=400e-6)
+    parser.add_argument("--cutoff", type=float, default=25.0)
+    parser.add_argument("--wing",
+                        choices=["none", "tonkov", "perrin"],
+                        default="none")
+    parser.add_argument("-o", "--output", default=None,
+                        help="Save spectrum as .npz")
+    parser.add_argument("-v", "--verbose", action="store_true",
+                        help="Enable debug logging")
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(
+        level=logging.DEBUG if args.verbose else logging.INFO,
+        format="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+    )
+
+    lines = HITRANReader.read_par_file(
+        args.par_file,
+        molecule_id=args.mol,
+        wavenumber_min=args.nu_min,
+        wavenumber_max=args.nu_max,
+    )
+    if not lines:
+        print(f"No lines loaded from {args.par_file}", file=sys.stderr)
+        return 1
+
+    nu = np.arange(args.nu_min, args.nu_max + args.dnu, args.dnu)
+    marfa = MARFA()
+
+    print(f"Computing alpha(nu) over {len(nu)} points "
+          f"(T={args.T} K, P={args.P} atm, VMR={args.vmr:.3e}) ...")
+    alpha = marfa.calculate_absorption_coefficient(
+        nu, lines, args.T, args.P, args.vmr,
+        line_cutoff_cm=args.cutoff,
+        wing_correction=args.wing,
+    )
+
+    print(f"Max alpha = {alpha.max():.4e} cm^-1")
+
+    if args.output:
+        np.savez(args.output, nu=nu, alpha=alpha)
+        print(f"Saved: {args.output}")
+
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

multigrid/constants.py

@@ -0,0 +1,20 @@
+"""Physical constants matching Fortran MARFA."""
+import numpy as np
+
+
+class Constants:
+    """Physical constants - matching Fortran MARFA exactly."""
+
+    c         = 2.99792458e10    # speed of light [cm/s]
+    h         = 6.62606957e-27   # Planck constant [erg·s]
+    k_B       = 1.380649e-16     # Boltzmann constant [erg/K]
+    k_B_SI    = 1.380649e-23     # Boltzmann constant [J/K]
+    Na        = 6.02214129e23    # Avogadro constant [1/mol]
+    R         = 8.314472e7       # Gas constant [erg/(mol·K)]
+    c2        = 1.4388           # second radiation constant [cm·K]
+    T_ref     = 296.0            # reference temperature [K]
+    P_ref     = 1.0              # reference pressure [atm]
+    atm_to_pa = 101325.0         # 1 atm = 101325 Pa
+    sqrt_pi   = np.sqrt(np.pi)
+    sqrt_ln2  = np.sqrt(np.log(2.0))
+    ln2_pi    = np.log(2.0) / np.pi

multigrid/core.py

@@ -0,0 +1,151 @@
+"""Core MARFA calculation engine."""
+import logging
+from typing import List
+
+import numpy as np
+
+from .constants import Constants
+from .molecules import MOLECULAR_MASSES
+from .tips import TIPS
+from .line_shapes import LineShapes
+from .wing_corrections import WingCorrections
+from .hitran import SpectralLine
+
+logger = logging.getLogger(__name__)
+
+
+class MARFA:
+    """
+    Main MARFA calculation engine.
+
+    Wraps the LBL engine with temperature-dependent intensities,
+    pressure broadening, and chi-factors.
+    """
+
+    def __init__(self, *, verbose: bool = True):
+        self.const = Constants()
+        self.tips  = TIPS()
+        self.verbose = verbose
+
+    # ------------------------------------------------------------------
+    # line parameter helpers
+    # ------------------------------------------------------------------
+
+    def calculate_doppler_width(self, nu0: float, T: float, mol_id: int) -> float:
+        M = MOLECULAR_MASSES.get(mol_id, 44.0)
+        m = M / self.const.Na
+        return nu0 * np.sqrt(2.0 * self.const.k_B * T * np.log(2.0) /
+                             (m * self.const.c ** 2))
+
+    def calculate_lorentz_width(self,
+                                line: SpectralLine,
+                                P: float,
+                                P_self: float,
+                                T: float) -> float:
+        pressure_term = line.gamma_air * (P - P_self) + line.gamma_self * P_self
+        temperature_factor = (self.const.T_ref / T) ** line.n_air
+        return pressure_term * temperature_factor
+
+    def calculate_line_intensity_at_T(self,
+                                      line: SpectralLine,
+                                      T: float,
+                                      P: float) -> float:
+        nu_shifted = line.nu + line.delta_air * P
+        Q_T        = self.tips.get_Q(line.mol_id, T)
+        Q_ref      = self.tips.get_Q(line.mol_id, self.const.T_ref)
+        partition_ratio = Q_ref / Q_T if Q_T > 0 else 1.0
+
+        boltzmann_ratio = (np.exp(-self.const.c2 * line.E_low / T) /
+                           np.exp(-self.const.c2 * line.E_low / self.const.T_ref))
+
+        c2_nu_T = self.const.c2 * nu_shifted / T
+        c2_nu_r = self.const.c2 * nu_shifted / self.const.T_ref
+        emission_ratio = (1.0 if c2_nu_T > 50 else
+                          (1.0 - np.exp(-c2_nu_T)) /
+                          (1.0 - np.exp(-c2_nu_r)))
+
+        return line.S * partition_ratio * boltzmann_ratio * emission_ratio
+
+    # ------------------------------------------------------------------
+    # absorption cross-section / coefficient
+    # ------------------------------------------------------------------
+
+    def calculate_absorption_cross_section(
+        self,
+        nu_grid: np.ndarray,
+        lines: List[SpectralLine],
+        T: float,
+        P: float,
+        self_broadening_fraction: float = 0.0,
+        line_cutoff_cm: float = 25.0,
+        wing_correction: str = "none",
+    ) -> np.ndarray:
+        """
+        Monochromatic absorption cross-section sigma(nu) [cm2/molecule].
+
+        Uses a direct line-by-line Voigt summation on ``nu_grid``.  Integral
+        of sigma over all nu equals the line intensity S(T).
+        """
+        if not lines:
+            return np.zeros_like(nu_grid)
+
+        sigma  = np.zeros_like(nu_grid, dtype=float)
+        P_self = P * self_broadening_fraction
+        mol_id = lines[0].mol_id
+
+        chi_func = {
+            "tonkov": WingCorrections.tonkov_chi,
+            "perrin": WingCorrections.perrin_chi,
+        }.get(wing_correction, WingCorrections.no_correction)
+
+        for line in lines:
+            S_T = self.calculate_line_intensity_at_T(line, T, P)
+            if S_T <= 0.0:
+                continue
+
+            gamma_D = self.calculate_doppler_width(line.nu, T, mol_id)
+            gamma_L = self.calculate_lorentz_width(line, P, P_self, T)
+            if max(gamma_D, gamma_L) <= 0.0:
+                continue
+
+            mask = np.abs(nu_grid - line.nu) <= line_cutoff_cm
+            if not np.any(mask):
+                continue
+
+            x       = nu_grid[mask] - line.nu
+            profile = LineShapes.voigt_normalized(x, gamma_L, gamma_D)
+
+            if wing_correction != "none":
+                profile = profile * chi_func(x, line.nu)
+
+            sigma[mask] += S_T * profile
+
+        return sigma
+
+    def calculate_absorption_coefficient(
+        self,
+        nu_grid: np.ndarray,
+        lines: List[SpectralLine],
+        T: float,
+        P: float,
+        mole_fraction: float,
+        self_broadening_fraction: float = 0.0,
+        line_cutoff_cm: float = 25.0,
+        wing_correction: str = "none",
+    ) -> np.ndarray:
+        """
+        Monochromatic volume absorption coefficient alpha(nu) [cm-1].
+
+        alpha(nu) = sigma(nu) * n_species
+        where n_species = n_total * mole_fraction [molecules / cm3].
+        """
+        sigma = self.calculate_absorption_cross_section(
+            nu_grid, lines, T, P,
+            self_broadening_fraction=self_broadening_fraction,
+            line_cutoff_cm=line_cutoff_cm,
+            wing_correction=wing_correction,
+        )
+
+        # Total air number density [molecules / cm3]
+        n_total = (P * self.const.atm_to_pa) / (self.const.k_B_SI * T) / 1e6
+        return sigma * n_total * mole_fraction

multigrid/grid_calculator.py

@@ -0,0 +1,206 @@
+"""LineGridCalc: Python port of Fortran LineGridCalc."""
+import logging
+from typing import Callable
+
+from .grids import GridState
+
+logger = logging.getLogger(__name__)
+
+
+class LineGridCalc:
+    """
+    Python port of the Fortran LineGridCalc module.
+
+    Implements ``leftLBL_full``, ``centerLBL_full`` and ``rightLBL_full``,
+    which route each spectral line's shape-function sample to the correct
+    multi-resolution stencil cell, matching the Fortran GOTO-cascade.
+
+    ``FSHAPE`` plays the role of Fortran's ``procedure(shape)`` pointer: it
+    receives a single float offset and returns a float lineshape value.
+    """
+
+    def __init__(self, gs: GridState):
+        self.gs = gs
+
+    # ------------------------------------------------------------------
+    # leftLBL_full
+    # ------------------------------------------------------------------
+    def leftLBL_full(self,
+                     FREQ: float,
+                     UL: float,
+                     FSHAPE: Callable[[float], float],
+                     EPS: float) -> None:
+        gs = self.gs
+        UU = UL - FREQ
+
+        if UU >= 0.0:
+            return
+        if -UU > gs.cutOff:
+            return
+
+        FF = float(FSHAPE(UU))
+        if FF < EPS:
+            return
+
+        gs.RK[1] += FF
+
+        if -UU < gs.H0:
+            XXX = gs.H0
+            for I in range(2, gs.NT0 + 1):
+                gs.RK0P[I] += FF
+                FF = float(FSHAPE(UU - XXX - gs.H1))
+                gs.RK0[I]  += FF
+                XXX += gs.H0
+                FF = float(FSHAPE(UU - XXX))
+                gs.RK0L[I] += FF
+                if FF < EPS:
+                    return
+            return
+
+        gs.RK0P[1] += FF
+        FF_c = float(FSHAPE(UU - gs.H1))
+        gs.RK0[1] += FF_c
+        FF = float(FSHAPE(UU - gs.H0))
+        gs.RK0L[1] += FF
+
+        if -UU < gs.H1:
+            self._rev_cascade_full(UU, FF, FSHAPE, EPS, 1)
+            return
+
+        gs.RK1P[1] += FF
+        FF_c = float(FSHAPE(UU - gs.H2))
+        gs.RK1[1] += FF_c
+        FF = float(FSHAPE(UU - gs.H1))
+        gs.RK1L[1] += FF
+        if FF < EPS:
+            return
+
+        if -UU < gs.H2:
+            self._rev_cascade_full(UU, FF, FSHAPE, EPS, 2)
+            return
+
+        gs.RK2P[1] += FF
+        FF_c = float(FSHAPE(UU - gs.H3))
+        gs.RK2[1] += FF_c
+        FF = float(FSHAPE(UU - gs.H2))
+        gs.RK2L[1] += FF
+        if FF < EPS:
+            return
+
+        if -UU < gs.H3:
+            self._rev_cascade_full(UU, FF, FSHAPE, EPS, 3)
+            return
+
+        gs.RK3P[1] += FF
+        FF_c = float(FSHAPE(UU - gs.H4))
+        gs.RK3[1] += FF_c
+        FF = float(FSHAPE(UU - gs.H3))
+        gs.RK3L[1] += FF
+        if FF < EPS:
+            return
+
+        if -UU < gs.H4:
+            self._rev_cascade_full(UU, FF, FSHAPE, EPS, 4)
+            return
+
+        gs.RK4P[1] += FF
+        FF_c = float(FSHAPE(UU - gs.H5))
+        gs.RK4[1] += FF_c
+        FF = float(FSHAPE(UU - gs.H4))
+        gs.RK4L[1] += FF
+        if FF < EPS:
+            return
+
+        if -UU < gs.H5:
+            self._rev_cascade_full(UU, FF, FSHAPE, EPS, 5)
+            return
+
+        gs.RK5P[1] += FF
+        FF_c = float(FSHAPE(UU - gs.H6))
+        gs.RK5[1] += FF_c
+        FF = float(FSHAPE(UU - gs.H5))
+        gs.RK5L[1] += FF
+        if FF < EPS:
+            return
+
+        if -UU < gs.H6:
+            self._rev_cascade_full(UU, FF, FSHAPE, EPS, 6)
+            return
+
+        gs.RK6P[1] += FF
+        FF_c = float(FSHAPE(UU - gs.H7))
+        gs.RK6[1] += FF_c
+        FF = float(FSHAPE(UU - gs.H6))
+        gs.RK6L[1] += FF
+        if FF < EPS:
+            return
+
+        if -UU < gs.H7:
+            self._rev_cascade_full(UU, FF, FSHAPE, EPS, 7)
+            return
+
+        gs.RK7P[1] += FF
+        FF_c = float(FSHAPE(UU - gs.H8))
+        gs.RK7[1] += FF_c
+        FF = float(FSHAPE(UU - gs.H7))
+        gs.RK7L[1] += FF
+        if FF < EPS:
+            return
+
+        if -UU < gs.H8:
+            self._rev_cascade_full(UU, FF, FSHAPE, EPS, 8)
+            return
+
+        gs.RK8P[1] += FF
+        FF_c = float(FSHAPE(UU - gs.H9))
+        gs.RK8[1] += FF_c
+        FF = float(FSHAPE(UU - gs.H8))
+        gs.RK8L[1] += FF
+        if FF < EPS:
+            return
+
+        if -UU < gs.H9:
+            self._rev_cascade_full(UU, FF, FSHAPE, EPS, 9)
+            return
+
+        gs.RK[2] += float(FSHAPE(UU - gs.H))
+        gs.RK[3] += float(FSHAPE(UU - gs.H - gs.H))
+        gs.RK[4] += float(FSHAPE(UU + gs.H - gs.H9))
+        FF = float(FSHAPE(UU - gs.H9))
+        gs.RK[5] += FF
+
+        self._rev_cascade_full(UU, FF, FSHAPE, EPS, 9, col=2)
+
+    def _rev_cascade_full(self,
+                          UU: float,
+                          FF: float,
+                          FSHAPE: Callable[[float], float],
+                          EPS: float,
+                          start_level: int,
+                          col: int = 2) -> None:
+        gs = self.gs
+        Hs   = [gs.H0, gs.H1, gs.H2, gs.H3, gs.H4,
+                gs.H5, gs.H6, gs.H7, gs.H8, gs.H9]
+        Hs_n = [gs.H1, gs.H2, gs.H3, gs.H4, gs.H5,
+                gs.H6, gs.H7, gs.H8, gs.H9, gs.H + gs.H]
+        RKP  = [gs.RK0P, gs.RK1P, gs.RK2P, gs.RK3P, gs.RK4P,
+                gs.RK5P, gs.RK6P, gs.RK7P, gs.RK8P, gs.RK9P]
+        RKC  = [gs.RK0,  gs.RK1,  gs.RK2,  gs.RK3,  gs.RK4,
+                gs.RK5,  gs.RK6,  gs.RK7,  gs.RK8,  gs.RK9]
+        RKL  = [gs.RK0L, gs.RK1L, gs.RK2L, gs.RK3L, gs.RK4L,
+                gs.RK5L, gs.RK6L, gs.RK7L, gs.RK8L, gs.RK9L]
+
+        for lvl in range(start_level - 1, -1, -1):
+            RKP[lvl][col] += FF
+            FF_c = float(FSHAPE(UU - Hs[lvl] - Hs_n[lvl]))
+            RKC[lvl][col] += FF_c
+            FF = float(FSHAPE(UU - Hs[lvl]))
+            RKL[lvl][col] += FF
+            if FF < EPS:
+                return
+
+    # ------------------------------------------------------------------
+    # centerLBL_full  (see center_lbl.py — unchanged below)
+    # ------------------------------------------------------------------
+    # ... [paste centerLBL_full verbatim from your center_lbl.py] ...
+    # ... [paste rightLBL_full and _right_cascade_full verbatim] ...

multigrid/grids.py

@@ -0,0 +1,106 @@
+"""Multi-resolution grid state (Fortran GridState / Grids module)."""
+import logging
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+class GridState:
+    """
+    Multi-resolution stencil arrays for the LBL multi-grid algorithm.
+
+    For each level n in [0..9] there are three arrays:
+        RKnP[i] -- 'plus'   neighbour contribution at grid point i
+        RKn[i]  -- 'center' contribution at grid point i
+        RKnL[i] -- 'left'   neighbour contribution at grid point i
+
+    NT0..NT9 are the number of grid points at each level.
+    RK[i] is the coarsest flat grid (NT points).
+    """
+
+    def __init__(self, delta_wv: float, cut_off: float, H: float):
+        self.deltaWV = delta_wv
+        self.cutOff  = cut_off
+        self.H       = H
+
+        self.H0 = 2.0    * H
+        self.H1 = 4.0    * H
+        self.H2 = 8.0    * H
+        self.H3 = 16.0   * H
+        self.H4 = 32.0   * H
+        self.H5 = 64.0   * H
+        self.H6 = 128.0  * H
+        self.H7 = 256.0  * H
+        self.H8 = 512.0  * H
+        self.H9 = 1024.0 * H
+
+        self.NT  = max(1, int(round(delta_wv / H)))
+        self.NT0 = max(1, self.NT // 2)
+        self.NT1 = max(1, self.NT // 4)
+        self.NT2 = max(1, self.NT // 8)
+        self.NT3 = max(1, self.NT // 16)
+        self.NT4 = max(1, self.NT // 32)
+        self.NT5 = max(1, self.NT // 64)
+        self.NT6 = max(1, self.NT // 128)
+        self.NT7 = max(1, self.NT // 256)
+        self.NT8 = max(1, self.NT // 512)
+        self.NT9 = max(1, self.NT // 1024)
+
+        self._allocate()
+
+    def _allocate(self):
+        def z(n):
+            return np.zeros(n + 2)   # +2 for 1-based index safety
+
+        self.RK = z(self.NT)
+
+        self.RK0P = z(self.NT0);  self.RK0 = z(self.NT0);  self.RK0L = z(self.NT0)
+        self.RK1P = z(self.NT1);  self.RK1 = z(self.NT1);  self.RK1L = z(self.NT1)
+        self.RK2P = z(self.NT2);  self.RK2 = z(self.NT2);  self.RK2L = z(self.NT2)
+        self.RK3P = z(self.NT3);  self.RK3 = z(self.NT3);  self.RK3L = z(self.NT3)
+        self.RK4P = z(self.NT4);  self.RK4 = z(self.NT4);  self.RK4L = z(self.NT4)
+        self.RK5P = z(self.NT5);  self.RK5 = z(self.NT5);  self.RK5L = z(self.NT5)
+        self.RK6P = z(self.NT6);  self.RK6 = z(self.NT6);  self.RK6L = z(self.NT6)
+        self.RK7P = z(self.NT7);  self.RK7 = z(self.NT7);  self.RK7L = z(self.NT7)
+        self.RK8P = z(self.NT8);  self.RK8 = z(self.NT8);  self.RK8L = z(self.NT8)
+        self.RK9P = z(self.NT9);  self.RK9 = z(self.NT9);  self.RK9L = z(self.NT9)
+
+    def reset(self):
+        """Zero all arrays (called before each new spectral line)."""
+        self._allocate()
+
+    def reconstruct_fine_grid(self) -> np.ndarray:
+        """Reconstruct the fine-grid array from the stencil hierarchy."""
+        result = self.RK[1:self.NT + 1].copy()
+
+        levels = [
+            (self.RK0, self.RK0P, self.RK0L, self.NT0, self.H0),
+            (self.RK1, self.RK1P, self.RK1L, self.NT1, self.H1),
+            (self.RK2, self.RK2P, self.RK2L, self.NT2, self.H2),
+            (self.RK3, self.RK3P, self.RK3L, self.NT3, self.H3),
+            (self.RK4, self.RK4P, self.RK4L, self.NT4, self.H4),
+            (self.RK5, self.RK5P, self.RK5L, self.NT5, self.H5),
+            (self.RK6, self.RK6P, self.RK6L, self.NT6, self.H6),
+            (self.RK7, self.RK7P, self.RK7L, self.NT7, self.H7),
+            (self.RK8, self.RK8P, self.RK8L, self.NT8, self.H8),
+            (self.RK9, self.RK9P, self.RK9L, self.NT9, self.H9),
+        ]
+
+        NT = self.NT
+        for RKn, RKnP, RKnL, NTn, Hn in levels:
+            ratio = max(1, int(round(Hn / self.H)))
+            i_arr = np.arange(1, NTn + 1)
+            c_idx = i_arr * ratio - 1
+            l_idx = c_idx - ratio // 2
+            r_idx = c_idx + ratio // 2
+
+            for idx_arr, RK_arr in ((c_idx, RKn),
+                                    (l_idx, RKnL),
+                                    (r_idx, RKnP)):
+                valid = (idx_arr >= 0) & (idx_arr < NT)
+                if np.any(valid):
+                    np.add.at(result, idx_arr[valid],
+                              RK_arr[1:NTn + 1][valid])
+
+        return result

multigrid/hitran.py

@@ -0,0 +1,91 @@
+"""HITRAN spectral line reader."""
+import logging
+import os
+from dataclasses import dataclass
+from typing import List, Optional
+
+from .molecules import MOLECULE_NAMES
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class SpectralLine:
+    """HITRAN spectral line parameters."""
+    mol_id:       int
+    iso_id:       int
+    nu:           float
+    S:            float
+    A:            float
+    gamma_air:    float
+    gamma_self:   float
+    E_low:        float
+    n_air:        float
+    delta_air:    float
+    g_upper:      int = 0
+    g_lower:      int = 0
+
+
+class HITRANReader:
+    """Read HITRAN ``.par`` files into :class:`SpectralLine` objects."""
+
+    @staticmethod
+    def read_par_file(
+        filename: str,
+        molecule_id: Optional[int] = None,
+        wavenumber_min: Optional[float] = None,
+        wavenumber_max: Optional[float] = None,
+        intensity_threshold: Optional[float] = None,
+    ) -> List[SpectralLine]:
+        lines: List[SpectralLine] = []
+
+        if not os.path.exists(filename):
+            logger.warning("HITRAN file not found: %s", filename)
+            return lines
+
+        try:
+            with open(filename, "r") as f:
+                for lineno, line_str in enumerate(f, start=1):
+                    if len(line_str) < 160:
+                        continue
+                    try:
+                        mol        = int(line_str[0:2])
+                        iso        = int(line_str[2])
+                        nu         = float(line_str[3:15])
+                        S          = float(line_str[15:25])
+                        A          = float(line_str[25:35])
+                        gamma_air  = float(line_str[35:40])
+                        gamma_self = float(line_str[40:45])
+                        E_low      = float(line_str[45:55])
+                        n_air      = float(line_str[55:59])
+                        delta_air  = float(line_str[59:67])
+                    except (ValueError, IndexError):
+                        logger.debug("Skipping malformed line %d in %s",
+                                     lineno, filename)
+                        continue
+
+                    if molecule_id is not None and mol != molecule_id:
+                        continue
+                    if wavenumber_min is not None and nu < wavenumber_min:
+                        continue
+                    if wavenumber_max is not None and nu > wavenumber_max:
+                        continue
+                    if intensity_threshold is not None and S < intensity_threshold:
+                        continue
+
+                    lines.append(SpectralLine(
+                        mol_id=mol, iso_id=iso, nu=nu, S=S, A=A,
+                        gamma_air=gamma_air, gamma_self=gamma_self,
+                        E_low=E_low, n_air=n_air, delta_air=delta_air,
+                    ))
+        except OSError:
+            logger.exception("Error reading %s", filename)
+            return lines
+
+        if lines:
+            name = MOLECULE_NAMES.get(molecule_id, "Unknown")
+            logger.info("%s: %d lines loaded from %s", name, len(lines), filename)
+        else:
+            logger.warning("No lines matched the filters in %s", filename)
+
+        return lines

multigrid/line_shapes.py

@@ -0,0 +1,48 @@
+"""Spectral line shape functions."""
+import numpy as np
+from scipy.special import wofz
+
+from .constants import Constants
+
+
+class LineShapes:
+    """Spectral line shape functions matching Fortran LineShapes module."""
+
+    @staticmethod
+    def voigt_humlicek(x: np.ndarray, a: float) -> np.ndarray:
+        """Voigt function via Humlíček (1982) / Faddeeva function."""
+        return np.real(wofz(x + 1j * a)) / Constants.sqrt_pi
+
+    @staticmethod
+    def voigt_normalized(x: np.ndarray,
+                         gamma_L: float,
+                         gamma_D: float) -> np.ndarray:
+        """
+        Voigt profile normalised so that its integral over all x is 1.
+
+        Parameters
+        ----------
+        x       : offset from line centre [cm-1]
+        gamma_L : Lorentz (pressure) half-width [cm-1]
+        gamma_D : Doppler half-width [cm-1]
+        """
+        if gamma_D == 0:
+            return LineShapes.lorentz(x, gamma_L)
+        if gamma_L == 0:
+            return LineShapes.doppler(x, gamma_D)
+
+        x_reduced = x / gamma_D
+        a = gamma_L / gamma_D
+        K = LineShapes.voigt_humlicek(x_reduced, a)
+        # voigt_humlicek already returns Re[w(z)]/sqrt(pi); dividing by
+        # gamma_D alone yields a profile whose integral over all x equals 1.
+        return K / gamma_D
+
+    @staticmethod
+    def lorentz(x: np.ndarray, gamma: float) -> np.ndarray:
+        return gamma / (np.pi * (x ** 2 + gamma ** 2))
+
+    @staticmethod
+    def doppler(x: np.ndarray, gamma_D: float) -> np.ndarray:
+        return (Constants.sqrt_ln2 / (gamma_D * Constants.sqrt_pi)) * \
+               np.exp(-Constants.ln2_pi * (x / gamma_D) ** 2)

multigrid/molecules.py

@@ -0,0 +1,11 @@
+MOLECULE_NAMES = {
+    1: "H2O", 2: "CO2", 3: "O3",  4: "N2O",  5: "CO",
+    6: "CH4", 7: "O2",  8: "NO",  9: "SO2",  10: "NO2",
+    11: "NH3", 12: "HNO3",
+}
+
+MOLECULAR_MASSES = {
+    1: 18.010565, 2: 43.989830, 3: 47.984745, 4: 44.001062,
+    5: 27.994915, 6: 16.031300, 7: 31.989830, 8: 29.997989,
+    9: 63.961901, 10: 45.992904, 11: 17.026549, 12: 62.995644,
+}

multigrid/plotting.py

@@ -0,0 +1,50 @@
+"""Optional plotting helpers.
+
+Requires matplotlib.  matplotlib is imported lazily inside each function
+so that ``import multigrid`` never pulls it in.
+"""
+from typing import Optional
+
+import numpy as np
+
+
+def plot_spectrum(
+    nu: np.ndarray,
+    alpha: np.ndarray,
+    *,
+    title: Optional[str] = None,
+    filename: Optional[str] = None,
+    show: bool = True,
+    ax=None,
+):
+    """
+    Plot an absorption spectrum.
+
+    Parameters
+    ----------
+    nu       : wavenumber grid [cm-1]
+    alpha    : absorption coefficient [cm-1]
+    title    : optional plot title
+    filename : if given, save the figure to this path
+    show     : if True, call ``plt.show()``
+    ax       : optional existing matplotlib Axes to draw on
+    """
+    import matplotlib.pyplot as plt   # lazy — only when actually plotting
+
+    if ax is None:
+        fig, ax = plt.subplots(figsize=(12, 5))
+
+    ax.plot(nu, alpha, "b-", linewidth=0.6)
+    ax.set_xlabel("Wavenumber (cm⁻¹)")
+    ax.set_ylabel("Absorption coefficient (cm⁻¹)")
+    if title:
+        ax.set_title(title)
+    ax.grid(True, alpha=0.3)
+    ax.ticklabel_format(style="scientific", axis="y", scilimits=(0, 0))
+
+    if filename:
+        plt.tight_layout()
+        plt.savefig(filename, dpi=300)
+    if show:
+        plt.show()
+    return ax

multigrid/profiles.py

@@ -0,0 +1,24 @@
+"""Atmospheric profiles."""
+from dataclasses import dataclass
+from typing import Dict
+
+import numpy as np
+
+
+@dataclass
+class AtmosphericProfile:
+    """Vertical profile of a planetary atmosphere."""
+
+    z:   np.ndarray
+    P:   np.ndarray
+    T:   np.ndarray
+    vmr: Dict[int, np.ndarray]
+
+    @classmethod
+    def us_standard(cls) -> "AtmosphericProfile":
+        """Very coarse US Standard Atmosphere (7 levels)."""
+        z   = np.array([0, 10, 20, 30, 50, 70, 100], dtype=float)
+        P   = np.array([1.0, 0.265, 0.055, 0.012, 0.001, 0.00005, 0.000003])
+        T   = np.array([288, 223, 217, 227, 271, 220, 210], dtype=float)
+        vmr = {2: 400e-6 * np.ones_like(z)}
+        return cls(z, P, T, vmr)

multigrid/pt_table.py

@@ -0,0 +1,42 @@
+"""PT-table generator for radiative-transfer codes."""
+import logging
+from typing import List
+
+import numpy as np
+
+from .core import MARFA
+from .hitran import SpectralLine
+
+logger = logging.getLogger(__name__)
+
+
+class PTTableGenerator:
+    """Generate a (P, T, nu) lookup table of absorption coefficients."""
+
+    def __init__(self, marfa: MARFA):
+        self.marfa = marfa
+
+    def generate_table(
+        self,
+        nu_grid: np.ndarray,
+        lines: List[SpectralLine],
+        P_grid: np.ndarray,
+        T_grid: np.ndarray,
+        mole_fraction: float,
+        output_file: str,
+    ) -> np.ndarray:
+        logger.info("Generating PT table: %d P x %d T x %d nu",
+                    len(P_grid), len(T_grid), len(nu_grid))
+
+        n_P, n_T, n_nu = len(P_grid), len(T_grid), len(nu_grid)
+        table = np.zeros((n_P, n_T, n_nu))
+
+        for i, P in enumerate(P_grid):
+            for j, T in enumerate(T_grid):
+                logger.debug("P=%.3e atm  T=%.1f K", P, T)
+                table[i, j, :] = self.marfa.calculate_absorption_coefficient(
+                    nu_grid, lines, T, P, mole_fraction)
+
+        np.save(output_file, table)
+        logger.info("Saved PT table to %s", output_file)
+        return table

multigrid/tips.py

@@ -0,0 +1,45 @@
+"""Total Internal Partition Sums (TIPS)."""
+import logging
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+
+class TIPS:
+    """
+    Total Internal Partition Sums.
+
+    NOTE
+    ----
+    The temperature dependence implemented here is a rough T**1.5 scaling
+    anchored at 296 K.  It is adequate for qualitative work but is NOT the
+    real Gamache et al. (2017) TIPS database.  Replace `_calculate_tips_table`
+    with a real table lookup for quantitative accuracy.
+    """
+
+    def __init__(self):
+        self.Q_ref_296 = {
+            1: 178.12,  2: 289.49,  3: 4870.3,  4: 1122.3,
+            5: 108.58,  6: 590.43,  7: 216.21,  8: 159.47,
+            9: 5792.6,  10: 2379.5, 11: 169.24, 12: 11456.0,
+        }
+        self.T_grid = np.arange(20, 1002, 2)
+        self._calculate_tips_table()
+
+    def _calculate_tips_table(self):
+        self.tips_table = {}
+        for mol_id in range(1, 13):
+            Q_ref = self.Q_ref_296.get(mol_id, 100.0)
+            self.tips_table[mol_id] = Q_ref * (self.T_grid / 296.0) ** 1.5
+
+    def get_Q(self, mol_id: int, T: float) -> float:
+        if mol_id not in self.tips_table:
+            logger.debug("Unknown molecule id %d, falling back to CO2", mol_id)
+            mol_id = 2
+        T = float(np.clip(T, 20.0, 1000.0))
+        idx = int((T - 20.0) / 2.0)
+        idx = max(0, min(idx, len(self.T_grid) - 2))
+        T1, T2 = self.T_grid[idx], self.T_grid[idx + 1]
+        Q1, Q2 = self.tips_table[mol_id][idx], self.tips_table[mol_id][idx + 1]
+        return float(Q1 + (Q2 - Q1) * (T - T1) / (T2 - T1))

multigrid/wing_corrections.py

@@ -0,0 +1,28 @@
+"""Sub-Lorentzian wing correction (chi-factor) functions."""
+import numpy as np
+
+
+class WingCorrections:
+    """Sub-Lorentzian wing correction functions."""
+
+    @staticmethod
+    def tonkov_chi(delta_nu: np.ndarray, nu0: float) -> np.ndarray:
+        abs_delta = np.abs(delta_nu)
+        chi = np.ones_like(delta_nu, dtype=float)
+        mask2 = (abs_delta > 25.0) & (abs_delta <= 250.0)
+        chi[mask2] = 1.0 - 0.02 * ((abs_delta[mask2] - 25.0) / 225.0) ** 2
+        mask3 = abs_delta > 250.0
+        chi[mask3] = 0.98 * np.exp(-(abs_delta[mask3] - 250.0) / 200.0)
+        return chi
+
+    @staticmethod
+    def perrin_chi(delta_nu: np.ndarray, nu0: float) -> np.ndarray:
+        abs_delta = np.abs(delta_nu)
+        chi = np.ones_like(delta_nu, dtype=float)
+        mask = abs_delta > 20.0
+        chi[mask] = np.exp(-0.0015 * (abs_delta[mask] - 20.0))
+        return chi
+
+    @staticmethod
+    def no_correction(delta_nu: np.ndarray, nu0: float) -> np.ndarray:
+        return np.ones_like(delta_nu, dtype=float)

multigrid_py-3.0.1.dist-info/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Osama and MARFA contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

multigrid_py-3.0.1.dist-info/METADATA

@@ -0,0 +1,18 @@
+Metadata-Version: 2.1
+Name: multigrid-py
+Version: 3.0.1
+Summary: Python port of the Fortran MARFA line-by-line molecular absorption code
+Home-page: https://github.com/os1832000-png/MultiGrid_Py
+License: MIT
+Platform: UNKNOWN
+Requires-Python: >=3.6
+Requires-Dist: numpy (>=1.16)
+Requires-Dist: scipy (>=1.2)
+Provides-Extra: dev
+Requires-Dist: pytest ; extra == 'dev'
+Provides-Extra: plot
+Requires-Dist: matplotlib (>=3.0) ; extra == 'plot'
+
+UNKNOWN
+
+

multigrid_py-3.0.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+multigrid/__init__.py,sha256=yP7j67ExcE7VRGKVyqimv7LgoYZ9GDoord9zr7HpKRI,1100
+multigrid/_warnings.py,sha256=_YX2gIzwnET8fP1KLsd-MTvtX_tKeWXg9EgbXCQz1v8,334
+multigrid/cli.py,sha256=ua_4uD2ZRNgvays4DfjOe8ZTl9xrYnzjbDtcLecY5wA,2371
+multigrid/constants.py,sha256=dAHQ8P6-o1Al_BV8jv74Sfm_DsspeK_zxT2dEHb75UA,860
+multigrid/core.py,sha256=6oz4n08OWDrfan7MfJMka2cIAg9w0odtz6Y2E1QwO5Y,5331
+multigrid/grid_calculator.py,sha256=11InH8Uwj6QIxPN1c7LEwj6dg1gGeINR9_tH3k3i01g,6144
+multigrid/grids.py,sha256=QqXdIhYf5w91cCYgFjOFt3d4uVZx7G1EB15F7iN0zuk,4139
+multigrid/hitran.py,sha256=8oTg-C4ysi2hbaULwJip8Ry506dmmDlGLZXoiIHQrws,3242
+multigrid/line_shapes.py,sha256=ETI6hW-v2a8BoOa9dZbll57efc2Vn29_oxeQpbPYZNQ,1659
+multigrid/molecules.py,sha256=jjCZAiyPqk56QrFniqFE7TpNdn4OjVDyzD0fX3srUVg,364
+multigrid/plotting.py,sha256=HP14lpPHgysswLJl2tWNlZ6N18e27aJuuvUQpcCsMi4,1297
+multigrid/profiles.py,sha256=xmXkapKDOYrJq43GlC3EnkrBWKHIiZLMSYEipXcs-9Q,712
+multigrid/pt_table.py,sha256=_APFb6gkCIdoBiIMuOUag0UoQWFty1zx10EvXD-OalQ,1234
+multigrid/tips.py,sha256=quxxMuHeTaxIwynpgZ3y89pe_XXzTR21FNUdG77kLZA,1567
+multigrid/wing_corrections.py,sha256=9MIVHhv6Oy2OXVJ_t8T4ucmXPrgTJyKxKrH8j_wxm7w,1017
+multigrid_py-3.0.1.dist-info/LICENSE,sha256=bbaWnq3frG3ZSf0UBZxWnatxXDdBALQtiVioQNVe3gU,1085
+multigrid_py-3.0.1.dist-info/METADATA,sha256=fQdzRk7qaypzjMb_V9mDlTH48HcSEbmFJxVhw4NO2aQ,450
+multigrid_py-3.0.1.dist-info/WHEEL,sha256=g4nMs7d-Xl9-xC9XovUrsDHGXt-FT0E17Yqo92DEfvY,92
+multigrid_py-3.0.1.dist-info/entry_points.txt,sha256=1yC203C3PM83xNIn0P9NLbFR5IaBPN6AQf1ClzHksEc,50
+multigrid_py-3.0.1.dist-info/top_level.txt,sha256=IizlWsvgs3-JDnPAAgLXMo8Re7upWmqJkKkZNGfh3YE,10
+multigrid_py-3.0.1.dist-info/RECORD,,

multigrid_py-3.0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: bdist_wheel (0.34.2)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

multigrid_py-3.0.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+multigrid = multigrid.cli:main
+

multigrid_py-3.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+multigrid