yld.run 0.1.0__tar.gz

yld_run-0.1.0/.gitignore

@@ -0,0 +1,86 @@
+# Editors and OS files
+.DS_Store
+Thumbs.db
+*~
+*.swp
+*.swo
+.vscode/
+.idea/
+
+# CMake/build outputs
+#
+# Anchored to the repository root. This is the CMake build tree and the home for generated
+# experiment output (`build/experiments/<experiment>/<run>/`). Unanchored, this rule also
+# swallowed two things it was never meant to: `yld-ui/build/`, which Wails keeps as *source*
+# for its build assets, and curated evidence under `experiments/*/evidence/build/`.
+/build/
+# `examples/ben_cutting_slope.ipynb` writes the archives it demonstrates into `build/notebook`
+# relative to its own working directory, which is `examples/`.
+/examples/build/
+cmake-build-*/
+CMakeFiles/
+CMakeCache.txt
+cmake_install.cmake
+compile_commands.json
+CTestTestfile.cmake
+Testing/
+
+# C/C++ artifacts
+*.o
+*.obj
+*.a
+*.lib
+*.so
+*.dylib
+*.dll
+*.exe
+
+# Python artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.venv/
+venv/
+
+# Node/JavaScript
+node_modules/
+
+# Local reference repositories (not part of yld source)
+geomat/
+
+# Local research/output scratch
+*.log
+*.tmp
+*.bak
+#
+# Curated experiment evidence is the exception. Logs belong under `build/` during a run, but the
+# experiment tooling deliberately records some of them under `experiments/<key>/evidence/`, and a
+# `--evidence` copy lands there explicitly. Ignoring those loses part of the record.
+!experiments/*/evidence/*.log
+!experiments/*/evidence/**/*.log
+
+# yld-ui (Wails v3 host + Svelte SPA)
+#
+# The Wails project directory is `yld-ui/`. Its `build/` directory holds the Taskfiles, `config.yml`,
+# per-platform tasks and the app icon as *source*, so it is tracked; only what Wails generates there
+# is ignored. Paths below are taken from the Wails build assets, not guessed.
+/yld-ui/build/bin/
+/yld-ui/build/darwin/icons.icns
+/yld-ui/build/darwin/Assets.car
+/yld-ui/build/windows/icon.ico
+/yld-ui/build/ios/DerivedData/
+/yld-ui/build/ios/xcode/
+# The Vite output. Embedded into the Go binary at compile time by `//go:embed all:frontend/dist`,
+# and regenerated by `task build:frontend`, so it is never committed.
+/yld-ui/frontend/dist/
+# Playwright artefacts from the browser checks (`npm run e2e`). The specs and helpers under
+# `frontend/e2e/` are source and stay tracked.
+/yld-ui/frontend/test-results/
+/yld-ui/frontend/playwright-report/
+/yld-ui/frontend/blob-report/
+# There is deliberately no rule for `frontend/bindings/`: no native Wails bindings are ever
+# generated (see architecture/DECISIONS.md), so an accidental bindings directory must show up as
+# untracked noise rather than be silently ignored.

yld_run-0.1.0/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_run-0.1.0/PKG-INFO

