From ebfe208f44dc936095204f2ea2ddc7d8dbe1dee9 Mon Sep 17 00:00:00 2001 From: Allamaprabhu Ani Date: Mon, 12 Oct 2026 09:47:12 +0100 Subject: [PATCH 1/2] Remove assistant configuration files and tool names Delete AGENTS.md, .cursorrules, llms.txt, .github/copilot-instructions.md and docs/agent-contribution-guide.md, remove their links from README.md, CONTRIBUTING.md and the documentation index, and state the coding-assistance acknowledgement without naming individual tools. --- .cursorrules | 66 ------------ .github/copilot-instructions.md | 37 ------- AGENTS.md | 129 ----------------------- CONTRIBUTING.md | 8 +- README.md | 9 +- docs/_templates/layout.html | 2 +- docs/agent-contribution-guide.md | 174 ------------------------------- docs/conf.py | 2 +- docs/index.md | 1 - llms.txt | 131 ----------------------- 10 files changed, 6 insertions(+), 553 deletions(-) delete mode 100644 .cursorrules delete mode 100644 .github/copilot-instructions.md delete mode 100644 AGENTS.md delete mode 100644 docs/agent-contribution-guide.md delete mode 100644 llms.txt diff --git a/.cursorrules b/.cursorrules deleted file mode 100644 index f57b0d6e9..000000000 --- a/.cursorrules +++ /dev/null @@ -1,66 +0,0 @@ -# PhAST Agent Instructions - -PhAST is a PyTorch-native finite-element solver for phase-field fracture, -explicit dynamics, and foundational solid mechanics workflows. Treat the -public repository as a scientific software package: changes must preserve -mechanics fidelity, differentiability boundaries, and reproducible examples. - -## Core Rules - -- Preserve PyTorch tensor semantics. Do not insert `.numpy()`, `.item()`, or - `.tolist()` inside differentiable forward paths unless the value is strictly - telemetry or postprocessing. -- Default mechanics and fracture calculations to `torch.float64` unless a - documented mixed-precision path explicitly permits otherwise. -- Avoid in-place tensor mutations in autograd-sensitive code. Prefer - out-of-place expressions, `torch.where`, `scatter_add`, sparse operators, and - vectorized batch operations. -- Keep paper-specific reproduction commands in `reproduction/paper1` with an - explicit input catalogue and separate replot and simulation-run status. - These commands preserve historical experiments rather than adding a general - inverse API. Keep unrelated inverse studies, hybrid/deep-learning research, - paper-2, paper-4, private HPC and proprietary-solver artifacts separate. -- Keep public examples flat, runnable, and reproducible: `config.yaml`, - optional fluent setup, standard manifests, CSV histories, lightweight visuals, - and documented result bundles. - -## Visual Standards - -- Use `plt.style.use("default")` before applying project-specific font settings. -- Use solid white figure backgrounds with black labels for public artifacts. -- Use `Reds` for phase-field/cohesive damage fields and `plasma` for equivalent - plastic strain or von Mises style scalar fields unless a local standard says - otherwise. -- Keep generated README/docs media lightweight. Do not commit raw HPC folders or - heavy trajectory stores. - -## Validation - -- Prefer focused pytest coverage for changed contracts, runners, result APIs, and - public examples. -- For promoted example scripts, run with the repository root and `src` on the - Python path: - -```bash -PYTHONPATH=src:. python -m phast doctor -PYTHONPATH=src:. python -m phast run examples/dynamic/B2_kalthoff_winkler/config.yaml --validate-only -PYTHONPATH=src:. python -m phast run examples/quasistatic/notched_holed_plate/config.yaml --validate-only -PYTHONPATH=src:. python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml --validate-only -``` - -Only curated, lightweight result artifacts that are part of the public examples -contract should be committed. - -## Tone and Language -- **Academic and Formal**: Documentation, comments, and public-facing text must use precise language appropriate for research software in computational mechanics. -- **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`. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 3e2de4898..000000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,37 +0,0 @@ -# Copilot Instructions for PhAST - -PhAST is a scientific Python/PyTorch finite-element solver. Treat code, -examples, documentation, and post-processing edits as part of the -reproducibility surface. - -- Follow `AGENTS.md`, `llms.txt`, and `CONTRIBUTING.md`. -- For agent contribution guidance, follow `docs/agent-contribution-guide.md`. -- For PyTorch solver code, follow `.cursorrules`. -- Do not add claims that are not supported by the code, examples, or - `docs/user_guide/capability_matrix.md`. -- Keep example documentation aligned with - `docs/user_guide/example_contract.md`. -- Prefer commands using `python -m phast ...` from the repository root. -- Do not commit `docs/_build/`, `runs/`, raw H5/Zarr stores, or local absolute - paths. -- When changing docs, run: - -```bash -sphinx-build -W -b html docs docs/_build/html -``` - -- When changing configs or examples, run: - -```bash -PYTHONPATH=src python -m phast run --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. diff --git a/AGENTS.md b/AGENTS.md deleted file mode 100644 index d18b92ac1..000000000 --- a/AGENTS.md +++ /dev/null @@ -1,129 +0,0 @@ -# Agent Guide - -This repository welcomes agent-assisted contributions to documentation, -examples, validation scripts, post-processing utilities, performance hygiene, -and solver code. Public scientific claims must remain traceable to the -checked-in code, examples, capability matrix, and citation metadata. - -## Start Here - -- Read `llms.txt` for repository orientation. -- Read `.cursorrules` before editing solver code or generated visuals. -- Read `CONTRIBUTING.md` before opening a pull request. -- For contribution lanes, prompt templates, and validation commands, follow - `docs/agent-contribution-guide.md`. -- For promoted examples, follow `docs/user_guide/example_contract.md`. - -## Agentic Contribution Loop - -Every agent contribution must follow this sequence. - -1. **Acquire context.** Read `llms.txt`, `.cursorrules`, `CONTRIBUTING.md`, and - the relevant documentation or example contract before editing. -2. **Classify the lane.** Identify the narrowest applicable lane: - documentation, examples and visuals, validation and contracts, solver and - performance, or public API. -3. **Inspect the current files.** Review the exact source, documentation, and - example files that will be changed. Do not overwrite files without reading - them first. -4. **Make a small change.** Prefer one coherent edit set per contribution. - Preserve scientific meaning, public claim boundaries, and existing output - contracts. -5. **Synchronize adjacent materials.** If a command, output, figure, example - input, or public API changes, update the linked README, tutorial, gallery, - or contract file in the same contribution. -6. **Verify.** Run the narrowest command set that covers the change. If a - command is documented, run it or state why it could not be run. -7. **Review the result.** Check that the change is consistent with the - capability matrix, that generated artifacts are not committed, and that the - repository remains scientifically defensible. - -### Lane Guide - -| Lane | Typical scope | Minimum verification | -|---|---|---| -| Documentation | theory pages, tutorials, landing pages, README text | `sphinx-build -W -b html docs docs/_build/html` | -| Examples and visuals | example READMEs, YAML decks, lightweight figures, manifests | `PYTHONPATH=src python -m phast run --validate-only` plus `sphinx-build -W -b html docs docs/_build/html` when docs links change | -| Validation and contracts | config checks, manifest checks, result loading, public example rules | focused `--validate-only` commands and a targeted Python check | -| Solver and performance | tensor code, device or dtype hygiene, allocation reduction | one affected public YAML deck and any required numerical sanity check | -| Public API | fluent interfaces, result loading, documented entry points | affected tests and documentation updates | - -### Final Self-Check - -- Confirm that no generated build output, trajectory store, or local scratch - directory is staged for commit. -- Confirm that every new command or example reference is reflected in the - relevant documentation. -- Confirm that no public-facing text overstates supported capabilities. -- Confirm that the change is small enough to review without reconstructing - hidden context from issue history or private notes. - -## Good Agent Tasks - -- Fix broken commands, stale imports, dead links, and renamed files. -- Expand theory documentation with clear equations, symbol tables, and links - from mathematical notation to YAML keys and fluent API calls. -- Improve examples by adding clearer YAML, fluent API companions, README - explanations, lightweight visuals, or validation commands. -- Improve post-processing and result-inspection ergonomics without changing - solver claims. -- Add focused validation checks for public contracts, config parsing, result - loading, and promoted example structure. -- Refactor clear duplication when behavior is covered by an explicit validation - command. -- Improve performance only when tensor semantics, dtype/device behavior, and - scientific equivalence are preserved. - -## Guardrails - -- Prefer small, reviewable pull requests. -- Do not invent benchmark results, solver capabilities, timings, references, - or paper/publication details. -- Keep the distinction between supported, beta, scaffold, and unsupported - workflows exactly aligned with `docs/user_guide/capability_matrix.md`. -- If a command appears in documentation or an example README, run it or state - why it was not run. -- If an example input, output, visual, or command changes, update the - corresponding example `README.md`. -- Do not add raw HPC folders, heavy H5/Zarr stores, unpublished notes, - proprietary solver files, or local absolute paths. -- Do not change mechanics kernels, damage evolution, material laws, or solver - convergence behavior without a validation plan. -- Do not add new public APIs without documenting the intended workflow and - capability boundary. - -## Validation - -Use the narrowest check that covers the change: - -```bash -sphinx-build -W -b html docs docs/_build/html -PYTHONPATH=src python -m phast doctor -PYTHONPATH=src python -m phast run --validate-only -``` - -For solver or tensor-code changes, also check dtype/device safety and avoid -breaking autograd-sensitive paths. Follow `.cursorrules` for PyTorch-specific -constraints. - -`docs/_build/`, `runs/`, raw trajectory stores, and local solver outputs are -generated artifacts and must not be committed. - -## Tone and Language -- **Academic and Formal**: Documentation, comments, and public-facing text must use precise language appropriate for research software in computational mechanics. -- **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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5ee7450aa..47ac22bda 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -134,11 +134,9 @@ 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 `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. +Contributions should follow `DOCUMENTATION_STYLE.md`, verify commands where +possible and must not invent solver capabilities, benchmark results, paper +metadata, or local/HPC provenance. ## 7. Adding Examples diff --git a/README.md b/README.md index ff950dd86..c1d427881 100644 --- a/README.md +++ b/README.md @@ -268,7 +268,6 @@ print(result.history_names()) | `assets/` | Lightweight visual assets for repository documentation. | | `tools/` | Maintenance utilities for documentation and release checks. | | `.github/` | Issue templates, Pull Request guidelines, and CI/CD Action workflows. | -| `AGENTS.md`, `llms.txt`, `.cursorrules` | Agent-facing contribution guidance and repository orientation. | ## Contributing @@ -289,12 +288,6 @@ examples, and report unclear instructions. If you become stuck at any point, about installation or usage is a valid issue and helps improve the documentation for subsequent users. -Agent-assisted contributions are also supported. Guidance lives in -[AGENTS.md](AGENTS.md), [llms.txt](llms.txt), [.cursorrules](.cursorrules), and -[docs/agent-contribution-guide.md](docs/agent-contribution-guide.md). These -files are intended to help contributors improve the solver and documentation -without inventing benchmark results, capabilities, or paper metadata. - ## Build The Docs ```bash @@ -334,6 +327,6 @@ Official code for the manuscript is hosted in this repository: ## Acknowledgments -The theoretical formulations, phase-field continuum equations, constitutive assumptions, and numerical discretization choices in PhAST are derived from the established computational solid mechanics literature and were selected, interpreted, and validated by the human authors, as described in the associated article and documentation. AI coding assistants, including Codex, Claude, Gemini, and GitHub Copilot, were used as auxiliary software-engineering tools for repository organization, documentation editing, boilerplate generation, and code-review support; they did not define the physics, benchmark claims, validation criteria, or scientific conclusions. The authors reviewed and verified the computational mechanics kernels, benchmark configurations, and validation artifacts, and take full responsibility for the correctness, limitations, and scientific content of the codebase. +The theoretical formulations, phase-field continuum equations, constitutive assumptions, and numerical discretization choices in PhAST are derived from the established computational solid mechanics literature and were selected, interpreted, and validated by the human authors, as described in the associated article and documentation. AI coding assistants were used as auxiliary software-engineering tools for repository organization, documentation editing, boilerplate generation, and code-review support; they did not define the physics, benchmark claims, validation criteria, or scientific conclusions. The authors reviewed and verified the computational mechanics kernels, benchmark configurations, and validation artifacts, and take full responsibility for the correctness, limitations, and scientific content of the codebase. PhAST is organised to support reproducible scientific computing. Machine-readable manifests, structured result metadata, command-line and Python interfaces, and repository guidance allow researchers to inspect, reproduce, and extend simulations without relying on undocumented local settings. Scientific claims remain limited to the formulations, tests, and validation cases described in the documentation. diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index 71d11202a..8ccfd9e20 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -4,7 +4,7 @@ {% set canonical_path = '' if pagename == 'index' else pagename ~ '.html' %} -{% if pagename.startswith('_modules/') or pagename.startswith('_sources/') or pagename.startswith('maintainer/') or pagename in ('agent-contribution-guide', 'genindex', 'py-modindex', 'search') %} +{% if pagename.startswith('_modules/') or pagename.startswith('_sources/') or pagename.startswith('maintainer/') or pagename in ('genindex', 'py-modindex', 'search') %} {% endif %} {% endblock %} diff --git a/docs/agent-contribution-guide.md b/docs/agent-contribution-guide.md deleted file mode 100644 index dde48f395..000000000 --- a/docs/agent-contribution-guide.md +++ /dev/null @@ -1,174 +0,0 @@ -# Agent Contribution Guide - -This guide is for AI agents and automated tools that propose improvements to -PhAST. Contributions are welcome, but this is scientific software: changes must -preserve reproducibility, numerical meaning, and public claim boundaries. - -## What Agents Can Improve - -- Documentation clarity, broken commands, stale links, and renamed files. -- Example READMEs, YAML decks, fluent API companions, and lightweight visuals. -- Validation scripts for public examples, config parsing, result loading, and - artifact contracts. -- Post-processing utilities, plotting consistency, result manifests, and - result-inspection workflows. -- Small, behavior-preserving refactors that remove duplication. -- Performance improvements that preserve PyTorch autograd, dtype, device, and - solver semantics. -- Packaging, install, CI, issue templates, and contributor ergonomics. - -## Contribution Lanes - -Use one lane per pull request unless the changes are tightly coupled. - -| Lane | Good changes | Required checks | -|---|---|---| -| Documentation polish | clearer wording, equations, theory-to-YAML tables, figure links, dead-link fixes | `sphinx-build -W -b html docs docs/_build/html` | -| Example maintenance | README updates, YAML cleanup, fluent companion scripts, visual manifests, lightweight PNG/GIF refreshes | `python -m phast run /config.yaml --validate-only` plus docs build when README links change | -| Validation ergonomics | config checks, manifest checks, result-loading checks, clearer error messages | relevant `--validate-only` commands and focused Python checks | -| Post-processing | plotting consistency, figure generation, result readers, artifact summaries | run the changed script on a retained lightweight example or explain why data is unavailable | -| Solver performance | vectorization, allocation reduction, dtype/device cleanup, cached quantities | validate an affected public YAML deck and document any numerical tolerance used | -| Solver physics | constitutive updates, damage evolution, boundary conditions, convergence behavior | requires a validation plan, capability-matrix update, and reviewer attention from a human maintainer | - -## High-Value Agent Tasks - -Agents are especially useful for bounded improvements that are easy to verify: - -- Expand theory pages with MyST/LaTeX equations, short derivations, and links - from each symbol to YAML keys and fluent API calls. -- Add visual examples to documentation using existing public PNG/GIF assets. -- Compare each example README against `docs/user_guide/example_contract.md`. -- Check that every documented command runs from the repository root. -- Remove stale internal wording, local paths, generated caches, and unsupported - claims from public-facing files. -- Improve diagnostics so invalid configs fail with actionable messages. -- Add small validation utilities that catch broken manifests, missing media, - or stale README commands. - -## What Agents Must Not Invent - -- New benchmark pass/fail claims. -- New timing or accuracy numbers. -- Unsupported solver capabilities. -- Paper DOI, arXiv identifiers, journal details, or publication status. -- Local HPC paths, raw cluster logs, proprietary solver artifacts, or heavy - trajectory stores. - -## Required Context - -Before editing, inspect the relevant source of truth: - -| Topic | Source of truth | -|---|---| -| Supported physics and maturity | `docs/user_guide/capability_matrix.md` | -| Example folder contents | `docs/user_guide/example_contract.md` | -| YAML execution | `docs/user_guide/yaml_workflow.md` | -| Python/fluent API | `docs/user_guide/python_api.md` | -| Result loading | `docs/user_guide/public_api_reference.md` | -| Public examples | `examples/README.md` and each example `README.md` | -| PyTorch/autograd constraints | `.cursorrules` | -| Citation | `CITATION.cff` | - -## Ready-to-Use Prompts - -These prompts are intentionally narrow. Replace the paths in angle brackets. - -### Documentation theory page - -```text -Improve as a public Sphinx/MyST documentation page for PhAST. -Preserve all scientifically correct content, remove redundancy, and add clear -equations where helpful. Link theory symbols to YAML keys and phast.Problem API -terms. Use only public examples and public docs as evidence. Do not invent -benchmark results, timings, paper metadata, or unsupported capabilities. Run -sphinx-build -W -b html docs docs/_build/html before finishing. -``` - -### Example folder audit - -```text -Audit against docs/user_guide/example_contract.md. The folder -must be flat and public-facing, with README.md, config.yaml, fluent Python where -available, lightweight setup/final-state visuals, appropriate animation, and -valid manifests. Remove or flag files outside the contract. Run -PYTHONPATH=src python -m phast run /config.yaml --validate-only -and update the README only with verified commands. -``` - -### Solver-code review - -```text -Review for correctness, device/dtype safety, autograd safety, -unnecessary tensor allocation, avoidable CPU/GPU transfers, and duplicated -logic. Do not change physics behavior unless there is a validation plan. Prefer -small patches. Validate with PYTHONPATH=src python -m phast doctor and at least -one affected public config using --validate-only. -``` - -### Post-processing and visuals - -```text -Improve public visuals. Use existing public result files or -document the missing input data. Keep figures lightweight, white-background, -readable on GitHub, and aligned with .cursorrules. Update visual_manifest.json -when outputs change. Do not commit raw H5/Zarr trajectories. -``` - -## Solver-Code Guardrails - -- Preserve differentiability unless the value is strictly telemetry or - post-processing. -- Do not insert `.item()`, `.numpy()`, `.tolist()`, or CPU/GPU transfers in - differentiable forward paths. -- Preserve float64 reference behavior unless a documented mixed-precision path - explicitly allows otherwise. -- Avoid in-place tensor mutation in autograd-sensitive code. -- Do not change constitutive models, damage evolution, boundary-condition - semantics, or convergence behavior without an explicit validation plan. -- If a refactor touches shared solver behavior, validate at least one relevant - public YAML deck with `--validate-only` and state what was not run. - -## Documentation and Example Style - -- Use precise scientific language. -- Prefer “supported”, “beta”, “scaffold”, or “unsupported” over vague claims. -- Prefer “reproduce this public example” over “guarantees validation” unless a - comparison report and acceptance metric are present. -- Keep instructions command-first and runnable from the repository root. -- Avoid internal process language such as “customer”, “private archive”, - “smoke workflow”, or local machine paths. -- When changing example inputs, outputs, visuals, or commands, update the - example README. - -## Checks - -For documentation-only changes: - -```bash -sphinx-build -W -b html docs docs/_build/html -``` - -For docs or examples that mention a YAML config: - -```bash -PYTHONPATH=src python -m phast run --validate-only -``` - -For environment or packaging changes: - -```bash -PYTHONPATH=src python -m phast doctor -``` - -If a command cannot be run because it is expensive or requires optional -hardware, say that explicitly in the pull request. - -## Pull Request Notes for Agents - -Every agent-authored pull request should state: - -- the contribution lane; -- the source-of-truth files that were checked; -- the exact commands run; -- any commands not run and why; -- whether scientific claims, public examples, or output artifacts changed. diff --git a/docs/conf.py b/docs/conf.py index 7c5545e66..cc8b56028 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -172,7 +172,7 @@ def _exclude_secondary_pages_from_sitemap(app, pagename, templatename, context, pagename.startswith("_modules/") or pagename.startswith("_sources/") or pagename.startswith("maintainer/") - or pagename in {"agent-contribution-guide", "genindex", "py-modindex", "search"} + or pagename in {"genindex", "py-modindex", "search"} ) if excluded and app.sitemap_links: app.sitemap_links.pop() diff --git a/docs/index.md b/docs/index.md index 8d5081f78..89ef699b6 100644 --- a/docs/index.md +++ b/docs/index.md @@ -218,5 +218,4 @@ api/adaptive community citing -agent-contribution-guide ``` diff --git a/llms.txt b/llms.txt deleted file mode 100644 index c5ef726ed..000000000 --- a/llms.txt +++ /dev/null @@ -1,131 +0,0 @@ -# PhAST: Phase-field Autograd Solver in Torch - -> PhAST is a PyTorch-native, differentiable finite-element solver for public -> phase-field fracture and solid-mechanics workflows. - -PhAST focuses on reproducible simulation workflows: YAML decks, fluent Python -authoring, structured result manifests, and curated validation visuals. This -file is written for AI agents and automated tools that need to understand how to -use the public repository without guessing from source code alone. - -## Authorship And Credit - -PhAST was developed by Allamaprabhu Ani as the lead developer and maintainer, -with the public release stewarded through CEMS Lab. The solver formulations, -finite-element implementation, validation examples, and documentation should be -credited to the PhAST authors and cited using the repository citation metadata -and linked papers when available. - -The project builds on the scientific Python and PyTorch ecosystem. External -libraries, benchmark references, and literature sources retain their own -licenses and citation requirements; do not strip attribution when generating -derived documentation, examples, or release material. - -## Usage Context - -- Public examples are YAML-first. Checked-in `config.yaml` decks are the - reference shared run inputs. -- The fluent `phast.Problem` API is the authoring path for supported workflows. -- Completed runs expose machine-readable artifacts such as `run_manifest.json`, - `run_lockfile.json`, `run_metadata.json`, `summary.json`, and CSV telemetry. -- Use `phast.load_result(path)` for read-only result inspection. -- Selected paper-specific retained-data checks and inverse replots are - documented in `reproduction/paper1`. General inverse and hybrid research, - raw HPC logs, proprietary files and heavy trajectory stores stay separate - from the public solver release. - -## Quick Start For Agents - -Install the package in editable mode, then inspect the environment: - -```bash -pip install -e . -python -m phast doctor -``` - -Validate public YAML decks without running the full simulations: - -```bash -python -m phast run examples/dynamic/B2_kalthoff_winkler/config.yaml --validate-only -python -m phast run examples/quasistatic/notched_holed_plate/config.yaml --validate-only -python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml --validate-only -``` - -Run a small public solid-mechanics example and inspect its result directory: - -```bash -python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml --output_dir runs/linear_plate -python - <<'PY' -import phast -result = phast.load_result('runs/linear_plate') -print(result.visuals()) -print(result.history_names()) -PY -``` - -Explain a YAML deck before modifying it: - -```bash -python -m phast explain-config examples/quasistatic/notched_holed_plate/config.yaml -``` - -## Repository Map - -- [`src/phast/`](src/phast/) - core package: workflow API, FEM kernels, - materials, solvers, result loading, and postprocessing utilities. -- [`examples/`](examples/) - curated public YAML examples and retained visual - result bundles. -- [`examples/README.md`](examples/README.md) - public example overview. -- [`reproduction/paper1/README.md`](reproduction/paper1/README.md) - manuscript - and supplement catalogue, retained-data verification and bounded replots. - Historical experiment sources and large fields use a separate data archive. -- [`configs/`](configs/) - benchmark decks, schemas, reference templates, and - reusable configuration material. -- [`docs/`](docs/) - Sphinx/user documentation source. -- [`docs/agent-contribution-guide.md`](docs/agent-contribution-guide.md) - - guidance for AI agents improving code, examples, validation, and docs. -- [`assets/`](assets/) - public README and documentation media. -- [`tools/`](tools/) - small public utilities for regenerating curated media. -- [`.github/`](.github/) - public issue templates, PR template, code ownership, - and GitHub Actions workflows. -- [`install.sh`](install.sh) - convenience source-install script; normal users - should start from the documented CLI commands. -- [`pyproject.toml`](pyproject.toml), [`requirements.txt`](requirements.txt), - and [`requirements-docs.txt`](requirements-docs.txt) - packaging and - dependency metadata. -- [`CITATION.cff`](CITATION.cff) - citation metadata. -- [`LICENSE`](LICENSE) and [`CONTRIBUTING.md`](CONTRIBUTING.md) - license and - contribution guidance. - -## Documentation Links - -Read these files before making changes or answering detailed usage questions: - -- [Capability Matrix](docs/user_guide/capability_matrix.md) - supported public - physics, examples, and execution surfaces. -- [Python API Guide](docs/user_guide/python_api.md) - fluent `phast.Problem` - authoring patterns. -- [YAML Workflow](docs/user_guide/yaml_workflow.md) - batch execution, - validation, and reproducible shared runs. -- [Public API Reference](docs/user_guide/public_api_reference.md) - inspecting completed runs with - `phast.load_result(path)`. -- [Problem Setup Guide](docs/user_guide/setup_problems.md) - geometry, meshes, - materials, boundary conditions, and outputs. -- [Example Contract](docs/user_guide/example_contract.md) - expected structure - for public example folders and visual artifacts. -- [Example Gallery](docs/example-gallery.md) - representative public examples - and expected outputs. - -## Contribution Rules - -Implementation rules for agents that write code live in [`.cursorrules`](.cursorrules). -General agent contribution rules live in [`AGENTS.md`](AGENTS.md). Use -[`docs/agent-contribution-guide.md`](docs/agent-contribution-guide.md) for -agent-assisted code, example, validation, and documentation work. Keep -`llms.txt` focused on repository orientation and usage. - -## Tone and Language -- **Academic and Formal**: Documentation, comments, and public-facing text must use precise language appropriate for research software in computational mechanics. -- **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. From 4839db5747c1d6561831b35515e84bd8f5af945c Mon Sep 17 00:00:00 2001 From: Allamaprabhu Ani Date: Mon, 12 Oct 2026 14:33:55 +0100 Subject: [PATCH 2/2] Reword a figure-size comment in postprocess_paper --- src/phast/utils/postprocess_paper.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/phast/utils/postprocess_paper.py b/src/phast/utils/postprocess_paper.py index e2565fa73..6e4216de3 100644 --- a/src/phast/utils/postprocess_paper.py +++ b/src/phast/utils/postprocess_paper.py @@ -495,9 +495,8 @@ def _get_stress(self, grp, data): def _savefig(self, fig, name, max_px=2000): """Save figure to figures directory, capped at max_px on the larger dimension. Publication figures need >= ~200 dpi at - column width; this cap keeps PNGs reviewable in Claude Code - (2000-px ceiling per feedback_image_size memory) without - dropping below that dpi on single/double-column layouts.""" + column width; this cap keeps PNGs at a size that is easy to review + without dropping below that dpi on single/double-column layouts.""" path = os.path.join(self.figures_dir, f'{name}.{self.fmt}') fig.savefig(path, dpi=self.dpi, bbox_inches='tight', facecolor=THEME['background'])