yld.run 0.1.0__py3-none-any.whl

yld/LICENSE

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

yld/__init__.py

@@ -0,0 +1,84 @@
+"""The public `yld` package: authoring, solve requests, execution client and archive results.
+
+This package is **pure Python by construction**.  It states problems, materials, spatial fields,
+targets and adaptation recipes; encodes the canonical solve request; submits it to an explicitly
+configured executor; and reads the canonical `.yld` archive the executor returns, including the
+material-parameter fields the analysis actually assembled.  It imports no native module, has no
+private dependency, and needs no compiler, CMake or nightly build variable to install or run.
+
+Numerical execution — meshing, assembly, the conic solve, adaptation, independent verification and
+archive writing — lives in the proprietary `yld_core` package, which is configured explicitly:
+
+    import yld, yld_core
+    yld.use_executor(yld_core.NativeExecutor())
+
+    problem = yld.Problem("prandtl")
+    ... author ...
+
+    result = yld.solve(problem, yld.FELA_LB_Solver(points=1200, order=3),
+                       target=yld.Target.strength(), adapt=[yld.adapt.p(order=3)])
+    result.multiplier, result.verified
+
+Without a configured executor, `yld.solve()` refuses with `yld.NoExecutorError`; there is no default
+executor, no discovery and no environment-variable backend switching.
+"""
+
+from __future__ import annotations
+
+from . import adapt, archive, bounds, edit, outputs, solve_request
+from .archive import ArchivedResult, open_yld
+from .execution import Executor, NoExecutorError, solve, use_executor
+from .outputs import Output
+from .problem import (
+    BondedInterface,
+    ConstantField,
+    Field,
+    Interface,
+    LinearField,
+    Map,
+    MeshFeature,
+    MohrCoulomb,
+    Problem,
+    ProblemLoad,
+    Random,
+    RigidBody,
+    SmoothInterface,
+    SplineField,
+    Tresca,
+)
+from .solvers import FELA_LB_Solver, FELA_UB_Solver
+from .targets import Target
+
+__all__ = [
+    "ArchivedResult",
+    "BondedInterface",
+    "ConstantField",
+    "Executor",
+    "FELA_LB_Solver",
+    "FELA_UB_Solver",
+    "Field",
+    "Interface",
+    "LinearField",
+    "Map",
+    "MeshFeature",
+    "MohrCoulomb",
+    "NoExecutorError",
+    "Output",
+    "Problem",
+    "ProblemLoad",
+    "Random",
+    "RigidBody",
+    "SmoothInterface",
+    "SplineField",
+    "Target",
+    "Tresca",
+    "adapt",
+    "archive",
+    "bounds",
+    "edit",
+    "open_yld",
+    "outputs",
+    "solve",
+    "solve_request",
+    "use_executor",
+]

yld/adapt.py

