multigrid-py 3.0.1__tar.gz

multigrid_py-3.0.1/PKG-INFO

@@ -0,0 +1,11 @@
+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
+Description: UNKNOWN
+Platform: UNKNOWN
+Requires-Python: >=3.6
+Provides-Extra: dev
+Provides-Extra: plot

multigrid_py-3.0.1/README.md

@@ -0,0 +1,143 @@
+# MultiGrid_Py
+
+**Python port of the Fortran MARFA line-by-line molecular absorption code.**
+
+Compute monochromatic absorption cross-sections and volume absorption
+coefficients for planetary atmospheres, using HITRAN spectral line data.
+
+Based on the original Fortran code by **Mikhail Razumovskiy**, **Boris Fomin**,
+and **Denis Astanin**.
+
+Reference: [MARFA: An Effective Line-by-line Tool for Calculating Molecular
+Absorption in Planetary Atmospheres](https://arxiv.org/abs/2411.03418)
+(arXiv:2411.03418, 2024).
+
+---
+
+## Features
+
+- **Line-by-line (LBL)** monochromatic absorption from HITRAN `.par` files
+- **Voigt, Lorentz, Doppler** line shapes (Voigt via Humlicek / Faddeeva)
+- **Temperature-dependent intensities** using TIPS partition sums
+- **Pressure and Doppler broadening** with HITRAN air/self parameters
+- **Wing corrections** (Tonkov, Perrin) for sub-Lorentzian continua
+- **Multi-resolution stencil machinery** (`GridState`, `LineGridCalc`)
+  for future PT-table work
+- Clean, tested, installable package -- 11 passing pytest tests
+- No import-time side effects: lazy matplotlib, no global warnings mutation
+
+---
+
+## Install
+
+Requires Python 3.6+, NumPy, and SciPy.
+
+From source (development):
+
+```bash
+git clone https://github.com/os1832000-png/MultiGrid_Py.git
+cd MultiGrid_Py
+pip install --user -e .
+With optional plotting support:
+
+bash
+pip install --user -e ".[plot]"
+Quick start
+python
+import numpy as np
+from multigrid import MARFA, HITRANReader
+
+# 1. Load CO2 lines from a HITRAN .par file
+lines = HITRANReader.read_par_file(
+    "CO2.par",
+    molecule_id=2,
+    wavenumber_min=2300.0,
+    wavenumber_max=2400.0,
+)
+print(f"loaded {len(lines)} lines")
+
+# 2. Build a wavenumber grid [cm^-1]
+nu = np.arange(2300.0, 2400.0, 0.01)
+
+# 3. Compute volume absorption coefficient [cm^-1]
+alpha = MARFA().calculate_absorption_coefficient(
+    nu, lines,
+    T=296.0,             # temperature [K]
+    P=1.0,               # pressure [atm]
+    mole_fraction=400e-6,
+    line_cutoff_cm=25.0,
+    wing_correction="none",   # 'none' | 'tonkov' | 'perrin'
+)
+print(f"max alpha = {alpha.max():.4e} cm^-1")
+For a runnable script see examples/co2_basic.py:
+
+bash
+python3 examples/co2_basic.py /path/to/CO2.par
+Plotting (optional)
+python
+from multigrid.plotting import plot_spectrum
+
+plot_spectrum(
+    nu, alpha,
+    title="CO2 2300-2400 cm^-1",
+    filename="co2_spectrum.png",
+)
+matplotlib is imported lazily, inside plot_spectrum. A plain
+import multigrid never loads matplotlib.
+
+Command line
+bash
+python3 -m multigrid.cli CO2.par --mol 2 --nu-min 2300 --nu-max 2400 \
+    --T 296 --P 1.0 --vmr 400e-6 -o co2_spectrum.npz
+The output .npz file contains nu and alpha arrays.
+
+Get help with:
+
+bash
+python3 -m multigrid.cli --help
+Public API
+Class / function	Purpose
+MARFA	Main calculation engine
+HITRANReader, SpectralLine	HITRAN .par file reader
+TIPS	Total Internal Partition Sums
+LineShapes	Voigt, Lorentz, Doppler profiles
+WingCorrections	Sub-Lorentzian chi factors (Tonkov, Perrin)
+GridState, LineGridCalc	Multi-resolution stencil machinery
+AtmosphericProfile	Simple vertical profile container
+PTTableGenerator	Pre-computed P-T absorption tables
+plotting.plot_spectrum	Optional matplotlib helper
+Tests
+bash
+pip install --user pytest
+python3 -m pytest tests/ -v
+11 tests covering line-shape normalisation, HITRAN parsing, the core
+engine, and import-time safety guarantees.
+
+Notes and limitations
+TIPS partition sums use a simplified Q_ref * (T/296)^1.5 model,
+not the full Gamache et al. (2017) tables. Adequate for qualitative work.
+
+Wing corrections are simple parametrisations; not validated against
+measured continua.
+
+Line mixing is not implemented.
+
+Continuum absorption (H2O, CO2, N2) is not implemented.
+
+The multi-grid stencil classes (GridState, LineGridCalc) are present
+but the working spectral path is the flat-grid Voigt sum.
+
+License
+MIT. See LICENSE.
+
+Citation
+If you use this code in a publication, please cite the original MARFA paper:
+
+Razumovskiy, M., Fomin, B., Astanin, D.
+MARFA: An Effective Line-by-line Tool for Calculating Molecular Absorption
+in Planetary Atmospheres. arXiv:2411.03418 (2024).
+
+Acknowledgements
+This is an independent Python port based on the Fortran MARFA code by
+Mikhail Razumovskiy, Boris Fomin, and Denis Astanin. All scientific credit
+for the underlying algorithm belongs to them.

multigrid_py-3.0.1/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=40.8.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "multigrid-py"
+version = "3.0.1"
+description = "MARFA: Molecular atmospheric Absorption with Rapid and Flexible Analysis"
+readme = "README.md"
+requires-python = ">=3.6"
+license = { text = "MIT" }
+authors = [
+    { name = "Osama" },
+    { name = "Mikhail Razumovskiy" },
+    { name = "Boris Fomin" },
+    { name = "Denis Astanin" },
+]
+keywords = ["atmospheric", "spectroscopy", "absorption", "HITRAN", "radiative-transfer"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering :: Atmospheric Science",
+]
+dependencies = [
+    "numpy>=1.16",
+    "scipy>=1.2",
+]
+
+[project.optional-dependencies]
+plot = ["matplotlib>=3.0"]
+dev  = ["pytest"]
+
+[project.urls]
+Homepage = "https://github.com/yourname/MARFA_PY_SIMPLE"
+Reference = "https://arxiv.org/abs/2411.03418"
+
+[project.scripts]
+multigrid = "multigrid.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["multigrid", "multigrid.*"]
+
+[tool.setuptools.package-data]
+multigrid = ["data/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

multigrid_py-3.0.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

multigrid_py-3.0.1/setup.py

@@ -0,0 +1,15 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="multigrid_py",
+    version="3.0.1",
+    description="Python port of the Fortran MARFA line-by-line molecular absorption code",
+    url="https://github.com/os1832000-png/MultiGrid_Py",
+    license="MIT",
+    package_dir={"": "src"},
+    packages=find_packages(where="src", include=["multigrid", "multigrid.*"]),
+    python_requires=">=3.6",
+    install_requires=["numpy>=1.16", "scipy>=1.2"],
+    extras_require={"plot": ["matplotlib>=3.0"], "dev": ["pytest"]},
+    entry_points={"console_scripts": ["multigrid=multigrid.cli:main"]},
+)

multigrid_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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_py-3.0.1/src/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/src/multigrid_py.egg-info/PKG-INFO

@@ -0,0 +1,11 @@
+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
+Description: UNKNOWN
+Platform: UNKNOWN
+Requires-Python: >=3.6
+Provides-Extra: dev
+Provides-Extra: plot

multigrid_py-3.0.1/src/multigrid_py.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+README.md
+pyproject.toml
+setup.py
+src/multigrid/__init__.py
+src/multigrid/_warnings.py
+src/multigrid/cli.py
+src/multigrid/constants.py
+src/multigrid/core.py
+src/multigrid/grid_calculator.py
+src/multigrid/grids.py
+src/multigrid/hitran.py
+src/multigrid/line_shapes.py
+src/multigrid/molecules.py
+src/multigrid/plotting.py
+src/multigrid/profiles.py
+src/multigrid/pt_table.py
+src/multigrid/tips.py
+src/multigrid/wing_corrections.py
+src/multigrid_py.egg-info/PKG-INFO
+src/multigrid_py.egg-info/SOURCES.txt
+src/multigrid_py.egg-info/dependency_links.txt
+src/multigrid_py.egg-info/entry_points.txt
+src/multigrid_py.egg-info/requires.txt
+src/multigrid_py.egg-info/top_level.txt

multigrid_py-3.0.1/src/multigrid_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

multigrid_py-3.0.1/src/multigrid_py.egg-info/entry_points.txt

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

multigrid_py-3.0.1/src/multigrid_py.egg-info/requires.txt

@@ -0,0 +1,8 @@
+numpy>=1.16
+scipy>=1.2
+
+[dev]
+pytest
+
+[plot]
+matplotlib>=3.0

multigrid_py-3.0.1/src/multigrid_py.egg-info/top_level.txt

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