allamaprabhuani · Oct 8, 2026 · Oct 8, 2026
@@ -56,3 +56,11 @@ contract should be committed.
 - **No Development Slang**: Do not use release or development slang such as "ships with", "hack", "epic", or "fix this later".
 - **No Process-Derived Claims**: Do not use issue numbers, pull-request numbers, ticket identifiers, or private workflow phases as scientific explanation. Describe the implemented behavior and evidence directly.
 - **No Emoticons**: Do not use emojis or emoticons in the documentation or source code.
+
+## Trajectory storage
+
+Default new trajectory/dataset writers and sample configurations to HDF5
+(`training_data.h5`; `trajectory_format: h5`). Zarr or both formats must be
+explicitly requested, never selected as a silent fallback. Preserve existing
+Zarr readers/results. Apply the same convention to notebooks and documentation;
+see `docs/user_guide/example_contract.md`.
@@ -27,3 +27,11 @@ PYTHONPATH=src python -m phast run <config.yaml> --validate-only
 ```
 
 - When changing solver code, preserve autograd, dtype, and device semantics.
+
+## Trajectory storage
+
+- Use HDF5 (`training_data.h5`, `trajectory_format: h5`) by default for new
+  trajectory/dataset writers, configurations, notebooks, and documentation.
+- Zarr requires explicit selection; do not add automatic Zarr fallbacks.
+- Preserve existing Zarr readers and artifacts. Follow
+  `docs/user_guide/example_contract.md` for output conventions.
@@ -41,7 +41,7 @@ the implementation.
 
 - [ ] No raw HPC result bundles, unpublished meeting material, or heavy generated
       media were added to git.
-- [ ] New trajectory output is Zarr-first, or legacy H5 use is explicitly
-      compatibility-only.
+- [ ] New trajectory output defaults to HDF5 (`training_data.h5`); any Zarr
+      output is explicitly requested and documented, not an automatic fallback.
 - [ ] New/changed benchmark configs are documented in the relevant README or
       contract.
@@ -39,6 +39,12 @@ jobs:
         run: |
           python -m phast run examples/dynamic/B2_kalthoff_winkler/config.yaml --validate-only
           python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml --validate-only
+          python -m phast run examples/standard_workflow/quasistatic_sent/config.yaml --validate-only
+          python -m phast run examples/standard_workflow/dynamic_sent/config.yaml --validate-only
+          python -m phast run examples/two_material_dcb_beta/config.yaml --validate-only
+
+      - name: Replot the retained DCB comparison
+        run: python examples/two_material_dcb_beta/compare_results.py --output-dir runs/public_comparison_check
 
   supported-python-range:
     name: Python ${{ matrix.python-version }} / Ubuntu

@@ -114,3 +114,16 @@ generated artifacts and must not be committed.
 - **No Development Slang**: Do not use release or development slang such as "ships with", "hack", "epic", or "fix this later".
 - **No Process-Derived Claims**: Do not use issue numbers, pull-request numbers, ticket identifiers, or private workflow phases as scientific explanation. Describe the implemented behavior and evidence directly.
 - **No Emoticons**: Do not use emojis or emoticons in the documentation or source code.
+
+## Default Trajectory Storage
+
+- Default new trajectory and dataset output to HDF5 (`training_data.h5`).
+  Keep trajectory saving opt-in where it is currently opt-in.
+- Do not create directory-based Zarr stores unless the user or configuration
+  explicitly requests `zarr` or `both`. Never use Zarr as a silent fallback.
+- Apply this convention to runtime defaults, schema defaults, examples,
+  notebooks, READMEs, documentation, and generated output manifests.
+- Preserve existing Zarr readers and results. Do not convert, rename, or
+  delete previous result stores without a separate request.
+- Follow the trajectory storage section of
+  `docs/user_guide/example_contract.md` when introducing a writer.
@@ -0,0 +1,107 @@
+# Configuration authoring rules
+
+These rules are mandatory for new public YAML examples, their READMEs, and
+tutorials. Use them with [DOCUMENTATION_STYLE.md](DOCUMENTATION_STYLE.md) and
+the [example contract](docs/user_guide/example_contract.md). Write for an
+undergraduate who knows forces and displacements but is new to PhAST.
+
+## One layout, supported execution routes
+
+Use `schema_version: 2` for new standard-workflow teaching problems when the
+required execution adapter exists and has passed its checks. Keep this
+top-level order, omitting only genuinely unused optional sections:
+
+| Order | Key | Question answered |
+|---|---|---|
+| 1 | `schema_version` | Which input format is this? |
+| 2 | `name` | What problem is being solved? |
+| 3 | `reference` | What is the source or teaching scope? |
+| 4 | `geometry` | What domain and mesh are used? |
+| 5 | `regions` | Which elements and nodes belong to each selection? |
+| 6 | `materials` | What properties does each material have? |
+| 7 | `assignments` | Which material belongs to each element region? |
+| 8 | `initial_conditions` | What starting state or maintained damage is prescribed? |
+| 9 | `boundary_conditions` | What is restrained or loaded? |
+| 10 | `analysis_steps` | What physical analysis and loading are requested? |
+| 11 | `solver` | How is the analysis solved numerically? |
+| 12 | `outputs` | Where are histories, fields, and visuals written? |
+
+Use actual parser keys, two-space indentation, descriptive region names, and
+brief section comments. In schema 2, do not substitute the legacy singular
+`material`, `loading`, or `output` sections. Put units and the effect of
+changing a value next to the input. Label partial YAML excerpts as partial;
+use a complete checked-in file for runnable instructions.
+
+A common layout is not a promise that every solver supports every section.
+Check the [capability matrix](docs/user_guide/capability_matrix.md). The
+documented multi-material route is a CPU float64, structured-T3 rectangle,
+quasi-static Amor AT2 model with elementwise `E` and `Gc`, shared `nu`
+and `l0`, and Dirichlet conditions. It is not dynamic multi-material
+fracture or an independent interface law.
+
+Keep existing schema-1 benchmark inputs explicitly labelled. Do not migrate
+frozen course assets or separate 3D research merely to make inputs uniform.
+Unsupported routes remain separate until an adapter and evidence exist.
+
+## Explain editable choices
+
+- Separate geometry from mesh resolution. Name the boundary, crack, and
+  material selectors that must change when dimensions or mesh change.
+- Explain `E` as elastic stiffness and `Gc` as fracture resistance.
+  A tougher region need not be stiffer; vary one property at a time.
+- State a consistent unit system. A `units` label does not repair
+  inconsistent bare numbers. Dynamics requires meaningful density and time.
+- Separate physical analysis from integration. Quasi-static analysis omits
+  inertia; dynamics includes inertia, and explicit integration needs a
+  CFL-limited time step.
+- Separate final physical time, step limits, load increments, solver
+  iterations, and output cadence. Use the selected adapter's actual keys.
+- Define the mesh measure in `h/l0`. Neither one resolution ratio nor a
+  smaller time step is a universal convergence or physical-validation test.
+
+## Use the same command sequence
+
+Run from the installed repository root. Replace `CONFIG` with the YAML
+path and `RUN` with a new output directory; neither is a literal filename.
+
+```bash
+python -m phast explain-config CONFIG
+python -m phast run CONFIG --validate-only
+python -m phast run CONFIG --output_dir RUN
+```
+
+Explain, check the supported input contract, then solve. Confirm all three
+commands for the selected schema before promoting the example. Do not
+present legacy `precheck --config` as a universal schema-2 command.
+
+## README and tutorial minimum
+
+Use this sequence: physical question; prerequisites and installation; exact
+commands; input-section map; safe edits; outputs; evidence and limitations;
+help. Source-install instructions require Python 3.10 or newer, separate
+macOS/Linux and Windows environment commands, editable installation, and
+the optional dependency route using `requirements.txt`. Do not claim a
+checkout is the latest release.
+
+The main teaching sequence is the small single-material quasi-static SENT,
+small single-material dynamic SENT, and full layered DCB configuration.
+Identify their execution-check status. A setup exercise need not propagate
+a crack; initial `damage = 1` is not new growth. Distinguish algebraic
+convergence, discretisation checks, matched controls, independent scientific
+review, and experimental validation.
+
+Compact complete comparison inputs are permitted duplication of model data,
+not duplicated solver code. Keep the same section order, change only the
+declared comparison inputs, use the common CLI and separate output directories,
+and state what is held fixed. Do not add a comparison-specific solver driver.
+
+When trajectory saving is requested, default to HDF5 (`training_data.h5`).
+Preserve existing opt-in behaviour and keep large raw stores out of the public
+payload. Show retained PNG/GIF assets with captions and a static fallback;
+use repository-relative MyST figure paths that Sphinx can collect, not
+unverified public raw URLs.
+
+Before publication, record exact command checks and the documentation build;
+identify checks not run. End substantial tutorials with a
+[GitHub issue invitation](https://github.com/CEMS-Lab/PhAST/issues/new/choose)
+requesting the config, command, OS, Python/PhAST version, and full error.
@@ -27,7 +27,8 @@ machine:
 pip install -e ".[dataset]"
 ```
 
