mpiemses3d-tools 4.7.0__tar.gz

mpiemses3d_tools-4.7.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CS12-Laboratory
+
+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.

mpiemses3d_tools-4.7.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: mpiemses3d-tools
+Version: 4.7.0
+Summary: CLI utilities for MPIEMSES3D plasma simulations
+Author: Jin Nakazono
+License: MIT
+Project-URL: Homepage, https://github.com/CS12-Laboratory/MPIEMSES3D
+Keywords: plasma,PIC,EMSES,simulation,tools
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: scipy
+Requires-Dist: typer>=0.9
+Dynamic: license-file
+
+# mpiemses3d-tools
+
+CLI utilities for [MPIEMSES3D](https://github.com/Nkzono99/mpiemses3d) plasma simulations.
+
+## Installation
+
+```bash
+pip install mpiemses3d-tools
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `inp2toml` | Convert Fortran namelist (`plasma.inp`) to TOML format |
+| `emu` / `emses-unit` | Unit conversion and TOML inspection |
+| `toml-upgrade` | Upgrade `plasma.toml` from format v1 to v2 |
+| `emses-cp` / `cpem` | Copy the mpiemses3D binary to a target directory |
+
+## Python API
+
+```python
+from mpiemses3d_tools.plasma_toml import PlasmaToml
+from mpiemses3d_tools.unit_system import UnitSystem
+from mpiemses3d_tools.inp2toml import inp2toml
+```

mpiemses3d_tools-4.7.0/README.md

@@ -0,0 +1,26 @@
+# mpiemses3d-tools
+
+CLI utilities for [MPIEMSES3D](https://github.com/Nkzono99/mpiemses3d) plasma simulations.
+
+## Installation
+
+```bash
+pip install mpiemses3d-tools
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `inp2toml` | Convert Fortran namelist (`plasma.inp`) to TOML format |
+| `emu` / `emses-unit` | Unit conversion and TOML inspection |
+| `toml-upgrade` | Upgrade `plasma.toml` from format v1 to v2 |
+| `emses-cp` / `cpem` | Copy the mpiemses3D binary to a target directory |
+
+## Python API
+
+```python
+from mpiemses3d_tools.plasma_toml import PlasmaToml
+from mpiemses3d_tools.unit_system import UnitSystem
+from mpiemses3d_tools.inp2toml import inp2toml
+```

mpiemses3d_tools-4.7.0/mpiemses3d_tools/_fmt.py

@@ -0,0 +1,37 @@
+"""Shared TOML formatting utilities for plasma.toml serialization."""
+
+from __future__ import annotations
+
+
+def fmt(value) -> str:
+    """Format a Python value as a TOML literal."""
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        r = repr(value)
+        if "." not in r and "e" not in r.lower():
+            r += ".0"
+        return r
+    if isinstance(value, str):
+        return f'"{value}"'
+    if isinstance(value, list):
+        if value and isinstance(value[0], list):
+            inner = ", ".join(
+                "[" + ", ".join(fmt(v) for v in row) + "]" for row in value
+            )
+            return f"[{inner}]"
+        return "[" + ", ".join(fmt(v) for v in value) + "]"
+    return str(value)
+
+
+def emit_kv(parts: list[str], params: dict, header: str | None = None):
+    """Emit [header] + key = value lines to *parts*."""
+    if not params:
+        return
+    if header:
+        parts.append(header)
+    for k, v in params.items():
+        parts.append(f"{k} = {fmt(v)}")
+    parts.append("")

mpiemses3d_tools-4.7.0/mpiemses3d_tools/_inp_parser.py

@@ -0,0 +1,292 @@
+"""Fortran namelist parser for plasma.inp files.
+
+Parses ``!!key`` headers, ``&group … /`` namelist blocks,
+array slice syntax, 2D indexing, and Fortran literals.
+"""
+
+from __future__ import annotations
+
+import re
+from collections import OrderedDict
+
+# ── LHS patterns (checked in order) ──────────────────────────────
+_RE_2D = re.compile(r"(\w+)\s*\(\s*(\d+)\s*,\s*(\d+)\s*\)")
+_RE_2D_COL_SLICE = re.compile(r"(\w+)\s*\(\s*(\d+)\s*,\s*(\d+)\s*:\s*(\d+)\s*\)")
+_RE_2D_ROW_SLICE = re.compile(r"(\w+)\s*\(\s*(\d+)\s*:\s*(\d+)\s*,\s*(\d+)\s*\)")
+_RE_2D_FULL_ROW = re.compile(r"(\w+)\s*\(\s*:\s*,\s*(\d+)\s*\)")  # var(:, col)
+_RE_2D_FULL_COL = re.compile(r"(\w+)\s*\(\s*(\d+)\s*,\s*:\s*\)")  # var(row, :)
+_RE_SLICE = re.compile(r"(\w+)\s*\(\s*(\d+)\s*:\s*(\d+)\s*\)")
+_RE_SINGLE = re.compile(r"(\w+)\s*\(\s*(\d+)\s*\)")
+_RE_PLAIN = re.compile(r"(\w+)")
+
+
+def _remove_inline_comment(line: str) -> str:
+    """Strip trailing ``!`` comment while preserving quoted strings."""
+    in_str = False
+    qchar = ""
+    for i, ch in enumerate(line):
+        if in_str:
+            if ch == qchar:
+                in_str = False
+        else:
+            if ch in ('"', "'"):
+                in_str = True
+                qchar = ch
+            elif ch == "!":
+                return line[:i].rstrip()
+    return line.rstrip()
+
+
+def _parse_scalar(s: str):
+    """Parse a single Fortran literal into a Python value."""
+    s = s.strip().rstrip(",")
+    if not s:
+        return None
+    low = s.lower()
+    if low in (".true.", "true"):
+        return True
+    if low in (".false.", "false"):
+        return False
+    if (s.startswith('"') and s.endswith('"')) or (
+        s.startswith("'") and s.endswith("'")
+    ):
+        return s[1:-1]
+    # Fortran double-precision exponent d/D -> e
+    s_num = re.sub(r"[dD]", "e", s)
+    try:
+        if "." in s_num or "e" in s_num.lower():
+            return float(s_num)
+        return int(s_num)
+    except ValueError:
+        return s
+
+
+def _split_values(text: str) -> list:
+    """Split comma-separated Fortran values respecting quoted strings."""
+    values: list = []
+    current = ""
+    in_str = False
+    qchar = ""
+    for ch in text:
+        if in_str:
+            current += ch
+            if ch == qchar:
+                in_str = False
+        elif ch in ('"', "'"):
+            in_str = True
+            qchar = ch
+            current += ch
+        elif ch == ",":
+            if current.strip():
+                values.append(_parse_scalar(current))
+            current = ""
+        else:
+            current += ch
+    if current.strip():
+        values.append(_parse_scalar(current))
+    return [v for v in values if v is not None]
+
+
+def _parse_key_header(line: str) -> dict | None:
+    """``!!key dx=[0.5],to_c=[10000.0]`` -> ``{'dx': 0.5, 'to_c': 10000.0}``."""
+    m = re.match(r"^!!key\s+(.*)", line.strip())
+    if not m:
+        return None
+    result: dict = {}
+    for kv in re.finditer(r"(\w+)\s*=\s*\[([^\]]*)\]", m.group(1)):
+        result[kv.group(1)] = _parse_scalar(kv.group(2))
+    return result
+
+
+def _parse_group_lines(lines: list[str]) -> OrderedDict:
+    """Parse raw lines inside ``&group ... /`` into an ordered parameter dict."""
+
+    # 1) Collect logical assignment strings (join continuation lines)
+    assignments: list[str] = []
+    current: str | None = None
+    for line in lines:
+        stripped = line.strip()
+        if not stripped or stripped.startswith("!"):
+            continue
+        stripped = _remove_inline_comment(stripped)
+        if not stripped:
+            continue
+        if re.match(r"\w+\s*(\(|=)", stripped):
+            if current is not None:
+                assignments.append(current)
+            current = stripped
+        elif current is not None:
+            current += " " + stripped
+    if current is not None:
+        assignments.append(current)
+
+    # 2) Interpret each assignment
+    storage: OrderedDict = OrderedDict()
+
+    for text in assignments:
+        eq_pos = text.index("=")
+        lhs = text[:eq_pos].strip()
+        rhs = text[eq_pos + 1 :].strip()
+        values = _split_values(rhs)
+        if not values:
+            continue
+
+        m2d_cs = _RE_2D_COL_SLICE.match(lhs)
+        m2d_rs = _RE_2D_ROW_SLICE.match(lhs)
+        m2d_fr = _RE_2D_FULL_ROW.match(lhs)
+        m2d_fc = _RE_2D_FULL_COL.match(lhs)
+        m2d = _RE_2D.match(lhs)
+        mslice = _RE_SLICE.match(lhs)
+        msingle = _RE_SINGLE.match(lhs)
+
+        if m2d_cs:
+            var = m2d_cs.group(1)
+            ri = int(m2d_cs.group(2))
+            cs, _ce = int(m2d_cs.group(3)), int(m2d_cs.group(4))
+            entry = storage.setdefault(var, {"kind": "matrix", "data": {}})
+            if entry["kind"] != "matrix":
+                entry["kind"] = "matrix"
+                entry["data"] = {}
+            for k, v in enumerate(values):
+                entry["data"][(ri, cs + k)] = v
+
+        elif m2d_rs:
+            var = m2d_rs.group(1)
+            rs, _re = int(m2d_rs.group(2)), int(m2d_rs.group(3))
+            ci = int(m2d_rs.group(4))
+            entry = storage.setdefault(var, {"kind": "matrix", "data": {}})
+            if entry["kind"] != "matrix":
+                entry["kind"] = "matrix"
+                entry["data"] = {}
+            for k, v in enumerate(values):
+                entry["data"][(rs + k, ci)] = v
+
+        elif m2d_fr:
+            # var(:, col) — full row-slice: values fill rows 1..N at fixed column
+            var = m2d_fr.group(1)
+            ci = int(m2d_fr.group(2))
+            entry = storage.setdefault(var, {"kind": "matrix", "data": {}})
+            if entry["kind"] != "matrix":
+                entry["kind"] = "matrix"
+                entry["data"] = {}
+            for k, v in enumerate(values):
+                entry["data"][(1 + k, ci)] = v
+
+        elif m2d_fc:
+            # var(row, :) — full col-slice: values fill cols 1..N at fixed row
+            var = m2d_fc.group(1)
+            ri = int(m2d_fc.group(2))
+            entry = storage.setdefault(var, {"kind": "matrix", "data": {}})
+            if entry["kind"] != "matrix":
+                entry["kind"] = "matrix"
+                entry["data"] = {}
+            for k, v in enumerate(values):
+                entry["data"][(ri, 1 + k)] = v
+
+        elif m2d:
+            var = m2d.group(1)
+            ri, ci = int(m2d.group(2)), int(m2d.group(3))
+            entry = storage.setdefault(var, {"kind": "matrix", "data": {}})
+            if entry["kind"] != "matrix":
+                entry["kind"] = "matrix"
+                entry["data"] = {}
+            for k, v in enumerate(values):
+                entry["data"][(ri + k, ci)] = v
+
+        elif mslice:
+            var = mslice.group(1)
+            start, _end = int(mslice.group(2)), int(mslice.group(3))
+            entry = storage.setdefault(var, {"kind": "array", "data": {}})
+            if entry["kind"] == "scalar":
+                entry.update(kind="array", data={})
+            if entry["kind"] == "flat":
+                entry.update(
+                    kind="array", data={i + 1: v for i, v in enumerate(entry["data"])}
+                )
+            for k, v in enumerate(values):
+                entry["data"][start + k] = v
+
+        elif msingle:
+            var = msingle.group(1)
+            idx = int(msingle.group(2))
+            entry = storage.setdefault(var, {"kind": "array", "data": {}})
+            if entry["kind"] == "scalar":
+                entry.update(kind="array", data={})
+            if entry["kind"] == "flat":
+                entry.update(
+                    kind="array", data={i + 1: v for i, v in enumerate(entry["data"])}
+                )
+            for k, v in enumerate(values):
+                entry["data"][idx + k] = v
+
+        else:
+            var = _RE_PLAIN.match(lhs).group(1)  # type: ignore[union-attr]
+            if len(values) == 1:
+                if var in storage and storage[var]["kind"] == "array":
+                    d = storage[var]["data"]
+                    d[max(d) + 1] = values[0]
+                else:
+                    storage[var] = {"kind": "scalar", "data": values[0]}
+            else:
+                storage[var] = {"kind": "flat", "data": values}
+
+    # 3) Finalize into plain Python values
+    result: OrderedDict = OrderedDict()
+    for var, entry in storage.items():
+        kind = entry["kind"]
+        data = entry["data"]
+
+        if kind == "scalar":
+            result[var] = data
+        elif kind == "flat":
+            result[var] = list(data)
+        elif kind == "array":
+            hi = max(data)
+            result[var] = [data.get(i, 0) for i in range(1, hi + 1)]
+        elif kind == "matrix":
+            rhi = max(k[0] for k in data)
+            chi = max(k[1] for k in data)
+            result[var] = [
+                [data.get((r, c), 0) for c in range(1, chi + 1)]
+                for r in range(1, rhi + 1)
+            ]
+
+    return result
+
+
+def parse_inp(text: str) -> tuple[dict | None, list[tuple[str, OrderedDict]]]:
+    """Parse full ``plasma.inp`` text.
+
+    Returns ``(meta, [(group_name, params), ...])``.
+    """
+    lines = text.splitlines()
+
+    # !!key header
+    meta = None
+    for line in lines:
+        s = line.strip()
+        if s.startswith("!!key"):
+            meta = _parse_key_header(s)
+            break
+        if s and not s.startswith("!"):
+            break
+
+    # Namelist groups
+    groups: list[tuple[str, OrderedDict]] = []
+    i = 0
+    while i < len(lines):
+        s = lines[i].strip()
+        m = re.match(r"&(\w+)", s)
+        if m:
+            gname = m.group(1)
+            glines: list[str] = []
+            i += 1
+            while i < len(lines):
+                if lines[i].strip() == "/":
+                    break
+                glines.append(lines[i])
+                i += 1
+            groups.append((gname, _parse_group_lines(glines)))
+        i += 1
+
+    return meta, groups

mpiemses3d_tools-4.7.0/mpiemses3d_tools/_serialize.py

@@ -0,0 +1,237 @@
+"""TOML format_version 2 serialization for plasma.toml."""
+
+from __future__ import annotations
+
+from collections import OrderedDict
+
+from ._fmt import emit_kv, fmt
+
+# Canonical output order for top-level groups.
+GROUP_ORDER = [
+    "meta",
+    "memo",
+    "real",
+    "realcv",
+    "species",
+    "esorem",
+    "jobcon",
+    "digcon",
+    "plasma",
+    "tmgrid",
+    "system",
+    "intp",
+    "others",
+    "inp",
+    "ptcond",
+    "wave",
+    "scrnt",
+    "emissn",
+    "dipole",
+    "testch",
+    "jsrc",
+    "mpi",
+    "verbose",
+    "gradema",
+]
+
+# AOT sub-keys inside their parent groups.
+AOT_KEYS: dict[str, list[str]] = {
+    "ptcond": ["objects", "boundaries"],
+    "emissn": ["planes"],
+    "dipole": ["sources"],
+    "testch": ["charges"],
+    "jsrc": ["sources"],
+}
+
+
+def serialize_v2(data: dict, schema: str | None = None) -> str:
+    """Serialize a plasma.toml dict to format_version 2 TOML string."""
+    parts: list[str] = []
+
+    if schema:
+        parts.append(f"#:schema {schema}")
+        parts.append("")
+
+    emitted: set[str] = set()
+
+    for group in GROUP_ORDER:
+        if group not in data:
+            continue
+        emitted.add(group)
+
+        if group == "meta":
+            _emit_meta(parts, data["meta"])
+        elif group == "species":
+            _emit_species(parts, data["species"])
+        elif group in AOT_KEYS:
+            _emit_group_with_aot(parts, group, data[group])
+        else:
+            emit_kv(parts, data[group], f"[{group}]")
+
+    # Any remaining groups not in the canonical order
+    for group in data:
+        if group not in emitted:
+            val = data[group]
+            if isinstance(val, dict):
+                emit_kv(parts, val, f"[{group}]")
+
+    return "\n".join(parts)
+
+
+def _emit_meta(parts: list[str], meta: dict) -> None:
+    """Emit [meta], [meta.unit_conversion], and [meta.physical]."""
+    _META_SUB = {"unit_conversion", "physical"}
+    parts.append("[meta]")
+    for k, v in meta.items():
+        if k in _META_SUB:
+            continue
+        parts.append(f"{k} = {fmt(v)}")
+    parts.append("")
+
+    uc = meta.get("unit_conversion")
+    if uc:
+        parts.append("[meta.unit_conversion]")
+        for k, v in uc.items():
+            parts.append(f"{k} = {fmt(v)}")
+        parts.append("")
+
+    phys = meta.get("physical")
+    if phys:
+        _PHYS_AOT = {"species", "conductors"}
+        parts.append("[meta.physical]")
+        for k, v in phys.items():
+            if k in _PHYS_AOT:
+                continue
+            parts.append(f"{k} = {fmt(v)}")
+        parts.append("")
+        for sp in phys.get("species", []):
+            parts.append("[[meta.physical.species]]")
+            for k, v in sp.items():
+                parts.append(f"{k} = {fmt(v)}")
+            parts.append("")
+        for cond in phys.get("conductors", []):
+            parts.append("[[meta.physical.conductors]]")
+            for k, v in cond.items():
+                parts.append(f"{k} = {fmt(v)}")
+            parts.append("")
+
+
+# Canonical key order for [[species]] — groups related parameters together.
+_SPECIES_KEY_ORDER = [
+    # Core physics
+    "wp",
+    "qm",
+    # Thermal velocity
+    "path",
+    "peth",
+    # Drift
+    "vdri",
+    "vdthz",
+    "vdthxy",
+    "vdx",
+    "vdy",
+    "vdz",
+    # Distribution
+    "spa",
+    "spe",
+    "speth",
+    "f",
+    # Particles
+    "npin",
+    "np",
+    "dnsf",
+    # Boundary
+    "npbnd",
+    # Injection
+    "inpf",
+    "inpb",
+    "injct",
+    "npr",
+    # Emission
+    "nflag_emit",
+    "curf",
+    "curb",
+    "nepl",
+    "emission_leave_anti_particle",
+    "emission_time_mode",
+    "emission_start_step",
+    "emission_end_step",
+    "emission_time_sigma",
+    "ray_zenith_angle_deg",
+    "ray_azimuth_angle_deg",
+    # Flux / charge
+    "flpf",
+    "flpb",
+    "qp",
+    "qpr",
+    "abvdem",
+    "dnsb",
+    # Diagnostics
+    "ipahdf",
+    "ipadig",
+    "ipaxyz",
+    "ildig",
+    "imdig",
+    "isort",
+    "irhsp",
+    # Velocity range
+    "vpa",
+    "vpb",
+    "vpe",
+    # Other
+    "mfpath",
+    "pemax",
+    "deltaemax",
+    "denmod",
+    "denk",
+    "omegalw",
+    "lcgamma",
+    "lcbeta",
+    "nphi",
+    "ndst",
+    "ioptd",
+]
+_SPECIES_KEY_SET = set(_SPECIES_KEY_ORDER)
+
+
+def _sorted_species_keys(sp: dict) -> list[str]:
+    """Return species keys in canonical order, unknown keys appended at end."""
+    ordered = [k for k in _SPECIES_KEY_ORDER if k in sp]
+    ordered.extend(k for k in sp if k not in _SPECIES_KEY_SET)
+    return ordered
+
+
+def _emit_species(parts: list[str], species_list: list[dict]) -> None:
+    """Emit [[species]] entries."""
+    for sp in species_list:
+        parts.append("[[species]]")
+        for k in _sorted_species_keys(sp):
+            parts.append(f"{k} = {fmt(sp[k])}")
+        parts.append("")
+
+
+def _emit_group_with_aot(parts: list[str], group: str, data: dict) -> None:
+    """Emit a group that may contain array-of-tables sub-keys."""
+    aot_keys = AOT_KEYS.get(group, [])
+    # Emit non-AOT keys first
+    simple = OrderedDict()
+    for k, v in data.items():
+        if k in aot_keys:
+            continue
+        if isinstance(v, dict):
+            # Nested table (e.g. ptcond.conductor_groups.group_1)
+            for subk, subv in v.items():
+                if isinstance(subv, dict):
+                    emit_kv(parts, subv, f"[{group}.{k}.{subk}]")
+                else:
+                    simple[f"{k}.{subk}"] = subv
+        else:
+            simple[k] = v
+    if simple:
+        emit_kv(parts, simple, f"[{group}]")
+    # Emit AOTs
+    for aot_key in aot_keys:
+        entries = data.get(aot_key, [])
+        if isinstance(entries, list):
+            for entry in entries:
+                emit_kv(parts, entry, f"[[{group}.{aot_key}]]")