@@ -0,0 +1,209 @@
+"""Typed adaptation recipe operations for the yld solver machinery.
+
+The recipe is an ordinary Python list; Python is the sequence language.  Build
+recipes with list literals, loops and any other Python control flow::
+
+    from yld.adapt import p, h, r
+
+    recipe = [p(order=2)]
+    for elements in (200, 400, 800):
+        recipe += [h(elements=elements), r()]
+    recipe += [p(order=3), r(tol=1e-4)]
+
+Each helper returns a typed, declarative operation: a value, not a compiled object.  It states the
+operation and the numbers the author wrote, and nothing else — the numerical executor translates the
+declarations into its own operations when it runs, so a client can author a recipe without any
+compiled extension and a recipe is part of a solve request like every other declaration.
+
+    p(*, order)                       set the polynomial order for subsequent solves
+    h(*, elements=None)               one h adaptation from the current solution
+    r(*, iterations=None, tol=None)   r adaptation toward a plateau
+
+There is no persistent target-element or r-control state.  `elements` belongs
+to the `h()` that consumes it, and `iterations`/`tol` belong to the `r()` that
+consumes them, so an operation never inherits an earlier one's numbers.  In
+particular ``h()`` targets the current mesh element count, resolved when the
+step executes:
+
+    [h(elements=400), r(), h()]
+
+means h toward ~400, r to plateau, then h again toward the post-r element
+count, not toward 400 again.
+
+`describe()` is the canonical serialised form of a recipe.  It is what a solve request carries and
+what a numerical executor translates back into its own operations.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import IntEnum
+from typing import Any, Iterable
+
+__all__ = [
+    "AdaptOp",
+    "AdaptOpKind",
+    "describe",
+    "from_description",
+    "h",
+    "p",
+    "r",
+]
+
+
+class AdaptOpKind(IntEnum):
+    """The three adaptation operations.  The values are the recipe's serialised op identity."""
+
+    SetOrder = 0
+    HAdapt = 1
+    RAdaptToPlateau = 2
+
+
+#: The canonical serialised operation name, by kind.
+_OP_BY_VALUE = {0: "p", 1: "h", 2: "r"}
+_KIND_BY_NAME = {name: AdaptOpKind(value) for value, name in _OP_BY_VALUE.items()}
+
+
+@dataclass(frozen=True)
+class AdaptOp:
+    """One declarative adaptation operation.
+
+    A value, not a command: it is compared, printed, described and transported as ordinary data.  The
+    executor decides what the operation does to its own mesh.
+    """
+
+    kind: AdaptOpKind
+    order: int = 1
+    elements: int | None = None
+    iterations: int | None = None
+    tol: float | None = None
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "kind", AdaptOpKind(self.kind))
+
+    @property
+    def name(self) -> str:
+        """The operation's canonical serialised name: `p`, `h` or `r`."""
+
+        return _OP_BY_VALUE[int(self.kind)]
+
+
+def _op(kind: AdaptOpKind, *, order: int = 1, elements=None, iterations=None, tol=None) -> AdaptOp:
+    return AdaptOp(
+        kind=kind, order=int(order), elements=elements, iterations=iterations, tol=tol
+    )
+
+
+def p(*, order: int):
+    """Set the polynomial order used by subsequent solves.
+
+    ``order`` is keyword-only, so ``p(3)`` is a ``TypeError``.  Changing the
+    order invalidates the current answer, but does not itself force a solve.
+    """
+    if int(order) < 1:
+        raise ValueError("p(order=...) needs order >= 1")
+    return _op(AdaptOpKind.SetOrder, order=int(order))
+
+
+def h(*, elements: int | None = None):
+    """Perform one h adaptation from the current solution.
+
+    ``elements`` is keyword-only.  When it is omitted the step targets the
+    current mesh element count, resolved at execution time; when it is given it
+    targets approximately that many elements for this step only.
+    """
+    if elements is not None and int(elements) < 1:
+        raise ValueError("h(elements=...) needs elements >= 1")
+    return _op(AdaptOpKind.HAdapt, elements=None if elements is None else int(elements))
+
+
+def r(*, iterations: int | None = None, tol: float | None = None):
+    """Run r adaptation toward a plateau.
+
+    ``iterations`` caps the number of outer r iterations and ``tol`` is the
+    relative objective improvement below which the plateau criterion is
+    satisfied; both are keyword-only and optional.  An ``iterations`` budget is
+    a maximum: the step may stop earlier when it has already converged.
+    """
+    if iterations is not None and int(iterations) < 1:
+        raise ValueError("r(iterations=...) needs iterations >= 1")
+    if tol is not None and not float(tol) > 0.0:
+        raise ValueError("r(tol=...) needs tol > 0")
+    return _op(
+        AdaptOpKind.RAdaptToPlateau,
+        iterations=None if iterations is None else int(iterations),
+        tol=None if tol is None else float(tol),
+    )
+
+
+def describe(recipe: Iterable[Any]) -> list[dict[str, Any]]:
+    """Canonical serialisable form of a recipe.
+
+    One entry per operation, in order, carrying only the numbers that operation states.  An omitted
+    optional number is absent rather than null, so ``h()`` and ``h(elements=None)`` describe
+    identically — they are the same operation.
+    """
+
+    described: list[dict[str, Any]] = []
+    for operation in recipe:
+        if not isinstance(operation, AdaptOp):
+            raise TypeError(
+                f"{operation!r} is not an adaptation operation; build a recipe from "
+                "yld.adapt.p(), h() and r()"
+            )
+        entry: dict[str, Any] = {"op": operation.name}
+        if operation.kind == AdaptOpKind.SetOrder:
+            entry["order"] = int(operation.order)
+        elif operation.kind == AdaptOpKind.HAdapt and operation.elements is not None:
+            entry["elements"] = int(operation.elements)
+        elif operation.kind == AdaptOpKind.RAdaptToPlateau:
+            if operation.iterations is not None:
+                entry["iterations"] = int(operation.iterations)
+            if operation.tol is not None:
+                entry["tol"] = float(operation.tol)
+        described.append(entry)
+    return described
+
+
+def from_description(described: Iterable[Any]) -> list[AdaptOp]:
+    """The recipe a `describe()` list states, rebuilt as ordinary declarations.
+
+    This is the inverse of :func:`describe` and the only place a serialised recipe becomes an
+    authorable one.  An unknown operation name or an unstated required number is refused by name.
+    """
+
+    recipe: list[AdaptOp] = []
+    for index, raw in enumerate(described):
+        if not isinstance(raw, dict):
+            raise ValueError(f"adapt[{index}]: expected an object, got {type(raw).__name__}")
+        name = raw.get("op")
+        if name not in _KIND_BY_NAME:
+            raise ValueError(
+                f"adapt[{index}].op: {name!r} is not an adaptation operation; the known operations "
+                f"are {', '.join(sorted(_KIND_BY_NAME))}"
+            )
+        kind = _KIND_BY_NAME[name]
+        known = {"op", "order", "elements", "iterations", "tol"}
+        unknown = sorted(set(raw) - known)
+        if unknown:
+            raise ValueError(f"adapt[{index}]: {name} states no member {unknown}")
+        try:
+            if kind == AdaptOpKind.SetOrder:
+                recipe.append(p(order=int(raw["order"])))
+            elif kind == AdaptOpKind.HAdapt:
+                elements = raw.get("elements")
+                recipe.append(h(elements=None if elements is None else int(elements)))
+            else:
+                iterations = raw.get("iterations")
+                tol = raw.get("tol")
+                recipe.append(
+                    r(
+                        iterations=None if iterations is None else int(iterations),
+                        tol=None if tol is None else float(tol),
+                    )
+                )
+        except KeyError as error:
+            raise ValueError(f"adapt[{index}]: {name} needs {error.args[0]!r}") from None
+        except (TypeError, ValueError) as error:
+            raise ValueError(f"adapt[{index}]: {error}") from None
+    return recipe

