AGENTS.md ยท diff
git:20260817.1775621 to git:20260819.3d28caa
7 added, 0 removed. Audit A to A.
# AgentFEM Repository Instructions
AgentFEM is a FEniCSx-first finite-element platform. Keep one readable public
Python workflow for humans, terminals, GUI clients, and AI agents.
## Environment and checks
- Use the `fenicsx-env` conda environment for local numerical tests.
- Run targeted tests before the full suite.
- Run examples from the source parent or install the built wheel; do not rely
on source-path insertion in new installed-use templates.
- Preserve user changes in `README.md`, `CITATION.cff`, and unrelated files.
## Architecture rules
- `Study` states the physical analysis; `SolutionProcedure` states the
numerical route.
- Start ordinary cases with the physical Study factories: `static_solid`,
`steady_heat_transfer`, `transient_heat_transfer`, `dynamic_solid`, or
`creep_solid`. Keep generic analysis-order factories for formulation work.
- Keep materials, constraints, loads, boundary models, steps, and outputs as
distinct concepts.
+ - Keep surrogates, neural operators, neural-field solvers, and learned
+ constitutive models distinct under the public `learning` umbrella. A
+ neural-field solver is a SolutionProcedure lowered by a Step provider, not
+ a surrogate and not an operator-assembly backend.
+ - Core owns learning semantics, result evidence, and extension compatibility;
+ optional frameworks and confidential domain assets belong in separately
+ installed extension packages.
- Add common finite-element functionality to its reusable module, not to one
example.
- GUI and agent integrations call the public Python API or the structured CLI;
they must not depend on private DOLFINx objects.
- `case.py` is the modeling source of truth. `agentfem.toml` contains only
operational project metadata.
- Every machine-facing command needs stable JSON, addressable failure, and a
non-zero exit code on failure.
- A completed solver call is not automatically a scientifically verified
result. Preserve the `SimulationResult` trust distinction.
## Public workflow
Prefer `studies -> mesh -> models -> fields -> materials -> constraints/loads
-> step -> SimulationResult`. Use `model.step(target=...)`, named regions,
`project.current_run()`, and `RunContext.publish(result)` in new application
templates.
Use `models.model_api("core")` as the generated application vocabulary.
Methods reported under `"compatibility"`, including material/procedure-specific
`*_step` factories, remain executable in 0.2.x but must not appear in new
application cases. Every built-in Step provider must publish and enforce a
`StepOptionContract`; capability inspection and execution must consume the
same contract.
Read `WORKFLOW.md`, `CONCEPTS.md`, `AGENT_GUIDE.md`, and focused files under
`docs/` before extending a scientific concept.