irma 1.0.0__py3-none-any.whl

irma/__init__.py

@@ -0,0 +1,66 @@
+"""IRMA — (In)elastic Representation of Materials As S(alpha,beta) evaluations.
+
+A standalone tool for generating thermal neutron scattering law S(alpha, beta)
+libraries in ENDF-6 format using the phonon expansion method.
+
+Supports:
+  - Continuous phonon frequency distributions
+  - Generalized coherent elastic (Bragg edges) for arbitrary crystals
+  - Phonopy-backed hybrid inelastic_mode paths for noncubic MT4 generation
+  - Free-gas and diffusion translational modes
+  - Discrete oscillators
+  - Cold hydrogen/deuterium (ortho/para)
+  - Automatic alpha/beta grid generation
+  - Neutron-scattering forward model (irma.spectra): powder S(Q,E) ->
+    instrument-resolved 1-D spectrum for VISION / indirect / direct geometries,
+    with an auto chopper-resolution model for the 8 PyChop direct instruments
+"""
+
+__version__ = "1.0.0"
+__author__ = "IRMA developers"
+
+# Pin native BLAS/OMP thread pools to 1 at package import, before numpy can be
+# loaded through irma. The mode-1/2 engine parallelizes across SPAWNED worker
+# processes (get_context("spawn")); a multithreaded BLAS in the parent or the
+# workers oversubscribes the cores under the process pool (measured >10x
+# slower). Doing it here covers the common `import irma` / CLI entry;
+# setdefault preserves a deliberate caller override (a host that imports numpy
+# before irma should set these itself, or accept threaded BLAS).
+import os as _os
+
+for _v in ("OMP_NUM_THREADS", "OPENBLAS_NUM_THREADS", "MKL_NUM_THREADS",
+           "NUMEXPR_NUM_THREADS", "VECLIB_MAXIMUM_THREADS", "BLIS_NUM_THREADS"):
+    _os.environ.setdefault(_v, "1")
+
+# Stable top-level public API. Importing these from `irma` directly
+# (`from irma import run_leapr, DeckError`) decouples callers from the internal
+# module layout, so the core modules can be refactored without breaking them.
+# Exposed LAZILY (PEP 562 __getattr__) so `import irma` stays light -- the heavy
+# engine is only imported when one of these names is actually accessed, and the
+# light core (numpy + endf-parserpy) install never pulls an optional extra.
+__all__ = ["run_leapr", "LeaprResult", "parse_leapr_input", "DeckError",
+           "__version__", "__author__"]
+
+# public name -> "module:attr" it is loaded from on first access
+_PUBLIC_API = {
+    "run_leapr": "irma.core.engine:run_leapr",
+    "LeaprResult": "irma.core.driver:LeaprResult",
+    "parse_leapr_input": "irma.core.deck:parse_leapr_input",
+    "DeckError": "irma.core.deck:DeckError",
+}
+
+
+def __getattr__(name):
+    """Lazily resolve the public API symbols (PEP 562)."""
+    target = _PUBLIC_API.get(name)
+    if target is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+    module_name, attr = target.split(":")
+    value = getattr(importlib.import_module(module_name), attr)
+    globals()[name] = value          # cache so later access skips __getattr__
+    return value
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))

irma/__main__.py

@@ -0,0 +1,7 @@
+"""Allow running IRMA as: python -m irma"""
+import sys
+
+from irma.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

irma/cli.py