yld/archive/__init__.py

@@ -0,0 +1,36 @@
+"""The `.yld` archive: one container, one manifest, native numerical members.
+
+`architecture/YLD_ARCHIVE.md` is the specification.  What the **public** package holds is everything
+needed to read an archive without executing anything:
+
+* `container` -- the zip, the append-only member table and canonical JSON (one writer);
+* `reader` -- `open_yld`: validate, then report, in pure Python and without solving anything;
+* `visualisation` -- one PyVista scene builder for archived Bernstein fields.
+
+There is one archive format, `format_version` 1: the shared container, the manifest that describes
+it, and canonical result records.  The producers are private, because producing one requires the
+numerical side: `yld_core.archive_writer` writes a Bernstein FELA analysis, and
+`yld_core.FeaResult.save` writes an incremental history into the same layout.
+"""
+
+from .container import (
+    FORMAT_VERSION,
+    MANIFEST,
+    PROBLEM_SOURCE,
+    SOLVE_REQUEST,
+    ArchiveError,
+    ArchiveWriter,
+)
+from .reader import ArchivedMember, ArchivedResult, open_yld
+
+__all__ = [
+    "ArchiveError",
+    "ArchiveWriter",
+    "ArchivedMember",
+    "ArchivedResult",
+    "FORMAT_VERSION",
+    "MANIFEST",
+    "PROBLEM_SOURCE",
+    "SOLVE_REQUEST",
+    "open_yld",
+]

yld/archive/container.py