@@ -0,0 +1,165 @@
+Metadata-Version: 2.5
+Name: yld.run
+Version: 0.1.0
+Summary: yld: programmatic problem authoring, solve requests and canonical `.yld` results.
+License: 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.
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.10
+Provides-Extra: view
+Requires-Dist: pyvista>=0.43; extra == 'view'
+Description-Content-Type: text/markdown
+
+# yld
+
+`yld` is pronounced “yield”.
+
+This is a private research project for a programmatic computational mechanics toolkit. The name
+reflects both mechanical yielding and the idea that the toolkit yields results.
+
+## Two packages
+
+`yld` is delivered as two independently installable Python packages, and the split is a licence and
+distribution boundary, not a convenience (`architecture/PLATFORM.md` §9):
+
+| package | licence | distributed | contents |
+|---|---|---|---|
+| **`yld`** | MIT | yes | problem authoring, materials and spatial fields as declarations, the solve-request document, the execution client, the archive reader and the PyVista viewer. Pure Python: no native module, no mandatory dependency. |
+| **`yld_core`** | proprietary | **no** | constitutive binding, meshing, assembly, the conic solve, adaptation, independent verification, field evaluation and archive writing, through one compiled extension (`yld_core._native`). |
+
+A problem is authored and a solve is requested with `yld` alone; a numerical installation is
+configured explicitly and is the only part that executes anything:
+
+```python
+import yld, yld_core
+yld.use_executor(yld_core.NativeExecutor())          # explicit; no discovery, no environment variables
+
+result = yld.solve(problem, yld.FELA_LB_Solver(order=3),
+                   target=yld.Target.strength(), adapt=[yld.adapt.p(order=3)])
+result.multiplier, result.verified                   # from the canonical `.yld` archive
+result.save("analysis.yld"); result.show("cohesion")
+```
+
+`solve()` always submits a canonical `yld.solve-request/1` document to the configured executor and
+always returns the same archive-backed result, so a local run and a service run are indistinguishable
+to the caller.  With nothing configured it raises `yld.NoExecutorError` rather than choosing a
+backend.
+
+Build both artefacts (the private one only for a local numerical installation):
+
+```bash
+tools/yld-package public   --out-dir build/dist   # yld-<version>-py3-none-any.whl + sdist
+tools/yld-package private  --out-dir build/dist   # yld_core-<version>-<platform>.whl
+```
+
+`tests/python/distribution_content_tests.py` builds and inspects the public artefacts (a positive
+allowlist: no C++ sources, no native binaries, no experiments, no private modules), and
+`tests/python/distribution_install_tests.py` installs each into a clean environment and checks what
+it can and cannot do.
+
+## Default production build
+
+Use the CMake preset so build artefacts stay under `build/dev`. The `dev` preset is intentionally the default production-solver build: `Release`, Python enabled, experiments disabled. CMake obtains Eigen 3.4.0 and Catch2 v3.8.1 through pinned `FetchContent`; no system Eigen/Catch2 path is required for the normal development build.
+
+System prerequisites: a C++20 compiler, CMake ≥ 3.20, Ninja or Make, **clang-format 21.1.8** (the pinned
+version CI installs, because `code_format` is a test and its verdict must not depend on the image), Python 3 with development headers and `uv` (the test suite runs Python oracles
+through `uv`), a Rust toolchain (Clarabel.cpp builds its Rust backend), and **header-only Boost**
+(`libboost-dev`) for the exact geometric predicates in `yld_mesh`.
+
+Canonical verification goes through the shared build/test wrappers, which bound memory on the
+workstation (see `AGENTS.md`, "Build discipline"):
+
+```bash
+tools/yld-build --preset dev
+tools/yld-test  --preset dev
+```
+
+For a stale or missing configure, refresh the cache first — `cmake --fresh --preset dev` — then
+build and test through the wrappers again.
+
+If dependency discovery or cache state gets stale, refresh the cache with `cmake --fresh --preset dev` rather than manually deleting the build tree.
+
+Debug builds are opt-in only:
+
+```bash
+cmake --fresh --preset debug
+tools/yld-build --preset debug
+tools/yld-test  --preset debug
+```
+
+The compiled extension is written **inside the private package** (`yld_core/_native*.so`) rather than
+into a build directory, because that is where an extension module has to be to be importable: a
+package's `__path__` is its own directory.  One checkout therefore has one native extension — rebuild
+for the preset you are testing.  No `PYTHONPATH` entry is needed to import it.
+
+Do not use the debug preset for solver performance, FELA regression timing, or ordinary commit validation.
+
+## Examples
+
+`examples/ben_cutting_slope.ipynb` is an executable introduction to slope limit analysis through
+the public Python API: gravity and strength-reduction targets, Bernstein lower and upper bounds
+with independent verification, adaptation recipes, and deterministic and random spatial strength
+fields. See `examples/README.md` for launch instructions.
+
+## Testing
+
+Routine development tests only the area a change touches. Catch2 tags and `ctest -R` are the
+normal entry points:
+
+```bash
+# one whole test binary
+./build/dev/tests/yld_mechanics_tests
+
+# a Catch2 tag, e.g. the model just changed
+./build/dev/tests/yld_mechanics_tests "[mohr_coulomb]"
+
+# ctest tests selected by name
+tools/yld-test --preset dev -R "mohr_coulomb|code_format"
+
+# the Python suite only
+tools/yld-test --preset dev -R "^python_|^bezier_member_vtk$|^parameter_archive_visualisation$"
+```
+
+The complete `tools/yld-test --preset dev` suite includes MFEM/Python integration tests and takes
+about four minutes. It is **not** the commit gate: it runs in CI (`.github/workflows/ci.yml`) on every
+push to `main` and on pull requests, against the production Release solver path.
+
+The local commit hook is deliberately fast, because a slow hook teaches people to use
+`--no-verify`:
+
+```bash
+git config core.hooksPath .githooks   # one-time setup
+```
+
+`.githooks/pre-commit` checks only what needs the working tree or is commit-specific —
+`clang-format` on staged C++ files, a 5 MB per-file size guard against bulk artefacts, validation of
+any staged experiment record, and a private-key scan. Bypass for work-in-progress commits with
+`YLD_SKIP_HOOKS=1 git commit ...`.
+
+Run the full suite locally before a substantial push, or when CI is unavailable:
+
+```bash
+tools/yld-test --preset dev
+```