@@ -0,0 +1,198 @@
+"""Command-line interface for IRMA.
+
+Four capabilities behind one ``irma`` entry point:
+
+    irma <deck> <out.endf>          ENDF/TSL evaluation (legacy, unchanged)
+    irma evaluate <deck> <out.endf> same, explicit (alias: run)
+    irma spectra vision|indirect|direct ...   neutron-scattering forward spectra
+    irma spectra run <config> -o out.csv
+    irma ncrystal -o <outdir> config.yaml     NCrystal .irmapack export
+    irma --gui | --version
+
+Backward compatibility is mandatory: if the first argument is not a known
+subcommand keyword, it is treated as the legacy 2-positional deck path, so
+``irma deck out.endf``, ``python -m irma deck out.endf`` and
+``python -m irma.core.engine deck out.endf`` keep working byte-for-byte.
+
+``main(argv=None)`` returns a process exit code; the console-script and
+``python -m irma`` wrappers both ``sys.exit(main())``.
+"""
+
+import os
+import sys
+
+
+def _print_help():
+    """Print the top-level CLI usage text."""
+    print("IRMA — (In)elastic Representation of Materials "
+          "As S(alpha,beta) evaluations")
+    print()
+    print("Usage:")
+    print("  irma <input_file> <output_file>            "
+          "Run ENDF/TSL evaluation from an input deck")
+    print("  irma evaluate <input_file> <output_file>   "
+          "Same, explicit (alias: run)")
+    print("  irma spectra vision|indirect|direct ...    "
+          "Neutron-scattering forward spectrum")
+    print("  irma spectra run <config> -o out.csv       "
+          "Run a spectra config file")
+    print("  irma ncrystal -o <outdir> config.yaml      "
+          "Bake NCrystal .irmapack set (alias: python -m irma.ncrystal)")
+    print("  irma mlip build <structure> -o <outdir>    "
+          "MLIP phonon model bundle (no DFT needed)")
+    print("  irma mlip emit <bundle> --to endf,...      "
+          "Generate IRMA inputs from a bundle")
+    print("  irma mlip validate <bundle>                "
+          "Check a bundle end to end")
+    print("  irma --gui                                 "
+          "Launch graphical interface")
+    print("  irma --version                             "
+          "Show version")
+
+
+def _launch_gui():
+    """Start the Tk GUI, with a clear message if tkinter is unavailable."""
+    try:
+        from irma.gui.app import main as gui_main
+    except ImportError as exc:
+        print(f"\nThe GUI could not be started: {exc}", file=sys.stderr)
+        print("The graphical interface requires tkinter, which is not "
+              "installed for this Python.", file=sys.stderr)
+        print("See the Tkinter section of INSTALL.md for how to install "
+              "it on your system.", file=sys.stderr)
+        return 4
+    gui_main()
+    return 0
+
+
+def validate_output_path(path):
+    """Pre-flight an output file path BEFORE a long compute (shared by the deck
+    and spectra CLIs). Catches the common fail-late cases: the target is an
+    existing directory, the parent directory is missing, or the parent is not
+    writable. Returns an error message on failure, else None (each caller picks
+    its own exit code / stream)."""
+    p = os.path.abspath(str(path))
+    if os.path.isdir(p):
+        return f"output path is a directory, not a file: {p}"
+    if os.path.exists(p) and not os.access(p, os.W_OK):
+        # An existing read-only target otherwise fails only at the
+        # post-compute open (review S10).
+        return f"output file exists and is not writable: {p}"
+    parent = os.path.dirname(p)
+    if not os.path.isdir(parent):
+        return f"output directory does not exist: {parent}"
+    if not os.access(parent, os.W_OK):
+        return f"output directory is not writable: {parent}"
+    return None
+
+
+def _run_deck(args):
+    """Legacy 2-positional ENDF/TSL evaluation (run_leapr), unchanged."""
+    # `irma evaluate --help` / `irma run --help` is the natural discovery
+    # command; asking for help must never be answered with an error.
+    if args and args[0] in ("-h", "--help"):
+        _print_help()
+        return 0
+    if len(args) < 2:
+        print("Error: both input_file and output_file are required.", file=sys.stderr)
+        print("Usage: irma <input_file> <output_file>", file=sys.stderr)
+        return 1
+    input_file, output_file = args[0], args[1]
+    # Mirror the output-side preflight: a directory passed as the input (a
+    # one-keystroke tab-completion slip) must fail with a clear message, not
+    # leak an IsADirectoryError traceback out of the deck parser's open().
+    if os.path.isdir(input_file):
+        print(f"Error: input path is a directory, not a file: {input_file}",
+              file=sys.stderr)
+        print("Pass the LEAPR-style input deck itself "
+              "(e.g. graphite.input).", file=sys.stderr)
+        return 1
+    if not os.path.isfile(input_file):
+        print(f"Error: input file not found: {input_file}", file=sys.stderr)
+        return 1
+    # Pre-validate the output path BEFORE the (multi-minute) compute, so a typo'd
+    # output path / directory target / read-only parent fails fast instead of only
+    # after the whole run finishes.
+    err = validate_output_path(output_file)
+    if err:
+        print(f"Error: {err}", file=sys.stderr)
+        return 1
+    from irma.core.engine import run_leapr, DeckError
+    try:
+        run_leapr(input_file, output_file)
+    except DeckError as exc:
+        print(f"\nInput deck error:\n  {exc}", file=sys.stderr)
+        print("Fix the input deck and rerun (see the README card-by-card "
+              "input reference).", file=sys.stderr)
+        return 2
+    except (RuntimeError, OSError, ValueError) as exc:
+        # User-meaningful failures (phonopy model loading, missing/unreadable
+        # files, semantic problems) get a clean message; a traceback is
+        # reserved for genuinely unexpected errors. OSError covers the
+        # filesystem backstops (FileNotFoundError, IsADirectoryError,
+        # PermissionError) for anything the preflights above did not catch.
+        print(f"\nIRMA failed: {exc}", file=sys.stderr)
+        return 3
+    return 0
+
+
+def main(argv=None):
+    """Console entry point: dispatch to help, GUI, spectra, ncrystal, or a
+    deck evaluation depending on the arguments."""
+    argv = list(sys.argv[1:] if argv is None else argv)
+
+    if not argv:
+        _print_help()
+        return 0
+    if argv[0] == "--version":
+        from irma import __version__
+        print(f"IRMA v{__version__}")
+        return 0
+    if argv[0] in ("--help", "-h"):
+        _print_help()
+        return 0
+    if argv[0] == "--gui":
+        return _launch_gui()
+    if argv[0] == "spectra":
+        from irma.spectra.cli import main as spectra_main
+        return spectra_main(argv[1:])
+    if argv[0] == "mlip" and (
+            len(argv) == 1
+            or argv[1] in ("build", "emit", "validate", "env", "-h",
+                           "--help")
+            or not os.path.exists("mlip")):
+        from irma.mlip.cli import main as mlip_main
+        return mlip_main(argv[1:])
+    if argv[0] == "ncrystal":
+        # Same code path as `python -m irma.ncrystal` (which keeps working);
+        # surfaced here so all three capabilities live behind one command.
+        from irma.ncrystal.__main__ import main as ncrystal_main
+        return ncrystal_main(argv[1:])
+    if argv[0] in ("evaluate", "run"):
+        return _run_deck(argv[1:])
+
+    # Fall-through: argv[0] is not a known subcommand. Before treating it as a
+    # legacy deck path, catch an obvious mistyped subcommand or unknown flag so
+    # the user gets a clear hint instead of a misleading "input file not found".
+    tok = argv[0]
+    if not os.path.exists(tok):
+        if tok.startswith("-"):
+            print(f"Error: unknown option {tok!r}", file=sys.stderr)
+            _print_help()
+            return 1
+        # only second-guess COMMAND-LIKE tokens (a bare word); a path-like token
+        # with a "." or "/" is a (missing) deck path -> let _run_deck report that.
+        if "." not in tok and "/" not in tok and os.sep not in tok:
+            import difflib
+            known = ["evaluate", "run", "spectra", "ncrystal", "mlip",
+                     "--gui", "--version", "--help"]
+            close = difflib.get_close_matches(tok, known, n=1, cutoff=0.7)
+            if close:
+                print(f"Error: unknown command {tok!r}. Did you mean {close[0]!r}?",
+                      file=sys.stderr)
+                return 1
+    return _run_deck(argv)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