-PETSc, MUMPS, cuDSS, AmgX, and vendor solvers are optional backend checks and are not required for the default CPU confidence suite.
+PETSc, MUMPS, cuDSS, AmgX, and vendor solvers are optional. They are not
+required for the standard CPU test suite.
 
 ## 2. First Contribution
 
@@ -45,9 +46,9 @@ All participation is governed by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
 
 ## 3. Coding Standards
 
-- **Type Hinting**: All new Python functions must use strict type hints.
-- **Device Safety**: Ensure tensor operations are device-agnostic (`cpu`/`cuda`).
-- **Autograd Compatibility**: Preserve and document autograd compatibility for
+- **Type hinting**: All new Python functions must use strict type hints.
+- **Device safety**: Ensure tensor operations are device-agnostic (`cpu`/`cuda`).
+- **Autograd compatibility**: Preserve and document autograd compatibility for
   supported smooth tensor pathways. Identify nonsmooth history updates,
   projections, bounds, active sets, and external sparse-backend boundaries.
 
@@ -57,8 +58,10 @@ All participation is governed by [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
   welcome, but public changes are merged only after maintainer review and
   approval.
 - Run the relevant validation commands locally.
-- Keep high-fidelity volumetric datasets (Zarr/H5), local diagnostic logs, and generated heavy media out of git.
-- Provide parity checks against established analytical or commercial benchmarks when modifying physics kernels.
+- Keep large volumetric datasets (Zarr/H5), local debugging logs, and generated
+  media out of git.
+- Compare changes to physics kernels against an appropriate analytical,
+  numerical, or published reference problem.
 - Update relevant documentation, such as `README.md`, YAML schemas, example
   READMEs, and capability pages, with user-facing changes.
 
@@ -78,7 +81,7 @@ For changed YAML examples or benchmark configs, also run:
 PYTHONPATH=src python -m phast run <config.yaml> --validate-only
 ```
 
-For generated visuals or retained example artifacts, inspect the output folder
+For generated visualisations or example results, inspect the output folder
 and update the relevant README or public contract file. The public repository
 includes the tests intended for public review. Run any additional,
 project-specific checks documented in the pull request or issue that motivated
@@ -91,6 +94,19 @@ folders also contain public-facing `README.md` files, so changes to example
 commands, inputs, outputs, or visuals usually require both docs and example
 README updates.
 
+All documentation, README, tutorial, and notebook prose must follow
+[`DOCUMENTATION_STYLE.md`](DOCUMENTATION_STYLE.md). The guide defines the
+project's academic tone, terminology, capability labels, command conventions,
+and checks for avoiding internal development language in public text.
+
+New YAML inputs, example READMEs, and tutorials must additionally follow
+[`CONFIGURATION_STYLE.md`](CONFIGURATION_STYLE.md). Keep the same schema-2
+section order across supported student problems, define units and editable
+choices, and use the explain/check/run sequence. A common layout does not
+imply an execution adapter: require adapter and command checks before
+promotion. Preserve numerical inputs in documentation-only edits. Frozen
+course assets and separate 3D research are not migration targets.
+
 Install the documentation dependencies:
 
 ```bash
@@ -118,7 +134,8 @@ When editing curated examples, use `docs/user_guide/example_contract.md` as
 the source of truth for required files, README content, visuals, and artifact
 conventions.
 
-AI-assisted contributions are welcome when they follow `AGENTS.md`, `llms.txt`,
+AI-assisted contributions are welcome when they follow `DOCUMENTATION_STYLE.md`,
+`AGENTS.md`, `llms.txt`,
 `.cursorrules`, and `docs/agent-contribution-guide.md`. Agents should verify
 commands where possible and must not invent solver capabilities, benchmark
 results, paper metadata, or local/HPC provenance.
@@ -132,13 +149,21 @@ available, manifests, lightweight CSV outputs, setup/final-state visuals, and
 an evolution animation appropriate to the physics.
 
 The README should document the problem definition, exact run command, expected
-artifacts, evidence boundary, and result-inspection snippet. Do not commit raw
+results, scope of validation, and result-inspection snippet. Do not commit raw
 HPC run trees, large H5/Zarr stores, or unpublished diagnostic archives.
 
-## 8. Asking For Help
+## 8. Trajectory Storage Convention
+
+New trajectory and dataset writers, example configurations, notebooks, and
+documentation must use HDF5 (`training_data.h5`) by default. Zarr is an explicit
+opt-in, not a fallback. Keep existing Zarr readers and previously generated
+artifacts intact. Match the selected format in output manifests and follow
+the [example contract](docs/user_guide/example_contract.md).
+
+## 9. Asking For Help
 
 Open an issue if you are unsure how to install PhAST, interpret a configuration,
 run an example, or contribute a change. A useful help request includes the
-command, configuration path, operating system, PyTorch version, and the first
-warning or traceback. It is acceptable to open an issue before diagnosing the
-solver internals.
+command, configuration path, PhAST version or commit, operating system, Python
+and PyTorch versions, and the complete first warning or traceback. It is
+acceptable to open an issue before diagnosing the solver internals.