Skip to content

Public release refresh: v0.2.0 +ruff_clean #3

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
SOSOVSKI merged 1 commit into from
Aug 30, 2026
Merged

Public release refresh: v0.2.0 +ruff_clean #3

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
6 changes: 6 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,14 @@ ti_cache/
.publisher-worktrees/
.sesskey

# Public-release staging tree (curated copy pushed to CEmM2/MechDSL)
/dev/MechDSL/

# MkDocs build output
/site/

# Generated wiki / code-intelligence index (logic-loom / akms tooling)
.repo_wiki/

# comment-sweep working tree
/.comment-review/
133 changes: 56 additions & 77 deletions CHANGELOG.md
View file
Open in desktop

Large diffs are not rendered by default.

101 changes: 0 additions & 101 deletions CLAUDE.md
View file
Open in desktop

This file was deleted.

21 changes: 21 additions & 0 deletions LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2026 Shmuel Osovski

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.
80 changes: 33 additions & 47 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# MechDSL

[![CI](https://github.com/SOSOVSKI/MechDSL/actions/workflows/ci.yml/badge.svg)](https://github.com/SOSOVSKI/MechDSL/actions/workflows/ci.yml)
[![CI](https://github.com/CEmM2/MechDSL/actions/workflows/ci.yml/badge.svg)](https://github.com/CEmM2/MechDSL/actions/workflows/ci.yml)

> **Write your mechanics in LaTeX. Get a tested finite-element solver back.**
>
Expand Down Expand Up @@ -38,7 +38,7 @@ viscoplasticity, and Lemaitre continuum damage. Backends: Taichi (MVP-stable), M
Clone the repository, install the workspace with `uv`, and keep all commands under `uv run`:

```bash
git clone https://github.com/SOSOVSKI/MechDSL.git
git clone https://github.com/CEmM2/MechDSL.git
cd MechDSL
uv sync
```
Expand Down Expand Up @@ -79,10 +79,10 @@ print(bundle.content_hash())
localisation, einsum planning, and Taichi emission.

A runnable version of this canonical first-run example lives in
[`dev/examples/run_compile_latex.py`](dev/examples/run_compile_latex.py):
[`examples/run_compile_latex.py`](examples/run_compile_latex.py):

```bash
uv run python dev/examples/run_compile_latex.py
uv run python examples/run_compile_latex.py
```

### Programmatic API (advanced / testing aid)
Expand Down Expand Up @@ -143,19 +143,19 @@ print(bundle.element_ir_summary)
print(bundle.content_hash())
```

Runnable examples live in `dev/examples/`. The canonical LaTeX-first
Runnable examples live in `examples/`. The canonical LaTeX-first
script is listed first; the remaining scripts use the programmatic API
and are kept as advanced/testing aids:

```bash
uv run python dev/examples/run_compile_latex.py # canonical: LaTeX -> compile_latex
uv run python examples/run_compile_latex.py # canonical: LaTeX -> compile_latex
# Programmatic API examples (advanced / testing aids):
uv run python dev/examples/elastic_cantilever.py
uv run python dev/examples/plastic_uniaxial.py
uv run python dev/examples/cook_membrane.py
uv run python dev/examples/necking_bar.py
uv run python dev/examples/patch_test.py
uv run python dev/examples/run_pipeline.py # SVK + J2, write emitted Taichi source to disk
uv run python examples/elastic_cantilever.py
uv run python examples/plastic_uniaxial.py
uv run python examples/cook_membrane.py
uv run python examples/necking_bar.py
uv run python examples/patch_test.py
uv run python examples/run_pipeline.py # SVK + J2, write emitted Taichi source to disk
```

## Usage examples
Expand Down Expand Up @@ -256,9 +256,9 @@ uv run mkdocs serve # live preview at http://127.0.0.1:8000
uv run mkdocs build # static site into ./site
```

The authoritative design specs remain under [`dev/design_docs/`](dev/design_docs/)
(read-only); the `docs/` site is the friendly, task-oriented entry point that links into
them.
The authoritative design specs live in the internal `dev/design_docs/` tree of the
private development repository (read-only); the `docs/` site is the friendly,
task-oriented entry point.

## Architecture

Expand All @@ -273,16 +273,13 @@ Layer 5 Einsum IR contraction-family registry, plans, and JIT-budget-aware
Layer 6 Codegen deterministic source emission — Taichi (MVP-stable), MFEM (experimental, C++), MOOSE (experimental)
```

Design docs are authoritative and read-only:

- [`dev/design_docs/00-OVERVIEW.md`](dev/design_docs/00-OVERVIEW.md) for the document map
- [`dev/design_docs/01-ARCHITECTURE.md`](dev/design_docs/01-ARCHITECTURE.md) for pipeline structure
- [`dev/design_docs/08-VERIFICATION.md`](dev/design_docs/08-VERIFICATION.md) for the verification matrix
- [`dev/design_docs/PLAN-B.md`](dev/design_docs/PLAN-B.md) for post-MVP roadmap phases
The design-doc set (document map, pipeline structure, verification matrix, and the
post-MVP roadmap) is maintained in the internal `dev/design_docs/` tree of the
private development repository.

Per-layer architecture notes (live alongside the source they describe):

- [`packages/mechdsl-core/src/mechdsl/frontend/ARCHITECTURE.md`](packages/mechdsl-core/src/mechdsl/frontend/ARCHITECTURE.md) — Layer 1 split: NRPyLaTeX as parser of record (math grammar) vs the local adapter / normalizer / validator triad (`parser.py` + `directives.py` + `build_context` + `two_point.py`). Introduced by recovery-plan Phase 2 (R1.3).
- [`packages/mechdsl-core/src/mechdsl/frontend/ARCHITECTURE.md`](packages/mechdsl-core/src/mechdsl/frontend/ARCHITECTURE.md) — Layer 1 split: NRPyLaTeX as parser of record (math grammar) vs the local adapter / normalizer / validator triad (`parser.py` + `directives.py` + `build_context` + `two_point.py`).

### `mechdsl-core` ↔ `algo2code` integration

Expand All @@ -295,40 +292,33 @@ calls through. Concrete adapters (`ScipyCGSolver`, `CGSolver`, `PCGSolver`,
and `Algo2CodePCGSolver`) all satisfy that interface and are selected via
`mechdsl.solver.integration.select_linear_solver(...)`.

Recovery-plan Phase 6 landed the canonical PCG path (P6-1 through P6-3):
`Algo2CodePCGSolver` is a verbatim line-by-line Python translation of the
The canonical PCG path: `Algo2CodePCGSolver` is a verbatim line-by-line Python translation of the
LaTeX algpseudocode held in `algo2code.library.pcg.PCG_ALGORITHM_LATEX`,
which is the single source of truth for the PCG algorithm. It is opt-in
via `select_linear_solver("generated")` or
`newton_solve(..., linear_solver=...)` — the default remains
`ScipyCGSolver` until further validation. The `algo2code`-generated
radial-return constitutive seam (Plan A Phase A9) is deferred per
recovery plan §P6-4.
`ScipyCGSolver` until further validation.

The authoritative architecture reference for this seam is
[`dev/design_docs/11-ALGO2CODE.md`](dev/design_docs/11-ALGO2CODE.md)
(see §1.1 for the integration points and §2.5 for the canonical PCG
algpseudocode).
The authoritative architecture reference for this seam is the `11-ALGO2CODE`
design doc in the internal `dev/design_docs/` tree (§1.1 for the integration
points, §2.5 for the canonical PCG algpseudocode).

## Support tiers

MechDSL classifies every public feature into one of two support tiers (introduced by
[`dev/plans/recovery_plan_latex_contract.md`](dev/plans/recovery_plan_latex_contract.md)
Phase 1):
MechDSL classifies every public feature into one of two support tiers:

- **`MVP-stable`** — features supporting the canonical LaTeX-driven compile path:
Hex8 element, Total Lagrangian formulation, convected curvilinear coordinates,
St. Venant–Kirchhoff elasticity, J2 plasticity with power-law hardening, and the
Taichi backend. These are the only surfaces guaranteed to remain stable across
recovery work.
releases.
- **`experimental`** — features preserved in the tree but not part of the
canonical contract: MFEM and MOOSE codegen backends, explicit dynamics, non-MVP
materials (Mooney-Rivlin, Ogden, HGO, viscoplasticity, damage), and non-canonical
elements (Hex8-R, Hex20, Tet4, Tet10). These remain available for use but may
shift, lose tests, or become labeled deprecated as the recovery plan
progresses.
shift, lose tests, or become labeled deprecated as development progresses.

The recovery plan is additive: experimental scope is **not** deleted; it is
The tier split is additive: experimental scope is **not** deleted; it is
labeled so the canonical story is unambiguous.

### `mechdsl.integration` — MVP-stable machine-readable façade
Expand Down Expand Up @@ -367,27 +357,22 @@ vr = verify("patch_test", {"lam": 1.0, "mu": 1.0}) # pays the Taichi cost
print(vr["passed"])
```

Do not add entry points to this module without a plan-level decision; the
Do not add entry points to this module without a deliberate design decision; the
surface is a machine API contract, not a convenience library.

### Stability policy

The two tiers carry different commitments:

- **MVP-stable** features have a stable public API and a passing test suite
on every commit to `main`. Breaking changes require an entry in the
recovery plan (or a follow-up plan) and a tracker row that follows the
status vocabulary in [`dev/tracking/STATUS_LEGEND.md`](dev/tracking/STATUS_LEGEND.md).
on every commit to `main`. Breaking changes require a documented design decision and a
changelog entry.
- **experimental** features may evolve, lose tests, or be deprecated without
a release-note entry. They live behind module docstrings that say so
(see e.g. `packages/mechdsl-core/src/mechdsl/codegen/mfem_printer.py`).
Reaching for an experimental feature is supported, but only with the
understanding that the contract is provisional.

The full motivation, including the historical drift that led to this
policy, is in [`dev/plans/recovery_plan_latex_contract.md`](dev/plans/recovery_plan_latex_contract.md)
and [`dev/reviews/frontend_drift_history.md`](dev/reviews/frontend_drift_history.md).

## CI and Verification

The repository currently runs three CI tiers:
Expand All @@ -414,4 +399,5 @@ from `build_context()` through emitted Taichi source generation.
| B9 | Contraction-family registry + family-aware emission dispatch | Done |
| B10 | Verification benchmark suite (thick cylinder, necking, HGO strip) | Done |

See [`dev/design_docs/PLAN-B.md`](dev/design_docs/PLAN-B.md) for the full roadmap.
The full roadmap lives in the internal `dev/design_docs/` tree of the private
development repository.
Loading
Loading