irma/core/__init__.py

@@ -0,0 +1 @@
+"""Core computation engine for IRMA."""

irma/core/constants.py

@@ -0,0 +1,88 @@
+"""Physical constants and element data shared across IRMA core modules.
+
+The numeric values match NJOY2016's physics module exactly (bit-compatible
+LEAPR reproduction depends on it).
+"""
+
+# ============================================================================
+# Physical constants (matching NJOY2016 physics module exactly)
+# ============================================================================
+BK = 8.617333262e-5       # Boltzmann constant, eV/K
+EV = 1.602176634e-12      # erg/eV
+CLIGHT = 2.99792458e10    # cm/s
+AMU = 931.49410242e6 * EV / (CLIGHT * CLIGHT)  # g/amu
+HBAR = 6.582119569e-16 * EV  # Planck/2pi, erg*s
+AMASSN = 1.00866491595     # neutron mass in amu
+
+THERM = 0.0253  # thermal energy in eV (for lat=1 scaling)
+
+# WL2EKIN = h²/(2 m_n)  [eV·Å²]   (de Broglie E = h²/(2 m_n λ²); CODATA 2018, matches NCrystal wl2ekin from NCDefs.hh)
+WL2EKIN: float = 0.081804209605330899
+
+# ============================================================================
+# CODATA 2018 / SI 2019 constants (phonopy-backed noncubic paths)
+# ============================================================================
+# References:
+#   E. Tiesinga, P. J. Mohr, D. B. Newell, and B. N. Taylor, "CODATA
+#   recommended values of the fundamental physical constants: 2018",
+#   Rev. Mod. Phys. 93, 025010 (2021); https://physics.nist.gov/constants
+#   h, e, and k_B are exact by the 2019 SI redefinition (BIPM, 9th SI
+#   brochure, 2019); BK above is that exact k_B/e value to 10 significant
+#   figures and is shared by the classic (NJOY-reproducing) path.
+# Derived values are computed from the defining constants rather than
+# hardcoded, so they cannot drift out of sync.
+from math import pi as _pi
+
+PLANCK_J_S = 6.62607015e-34          # h    [J s]   (exact, SI 2019)
+ECHARGE_C = 1.602176634e-19          # e    [C]     (exact, SI 2019)
+KB_J_PER_K = 1.380649e-23            # k_B  [J/K]   (exact, SI 2019)
+HBAR_J_S = PLANCK_J_S / (2.0 * _pi)  # ħ    [J s]
+HBAR_EV_S = HBAR_J_S / ECHARGE_C     # ħ    [eV s]  = 6.582119569...e-16
+NEUTRON_MASS_KG = 1.67492749804e-27  # m_n  [kg]    (CODATA 2018)
+AMU_KG = 1.66053906660e-27           # m_u  [kg]    (CODATA 2018)
+
+# 1 THz in eV: h * 1e12 / e = 4.135667696...e-3 eV
+THZ_TO_EV = PLANCK_J_S * 1.0e12 / ECHARGE_C
+
+# ħ²/(2 m_n) in meV·Å² = 2.0721248551... (the free-neutron kinematic
+# constant linking alpha to Q²: E[meV] = HBAR2_OVER_2MN_MEV_A2 · Q[1/Å]²)
+HBAR2_OVER_2MN_MEV_A2 = (
+    HBAR_J_S ** 2 / (2.0 * NEUTRON_MASS_KG) / (ECHARGE_C * 1.0e-3) * 1.0e20
+)
+
+# ============================================================================
+# Phonon-mode floor policy (mesh-sum numerical guards, modes 1/2)
+# ============================================================================
+# Per-mode one-phonon amplitudes and thermal displacements diverge as
+# kT/ω² for ω → 0. In the exact BZ integral the acoustic divergence is
+# integrable, but on a DISCRETE mesh the three Goldstone modes at Γ carry
+# finite weight with a numerically meaningless ω (acoustic-sum-rule
+# noise, commonly up to ~0.05 meV), so they must be excluded outright.
+# Away from Γ every mode is physical and only an overflow guard is
+# needed. Hence a two-tier rule:
+#   - at Γ q-points: drop modes below GAMMA_ACOUSTIC_FLOOR_MEV
+#     (optical Γ modes pass; Goldstone noise cannot);
+#   - elsewhere: drop modes below MODE_ENERGY_FLOOR_MEV (1 μeV), far
+#     under any acoustic energy at a nonzero mesh q-point, so genuinely
+#     ultra-soft physics is kept.
+# Shifted Monkhorst-Pack production meshes contain no Γ point and no
+# sub-μeV modes, so both guards are inert there.
+MODE_ENERGY_FLOOR_MEV = 1.0e-3
+GAMMA_ACOUSTIC_FLOOR_MEV = 0.1
+
+_Z_TO_SYMBOL = {
+    1: 'H',  2: 'He', 3: 'Li', 4: 'Be', 5: 'B',  6: 'C',  7: 'N',  8: 'O',
+    9: 'F', 10: 'Ne',11: 'Na',12: 'Mg',13: 'Al',14: 'Si',15: 'P', 16: 'S',
+   17: 'Cl',18: 'Ar',19: 'K', 20: 'Ca',21: 'Sc',22: 'Ti',23: 'V', 24: 'Cr',
+   25: 'Mn',26: 'Fe',27: 'Co',28: 'Ni',29: 'Cu',30: 'Zn',31: 'Ga',32: 'Ge',
+   33: 'As',34: 'Se',35: 'Br',36: 'Kr',37: 'Rb',38: 'Sr',39: 'Y', 40: 'Zr',
+   41: 'Nb',42: 'Mo',43: 'Tc',44: 'Ru',45: 'Rh',46: 'Pd',47: 'Ag',48: 'Cd',
+   49: 'In',50: 'Sn',51: 'Sb',52: 'Te',53: 'I', 54: 'Xe',55: 'Cs',56: 'Ba',
+   57: 'La',58: 'Ce',59: 'Pr',60: 'Nd',61: 'Pm',62: 'Sm',63: 'Eu',64: 'Gd',
+   65: 'Tb',66: 'Dy',67: 'Ho',68: 'Er',69: 'Tm',70: 'Yb',71: 'Lu',72: 'Hf',
+   73: 'Ta',74: 'W', 75: 'Re',76: 'Os',77: 'Ir',78: 'Pt',79: 'Au',80: 'Hg',
+   81: 'Tl',82: 'Pb',83: 'Bi',84: 'Po',85: 'At',86: 'Rn',87: 'Fr',88: 'Ra',
+   89: 'Ac',90: 'Th',91: 'Pa',92: 'U', 93: 'Np',94: 'Pu',95: 'Am',96: 'Cm',
+   97: 'Bk',98: 'Cf',99: 'Es',100:'Fm',101:'Md',102:'No',103:'Lr',
+}
+