@@ -0,0 +1,208 @@
+"""The `.yld` container: one zip, an append-only member table and canonical metadata.
+
+`architecture/YLD_ARCHIVE.md` fixes the container.  What lives here is the part every producer
+shares, so there is exactly one implementation of it:
+
+* member names are fixed by the specification, and each member is written **once** (an archive is
+  evidence, so it is never rewritten in place);
+* every member's bytes are hashed as they are written, in one pass, so the manifest's
+  `(name, sha256, bytes)` table describes exactly the bytes the container holds;
+* the container records no wall-clock time -- two writings of one result have to be the same bytes
+  (Q30) -- so every member carries the same fixed timestamp;
+* publication is atomic (write `*.partial`, then replace), and an existing archive is refused
+  rather than overwritten.
+
+Format version 1 is the single supported layout: `manifest.json`, the structured solve request, the
+optional authored script, and one member per accepted result and native degree.  A reader supports
+exactly that version; a writer states it once.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import json
+import math
+import os
+from pathlib import Path
+import re
+import zipfile
+
+#: The `.yld` archive format this build writes, and the only one it reads.  One integer, as
+#: `architecture/YLD_ARCHIVE.md` §10 states: version 1 is the initial contract, and a reader refuses
+#: any other number, naming what it found.  An incompatible change to the layout is a new number and
+#: a deliberate break, never a second layout behind the same one.
+FORMAT_VERSION = 1
+
+MANIFEST = "manifest.json"
+SOLVE_REQUEST = "solve-request.json"
+PROBLEM_SOURCE = "problem.py"
+RESULTS = "results"
+#: `results/step-NNNN.vtu`: one member per committed FEA increment.  The member name is the
+#: producer's; what the archive *means* is stated by its result records, not by a name.
+INCREMENT_MEMBER = RESULTS + "/step-{:04d}.vtu"
+#: `results/result-NNNN-orderK.vtu`: one member per accepted FELA result **and native degree**.
+RESULT_MEMBER = RESULTS + "/result-{:04d}-order{}.vtu"
+#: `results/result-NNNN-parameter-<name>-aA-orderK.vtu`: one member per accepted result's
+#: material-parameter field, per parameter, **material attribute** and degree.  Its cells are the
+#: exact polynomial pieces of the strength field the assembly consumed, not a resampled plot of it.
+#: The attribute is part of the name because two materials may declare the same parameter name.
+PARAMETER_MEMBER = RESULTS + "/result-{:04d}-parameter-{}-a{}-order{}.vtu"
+
+#: The DOS epoch.  A fixed timestamp is what makes two writings of one result the same bytes.
+TIMESTAMP = (1980, 1, 1, 0, 0, 0)
+#: A block size for streaming a member into the container without holding it in memory.
+BLOCK = 1 << 20
+#: How much of a member's XML header is scanned for its declared arrays.  The header of an
+#: appended-raw `.vtu` is a few kilobytes; the limit only bounds the scan.
+HEADER_LIMIT = 1 << 20
+#: A named `Float64` array, read from a member's own XML header: the quantities it carries are what
+#: the member holds, never what the writer meant to hold.
+ARRAY_NAME = re.compile(rb'<DataArray type="Float64" Name="([^"]+)"')
+
+
+def finite(value) -> float | None:
+    """A JSON-safe reading of a measured number: `null` where the number does not exist.
+
+    `json.dumps(..., allow_nan=False)` is deliberate -- a bare `NaN` is not valid JSON and an archive
+    that cannot be parsed is not evidence -- so a non-finite measurement is recorded as `null`, never
+    as a fabricated zero.
+    """
+
+    try:
+        number = float(value)
+    except (TypeError, ValueError):
+        return None
+    return number if math.isfinite(number) else None
+
+
+def member_arrays(header: bytes) -> list[str]:
+    """The named `Float64` arrays a member declares, in emission order.
+
+    The mesh's own arrays are not quantities: `Points` carries no name and
+    `connectivity`/`offsets`/`types` are integer types, so the member's structure never appears in
+    the inventory as data.
+    """
+
+    return sorted({found.decode("utf-8") for found in ARRAY_NAME.findall(header)})
+
+
+def add_member(archive: zipfile.ZipFile, name: str, blocks, header: bytearray | None = None) -> dict:
+    """Write one member once, and describe exactly the bytes that were stored.
+
+    The digest and the length are computed over the same bytes the container holds -- one pass, one
+    encoding -- so the member table cannot describe something other than the member.  `header`, when
+    given, gathers the member's XML prefix for the caller's quantity inventory.
+    """
+
+    info = zipfile.ZipInfo(name, date_time=TIMESTAMP)
+    info.compress_type = zipfile.ZIP_DEFLATED
+    info.external_attr = 0o644 << 16
+    digest = hashlib.sha256()
+    length = 0
+    with archive.open(info, "w") as member:
+        for block in blocks:
+            if header is not None and len(header) < HEADER_LIMIT:
+                header += block[: HEADER_LIMIT - len(header)]
+            digest.update(block)
+            member.write(block)
+            length += len(block)
+    return {"name": name, "sha256": digest.hexdigest(), "bytes": length}
+
+
+def file_blocks(path: Path, header: bytearray | None = None):
+    """A file's bytes in blocks, gathering the XML header its arrays are read from."""
+
+    with open(path, "rb") as handle:
+        while True:
+            block = handle.read(BLOCK)
+            if not block:
+                return
+            if header is not None and len(header) < HEADER_LIMIT:
+                header += block[: HEADER_LIMIT - len(header)]
+            yield block
+
+
+def canonical_json(document: dict) -> str:
+    """The container's one JSON encoding: sorted keys, two-space indent, no NaN, a final newline."""
+
+    return json.dumps(document, sort_keys=True, indent=2, ensure_ascii=True, allow_nan=False) + "\n"
+
+
+class ArchiveError(ValueError):
+    """An archive cannot be written or read as the specification states it."""
+
+
+class ArchiveWriter:
+    """One `.yld` archive, published atomically -- to a file, or to memory.
+
+    `target` must not exist: an archive is written once.  Members are added in the order the
+    specification puts them (the problem record, then results), and `publish` appends the manifest
+    last, so the manifest can describe every other member without describing itself.
+
+    With `target=None` the archive is built in memory and `publish` leaves its bytes in `data`.
+    That is how an executor returns "archive bytes": a service hands the same bytes to a response
+    body, and no temporary file stands between a result and its reader.
+    """
+
+    def __init__(self, target: Path | None):
+        self._table: list[dict] = []
+        self._published = False
+        if target is None:
+            self.target = None
+            self._partial = None
+            self._buffer = io.BytesIO()
+            self._archive = zipfile.ZipFile(self._buffer, "w")
+            self.data: bytes | None = None
+            return
+        self.data = None
+        self.target = Path(target)
+        if self.target.exists():
+            raise FileExistsError(
+                f"{self.target} already exists; a `.yld` archive is written once, because its "
+                f"members are append-only and an existing archive is evidence rather than a draft"
+            )
+        self._partial = self.target.with_name(self.target.name + ".partial")
+        self._buffer = None
+        self._archive = zipfile.ZipFile(self._partial, "w")
+
+    def __enter__(self) -> "ArchiveWriter":
+        return self
+
+    def __exit__(self, exc_type, exc, traceback) -> None:
+        self.close(published=exc_type is None and self._published)
+
+    def add(self, name: str, blocks, header: bytearray | None = None) -> dict:
+        entry = add_member(self._archive, name, blocks, header)
+        self._table.append(entry)
+        return entry
+
+    def add_bytes(self, name: str, data: bytes, header: bytearray | None = None) -> dict:
+        return self.add(name, [data], header)
+
+    def publish(self, manifest: dict) -> None:
+        """Write `manifest.json` last, with the member table it describes."""
+
+        document = dict(manifest)
+        # Sorted by member name; the manifest cannot list itself, because a table cannot hold its
+        # own digest.
+        document["members"] = sorted(self._table, key=lambda entry: entry["name"])
+        self.add_bytes(MANIFEST, canonical_json(document).encode("utf-8"))
+        self._published = True
+        self.close(published=True)
+
+    def close(self, *, published: bool) -> None:
+        if self._archive is None:
+            return
+        self._archive.close()
+        self._archive = None
+        if self._buffer is not None:
+            if published:
+                self.data = self._buffer.getvalue()
+            self._buffer.close()
+            self._buffer = None
+            return
+        if published:
+            os.replace(self._partial, self.target)
+        elif self._partial.exists():
+            self._partial.unlink()