yld_run-0.1.0/README.md

@@ -0,0 +1,131 @@
+# yld
+
+`yld` is pronounced “yield”.
+
+This is a private research project for a programmatic computational mechanics toolkit. The name
+reflects both mechanical yielding and the idea that the toolkit yields results.
+
+## Two packages
+
+`yld` is delivered as two independently installable Python packages, and the split is a licence and
+distribution boundary, not a convenience (`architecture/PLATFORM.md` §9):
+
+| package | licence | distributed | contents |
+|---|---|---|---|
+| **`yld`** | MIT | yes | problem authoring, materials and spatial fields as declarations, the solve-request document, the execution client, the archive reader and the PyVista viewer. Pure Python: no native module, no mandatory dependency. |
+| **`yld_core`** | proprietary | **no** | constitutive binding, meshing, assembly, the conic solve, adaptation, independent verification, field evaluation and archive writing, through one compiled extension (`yld_core._native`). |
+
+A problem is authored and a solve is requested with `yld` alone; a numerical installation is
+configured explicitly and is the only part that executes anything:
+
+```python
+import yld, yld_core
+yld.use_executor(yld_core.NativeExecutor())          # explicit; no discovery, no environment variables
+
+result = yld.solve(problem, yld.FELA_LB_Solver(order=3),
+                   target=yld.Target.strength(), adapt=[yld.adapt.p(order=3)])
+result.multiplier, result.verified                   # from the canonical `.yld` archive
+result.save("analysis.yld"); result.show("cohesion")
+```
+
+`solve()` always submits a canonical `yld.solve-request/1` document to the configured executor and
+always returns the same archive-backed result, so a local run and a service run are indistinguishable
+to the caller.  With nothing configured it raises `yld.NoExecutorError` rather than choosing a
+backend.
+
+Build both artefacts (the private one only for a local numerical installation):
+
+```bash
+tools/yld-package public   --out-dir build/dist   # yld-<version>-py3-none-any.whl + sdist
+tools/yld-package private  --out-dir build/dist   # yld_core-<version>-<platform>.whl
+```
+
+`tests/python/distribution_content_tests.py` builds and inspects the public artefacts (a positive
+allowlist: no C++ sources, no native binaries, no experiments, no private modules), and
+`tests/python/distribution_install_tests.py` installs each into a clean environment and checks what
+it can and cannot do.
+
+## Default production build
+
+Use the CMake preset so build artefacts stay under `build/dev`. The `dev` preset is intentionally the default production-solver build: `Release`, Python enabled, experiments disabled. CMake obtains Eigen 3.4.0 and Catch2 v3.8.1 through pinned `FetchContent`; no system Eigen/Catch2 path is required for the normal development build.
+
+System prerequisites: a C++20 compiler, CMake ≥ 3.20, Ninja or Make, **clang-format 21.1.8** (the pinned
+version CI installs, because `code_format` is a test and its verdict must not depend on the image), Python 3 with development headers and `uv` (the test suite runs Python oracles
+through `uv`), a Rust toolchain (Clarabel.cpp builds its Rust backend), and **header-only Boost**
+(`libboost-dev`) for the exact geometric predicates in `yld_mesh`.
+
+Canonical verification goes through the shared build/test wrappers, which bound memory on the
+workstation (see `AGENTS.md`, "Build discipline"):
+
+```bash
+tools/yld-build --preset dev
+tools/yld-test  --preset dev
+```
+
+For a stale or missing configure, refresh the cache first — `cmake --fresh --preset dev` — then
+build and test through the wrappers again.
+
+If dependency discovery or cache state gets stale, refresh the cache with `cmake --fresh --preset dev` rather than manually deleting the build tree.
+
+Debug builds are opt-in only:
+
+```bash
+cmake --fresh --preset debug
+tools/yld-build --preset debug
+tools/yld-test  --preset debug
+```
+
+The compiled extension is written **inside the private package** (`yld_core/_native*.so`) rather than
+into a build directory, because that is where an extension module has to be to be importable: a
+package's `__path__` is its own directory.  One checkout therefore has one native extension — rebuild
+for the preset you are testing.  No `PYTHONPATH` entry is needed to import it.
+
+Do not use the debug preset for solver performance, FELA regression timing, or ordinary commit validation.
+
+## Examples
+
+`examples/ben_cutting_slope.ipynb` is an executable introduction to slope limit analysis through
+the public Python API: gravity and strength-reduction targets, Bernstein lower and upper bounds
+with independent verification, adaptation recipes, and deterministic and random spatial strength
+fields. See `examples/README.md` for launch instructions.
+
+## Testing
+
+Routine development tests only the area a change touches. Catch2 tags and `ctest -R` are the
+normal entry points:
+
+```bash
+# one whole test binary
+./build/dev/tests/yld_mechanics_tests
+
+# a Catch2 tag, e.g. the model just changed
+./build/dev/tests/yld_mechanics_tests "[mohr_coulomb]"
+
+# ctest tests selected by name
+tools/yld-test --preset dev -R "mohr_coulomb|code_format"
+
+# the Python suite only
+tools/yld-test --preset dev -R "^python_|^bezier_member_vtk$|^parameter_archive_visualisation$"
+```
+
+The complete `tools/yld-test --preset dev` suite includes MFEM/Python integration tests and takes
+about four minutes. It is **not** the commit gate: it runs in CI (`.github/workflows/ci.yml`) on every
+push to `main` and on pull requests, against the production Release solver path.
+
+The local commit hook is deliberately fast, because a slow hook teaches people to use
+`--no-verify`:
+
+```bash
+git config core.hooksPath .githooks   # one-time setup
+```
+
+`.githooks/pre-commit` checks only what needs the working tree or is commit-specific —
+`clang-format` on staged C++ files, a 5 MB per-file size guard against bulk artefacts, validation of
+any staged experiment record, and a private-key scan. Bypass for work-in-progress commits with
+`YLD_SKIP_HOOKS=1 git commit ...`.
+
+Run the full suite locally before a substantial push, or when CI is unavailable:
+
+```bash
+tools/yld-test --preset dev
+```

