pynumgeo 2026.2.0.dev2__py3-none-any.whl

pynumgeo/__init__.py

@@ -0,0 +1,144 @@
+# =~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~=~
+#                                                pynumgeo
+#                              Python API for the finite element code numgeo
+#                                     Copyright (C) 2026 Jan Machacek
+# =~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~=~
+#
+# Author: Jan Machacek
+#
+# pynumgeo writes, checks and runs numgeo input files and reads numgeo results. It follows the
+# development of numgeo: new developments in the numgeo source code are taken over into the API, and a
+# CI pipeline tests every change.
+#
+# License: BSD-3-Clause, see LICENSE.
+# =~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~=~
+"""pynumgeo — Python API for the finite element code numgeo.
+
+Read, build, validate and write numgeo input decks, run the solver and read its results::
+
+    import pynumgeo as ng
+
+    deck = ng.read("model.inp")              # numgeo input -> Deck (mesh, materials, steps, ...)
+    issues = ng.validate(deck)               # what numgeo would reject or read differently
+    ng.write(deck, "job/model.inp")          # normal-case, deterministic numgeo input
+    res = ng.run(deck, "job", job="model")   # run numgeo, judge the outcome from its logs
+    frames = ng.open_results("job", "model").frames()
+
+Everything numgeo-specific (keywords, options, element types, constitutive models, messages) comes from
+the catalogue (:mod:`pynumgeo.catalogue`), generated from the numgeo source. Submodules are imported
+lazily, so ``import pynumgeo`` stays fast. The functions ``run`` and ``validate`` live in the subpackages
+:mod:`pynumgeo.solver` and :mod:`pynumgeo.validation`; the subpackages are named differently from the
+functions so that importing one never replaces ``pynumgeo.run`` or ``pynumgeo.validate`` by a module.
+"""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+from pynumgeo._version import NUMGEO_DOCS_COMMIT, NUMGEO_SOURCE_COMMIT, NUMGEO_VERSION, __version__
+
+if TYPE_CHECKING:  # pragma: no cover
+    from pynumgeo import catalogue
+    from pynumgeo.deck import Amplitude, Deck, Keyword, Material, Section, Step, diff
+    from pynumgeo.io.reader import (
+        FragmentResult,
+        ReadError,
+        ReadResult,
+        data_tokens,
+        parse,
+        parse_fragment,
+        parse_text,
+        read,
+    )
+    from pynumgeo.io.writer import WriteError, format_keyword, format_material, write, write_text, write_texts
+    from pynumgeo.issue import Issue
+    from pynumgeo.mesh import Mesh
+    from pynumgeo.results import open_results
+    from pynumgeo.solver import RunResult, RunStatus, run
+    from pynumgeo.validation import BuildProfile, validate
+
+__all__ = [
+    "NUMGEO_DOCS_COMMIT",
+    "NUMGEO_SOURCE_COMMIT",
+    "NUMGEO_VERSION",
+    "Amplitude",
+    "BuildProfile",
+    "Deck",
+    "FragmentResult",
+    "Issue",
+    "Keyword",
+    "Material",
+    "Mesh",
+    "ReadError",
+    "ReadResult",
+    "RunResult",
+    "RunStatus",
+    "Section",
+    "Step",
+    "WriteError",
+    "__version__",
+    "catalogue",
+    "data_tokens",
+    "diff",
+    "format_keyword",
+    "format_material",
+    "open_results",
+    "parse",
+    "parse_fragment",
+    "parse_text",
+    "read",
+    "run",
+    "validate",
+    "write",
+    "write_text",
+    "write_texts",
+]
+
+_LAZY = {
+    "catalogue": ("pynumgeo.catalogue", None),
+    "Amplitude": ("pynumgeo.deck", "Amplitude"),
+    "Deck": ("pynumgeo.deck", "Deck"),
+    "Keyword": ("pynumgeo.deck", "Keyword"),
+    "Material": ("pynumgeo.deck", "Material"),
+    "Section": ("pynumgeo.deck", "Section"),
+    "Step": ("pynumgeo.deck", "Step"),
+    "diff": ("pynumgeo.deck", "diff"),
+    "Mesh": ("pynumgeo.mesh", "Mesh"),
+    "Issue": ("pynumgeo.issue", "Issue"),
+    "ReadError": ("pynumgeo.io.reader", "ReadError"),
+    "ReadResult": ("pynumgeo.io.reader", "ReadResult"),
+    "FragmentResult": ("pynumgeo.io.reader", "FragmentResult"),
+    "parse_fragment": ("pynumgeo.io.reader", "parse_fragment"),
+    "data_tokens": ("pynumgeo.io.reader", "data_tokens"),
+    "parse": ("pynumgeo.io.reader", "parse"),
+    "parse_text": ("pynumgeo.io.reader", "parse_text"),
+    "read": ("pynumgeo.io.reader", "read"),
+    "WriteError": ("pynumgeo.io.writer", "WriteError"),
+    "write": ("pynumgeo.io.writer", "write"),
+    "write_text": ("pynumgeo.io.writer", "write_text"),
+    "write_texts": ("pynumgeo.io.writer", "write_texts"),
+    "format_keyword": ("pynumgeo.io.writer", "format_keyword"),
+    "format_material": ("pynumgeo.io.writer", "format_material"),
+    "BuildProfile": ("pynumgeo.validation", "BuildProfile"),
+    "validate": ("pynumgeo.validation", "validate"),
+    "run": ("pynumgeo.solver", "run"),
+    "RunResult": ("pynumgeo.solver", "RunResult"),
+    "RunStatus": ("pynumgeo.solver", "RunStatus"),
+    "open_results": ("pynumgeo.results", "open_results"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    try:
+        mod, attr = _LAZY[name]
+    except KeyError:
+        raise AttributeError(f"module 'pynumgeo' has no attribute {name!r}") from None
+    m = importlib.import_module(mod)
+    value = m if attr is None else getattr(m, attr)
+    globals()[name] = value
+    return value
+
+
+def __dir__() -> list[str]:
+    return sorted(__all__)

pynumgeo/_provenance.py

@@ -0,0 +1,77 @@
+# =~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~=~
+#                                                pynumgeo
+#                              Python API for the finite element code numgeo
+#                                     Copyright (C) 2026 Jan Machacek
+# =~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~=~
+#
+# Author: Jan Machacek
+#
+# pynumgeo writes, checks and runs numgeo input files and reads numgeo results. It follows the
+# development of numgeo: new developments in the numgeo source code are taken over into the API, and a
+# CI pipeline tests every change.
+#
+# License: BSD-3-Clause, see LICENSE.
+# =~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~=~
+"""What pynumgeo writes into every file it creates: program, version and author.
+
+* Input files start with a banner of numgeo comment lines (``**``), in the style of the numgeo source
+  files: :func:`input_file_header`. numgeo cuts every line at ``**``, so the banner is not read.
+* The console log of a run (``<job>.console.log``) starts with :func:`console_header`; the console
+  parser skips that line.
+* The JSON reports of the command line carry :func:`provenance` under the key ``"pynumgeo"``.
+
+The creation date is not written: the same deck always gives the same file.
+
+Examples:
+    >>> print("\\n".join(input_file_header()))  # doctest: +ELLIPSIS
+    ** =~~=~~=...=~=~
+    ...numgeo input file
+    ...Created with pynumgeo ..., the Python API for numgeo by Jan Machacek
+    ...Written for numgeo... (numgeo source ...)
+    ** =~~=~~=...=~=~
+"""
+
+from __future__ import annotations
+
+from pynumgeo._version import NUMGEO_SOURCE_COMMIT, NUMGEO_VERSION, __version__
+
+__all__ = ["AUTHOR", "BANNER", "CONSOLE_MARK", "console_header", "input_file_header", "provenance"]
+
+#: The author of pynumgeo.
+AUTHOR = "Jan Machacek"
+#: Banner line of the numgeo source files (103 characters).
+BANNER = "=~~" * 33 + "=~=~"
+#: Start of the first line of a console log written by pynumgeo.
+CONSOLE_MARK = "pynumgeo "
+
+
+def _centre(text: str) -> str:
+    return " " * max((len(BANNER) - len(text)) // 2, 0) + text
+
+
+def input_file_header() -> list[str]:
+    """The comment lines at the top of every input file pynumgeo writes (each at most 106 characters)."""
+    lines = [
+        BANNER,
+        _centre("numgeo input file"),
+        _centre(f"Created with pynumgeo {__version__}, the Python API for numgeo by {AUTHOR}"),
+        _centre(f"Written for {NUMGEO_VERSION} (numgeo source {NUMGEO_SOURCE_COMMIT[:8]})"),
+        BANNER,
+    ]
+    return [f"** {ln}" for ln in lines]
+
+
+def console_header(command: list[str]) -> str:
+    """The first line of ``<job>.console.log``: who recorded it, and the command that started numgeo."""
+    return f"{CONSOLE_MARK}{__version__} (Python API for numgeo by {AUTHOR}): console output of {' '.join(command)}"
+
+
+def provenance() -> dict[str, str]:
+    """Program, version and author, plus the numgeo build pynumgeo was written for (JSON reports)."""
+    return {
+        "program": "pynumgeo",
+        "version": __version__,
+        "author": AUTHOR,
+        "numgeo_version": NUMGEO_VERSION,
+        "numgeo_source_commit": NUMGEO_SOURCE_COMMIT,
+    }

pynumgeo/_version.py

@@ -0,0 +1,28 @@
+# =~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~=~
+#                                                pynumgeo
+#                              Python API for the finite element code numgeo
+#                                     Copyright (C) 2026 Jan Machacek
+# =~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~=~
+#
+# Author: Jan Machacek
+#
+# pynumgeo writes, checks and runs numgeo input files and reads numgeo results. It follows the
+# development of numgeo: new developments in the numgeo source code are taken over into the API, and a
+# CI pipeline tests every change.
+#
+# License: BSD-3-Clause, see LICENSE.
+# =~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~~=~=~
+"""Version of pynumgeo and of the numgeo source it was derived from.
+
+pynumgeo follows the numgeo version: numgeo ``numgeo2026-v2`` corresponds to pynumgeo ``2026.2.x``
+(``.devN`` until it is released together with numgeo).
+"""
+
+__version__ = "2026.2.0.dev2"
+
+#: numgeo version string this pynumgeo was derived from (console banner of the solver).
+NUMGEO_VERSION = "numgeo2026-v2"
+#: numgeo-src commit the catalogue was generated from.
+NUMGEO_SOURCE_COMMIT = "834564ed77c2aa9ce5f6cdeabc03293c331520af"
+#: numgeo documentation commit the bundled reference pages come from.
+NUMGEO_DOCS_COMMIT = "eceee9749a1f0e47ff9aeedd50131707c4d7290a"