yld_run-0.1.0/pyproject.toml

@@ -0,0 +1,59 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+# The distribution name and the import namespace are different things here, deliberately: the
+# package is published as `yld.run`, while `import yld` stays what it has always been.  There is no
+# alias package and no second import name.
+name = "yld.run"
+version = "0.1.0"
+description = "yld: programmatic problem authoring, solve requests and canonical `.yld` results."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+# The public distribution is pure Python by construction: authoring, the solve-request document, the
+# archive reader and the PyVista viewer.  Native execution lives in the separately distributed
+# `yld-core` package, which is never a dependency of this one.
+dependencies = []
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+
+[project.optional-dependencies]
+# Visualisation only: `ArchivedResult.show()` needs PyVista.  Authoring, encoding, decoding and
+# archive reading work without it.
+view = ["pyvista>=0.43"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["yld"]
+
+# --------------------------------------------------------------------------------------------------
+# The public distribution is a positive allowlist, not an exclusion list.
+#
+# The repository also holds the proprietary native core, internal experiments, agent configuration
+# and research notes.  An sdist built from the repository root used to include all of it -- including
+# the C++ source tree -- because that is the hatchling default.  Only what is listed here ships, so a
+# new file elsewhere in the repository cannot leak into a public artefact by being forgotten.
+#
+# `tests/python/distribution_content_tests.py` builds both artefacts and asserts this list.
+# --------------------------------------------------------------------------------------------------
+[tool.hatch.build.targets.sdist]
+only-include = [
+    "yld",
+    "pyproject.toml",
+    "README.md",
+    "LICENSE",
+]
+exclude = [
+    "**/__pycache__",
+    "**/*.py[cod]",
+]
+# Hatchling force-includes the VCS exclusion file into every sdist, and a force-include wins over
+# `exclude`.  `.gitignore` therefore appears in the sdist; it is a public repository file and
+# `distribution_content_tests.py` pins it to this repository's own copy.
+
+[tool.hatch.build.targets.wheel.force-include]
+"LICENSE" = "yld/LICENSE"

yld_run-0.1.0/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",
+]