diff --git a/.cursorrules b/.cursorrules index 81af038be..f57b0d6e9 100644 --- a/.cursorrules +++ b/.cursorrules @@ -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`. diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index d48cd08ba..3e2de4898 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -27,3 +27,11 @@ 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/.github/pull_request_template.md b/.github/pull_request_template.md index 62ecd798c..272b20da8 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -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. diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index becff143a..d8300f9d4 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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 diff --git a/AGENTS.md b/AGENTS.md index 4ee25ecfa..d18b92ac1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -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. diff --git a/CONFIGURATION_STYLE.md b/CONFIGURATION_STYLE.md new file mode 100644 index 000000000..3a6002525 --- /dev/null +++ b/CONFIGURATION_STYLE.md @@ -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. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 89c9ede44..5ee7450aa 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 --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. diff --git a/DOCUMENTATION_STYLE.md b/DOCUMENTATION_STYLE.md new file mode 100644 index 000000000..e1367bd3e --- /dev/null +++ b/DOCUMENTATION_STYLE.md @@ -0,0 +1,771 @@ +# PhAST Public Documentation Style and Conventions + +This guide applies to all public-facing prose in the PhAST repository. Check +it whenever creating or reviewing: + +- the root `README.md`; +- a README under `examples/`, `configs/`, `scripts/`, or another subdirectory; +- pages under `docs/`; +- tutorial and notebook narrative cells; +- public configuration comments; +- public release notes and changelog entries. + +The objective is clear, accurate, academic documentation that an undergraduate +student can follow without prior knowledge of PhAST. Documentation must also +state the implemented scope honestly so that readers can decide whether the +software is suitable for their work. + +This file governs public software documentation. Journal manuscripts, +responses to reviewers, private research notes, and generated API text may +have additional requirements. + +New YAML examples, example READMEs, and tutorials must also follow +[`CONFIGURATION_STYLE.md`](CONFIGURATION_STYLE.md). It defines the common +schema-2 section order, student-facing explanations, command sequence, and +checks required before promoting an execution route. Preserve numerical +inputs during writing-only edits; do not migrate frozen course assets or +separate 3D research simply to make inputs uniform. + +Sections 19 and 20 provide transferable writing directives for scientific +explanations and, when requested, research proposals. Apply the structure +appropriate to the document: a proposal describes work to be tested, whereas +public software documentation describes verified capabilities. Writing +examples below do not establish implemented features or numerical results. + +## 1. Required working practice + +Before writing: + +1. Identify the reader and the task the page supports. +2. Check the current implementation, command help, schema, and runnable + examples before describing a capability. +3. Decide whether the page is a tutorial, explanation, reference, example + README, or installation guide. +4. Use the relevant page structure in Section 4. + +Before merging: + +1. Read the page once from beginning to end as a new user would. +2. Run every new command and runnable configuration when the change requires + execution verification. +3. Confirm that paths, command-line options, configuration keys, units, and + output filenames match the repository. +4. Check all capability statements against the public capability matrix. +5. Remove internal project-management language and unsupported claims. +6. Confirm that links, equations, tables, images, and code blocks render. +7. Keep limitations and experimental status visible. + +Passing a documentation build confirms that the page renders. It does not +confirm that a scientific claim or numerical result is correct. + +## 2. Voice and audience + +Write as a researcher explaining a numerical method to another researcher. +Use direct, neutral language. Be precise without assuming that the reader +already knows the repository. + +- Put one main idea in each sentence. +- Prefer sentences shorter than 30 words. Split sentences longer than 40. +- Introduce a term before using its abbreviation. +- State what the software does before discussing implementation details. +- Explain why a command, parameter, or numerical choice matters. +- Give a limitation once in the most relevant location. +- Use positive statements without hiding unsupported cases. +- Distinguish mathematical properties, implementation choices, numerical + results, and physical validation. +- Avoid conversational filler, exaggerated language, and sales language. +- Address the reader as `you` in step-by-step instructions when this improves + clarity. Use impersonal academic prose for theory and method descriptions. + +A technical paragraph should normally follow this order: + +1. Setup or question. +2. Method or operation. +3. Result or expected output. +4. Meaning and stated scope. + +## 3. Academic language + +### 3.1 UK English + +Use UK English except in code identifiers, software names, quotations, and +external taxonomy names. + +Preferred forms include: + +- optimisation, regularisation, discretisation, normalisation; +- behaviour, colour; +- centre, centred; +- modelling, labelled; +- analyse, summarise; +- artefact in ordinary prose. + +Do not rename code identifiers to enforce UK spelling. + +### 3.2 Punctuation and typography + +- Do not use em dashes. Use a comma, parentheses, or a separate sentence. +- Use hyphens consistently in terms such as `phase-field`, `finite-element`, + `load-displacement`, and `matrix-free`. +- Use commas as thousands separators in Markdown, for example `10,300`. +- Put spaces between numerical values and units in prose. +- Define symbols and units at first use on each self-contained page. +- Use `$G_c$` for fracture toughness and `$\ell_0$` for the regularisation + length in Markdown equations. +- Do not use raw LaTeX commands outside supported mathematics delimiters. + +### 3.3 Remove filler + +Delete phrases that delay the technical statement: + +- importantly; +- notably; +- crucially; +- it is worth noting that; +- it can be observed that; +- it is clear that; +- needless to say; +- as everyone knows. + +Write the fact directly. + +## 4. Page structures + +### 4.1 Tutorial + +A tutorial should contain: + +1. Purpose and learning outcome. +2. Prerequisites. +3. Required files and working directory. +4. Geometry and mesh. +5. Material and phase-field parameters. +6. Loads and boundary conditions. +7. Solver selection and convergence settings. +8. Exact execution command. +9. Expected outputs. +10. Visualisation and physical interpretation. +11. Limitations and supported variations. +12. A small next experiment. + +Do not hide essential setup in an earlier tutorial unless the dependency is +explicitly linked. + +### 4.2 Installation guide + +An installation guide should contain: + +1. Supported or tested operating systems and Python versions. +2. The recommended installation route first. +3. Alternative routes and their additional requirements. +4. Exact commands from a clean environment. +5. A short verification command. +6. Expected success output. +7. Common errors and recovery steps. +8. Optional backend requirements. + +Do not call installation easy, simple, or one-command unless the documented +procedure demonstrates that statement on the stated platforms. + +### 4.3 Reference page + +A reference page should contain: + +1. Purpose. +2. Capability status. +3. Inputs, types, defaults, and units. +4. Supported combinations. +5. Outputs and side effects. +6. Errors and failure conditions. +7. A minimal valid example. +8. Links to relevant tutorials and implementation notes. + +Reference pages should be complete enough to use without reading source code. + +### 4.4 Explanation or theory page + +An explanation page should proceed from the physical model to the numerical +method and then to the PhAST implementation: + +1. Physical question and assumptions. +2. Governing equations. +3. Definition of every symbol and unit. +4. Spatial and temporal discretisation. +5. Coupling and solution procedure. +6. Configuration keys controlling the implementation. +7. Numerical limitations and validation scope. + +Do not present a mathematical formulation as implemented unless the code and +configuration route support it. + +### 4.5 Root README + +The root README should remain concise. It should contain: + +1. A one-paragraph description of PhAST. +2. Current supported scope and important boundaries. +3. The shortest verified installation and first-run commands. +4. Links to the documentation, examples, capability matrix, citation, + licence, contribution guide, and issue tracker. +5. One representative result or visual with a precise caption. + +Do not duplicate the complete theory, configuration reference, or every +example in the root README. + +### 4.6 Example README + +Every runnable example README should state: + +1. The physical problem and benchmark identifier. +2. Geometry and dimensionality. +3. Material and phase-field formulation. +4. Loading and boundary conditions. +5. Mesh scale relative to `$\ell_0$`. +6. Solver route and important tolerances. +7. Exact command from a stated working directory. +8. Expected runtime only when measured on stated hardware. +9. Expected output files. +10. Which outputs are included in the repository. +11. What comparison or validation supports the example. +12. Known limitations. + +Clearly distinguish runnable inputs from retained outputs, manifests, +contracts, schemas, and templates. + +## 5. Internal vocabulary and public replacements + +Do not expose release engineering, issue tracking, or private research +shorthand in ordinary public prose. + +| Avoid in narrative prose | Prefer | +| --- | --- | +| gate, configured gate | verification criterion, validation condition | +| lane | solver path, execution path, workstream | +| tracker | issue, task list, status page | +| receipt | run record, metadata record | +| smoke test | installation check, short verification calculation | +| paper-grade | publication-quality | +| production route | supported solver path | +| production-ready | supported for the documented scope | +| promote, demote | change the documented capability status | +| claim boundary | stated scope or limitation | +| payload | released files, package contents | +| accepted target | converged load increment | +| accepted state | converged state | +| source-locked result | result tied to the stated source revision | +| fail closed | stop with an error when verification cannot be completed | +| safe subcycling | damage subcycling with the stated interval | +| job ID in visible prose | omit it or place it in a reproducibility record | + +Use the exact filename or identifier when the reader needs it to run a +command, inspect an output, or reproduce a result. + +## 6. Words to avoid + +Avoid these words in authored narrative because they are usually vague, +promotional, or associated with formulaic writing: + +```text +beacon +bespoke +cornerstone +crucial +delve +foster +game-changing +groundbreaking +harness +holistic +interplay +leverage +leveraging +massive +meticulous +notably +novel +paradigm +paramount +pivotal +revolutionise +seamless +showcase +streamlined +tapestry +testament +underscores +utilise +vital +``` + +Replace the word with the exact technical statement. For example, replace +`a groundbreaking acceleration strategy` with `the method reduced wall time +from X to Y for the stated benchmark and hardware`. + +The list is a writing prompt, not a blind text-replacement rule. Verbatim +quotations, titles, citations, filenames, code, and external project names +are exempt. + +## 7. Context-sensitive technical words + +The following words are valid when they have a precise software or numerical +meaning. Do not ban them globally. + +| Word | Appropriate use | +| --- | --- | +| diagnostic | the documented purpose of `phast doctor`, `precheck`, or a numerical check | +| trajectory | a defined stored time or load sequence | +| provenance | source revision, configuration, and data origin needed for reproducibility | +| artefact or artifact | a generated package, CI artefact, or literal API/file-format term | +| workflow | a GitHub Actions workflow or a clearly defined sequence of operations | +| terminal | instructions that require a command-line terminal | +| proxy | a defined mathematical or computational surrogate measure | +| evidence | an academic argument supported by stated results, not a synonym for files | +| protocol | a formally defined numerical or experimental procedure | + +Prefer a more specific term whenever one exists. + +## 8. Canonical PhAST terminology + +| Concept | Public wording | +| --- | --- | +| Package name | PhAST | +| Framework | modular tensor-based finite-element framework | +| Primary application | phase-field fracture | +| Coupling | staggered solution scheme | +| Damage equation | damage subproblem or phase-field subproblem | +| Mechanics equation | mechanics subproblem | +| Amor model | Amor tension-compression split at first use, then Amor split | +| Miehe model | Miehe spectral split | +| AT2 bound treatment | post-solve projection to `$[d_n,1]$`, then post-clamping | +| AT1 bound treatment | projected conjugate gradients, then projected CG | +| Explicit route | explicit dynamics with the integrator named | +| Quasi-static route | implicit equilibrium solve within the staggered scheme | +| Learned proposal | learned damage proposal followed by the documented checks | +| Learned replacement | audited learned damage replacement with classical fallback | +| Subcycling | damage subcycling with interval `$N$` | +| Fracture toughness | `$G_c$`, with units defined | +| Regularisation length | `$\ell_0$`, with units defined | + +Use `subproblem` rather than `sub-problem`. + +## 9. Capability and validation statements + +Use the public maturity labels consistently: + +- **Supported** means the public pathway is documented and covered by the + stated tests and examples. +- **Beta** means an implemented pathway is available but requires + case-specific verification. +- **Experimental** means the interface may change and claims must remain + narrow. +- **Scaffold** means partial infrastructure exists without a complete public + workflow. +- **Unsupported** means the public solver does not provide the capability. + +Do not convert a passing test into a physical-validation claim. Keep these +statements separate: + +1. The code executed. +2. The nonlinear or linear solver converged to the stated criterion. +3. The result agrees with a numerical reference. +4. The result agrees with experimental measurements. +5. The method is supported beyond the tested configuration. + +Only state the levels demonstrated by the cited result. + +When comparing performance, report: + +- the complete operation being timed; +- hardware and software environment; +- precision and backend; +- mesh and problem size; +- number of repetitions and summary statistic; +- setup, solve, transfer, inference, and output costs when relevant. + +Do not describe one backend as universally fastest. + +## 10. Differentiability and learned models + +Avoid unqualified statements that PhAST differentiates every fracture +calculation. Prefer: + +> Supported tensor operations can participate in PyTorch autograd. History +> updates, bounds, active-set changes, remeshing decisions, and other +> non-smooth operations require case-specific interpretation. + +For learned damage updates, state who remains responsible for the physical +solution: + +- A learned proposal supplies an initial damage estimate. +- PhAST checks bounds, irreversibility, phase-field boundary conditions, and + the projected residual where the selected route provides those checks. +- The classical damage solver remains available as the fallback. +- No trained model is implied unless a checkpoint is distributed and linked. + +Do not call a learned model faster without measuring its complete inference, +checking, rejection, and fallback cost against the matched classical solve. + +## 11. Commands and configurations + +- Copy commands from the current CLI help. +- State the working directory when it is not the repository root. +- Use copy-ready fenced code blocks. +- Do not include shell prompts such as `$` inside copy-ready commands. +- Explain placeholders such as `CONFIG` and `OUTPUT_DIR`. +- Use public repository paths rather than private machine paths. +- Show the recommended command before optional variants. +- State whether a command validates, generates files, or executes a solve. + +For example: + +```bash +python -m phast explain-config CONFIG +python -m phast run CONFIG --validate-only +python -m phast run CONFIG --output_dir RUN +``` + +Every runnable YAML file should declare its schema version and use only +supported public keys. A file that is not directly runnable must identify +itself as a manifest, contract, schema, or template in both its filename or +heading and its surrounding documentation. + +Here `CONFIG` is an input path and `RUN` is a new result directory. +Check this sequence for the selected schema/adapter; legacy +`precheck --config` is not a universal schema-2 command. Separate physical +analysis from integration, and a step limit from final physical time. + +## 12. Inputs, outputs, and reproducibility + +Document the complete path from input to result: + +- geometry source and mesh-generation method; +- named boundaries and physical groups; +- material parameters and units; +- phase-field model and energy split; +- loads and boundary conditions; +- solver type, backend, tolerances, and step count; +- output directory and generated files; +- configuration and source revision recorded with the result. + +Do not imply that a retained image proves that its generating calculation can +be reproduced. Distinguish: + +- runnable input; +- retained numerical output; +- visualisation generated from retained output; +- manifest describing expected files; +- reference or comparison data; +- template requiring user values. + +## 13. Equations, numbers, and tables + +- Introduce each equation in prose. +- Define every symbol immediately after the equation or in a nearby table. +- State units and sign conventions. +- Connect equations to the corresponding configuration keys. +- Put more than three related numerical values in a table where practical. +- Use meaningful precision. Do not copy more digits than the result supports. +- Explain a value when it changes the scientific conclusion. +- Do not describe convergence solely through a plot. State the criterion. + +## 14. Figures and accessibility + +- Use descriptive alternative text. +- Explain what the reader should notice. +- Label axes with quantities and units. +- Use a neutral, high-contrast palette. +- Do not rely on colour alone to distinguish curves or regions. +- Use consistent symbols and colours across related pages. +- Keep captions self-contained and concise. +- Do not write `computed`, `simulated`, or `calculated` before a noun when the + context already makes this clear. +- Check figures at desktop and mobile widths. + +Animations must have a static fallback image and a short explanation of the +displayed time or load interval. + +## 15. Citations and links + +- Cite the original paper for a mathematical model or benchmark. +- Prefer primary sources and official software documentation. +- Link to the relevant PhAST page rather than duplicating long explanations. +- Check that repository URLs use `CEMS-Lab/PhAST` and documentation URLs use + `https://cems-lab.github.io/PhAST/`. +- Do not cite a paper as proof of a PhAST implementation unless the public + code and documentation implement the stated method. +- Keep the citation instructions and software citation metadata consistent. + +## 16. Limitations and user support + +State unsupported combinations directly. For example: + +> Three-dimensional fracture is not supported by the current public solver +> pathway. + +Do not hide limitations in vague positive language. Do not repeat the same +qualification after every sentence. + +End installation guides and substantial tutorials with a support statement: + +> If a documented step fails, open a GitHub issue and include the +> configuration, command, operating system, Python version, PhAST version or +> commit, and complete error output. + +Invite contributions without implying that an unsupported feature is already +planned or promised. + +## 17. Final checklist + +### Accuracy + +- [ ] Every described capability exists in the current public code. +- [ ] Maturity labels agree with the capability matrix. +- [ ] Commands and paths are current. +- [ ] Configuration keys agree with the schema. +- [ ] Units and defaults are stated correctly. +- [ ] Numerical and physical validation are not conflated. +- [ ] Optional dependencies are identified. + +### Usability + +- [ ] The intended reader and task are clear. +- [ ] Prerequisites and working directory are stated. +- [ ] Inputs, commands, and outputs form a complete sequence. +- [ ] A new user can identify the next step. +- [ ] Runnable files are separated from manifests and templates. +- [ ] Failure recovery or support information is present where needed. + +### Language + +- [ ] The prose uses UK English. +- [ ] Sentences contain one main idea. +- [ ] Internal project vocabulary has been removed. +- [ ] Promotional and formulaic words have been removed. +- [ ] Technical terms are defined and used consistently. +- [ ] Limitations remain visible. +- [ ] No em dashes are present. +- [ ] Physical mechanisms and concrete actions replace abstract promises. +- [ ] Each paragraph adds information rather than restating the aim. + +### Presentation + +- [ ] Headings describe the content below them. +- [ ] Equations and tables render correctly. +- [ ] Figures have useful captions and alternative text. +- [ ] Links resolve to public locations. +- [ ] Code blocks are copy-ready. +- [ ] The page remains readable on desktop and mobile. + +## 18. Exceptions + +Code, command output, filenames, configuration keys, API identifiers, quoted +errors, paper titles, and verbatim quotations retain their original spelling +and punctuation. Do not alter a technically meaningful identifier merely to +match prose style. + +When this guide conflicts with a file format, external standard, citation, +or required software identifier, preserve the technically correct form and +explain the exception if readers may be confused. + +## 19. Scientific writing design directives + +The preferred voice is analytical, explanatory, and restrained. Build the +argument through physical causes, named operations, observable consequences, +and appropriately limited conclusions. Precision should make the prose easier +to follow, not merely increase its technical density. + +### 19.1 Lead with the physical question + +For a research narrative, introduce the material behaviour or unresolved +question before listing computational methods. Explain why the question +matters and what existing descriptions cannot yet resolve. Then introduce +the method as a means of answering it. + +Avoid opening with a stack of descriptors such as differentiable, multiscale, +multiphysics, data-efficient, and generalisable. Retain each term where its +specific role is explained. In command references and installation pages, +continue to lead with the user's task rather than a research motivation. + +### 19.2 Make causal relationships explicit + +Prefer a short physical sequence to a list of interacting phenomena. Name +what changes, what it acts on, and what consequence is expected. Distinguish +a proposed mechanism from an observed one. + +For example, a hypothetical account might read: + +> Cracks open transport paths. Reaction at the exposed interface changes +> sliding resistance, which can alter load transfer during subsequent loading. + +Do not use a model sensitivity alone to establish a physical mechanism. +Explain which comparison, field observation, or measurement supports that +interpretation. Homogenisation transfers effective responses between scales; +differentiation evaluates how those responses depend on specified inputs. + +### 19.3 Give each paragraph a distinct job + +Use a topic sentence followed by the explanation or evidence needed to +support it. End with an implication or limitation only when it adds meaning. +Vary sentence length to preserve a readable argument; do not turn the +sentence-length guidance into disconnected short statements. + +In proposals, distinguish the jobs of adjacent sections: + +- The research gap identifies what existing work cannot yet explain. +- The question identifies what the study will investigate. +- The hypothesis states a proposition that a comparison could contradict. +- The aim states the intended contribution. +- The objectives identify the work needed to test the proposition. +- The approach explains how that work will be carried out and assessed. + +Do not make each section another version of "we will establish a framework". +Repeat a technical term when needed for accuracy, but remove repeated claims. +Do not substitute loose synonyms merely to make the prose appear varied. + +### 19.4 Replace abstract promises with actions and observations + +Use verbs such as compute, compare, calibrate, withhold, measure, and test +when they describe the actual work. Specify their objects. Words such as +establish, enable, preserve, and generalise are not prohibited, but require +an explanation of what would demonstrate the claim. + +Make the comparison legible: what is varied, what is held fixed, what is +measured, and what result would challenge the interpretation? Include a +numerical target only when it is justified. Never invent a threshold to make +a sentence sound more precise. + +Keep physical and methodological hypotheses distinct. A hypothesis about +damage mechanisms differs from a hypothesis that derivative supervision +improves prediction at a given computational cost. A negative result for +one need not invalidate the other. + +### 19.5 Match the verb to the evidence + +Use present tense for verified capabilities and established descriptions, +past tense for completed work, and future tense for proposed actions. Use +conditional language for outcomes that remain hypotheses. A confident plan +can say "we will compare" without promising "the comparison will prove". + +Keep these distinctions visible in the prose: + +- Calibration fits parameters; independent measurements test the resulting + predictions under specified conditions. +- Agreement with a reference solver assesses numerical or approximation + error; it does not independently validate the physical model. +- An unseen combination within sampled ranges differs from extrapolation + beyond those ranges or transfer to another material. +- A preliminary calculation demonstrates only the operations and responses + actually assessed, even if its visualisation resembles a final result. + +Place a material limitation next to the claim it qualifies. State it once +clearly, and repeat it only where a figure or section must stand alone. +Preserve unresolved convergence, energy balance, validation, and scope +limitations during editing. Do not replace them with vague assurances. + +### 19.6 Use technical terms according to their role + +| Term | Writing directive | +| --- | --- | +| Differentiable | Describe the formulation or verified mathematical property, with its domain of validity. | +| Automatic differentiation | Name the computational technique when that is the technique used. | +| Sensitivity | Identify the response and physical input being differentiated. | +| Constitutive tangent | Identify the constitutive update and which prior states are held fixed. | +| Gradient | Name the differentiated quantity; distinguish optimisation gradients from physical-response sensitivities. | +| History dependence | State which earlier changes affect the later response and how this is assessed. | +| Generalisation | Identify the withheld conditions, sampled ranges, and any extrapolation. | + +Use the simplest accurate term for the passage. Do not add implementation +details unless they explain the method, its assessment, or a limitation. + +### 19.7 Describe feasibility and impact through concrete commitments + +For proposed work, connect each difficult step to its required input, +assessment, and useful outcome. If success is uncertain, explain what narrower +result remains achievable. "Revise the model" is a possible activity, not a +complete description of a fallback outcome. + +Distinguish a measured runtime for one example from the estimated workload +of a research programme. Identify assumptions when extrapolating costs. +Do not turn a writing edit into a new scientific or resource commitment. + +For impact, name the intended user, the decision the output could inform, +and the further testing or adoption needed. Keep long-term sector benefits +separate from project deliverables. Use policy and investment figures +selectively; they establish context but do not substitute for a use case. + +### 19.8 Make tables and figures carry specific information + +Use a table for repeated mappings, such as measurement source, calibration +use, independent assessment, and conditions. Do not repeat every table entry +in the surrounding paragraph. Explain the relationship or gap that matters. + +A scientific figure caption should identify the problem, quantities, +conditions, and interpretation needed to read the result. Distinguish +schematics, hypotheses, preliminary calculations, and validated comparisons. +Define visual alterations such as smoothing, exaggerated geometry, or lines +joining discrete states when they affect interpretation. + +Keep essential limitations with the figure. Move routine configuration +detail to a linked method description when appropriate; do not achieve a +shorter caption by hiding unresolved scientific issues. + +### 19.9 Remove formulaic writing without flattening the science + +Review repeated abstract nouns, identical paragraph openings, method lists, +unsupported superlatives, and stock transitions. Repair the missing meaning +before substituting words. Formal language, repetition, or polished syntax +alone cannot establish whether a person or an AI wrote a passage. + +Do not mechanically remove every passive construction or specialist term. +Use active voice to clarify who performs an action. Use passive voice when +the measured quantity or operation is the relevant subject. Preserve logical +connections and qualifications even when a shorter sentence is possible. + +## 20. Writing examples and revision checks + +The pairs below illustrate editing decisions. They are not quotations from +a manuscript, statements of current PhAST support, or approved research +commitments. Use a replacement only when its scientific content is accurate. + +| Less informative wording | More specific wording | +| --- | --- | +| We will establish a generalisable framework for coupled evolution. | We will test whether a model trained on one set of exposure histories predicts the response under withheld histories. | +| The method captures complex interactions across scales. | The tow model supplies stress and transport response to the woven equations, which determine the next local loading and exposure conditions. | +| Extensive validation will demonstrate accuracy. | Separate measurements will test the calibrated model; reference simulations will assess the additional error introduced by learning. | +| Sensitivities reveal the governing mechanism. | Sensitivities identify influential inputs within the model; paired histories and damage fields test the proposed mechanism. | +| Preliminary results demonstrate reliable failure prediction. | The preliminary calculation produces a damage field; its post-peak energy balance has not yet been established. | +| The model will generalise to new materials. | Predictions for a second material will use independently specified properties without refitting the learned weights. | +| The work will transform sustainable aerospace design. | The results could help researchers select interphase properties for subsequent material testing. | + +Before completing a scientific prose revision: + +1. Read only the opening sentences. They should form a coherent argument + without repeating the same promise. +2. Underline the main claim in each paragraph and identify its supporting + mechanism, comparison, or source. +3. Check that every proposed method has a stated purpose and that existing + results are not written as evidence for an untested extension. +4. Check that a reader can distinguish physical validation, numerical + verification, learning accuracy, and computational performance. +5. Remove duplicated explanations before deleting substantive caveats. +6. Compare the revision with the original for changes in certainty, scope, + attribution, and proposed commitments. Flag scientific changes explicitly. +7. Read the result aloud for long noun sequences, abrupt transitions, and + repeated sentence patterns. Prefer connected explanation over slogans. + +## Trajectory And Dataset Storage + +Use HDF5 (`training_data.h5`, configuration value `h5`) as the default +trajectory format in documentation, READMEs, examples, and teaching notebooks. +State that trajectory saving must be enabled where applicable; do not imply +every run writes a trajectory. + +Show Zarr only as an explicit alternative for a workflow that requires it. +Do not describe HDF5 as legacy-only or Zarr as the preferred default. Keep +commands, expected filenames, readers, and manifests consistent with the +selected format. Preserve the recorded format of historical results, and do +not relabel saved notebook output as evidence of an HDF5 run without rerunning +it. Clear stale outputs when changing a notebook's storage backend. + +A single HDF5 file reduces the number of files to synchronise. It does not +make simultaneous writes from different machines safe. diff --git a/README.md b/README.md index 791adff7d..ff950dd86 100644 --- a/README.md +++ b/README.md @@ -6,9 +6,7 @@

Phase-field Autograd Solver in Torch
- A matrix-free, differentiable PyTorch solver for phase-field fracture and FEM benchmarks. -

- PhAST is a matrix-free, differentiable PyTorch solver for phase-field fracture. + A matrix-free, differentiable PyTorch finite-element solver for two-dimensional phase-field fracture.

@@ -55,9 +53,10 @@ controls, and requested outputs in one reviewable file. with PyTorch autograd where documented, enabling carefully interpreted sensitivity studies. - **Phase-Field Fracture Focus:** Dynamic impact, crack branching, and quasi-static fracture workflows share a consistent mechanics/damage formulation and output schema. -- **Public Benchmark Bundles:** Public examples provide `config.yaml`, setup figures, final field plots, response histories, manifests, and compact animations. Numerical fields are reloadable only when the result bundle retains a trajectory store. +- **Documented Examples:** Examples provide `config.yaml`, setup figures, final field plots, response histories, manifests, and compact animations. Numerical fields can be reloaded when the result directory contains a trajectory store. - **YAML Plus Fluent API:** Use declarative YAML for reproducible runs and `phast.Problem` for programmatic model authoring. -- **Standardized Post-Processing:** `phast.load_result` handles stored manifests, CSV histories, visuals, and retained trajectory fields. +- **Standardised Post-Processing:** `phast.load_result` reads stored manifests, CSV histories, visualisations, and available trajectory fields. +- **Single-File Trajectories:** When enabled, trajectory output defaults to HDF5 (`training_data.h5`). Zarr remains available by explicit selection. ## How The Solver Works @@ -65,8 +64,8 @@ controls, and requested outputs in one reviewable file. For a phase-field fracture run, PhAST constructs or imports a two-dimensional finite-element mesh, evaluates the mechanical state, updates the tensile -history field, solves the regularized damage problem, enforces damage bounds -and irreversibility, and writes fields, histories, manifests, and provenance. +history field, solves the regularised damage problem, enforces damage bounds +and irreversibility, and writes fields, histories, manifests, and run metadata. Explicit dynamics and quasi-static fracture use different mechanics updates; the [solver overview](docs/user_guide/overview.md) and [formulation guide](docs/user_guide/physics.md) describe both pathways. @@ -77,19 +76,25 @@ If you are new to PhAST, follow this sequence: 1. Read the [phase-field primer](docs/tutorial/01_phase_field_primer.md) if the formulation is new to you. -2. Follow the [installation and first-run guide](docs/getting-started.md). -3. Validate a fracture YAML before allocating a full simulation. -4. Run the small linear-elastic example to verify end-to-end execution and - result loading. +2. Follow the [standard simulation tutorial](docs/tutorial/07_standard_simulation_workflow.md) + for source installation and the common editable YAML layout. +3. Explain and check a fracture input before allocating a full simulation. +4. Run the small linear-elastic example to check solver execution and result + loading on the current machine. 5. Consult the [capability matrix](docs/user_guide/capability_matrix.md) before selecting a model for research use. ## Quickstart +Install Python 3.10 or newer and Git first. These commands install the source +checkout you clone; they do not assert that it is the latest release. + +On macOS or Linux: + ```bash git clone https://github.com/CEMS-Lab/PhAST.git cd PhAST -python3.11 -m venv .venv +python3 -m venv .venv source .venv/bin/activate python -m pip install --upgrade pip python -m pip install -e . @@ -97,10 +102,36 @@ python -m pip install -e . python -m phast doctor ``` -PhAST requires Python 3.10 or newer; Python 3.11 is recommended for a first -source installation. Continuous integration currently verifies Python -3.10-3.12, so later Python versions are permitted but not yet part of the -regular test matrix. +On Windows PowerShell: + +```powershell +git clone https://github.com/CEMS-Lab/PhAST.git +cd PhAST +py -3 -m venv .venv +.\.venv\Scripts\python.exe -m pip install --upgrade pip +.\.venv\Scripts\python.exe -m pip install -e . +.\.venv\Scripts\Activate.ps1 +python -m phast doctor +``` + +Ensure `python3` or `py -3` selects Python 3.10 or newer. If activation +is blocked on Windows, use `.\.venv\Scripts\python.exe` instead of +`python` in subsequent commands; do not change system policy. + +Editable installation already installs runtime dependencies. To install +them separately in the same environment, use: + +```bash +python -m pip install -r requirements.txt +python -m pip install -e . +``` + +The main student route is the small single-material quasi-static SENT, +small single-material dynamic SENT, and full layered DCB example in the +[standard tutorial](docs/tutorial/07_standard_simulation_workflow.md). +The new adapters and schema-2 explanation command require combined checks +before those sequences are labelled verified. Existing compatibility +examples below provide a separate established first-check route. Validate a public fracture configuration without launching a full solve: @@ -146,6 +177,14 @@ first workflow. ## Reproducible Workflows +The [standard simulation workflow](docs/tutorial/07_standard_simulation_workflow.md) +uses one schema-2 layout for editable geometry, mesh, materials, and loading. +It includes retained DCB PNG/GIF evidence and complete coarse comparison +inputs using the same CLI, not new solver drivers. The DCB result is +qualitative layered-material interaction, not calibrated inclusion bypass. +Its multi-material route is limited to CPU float64, structured-T3, +quasi-static Amor AT2, and prescribed-displacement conditions. +
@@ -178,6 +217,7 @@ Browse the full [example gallery](docs/example-gallery.md) for the complete list | Objective | Interface | Documentation Link | |---|---|---| +| Learn one editable input layout | Schema-2 student workflow | [Standard Simulation Workflow](docs/tutorial/07_standard_simulation_workflow.md) | | Author a forward model | Fluent `phast.Problem` API | [Python API](docs/user_guide/python_api.md) | | Execute public benchmarks | Declarative `config.yaml` | [YAML Workflow](docs/user_guide/yaml_workflow.md) | | Post-process simulation data | `phast.load_result(path)` | [Public API Reference](docs/user_guide/public_api_reference.md) | @@ -238,6 +278,10 @@ with [CONTRIBUTING.md](CONTRIBUTING.md), then use the [capability matrix](docs/u and [example contract](docs/user_guide/example_contract.md) to keep public claims, examples, and artifacts consistent. +New YAML examples and their READMEs/tutorials must follow +[CONFIGURATION_STYLE.md](CONFIGURATION_STYLE.md) alongside +[DOCUMENTATION_STYLE.md](DOCUMENTATION_STYLE.md). + Students, researchers, scientific-software developers, and users evaluating PhAST are invited to review the code and documentation, propose reproducible examples, and report unclear instructions. If you become stuck at any point, @@ -292,4 +336,4 @@ Official code for the manuscript is hosted in this repository: 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. -PhAST is organized with reproducible scientific computing in mind. Machine-readable manifests, structured result metadata, headless CLI/API entry points, and repository-level guidance files are provided so researchers can inspect, reproduce, and extend simulations without relying on hidden local state. These files are engineering aids; the scientific claims and solver validity remain governed by the documented formulations, tests, and validation artifacts above. +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/configs/REFERENCE.yaml b/configs/REFERENCE.yaml index 84c09c573..6594a436c 100644 --- a/configs/REFERENCE.yaml +++ b/configs/REFERENCE.yaml @@ -406,7 +406,7 @@ output: # output_dir: null # str or null # h5: false # bool # trajectory: false # bool - # trajectory_format: zarr # str + # trajectory_format: h5 # str # h5_every: 20 # int, range: [1, +inf] # vtu: false # bool # vtu_every: 10 # int, range: [1, +inf] diff --git a/configs/benchmarks/dynamic/B7_dynamic_crack_branching_comsol.yaml b/configs/benchmarks/dynamic/B7_dynamic_crack_branching_comsol.yaml index 814b685f6..3bf1f6da7 100644 --- a/configs/benchmarks/dynamic/B7_dynamic_crack_branching_comsol.yaml +++ b/configs/benchmarks/dynamic/B7_dynamic_crack_branching_comsol.yaml @@ -31,7 +31,7 @@ acceptance: required_outputs: - run_lockfile.json - config.yaml - - training_data.zarr + - training_data.h5 - energy.csv - crack_tip.csv - compare_report.txt diff --git a/configs/phast.schema.json b/configs/phast.schema.json index aa0a9252b..8b853691f 100644 --- a/configs/phast.schema.json +++ b/configs/phast.schema.json @@ -725,7 +725,7 @@ }, "trajectory_format": { "type": "string", - "default": "zarr" + "default": "h5" }, "h5_every": { "type": "integer", diff --git a/docs/api/public_workflow.md b/docs/api/public_workflow.md index fa52e70f4..43a5a154d 100644 --- a/docs/api/public_workflow.md +++ b/docs/api/public_workflow.md @@ -103,7 +103,7 @@ It does not select individual files or store reloadable tensor fields. Every curated public example should expose a flat, predictable result bundle: `config.yaml`, `run_manifest.json`, `visual_manifest.json`, representative -PNG/MP4 artifacts, CSV histories where relevant, and Zarr-first trajectory +PNG/MP4 artifacts, CSV histories where relevant, and HDF5 trajectory (the default) outputs when the run stores fields. See [Curated example contract](../user_guide/example_contract.md) for the artifact contract. diff --git a/docs/community.md b/docs/community.md index 99c5e78f4..3324a7aef 100644 --- a/docs/community.md +++ b/docs/community.md @@ -28,17 +28,20 @@ you do not need to identify the underlying code defect first. When opening bugs or documentation gaps, include: -- exact command and config file (if any), -- reproducibility details (PyTorch/CUDA/OS), -- minimal output snippet or traceback, -- the first failing file or assertion. +- the exact command and configuration file, if applicable; +- the PhAST version or Git commit; +- the operating system and Python, PyTorch, and CUDA versions; +- the complete first warning or traceback; and +- the first failing file or assertion, if known. Questions and partial reports are welcome. Maintainers can request additional -reproducibility information during triage. +information when investigating the issue. ## Contributing - Use `CONTRIBUTING.md` for workflow expectations and code review requirements. +- Follow `DOCUMENTATION_STYLE.md` for README, documentation, tutorial, and + notebook prose. - Keep new capability claims aligned with [capability matrix](user_guide/capability_matrix.md). - Add or update docs pages in one commit with any user-facing behavior change. diff --git a/docs/example-gallery.md b/docs/example-gallery.md index 3eb072a81..08c18416c 100644 --- a/docs/example-gallery.md +++ b/docs/example-gallery.md @@ -16,6 +16,12 @@ today. Each example-local README is authoritative for its exact command, runtime, outputs, limitations, and evidence boundary. +For the main student route, use the +[standard simulation workflow](tutorial/07_standard_simulation_workflow.md): +small quasi-static SENT, small dynamic SENT, and full layered DCB with one +schema-2 section order. New adapter checks remain a promotion gate; a short +setup exercise is not automatically a crack-growth benchmark. + ## Representative results The panels below are lightweight documentation thumbnails, not raw benchmark @@ -30,6 +36,8 @@ archives. They point to the same workflows listed in the sections that follow. | Linear plate | Supported | YAML-first | `python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml --output_dir runs/linear_plate` | response curve, displacement, von Mises, strain energy, manifests | `phast.load_result("runs/linear_plate")` | | Kalthoff-Winkler | Supported | YAML-first | `python -m phast run examples/dynamic/B2_kalthoff_winkler/config.yaml --output_dir runs/B2_kalthoff_winkler` | setup preview, damage image, energy/history CSVs, manifests | `phast.load_result("runs/B2_kalthoff_winkler")` | | Heterogeneous fields | Teaching example | Script contract | `python examples/heterogeneous_fields/run.py --config examples/heterogeneous_fields/parameters.yaml --output-dir runs/heterogeneous_fields` | elementwise `E`/`Gc` CSV, nodal damage CSV, field plots, manifests | `phast.load_result("runs/heterogeneous_fields")` | +| Layered DCB with tough disk | Beta; retained qualitative evidence | Schema-2 YAML | `python -m phast run examples/two_material_dcb_beta/config.yaml --output_dir runs/dcb_fine_reference` | HDF5, CSV, PNG/GIF, VTU, manifests | `phast.load_result("runs/dcb_fine_reference")` | +| Heterogeneous SENT | Beta configuration | Schema-2 YAML | `python -m phast run examples/heterogeneous_sent_beta/config.yaml --output_dir runs/heterogeneous_sent` | CSV, PNG/GIF, VTU, manifests; trajectory opt-in | `phast.load_result("runs/heterogeneous_sent")` | Use the [capability matrix](user_guide/capability_matrix.md) before assuming a workflow status. Use the @@ -127,6 +135,50 @@ The quasi-static family provides documented pathways for selected literature com validated microstructure-fracture study. See the example README before adapting image or segmentation data. +### DCB-style layered fracture (beta) + +- `python -m phast run examples/two_material_dcb_beta/config.yaml --output_dir runs/two_material_dcb` + runs the standard schema-v2 staggered quasi-static AT2 workflow in which a + mid-plane crack in a weak bulk layer approaches a circular Material 2 + inclusion between fracture-resistant outer regions. +- The example uses elementwise `E(x)` and `Gc(x)`, records the crack-front + coordinate and material-region damage measures, and writes a damage + animation with material boundaries and a single-file HDF5 trajectory. +- This is a beta teaching example, not ASTM D5528 calibration or + a validated bimaterial crack-deflection benchmark. The inclusion is tougher + than the weak layer, not the outer regions; its confinement is part of this + teaching model. + +```{figure} ../examples/two_material_dcb_beta/results/damage_final.png +:alt: Retained DCB final damage showing a forked crack in a weak layer near a circular tougher region. +:width: 100% + +Retained state at 0.30 mm total opening. No seed-connected nodes with +`d >= 0.80` enter the disk. Neither penetration nor completed bypass is +demonstrated; this is qualitative layered-material interaction. +``` + +The fine `160 x 48` reference has 120 accepted increments, no cutbacks, +maximum projected damage residual `6.91e-6`, and reaction `0.61495` +in the recorded unit-thickness convention. The separate `120 x 48` matched +pair changes only disk `Gc`: reactions are `0.60938` (tough region) and +`0.45847` (uniform-layer control), with shorter final advance for the tough +region. Both fork early; the disk cannot be credited with causing branching. +The control retains the weak layer and outer regions. + +Complete inputs are `examples/two_material_dcb_beta/comparisons/tough_region.yaml` +and `examples/two_material_dcb_beta/comparisons/uniform_layer.yaml`. +The [standard tutorial](tutorial/07_standard_simulation_workflow.md) gives +exact commands with separate output directories, a retained animation, and +numerical records. These inputs reuse the common runner. Independent fixed-field +review is not a solver rerun; input guards and combined execution checks +remain separate. Historical generating source identity is unknown, and the +coarse historical runs did not write HDF5. + +The documented multi-material route is structured T3 rectangles, CPU float64, +quasi-static Amor AT2, elementwise `E`/`Gc`, common `nu`/`l0`, and +Dirichlet conditions, not dynamic multi-material or independent-interface physics. + ### Beta plasticity, cohesive, and PF-CZM validation - **J2 plasticity and ductile PF-plasticity**: diff --git a/docs/getting-started.md b/docs/getting-started.md index 86bd2ac13..c8caa0394 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -1,7 +1,7 @@ # Getting Started -This is the canonical installation and first-run route. The README and tutorial -index summarize this page rather than defining separate installation contracts. +This page defines the recommended installation and first-run sequence. The +README and tutorial index provide shorter summaries of the same procedure. ## Installation Route Selector @@ -19,9 +19,9 @@ conda activate phast python run_sanitizer.py ``` -The supplied environment is a portable Python 3.11 CPU baseline. PETSc/MUMPS, +The supplied environment is a portable Python 3.11 CPU configuration. PETSc/MUMPS, CUDA, AmgX, and site-specific MPI stacks remain optional installations and are -not implied by this environment. +not included in this environment. ### CPU Docker image @@ -120,9 +120,9 @@ OK: examples/dynamic/B2_kalthoff_winkler/config.yaml passes schema validation. ``` This message means that the YAML satisfies the schema and the implemented -semantic preflight checks. It does not run a fracture solve and does not prove +consistency checks. It does not run a fracture solve and does not prove mesh convergence, benchmark reproduction, or physical validity. Review the -example README, `explain-config` warnings, retained comparison evidence, and +example README, `explain-config` warnings, published comparison results, and mesh-to-length-scale ratio before making a scientific claim. For a readable summary of the model before execution: @@ -147,8 +147,8 @@ PhAST contains several kinds of YAML file: | `examples///config.yaml` | `python -m phast run ` | Recommended starting point; a complete example-local solver input. | | `configs/benchmarks//.yaml` | `python -m phast run ` | Complete benchmark solver input. | | `configs/REFERENCE.yaml` | Not intended for execution | Field-by-field reference and template. | -| `examples/PUBLIC_EXAMPLES_CONTRACT.yaml` | Not a solver input | Documentation and artifact inventory for public examples. | -| `configs/benchmarks/plasticity_interface/reproducibility_contracts.yaml` | Requires `--validation-id` | Dispatcher manifest for beta validation scripts, not a single fracture deck. | +| `examples/PUBLIC_EXAMPLES_CONTRACT.yaml` | Not a solver input | Documentation and file inventory for published examples. | +| `configs/benchmarks/plasticity_interface/reproducibility_contracts.yaml` | Requires `--validation-id` | Index for beta validation scripts, not a single fracture input. | | `configs/phast.schema.json` | Not YAML and not executable | JSON Schema for editors and external validation. | If a file is not named `config.yaml` and is described as a contract, manifest, @@ -166,9 +166,9 @@ python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml \ ``` The example is a supporting solid-mechanics check rather than a phase-field -fracture validation case. It is used here because it provides a compact first -execution. It writes response data, metadata, manifests, and field plots; it -does not retain reloadable displacement or stress arrays in a trajectory store. +fracture validation case. It is used here because it provides a small first +simulation. It writes response data, metadata, manifests, and field plots; it +does not store reloadable displacement or stress arrays in a trajectory store. The expected finite-element tip displacement is approximately `-2.024e-6 m`, about `-14.98%` relative to the documented Euler-Bernoulli estimate. Reproducing that recorded value indicates that the compact example @@ -220,7 +220,7 @@ For a fracture simulation, PhAST: 5. updates the tensile history field used to enforce crack irreversibility; 6. solves the AT1, AT2, or documented beta damage formulation; 7. enforces damage bounds and configured boundary conditions; and -8. writes fields, histories, manifests, configuration provenance, and visuals. +8. writes fields, histories, manifests, resolved configuration data, and visualisations. Read [User Guide Overview](user_guide/overview.md) for the software pathway and [Physics, Units, and Formulation](user_guide/physics.md) for the governing @@ -268,8 +268,9 @@ the problem remains or the instructions are unclear. Include: - the exact command; - the YAML path; - operating system and Python/PyTorch versions; +- the PhAST version or Git commit; - relevant `python -m phast doctor` output; and -- the first warning or traceback. +- the complete first warning or traceback. Students and first-time users are explicitly welcome to ask installation and usage questions. An unclear step is a documentation defect worth reporting. diff --git a/docs/index.md b/docs/index.md index 75cecf860..a013a8a6e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -26,6 +26,7 @@

Get started + Standard simulation workflow View examples Capability matrix Source on GitHub @@ -83,6 +84,7 @@ python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml --out |---|---| | [Install](install.md) | Recommended source, Conda, and Docker routes. | | [Getting started](getting-started.md) | Installation, `phast doctor`, validation, first run, and result inspection. | +| [Standard simulation workflow](tutorial/07_standard_simulation_workflow.md) | One student-readable schema-2 layout, editable geometry/mesh/materials, short SENT exercises, and full retained DCB evidence. | | [Verify install](verify-install.md) | Environment discovery, sanitizer, configuration preflight, and completed-run checks. | | [User guide](user_guide/overview.md) | Problem setup, YAML, Python API, physics, meshes, sparse solves, and result APIs. | | [Example gallery](example-gallery.md) | Runnable fracture, solid-mechanics, and beta validation examples with visual outputs. | @@ -97,9 +99,9 @@ If you are new to PhAST, follow one continuous route: 1. **Install and diagnose the environment:** Use [Install](install.md), then run the sanitizer and `python -m phast doctor`. 2. **Complete a bounded solve:** Run the linear-plate example and inspect its result directory. 3. **Learn the formulation:** Read the [Phase-Field Primer](tutorial/01_phase_field_primer.md) and [Visual Glossary](tutorial/02_visual_glossary.md). -4. **Construct a model:** Work through the [problem-setup notebook](tutorial/notebook_setup.ipynb) and the [Python API](user_guide/python_api.md). +4. **Run a complete fracture workflow:** Work through the [square-plate fracture notebook](tutorial/notebook_square_plate_fracture.ipynb), then use the [problem-setup notebook](tutorial/notebook_setup.ipynb) and [Python API](user_guide/python_api.md) when constructing a new model. 5. **Check the capability boundary:** Review the [Capability Matrix](user_guide/capability_matrix.md) before selecting a fracture, beta, or experimental route. -6. **Progress to fracture and heterogeneity:** Use the tutorial sequence and example-local READMEs, which state runtime and evidence boundaries. +6. **Use the common student route:** Follow the [standard simulation workflow](tutorial/07_standard_simulation_workflow.md): small quasi-static SENT, small dynamic SENT, then the full layered DCB. It distinguishes pending adapter checks, setup exercises, and retained crack-growth evidence. ## Which Path Should I Use? @@ -108,6 +110,7 @@ If you are new to PhAST, follow one continuous route: | Install and run a first case | [Install](install.md) and [Getting started](getting-started.md) | `python run_sanitizer.py` followed by `python -m phast doctor` | | Author new models | [Python API](user_guide/python_api.md) and [Setting up problems](user_guide/setup_problems.md) | `phast.Problem` | | Reproduce or batch-run examples | [YAML workflow](user_guide/yaml_workflow.md) | `python -m phast run config.yaml` | +| Edit a standard student problem | [Standard simulation workflow](tutorial/07_standard_simulation_workflow.md) | Schema-2 sections with route-specific capability checks | | Inspect completed runs | [Public API reference](user_guide/public_api_reference.md) | `phast.load_result(path)` | | Browse runnable examples | [Example gallery](example-gallery.md) | flat public example folders | | Diagnose failed runs | [Troubleshooting](troubleshooting.md) | units, mesh, backend, and output checks | @@ -139,6 +142,7 @@ troubleshooting tutorial/index tutorial/01_phase_field_primer tutorial/02_visual_glossary +tutorial/notebook_square_plate_fracture tutorial/notebook_dynamic_sent tutorial/notebook_setup tutorial/notebook_mesh_resolution @@ -147,6 +151,7 @@ tutorial/03_modular_fem_and_learned_damage tutorial/04_exploration_experiments tutorial/05_heterogeneous_material_fields tutorial/06_first_research_study +tutorial/07_standard_simulation_workflow ``` ```{toctree} diff --git a/docs/install.md b/docs/install.md index 79b894be3..f4258b497 100644 --- a/docs/install.md +++ b/docs/install.md @@ -10,9 +10,9 @@ PETSc/MUMPS, GPU direct solvers, and other HPC backends remain optional. | Platform | Python | Public CI status | Recommended first route | |---|---:|---|---| -| Ubuntu | 3.10, 3.11, 3.12 | Package and public tests | CPU float64 | -| macOS | 3.11 | Package and public tests | CPU float64; inspect MPS separately | -| Windows | 3.11 | Package and public tests | CPU float64 | +| Ubuntu | 3.10, 3.11, 3.12 | Package and repository tests | CPU float64 | +| macOS | 3.11 | Package and repository tests | CPU float64; evaluate MPS separately | +| Windows | 3.11 | Package and repository tests | CPU float64 | | CUDA Linux | Environment-dependent | Not part of the portable CI matrix | Run `doctor`, sanitizer, then a bounded case | | HPC optional backends | Site-dependent | Not part of the portable CI matrix | Validate against the site module and scheduler environment | @@ -68,8 +68,8 @@ Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass ## Docker -The repository image is a portable CPU route for the bounded installation -check. It does not start a fracture simulation: +The repository image provides a portable CPU environment for the small +installation check. It does not start a fracture simulation: ```bash git clone https://github.com/CEMS-Lab/PhAST.git @@ -114,12 +114,13 @@ docker run --rm -it --cpus 2 --memory 4g --entrypoint /bin/sh phast:local ## Verify before running a simulation -Use the [verification ladder](verify-install.md): doctor, sanitizer, -`--validate-only`, then a deliberately selected completed run. Use an explicit -output directory for completed runs and inspect the resulting manifest and -metadata. A preflight pass does not establish runtime or scientific validity. +Use the [installation verification sequence](verify-install.md): run `doctor`, +the sanitizer, `--validate-only`, and then a deliberately selected example. +Use an explicit output directory and inspect the resulting manifest and +metadata. Configuration validation alone does not establish numerical accuracy +or physical validity. -If installation fails, retain the first traceback and consult +If installation fails, record the complete first traceback and consult [Troubleshooting](troubleshooting.md). Optional backend installation should be deferred until the doctor shows that the intended workflow needs it. @@ -134,5 +135,5 @@ deferred until the doctor shows that the intended workflow needs it. | Example path not found | Run repository-relative commands from the repository root. | | Permission denied for output | Select a writable `--output_dir`; do not write into the installed package directory. | -Preserve the first traceback. Opening a question issue is appropriate whenever +Preserve the complete first traceback. Opening a question issue is appropriate whenever the documented recovery step does not resolve it. diff --git a/docs/performance-reproducibility.md b/docs/performance-reproducibility.md index 4d612f84d..2371d1b61 100644 --- a/docs/performance-reproducibility.md +++ b/docs/performance-reproducibility.md @@ -37,7 +37,7 @@ metadata, lockfile, CSV histories, and visuals kept together. 2. Run with an explicit `--output_dir`. 3. Keep `run_manifest.json`, `run_metadata.json`, `run_lockfile.json`, CSVs, visuals, and `visual_manifest.json` together. -4. Store `training_data.zarr` trajectories outside git unless they are +4. Store `training_data.h5` trajectories outside git unless they are intentionally published as external release artifacts. 5. Inspect outputs with `phast.load_result(path)`. diff --git a/docs/reference/cli.md b/docs/reference/cli.md index 9fc80a62f..8c2acf88d 100644 --- a/docs/reference/cli.md +++ b/docs/reference/cli.md @@ -36,7 +36,7 @@ python -m phast precheck examples/dynamic/B2_kalthoff_winkler/config.yaml python -m phast explain-config examples/dynamic/B2_kalthoff_winkler/config.yaml python -m phast precheck --config examples/dynamic/B2_kalthoff_winkler/config.yaml python -m phast run config.yaml --validate-only -python -m phast run config.yaml --device cuda --trajectory-format zarr +python -m phast run config.yaml --device cuda --trajectory --trajectory-format h5 python -m phast schema --output configs/phast.schema.json python -m phast doctor python -m phast postprocess runs/example --dpi 300 diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md index ec9418601..d2dddd1f7 100644 --- a/docs/reference/configuration.md +++ b/docs/reference/configuration.md @@ -30,7 +30,7 @@ validity. `solver.solver_type` selects the analysis family. `solver.backend` controls linear-solver backend dispatch where supported; `solver.preconditioner` selects a preconditioning choice where supported. `solver.time_integrator` accepts the implemented central-difference route and documented aliases; reserved routes remain bounded by their implementation. -`output.trajectory: true` enables snapshots, with `output.trajectory_format: zarr` preferred and `h5` retained for legacy compatibility. `output.plots`, `gif`, `vtu`, and `viz_format` control visual products where the selected route supports them. These settings do not make a field reloadable unless the corresponding trajectory or stored field exists. +`output.trajectory: true` enables snapshots, with `output.trajectory_format: h5` as the default single-file format; `zarr` and `both` require explicit selection. `output.plots`, `gif`, `vtu`, and `viz_format` control visual products where the selected route supports them. These settings do not make a field reloadable unless the corresponding trajectory or stored field exists. `device.device` can request `cpu`, `cuda`, or `mps` when supported. A material-aware or backend-aware fallback may change the runtime route; inspect the run metadata and manifest rather than inferring it from the request. diff --git a/docs/tutorial/07_standard_simulation_workflow.md b/docs/tutorial/07_standard_simulation_workflow.md new file mode 100644 index 000000000..929cd7522 --- /dev/null +++ b/docs/tutorial/07_standard_simulation_workflow.md @@ -0,0 +1,424 @@ +# One configuration workflow for student simulations + +This tutorial teaches how to read, run, and change a PhAST problem without +writing a solver loop. It assumes basic knowledge of stress, strain, and +boundary conditions. Read the [phase-field primer](01_phase_field_primer.md) +if a smooth damage field is unfamiliar. + +Use the same sequence for each problem: geometry, regions, materials, +assignments, initial conditions, boundary conditions, analysis, solver, and +outputs. A shared input layout does not make every combination of physics +available. + +## 1. Install from source + +Install **Python 3.10 or newer** and Git. An internet connection is needed +for installation. These commands install the checkout you clone; they do not +identify it as the latest release. Run subsequent commands from the repository +root, where `pyproject.toml` and `examples/` are located. + +### macOS or Linux + +```bash +git clone https://github.com/CEMS-Lab/PhAST.git +cd PhAST +python3 -m venv .venv +source .venv/bin/activate +python -m pip install --upgrade pip +python -m pip install -e . +python -m phast doctor +``` + +Ensure `python3` selects Python 3.10 or newer. A virtual environment keeps +dependencies separate from other projects; editable installation uses the +source in this checkout. + +### Windows PowerShell + +```powershell +git clone https://github.com/CEMS-Lab/PhAST.git +cd PhAST +py -3 -m venv .venv +.\.venv\Scripts\python.exe -m pip install --upgrade pip +.\.venv\Scripts\python.exe -m pip install -e . +.\.venv\Scripts\Activate.ps1 +python -m phast doctor +``` + +Ensure `py -3` selects Python 3.10 or newer. If local policy blocks +activation, do not change system policy for this lesson. Replace `python` +in subsequent commands with `.\.venv\Scripts\python.exe`; activation +is unnecessary with that form. + +### Dependencies installed separately + +Editable installation already installs the declared runtime dependencies. +Environments that manage dependencies separately can use this sequence in +the same virtual environment: + +```bash +python -m pip install -r requirements.txt +python -m pip install -e . +``` + +Optional GPU/HPC solvers are not prerequisites for the CPU teaching route. +Install `requirements-docs.txt` only if you need to build the website. + +## 2. Follow the three-problem teaching route + +| Configuration | Physical question | Evidence boundary | +|---|---|---| +| `examples/standard_workflow/quasistatic_sent/config.yaml` | How is a small single-material single-edge-notched tension (SENT) problem loaded without inertia? | Short setup exercise; adapter and exact CLI checks must be recorded before promotion. | +| `examples/standard_workflow/dynamic_sent/config.yaml` | How does a single-material SENT setup include inertia and explicit time integration? | Short setup exercise; successful execution is not implied by this path or by a completed quasi-static run. | +| `examples/two_material_dcb_beta/config.yaml` | How does a crack interact with a tougher disk inside a weak bulk layer? | Full retained calculation and coarse matched control; qualitative evidence, not calibrated inclusion bypass. | + +The first two inputs use the same schema as the DCB example. Their combined +implementation and execution checks remain a release requirement; this page +does not claim those checks have passed. A short exercise may show correct +setup and output without appreciable new crack growth. The additional +`examples/heterogeneous_sent_beta/config.yaml` applies the layout to a +multi-material square plate. + +Frozen historical course assets and separate 3D research keep their own +inputs. They are not migrated into this public route without adapters and +evidence. + +## 3. Explain, check, and run the same input + +Use this exact command shape for every supported standard example: + +```bash +python -m phast explain-config CONFIG +python -m phast run CONFIG --validate-only +python -m phast run CONFIG --output_dir RUN +``` + +`CONFIG` is a complete YAML path and `RUN` is a new output directory. +They are placeholders, not shell variables. For the small quasi-static +exercise, the corresponding commands are: + +```bash +python -m phast explain-config examples/standard_workflow/quasistatic_sent/config.yaml +python -m phast run examples/standard_workflow/quasistatic_sent/config.yaml --validate-only +python -m phast run examples/standard_workflow/quasistatic_sent/config.yaml --output_dir runs/standard_quasistatic_sent +``` + +For the dynamic exercise: + +```bash +python -m phast explain-config examples/standard_workflow/dynamic_sent/config.yaml +python -m phast run examples/standard_workflow/dynamic_sent/config.yaml --validate-only +python -m phast run examples/standard_workflow/dynamic_sent/config.yaml --output_dir runs/standard_dynamic_sent +``` + +For the full fine-mesh DCB reference: + +```bash +python -m phast explain-config examples/two_material_dcb_beta/config.yaml +python -m phast run examples/two_material_dcb_beta/config.yaml --validate-only +python -m phast run examples/two_material_dcb_beta/config.yaml --output_dir runs/dcb_fine_reference +``` + +The explanation command describes the input. `--validate-only` checks +implemented schema/workflow constraints without solving. For multi-material +inputs, this includes constructing the geometric mesh to check region +selections, material assignments, and boundary conditions. The last command +executes the model. Input validation is not evidence of numerical convergence +or physical accuracy. Do not change `schema_version` to hide +an unsupported command; legacy `precheck --config` is not a universal +schema-2 replacement. + +The retained DCB reference took about 968 seconds on its recorded CPU run, +not a runtime promise for your machine. Use a fresh directory for each +rerun; its trajectory writer refuses to overwrite `training_data.h5`. + +## 4. Read the sections in the same order + +Open the {download}`complete DCB input <../../examples/two_material_dcb_beta/config.yaml>`. + +| Section | Meaning in this example | +|---|---| +| `schema_version`, `name`, `reference` | Schema 2, the problem identity, and its teaching scope. | +| `geometry` | A 6.0 mm by 1.2 mm rectangle, origin `(0, -0.6)`, with `160 x 48` cells split into three-node triangles (T3). | +| `regions` | Element selections for materials and node selections for the crack, clamp, and loading. | +| `materials` | Named elastic and fracture properties. | +| `assignments` | One material for every element, without gaps or overlap. | +| `initial_conditions` | Starting damage; on this multi-material route the selected values remain constrained. | +| `boundary_conditions` | Right-edge clamp and opposite left-edge opening displacements. | +| `analysis_steps` | Physical analysis, active conditions, and loading controls. | +| `solver` | Algorithms, tolerances, and iteration/cutback limits. | +| `outputs` | Result directory, fields, histories, and visuals. | + +Use the {download}`configuration authoring rules <../../CONFIGURATION_STYLE.md>` +for new inputs. Older schema-1 benchmarks use singular `material`, +`loading`, and `output` sections. Do not mix the two layouts or migrate a +file by changing its version number alone. + +## 5. Edit geometry and mesh with their dependent selections + +Geometry is the specimen shape. A mesh divides it into elements on which +the equations are approximated. Changing `nx` or `ny` refines the +structured mesh without changing the declared dimensions. + +| Edit | Related inputs to inspect | +|---|---| +| Rectangle length | The `right_clamp` selector uses `side: right` and follows the edge. Adjust both layer rectangles and reconsider disk and crack positions. | +| Height or origin | Update layer extents, loading bounds, boundary coordinates, and crack coordinates. | +| Disk centre or radius | Keep the `circle` and every complementary `outside_circle` selector identical; check layer clearance. | +| `nx` or `ny` | Confirm that crack/load selections still contain nodes and material regions contain elements. | +| Starter crack | Update its `from`, `to`, and selection `thickness`; do not prescribe a desired future path. | + +The line selector's `thickness` is a selection distance, not a physical +crack opening. Changing mesh rows can remove nodes from the mid-plane, +leaving a narrow selection empty. A preflight does not check the generated +mesh; inspect selection errors and the setup/material plots after a run. + +Materials are assigned at **element centroids**. A circular selector does +not produce a conforming curved interface. Its discrete representation can +change with the mesh. + +State how mesh size `h` is measured when reporting `h/l0`. The fine DCB +maximum triangle edge is about `0.0451 mm`, with `l0 = 0.10 mm`, giving +`h/l0 = 0.451`. This is not a universal convergence guarantee. Compare +forces and crack paths across meshes at fixed physical inputs and examine +load-increment sensitivity. Changing `l0` changes the regularised model, +not merely the mesh. + +## 6. Change stiffness and fracture resistance independently + +The historical DCB folder name contains "two material", but its input has +three bulk regions: + +| Region | `E` [MPa] | `Gc` [N/mm] | +|---|---:|---:| +| Fracture-resistant outer regions | 5000 | 1.00 | +| Weak mid-plane layer | 5000 | 0.04 | +| Circular region | 5000 | 0.12 | + +`E` is Young's modulus: it controls elastic stiffness and affects stress +redistribution and stored elastic energy. `Gc` is fracture energy per new +crack area: it controls energetic resistance to damage. Increasing `Gc` +does not increase initial elastic stiffness; increasing `E` does not by +itself make a material tougher. Neither change guarantees a particular path. + +For a toughness comparison, change only the disk's `Gc`; keep `E`, +geometry, mesh, loading, and tolerances fixed. For a stiffness question, +vary only `E` first. The retained DCB has equal `E` throughout and is not +evidence of a stiffness-inclusion effect. + +The documented multi-material route is limited to structured T3 rectangles, +CPU float64, elementwise `E`/`Gc`, common `nu`/`l0`, shared Amor AT2 +constitutive settings, and Dirichlet (prescribed-value) conditions. Keep +plane-stress and other shared settings consistent. A bulk-property boundary +is not an independently calibrated interface or debonding law. Do not infer +dynamic multi-material, arbitrary imported-mesh, or 3D support from this +layout. + +### Units + +These inputs use mm for lengths/displacements, MPa (`N/mm^2`) for `E`, +and `N/mm` for `Gc`. Strain, damage, and `nu` are dimensionless. +Reactions use the runner's unit-thickness convention; declare out-of-plane +thickness before comparing measured forces. `geometry.units: mm` does not +convert arbitrary bare numbers elsewhere in a schema-2 file. + +Dynamics requires consistent time and density. In an mm-N-s system, density +is in tonne/mm^3. The illustrative `rho: 1.0` in the quasi-static DCB/SENT +inputs is not calibrated density and must not be copied into a physical +dynamic model without justification and conversion. + +## 7. Separate physical analysis from integration + +**Quasi-static analysis** neglects inertia and finds equilibrium at successive +loads. Its load factor is not physical time. The DCB uses +`analysis_steps[0].type: quasi_static` and a staggered quasi-static solver. + +**Dynamics** includes inertia, density, and physical time. Explicit integration +advances motion subject to a Courant-Friedrichs-Lewy (CFL) stability limit +that depends on mesh size and wave speed. Changing `E`, density, or mesh +can change that limit. Dynamic physics and numerical integration are separate +choices; not every possible combination is an implemented adapter. + +| Control | Meaning | +|---|---| +| DCB `controls.number_of_steps: 121` | 121 nominal load levels including zero: 120 nominal increments, possibly more accepted increments after cutbacks. | +| Final physical time | Requested duration of a dynamic calculation. | +| Maximum step count | A work limit; a short cap may stop before final time or crack growth. | +| Time step / CFL safety factor | Stability and temporal resolution, not physical validation. | +| `maximum_staggered_iterations` | Iteration budget within an increment, not additional physical loading. | +| Trajectory `every` | Saved-state cadence, not integration or load resolution. | + +Use the actual controls in the selected exercise, not guessed aliases named +`max_steps` or `final_time`. The legacy dynamic route uses controls such +as `loading.t_total` and `loading.num_steps`; the schema-2 adapter must +document and test its mapping. Do not switch the heterogeneous DCB deck to +`explicit`: this route does not provide dynamic multi-material execution. + +Smaller time/load steps are sensitivity checks, not validation by themselves. +Compare responses at the same physical time or load, and inspect convergence, +energy where available, and mesh sensitivity before drawing a conclusion. + +## 8. Inspect outputs, not just successful termination + +For DCB, inspect `history.csv`, `solver_telemetry.csv`, `summary.json`, +and the setup, material, field, and response plots. This **partial** schema-2 +excerpt requests a local trajectory; retain the other output requests: + +```yaml +outputs: + fields: + - {name: trajectory, format: h5, every: 1} +``` + +HDF5 is the default when a trajectory is requested on this route. DCB requests +it; heterogeneous SENT leaves it opt-in. PNG/GIF and CSV files alone are not +a reloadable field trajectory. + +```python +import phast + +result = phast.load_result("runs/dcb_fine_reference") +print(result.metadata()) +print(result.history_names()) +print(result.visuals()) +if result.has_field("damage"): + damage = result.field("damage", step=-1) +``` + +A short exercise can demonstrate setup and output without new crack growth. +The starter crack already has `d = 1`, so `max_damage = 1` alone proves +no propagation. Compare the seed-connected damaged region with its initial +extent, inspect fields, and read the reaction history. A front coordinate +overlapping the disk's x-range does not establish penetration or bypass. + +Keep large raw `training_data.h5` files in local outputs or a separate, +explicit data release. The online lesson needs only compact retained +figures and numerical records, not public raw HDF5. + +## 9. Read the retained fine DCB result + +These figures are **retained evidence**, not a new run executed by this page. +Coordinates are in mm; damage ranges from zero to one. Grey outlines show +bulk-material boundaries. + +```{figure} ../../examples/two_material_dcb_beta/results/damage_final.png +:alt: Retained DCB damage field with a forked crack in the weak layer near the circular tougher region. +:width: 100% + +Final state at 0.30 mm total opening. No seed-connected nodes with damage +at least 0.80 enter the disk. Neither penetration nor completed bypass is +demonstrated; this is qualitative layered-material interaction. +``` + +```{figure} ../../examples/two_material_dcb_beta/results/damage_evolution.gif +:alt: Retained DCB damage evolution from the starter crack to 0.30 mm total opening, with material boundaries outlined. +:width: 100% + +Evolution over load factors zero to one, ending at 0.30 mm total opening. +This is quasi-static loading, not physical time. The static figure above +is the animation fallback. The sequence is not calibrated inclusion-bypass +evidence. +``` + +| Fine reference quantity | Retained value | +|---|---:| +| Mesh | 160 x 48 cells split into T3 triangles | +| Accepted increments / cutbacks | 120 / 0 | +| Maximum projected damage residual | 6.91e-6 | +| Final reaction, recorded unit-thickness convention | 0.61495 | +| Connected front at `d >= 0.80` | 2.0625 mm | + +Sources: {download}`solver summary <../../examples/two_material_dcb_beta/results/summary.json>` +and {download}`numerical audit <../../examples/two_material_dcb_beta/results/numerical_review.json>`. +The historical generating source fingerprint was not recorded at runtime +and remains unknown. A later public-availability fingerprint does not attest +which source generated these fields. Independent stored-field checks found +the damage/history bounded and irreversible and recomputed projected residuals +using history from the final displacement: maximum 6.97e-6 for the fine case +and 5.23e-6 for the control. These final-state checks are distinct from the +solver-recorded maximum over accepted steps and are not independent reruns. + +## 10. Reproduce the separate coarse matched pair + +Two compact, complete inputs reuse the same runner and section order: + +- {download}`tough_region.yaml <../../examples/two_material_dcb_beta/comparisons/tough_region.yaml>` + uses the full DCB physics/settings with `nx: 120` instead of `160`. +- {download}`uniform_layer.yaml <../../examples/two_material_dcb_beta/comparisons/uniform_layer.yaml>` + uses that coarse configuration with only disk `Gc: 0.12` changed to + `0.04`, equal to the weak layer. + +The outer regions remain fracture-resistant. "Uniform layer" means no disk +toughness contrast within the layer, not a homogeneous specimen. These are +duplicated model inputs, not duplicated solver code or new solver drivers. +The new inputs request HDF5 for local reruns. The retained coarse tough-region +run did not write HDF5. The retained uniform-layer control did: its HDF5 +mesh supplies the original triangle connectivity used by the comparison +plots. Full trajectory files are not included in the compact public results. + +```bash +python -m phast explain-config examples/two_material_dcb_beta/comparisons/tough_region.yaml +python -m phast run examples/two_material_dcb_beta/comparisons/tough_region.yaml --validate-only +python -m phast run examples/two_material_dcb_beta/comparisons/tough_region.yaml --output_dir runs/dcb_coarse_tough_region + +python -m phast explain-config examples/two_material_dcb_beta/comparisons/uniform_layer.yaml +python -m phast run examples/two_material_dcb_beta/comparisons/uniform_layer.yaml --validate-only +python -m phast run examples/two_material_dcb_beta/comparisons/uniform_layer.yaml --output_dir runs/dcb_coarse_uniform_layer +``` + +Use these explicit, separate output directories rather than the inherited +default. The fine reference retains its geometry, material parameters, and +loading. The values below describe the retained coarse comparison, not a +new run of these input files. + +| At 0.30 mm opening on 120 x 48 cells | Tough region | Uniform-layer control | +|---|---:|---:| +| Disk `Gc` [N/mm] | 0.12 | 0.04 | +| Final reaction, recorded convention | 0.60938 | 0.45847 | +| Connected front at `d >= 0.80` [mm] | 2.10 | 2.40 | +| Accepted increments / cutbacks | 120 / 0 | 123 / 3 | + +Only the disk toughness differs in the physical inputs. Cutbacks produce +different accepted load sequences despite matched loading and solver +settings. Both cases fork early. The tougher region has shorter final +advance and a higher final reaction in this discrete comparison, but cannot +be credited with causing the initial branching. The fine reaction +`0.61495` is not the coarse matched tough-region reaction. + +See the {download}`matched comparison record <../../examples/two_material_dcb_beta/results/matched_control_review.json>`. +The disk radius is only `2 l0`, and its clearance from the outer regions is +`l0`. Confinement, regularisation, centroid-based boundaries, load-increment +sensitivity, and small-strain/rotation assumptions remain relevant. Two mesh +sizes are not a formal convergence study. Fixed-field review does not close +input-guard or publication checks; no experimental, ASTM, or interface-law +validation is claimed. + +## 11. Replot compact retained data without solving + +The compact-data postprocessor is separate from the FEM commands above: + +```bash +python examples/two_material_dcb_beta/compare_results.py --output-dir runs/dcb_comparison_replot +``` + +It reads the retained `coarse_tough_history.csv`, `uniform_layer_history.csv`, +`matched_control_fields.csv.gz`, `matched_control_elements.csv.gz`, and +`comparison_provenance.json` under the example's `results/` directory. It +regenerates `matched_control_comparison.png` and `matched_control_damage.png` +in the requested output directory without a FEM solve or raw HDF5. +A separate replot check regenerated both PNGs from the 250532-byte compact +history/field/connectivity payload. This is postprocessing evidence, not a +new FEM calculation. + +The histories use their own accepted load grids. Compare at matched opening +rather than equating row numbers. `comparison_provenance.json` must keep +historical source identity explicitly unknown where it was not recorded; +a public-availability fingerprint is not proof of prior generation. + +## Ask for help + +If a command, configuration section, or interpretation is unclear, +[open a GitHub issue](https://github.com/CEMS-Lab/PhAST/issues/new/choose). +Include the complete input, exact command, OS, Python/PhAST version or +source revision, full error output, and whether you inspected retained +figures or a new result. You need not diagnose solver internals first. diff --git a/docs/tutorial/index.md b/docs/tutorial/index.md index 4b4df4b71..003667519 100644 --- a/docs/tutorial/index.md +++ b/docs/tutorial/index.md @@ -1,19 +1,36 @@ # Tutorials +## Main configuration route + +Use [One configuration workflow for student simulations](07_standard_simulation_workflow.md) +for source installation and the common schema-2 layout. Its teaching sequence +is small quasi-static SENT, small dynamic SENT, and the full layered DCB +example. It explains editable geometry/mesh/materials, identifies pending +adapter checks, and shows retained DCB PNG/GIF evidence without claiming +calibrated inclusion bypass. + +The notebooks below are a separate learning route. Existing notebooks and +frozen course assets retain their inputs; the writing convention does not +silently migrate them or add 3D fracture support. + ## Student Notebook Sequence -1. [Dynamic SENT: inspect a complete public example](notebook_dynamic_sent.ipynb) +1. [Square-plate SENT: geometry to crack animation](notebook_square_plate_fracture.ipynb) + performs a fresh, laptop-scale calculation: generate the mesh, inspect named + boundaries, define material and loading data, select the supported dynamic + solver route, follow progress, and plot displacement, strain, stress, and damage. +2. [Dynamic SENT: inspect a complete public example](notebook_dynamic_sent.ipynb) connects an existing mesh, named regions, boundary conditions, YAML, explicit solver route, retained energy history, and visible crack-growth animation. It does not rerun the full dynamic calculation by default. -2. [SENT setup and two-step CPU workflow check](notebook_setup.ipynb) +3. [SENT setup and two-step CPU workflow check](notebook_setup.ipynb) teaches geometry, meshing, named regions, boundary conditions, material, solver selection, and retained outputs. Its default run is not crack-growth validation. -3. [Mesh-resolution diagnostic](notebook_mesh_resolution.ipynb) +4. [Mesh-resolution diagnostic](notebook_mesh_resolution.ipynb) samples an AT2 profile at several $h/\ell_0$ ratios. It is not a solved convergence study. -4. [Retained Miehe SENT results](notebook_retained_results.ipynb) +5. [Retained Miehe SENT results](notebook_retained_results.ipynb) examines checked-in load-displacement and damage evidence and states the current post-processing boundary. @@ -37,7 +54,9 @@ checkout, and prints the resolved commit before installation. | Tutorial | Time | What you learn | |---|---:|---| +| [Standard simulation workflow](07_standard_simulation_workflow.md) | Self-paced; full DCB runtime is machine-dependent | Use one schema-2 layout across the small SENT exercises and full DCB, edit inputs, and distinguish numerical and physical evidence. | | [Getting started](../getting-started.md) | 10-20 min on a fresh machine | Create an environment, install PyTorch and PhAST, run `doctor`, validate a shipped example, and inspect a result. A prepared teaching environment is faster. | +| [Square-plate fracture: complete workflow](notebook_square_plate_fracture.ipynb) | 25-40 min including installation; about 15-60 s for the solve on a prepared laptop | Generate the B3 square-plate mesh, inspect named boundaries, assemble a CFL-safe teaching configuration, run explicit mechanics with an implicit damage update, and create fresh field plots and a crack animation. Runtime is machine-dependent. | | [Dynamic SENT example](notebook_dynamic_sent.ipynb) | 20-30 min | Inspect the existing B3 mesh, named regions, loading, explicit solver route, retained histories, and crack-growth animation without presenting retained evidence as a new run. | | [Phase-field primer](01_phase_field_primer.md) | 15 min | Connect Griffith fracture energy, regularization, degradation, energy splits, history, and the staggered solve. | | [Problem setup notebook](notebook_setup.ipynb) | 35-50 min | Predict the setup, create and inspect the geometry and named regions, apply conditions and solver settings, run a short solve, change one parameter, and interpret the artifacts. A rendered fallback supports sessions without a working runtime. | @@ -55,10 +74,13 @@ checkout, and prints the resolved commit before installation. ## Recommended Learning Path 1. Install the package (`git clone` + `pip install -e .`) and run `python -m phast doctor`. -2. Validate a public YAML configuration with `--validate-only`. -3. Inspect the [B3 dynamic SENT notebook](notebook_dynamic_sent.ipynb) to connect - a complete public configuration with visible retained crack propagation. -4. Run one small public example into `runs/`. +2. Read the [standard simulation workflow](07_standard_simulation_workflow.md), + then explain and check a supported input with `--validate-only`. +3. Run the [square-plate fracture notebook](notebook_square_plate_fracture.ipynb) + to connect geometry, meshing, model data, solver selection, execution, and + post-processing in one fresh calculation. +4. Inspect the [B3 dynamic SENT notebook](notebook_dynamic_sent.ipynb) to compare + the fresh teaching calculation with the separately retained public evidence. 5. Inspect the completed run with `phast.load_result(...)`. 6. Build a small model with `phast.Problem`. 7. Read the [visual glossary](02_visual_glossary.md) if the terminology feels abstract. @@ -89,7 +111,7 @@ the solver. | 5-12 min | Inspect geometry, mesh, and named physical groups. | Setup figure and group table. | | 12-20 min | Identify material, phase-field, loading, and solver choices. | Completed modelling-decision table. | | 20-25 min | Run `--validate-only` and explain what it does not verify. | Configuration preflight record. | -| 25-33 min | Inspect the retained B3 propagation sequence, or execute the bounded two-step setup workflow when the environment is prepared. | A clearly labelled retained animation or a newly generated result directory. | +| 25-33 min | Execute the square-plate tutorial, or use its rendered fresh-run output when execution is unavailable. | A newly generated result directory or clearly labelled rendered fallback. | | 33-39 min | Change one parameter and predict the consequence before rerunning. | Before/after observation. | | 39-45 min | Inspect manifests, histories, and fields; state one limitation and one next test. | Exit statement suitable for a lab notebook. | @@ -101,6 +123,8 @@ record and to distinguish execution evidence from scientific evidence. | Workflow | Entry point | Typical output | |---|---|---| +| Full layered DCB teaching model, beta | `python -m phast run examples/two_material_dcb_beta/config.yaml --output_dir runs/dcb_fine_reference` | HDF5 trajectory, CSV, PNG/GIF, and manifests; retained evidence is qualitative, not a validated bypass result. | +| Complete square-plate teaching workflow | `jupyter lab docs/tutorial/notebook_square_plate_fracture.ipynb` | Fresh mesh, resolved YAML, histories, stored fields, final-field figure, and crack animation. | | Dynamic-fracture preflight | `python -m phast run examples/dynamic/B2_kalthoff_winkler/config.yaml --validate-only` | Configuration acceptance report only; no simulation fields are generated. | | Dynamic-branching preflight | `python -m phast run examples/dynamic/B7_dynamic_crack_branching_comsol/config.yaml --validate-only` | Configuration acceptance report only; retained artifacts are separate evidence. | | Quasi-static fracture | `python -m phast run examples/quasistatic/notched_holed_plate/config.yaml --output_dir runs/notched_holed_plate` | Final damage, response histories, comparison artifacts, and result manifests. | diff --git a/docs/tutorial/notebook_setup.ipynb b/docs/tutorial/notebook_setup.ipynb index aa1908f13..af1c0d493 100644 --- a/docs/tutorial/notebook_setup.ipynb +++ b/docs/tutorial/notebook_setup.ipynb @@ -1,4 +1,20 @@ { + "nbformat": 4, + "nbformat_minor": 5, + "metadata": { + "colab": { + "provenance": [] + }, + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python", + "pygments_lexer": "ipython3" + } + }, "cells": [ { "cell_type": "markdown", @@ -11,7 +27,7 @@ "This notebook builds a small single-edge-notched tension problem from first\n", "principles. It creates and inspects the geometry and mesh, defines the material\n", "and boundary-value problem with the fluent Python API, writes a runnable\n", - "schema-v1 YAML configuration, performs a bounded two-step CPU solve, and\n", + "schema-v2 YAML configuration, performs a bounded two-step CPU solve, and\n", "inspects the resulting artifacts.\n", "\n", "Learning objectives:\n", @@ -20,8 +36,7 @@ "2. Verify physical groups before using them as PhAST regions.\n", "3. Apply material parameters, initial-condition choices, supports, and\n", " prescribed loading.\n", - "4. Distinguish the fluent authoring representation from the runnable YAML\n", - " contract.\n", + "4. Use one saved configuration for setup validation and solver execution.\n", "5. Run a short quasi-static phase-field workflow check and inspect the generated\n", " output directory.\n", "6. Locate final field images, histories, trajectory stores, and optional\n", @@ -37,8 +52,8 @@ " do not change all three at once.\n", "- **Explain:** state which discretization, constitutive, or loading choice\n", " changed and which output should respond.\n", - "- **Fallback:** if installation or execution is unavailable, use the rendered\n", - " cell outputs and continue with the retained-results notebook.\n", + "- **Fallback:** if installation or execution is unavailable, continue with the\n", + " retained-results notebook. Cleared output cells are not computed evidence.\n", "\n", "The default run is intentionally short and is not crack-growth validation. For\n", "a research calculation, start from the closest checked-in example, refine the\n", @@ -84,7 +99,8 @@ "\n", "**Predict before continuing:** Which named boundary should remove rigid vertical\n", "motion? Which boundary should carry the prescribed displacement? Where should\n", - "the initial notch appear in the setup plot?\n" + "the initial notch appear in the setup plot?\n", + "" ], "id": "setup-002" }, @@ -94,26 +110,33 @@ "source": [ "## 1. Install dependencies\n", "\n", - "Run this cell in Colab. In a local clone, install PhAST with\n", - "`pip install -e .` from the repository root and skip the Colab-specific\n", - "package installation if your environment is already configured.\n", + "Use Python >=3.10 with compatible dependency wheels. From the **current\n", + "repository checkout**, prepare a local environment and install JupyterLab:\n", + "\n", + "```bash\n", + "python -m pip install -e . jupyterlab\n", + "jupyter lab docs/tutorial/notebook_setup.ipynb\n", + "```\n", + "\n", + "The cell below installs packages only in Colab. Local notebook execution and\n", + "documentation builds use the current checkout without changing the environment\n", + "or replacing its source with an older release.\n", "\n", - "The Colab route checks out the published\n", - "`v0.16.2-arxiv.2606.23458` release rather than the mutable default branch. It\n", - "rejects a cached checkout whose origin, commit, or tracked files do not match\n", - "the expected release and prints the resolved commit for the session record.\n", + "Colab uses the public `main` branch, which is **mutable**, and prints the\n", + "resolved commit. A local branch may contain changes not yet published on\n", + "`main`; use the notebook bundled with your selected checkout. The subsequent\n", + "configuration check and solve must succeed before interpreting any result.\n", + "This notebook does not establish that unpublished changes are available remotely.\n", "\n", - "The notebook uses Gmsh to create `mesh.msh`, MeshIO to inspect physical\n", - "groups, Matplotlib and Pillow for visual checks, and PhAST for solving and\n", - "result inspection.\n" + "Gmsh creates the mesh, MeshIO inspects physical groups, and Matplotlib and Pillow\n", + "provide visualisation. HDF5 stores the requested trajectory. See the\n", + "[installation guide](../install.md) for platform-specific Gmsh dependencies.\n" ], "id": "ff30f055" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "import os\n", "import sys\n", @@ -122,107 +145,62 @@ "\n", "IN_COLAB = \"google.colab\" in sys.modules\n", "PHAST_REPOSITORY = \"https://github.com/CEMS-Lab/PhAST.git\"\n", - "PHAST_REVISION = \"v0.16.2-arxiv.2606.23458\"\n", + "PHAST_REVISION = \"main\" # Mutable public branch, not an immutable release.\n", "\n", "if IN_COLAB:\n", " subprocess.run([\"apt-get\", \"update\", \"-qq\"], check=True)\n", - " subprocess.run([\"apt-get\", \"install\", \"-y\", \"-qq\", \"gmsh\", \"ffmpeg\"], check=True)\n", - "\n", - " checkout = Path(\"/content\") / f\"PhAST-{PHAST_REVISION}\"\n", + " subprocess.run([\"apt-get\", \"install\", \"-y\", \"-qq\", \"gmsh\"], check=True)\n", + " checkout = Path(\"/content/PhAST-main\")\n", " if checkout.exists():\n", " if not (checkout / \".git\").is_dir():\n", " raise RuntimeError(\n", - " f\"{checkout} exists but is not a Git checkout. \"\n", - " \"Restart the runtime or remove that directory explicitly.\"\n", + " f\"{checkout} is not a Git checkout. Restart the Colab runtime.\"\n", " )\n", " origin = subprocess.check_output(\n", " [\"git\", \"-C\", str(checkout), \"config\", \"--get\", \"remote.origin.url\"],\n", " text=True,\n", " ).strip()\n", " if origin != PHAST_REPOSITORY:\n", - " raise RuntimeError(\n", - " f\"Cached checkout origin is {origin!r}, expected {PHAST_REPOSITORY!r}.\"\n", - " )\n", + " raise RuntimeError(f\"Unexpected cached checkout origin: {origin!r}\")\n", " else:\n", " subprocess.run(\n", - " [\n", - " \"git\",\n", - " \"clone\",\n", - " \"--branch\",\n", - " PHAST_REVISION,\n", - " \"--depth\",\n", - " \"1\",\n", - " PHAST_REPOSITORY,\n", - " str(checkout),\n", - " ],\n", + " [\"git\", \"clone\", \"--branch\", PHAST_REVISION, \"--depth\", \"1\",\n", + " PHAST_REPOSITORY, str(checkout)],\n", " check=True,\n", " )\n", - "\n", " subprocess.run(\n", - " [\n", - " \"git\",\n", - " \"-C\",\n", - " str(checkout),\n", - " \"fetch\",\n", - " \"--depth\",\n", - " \"1\",\n", - " \"origin\",\n", - " f\"refs/tags/{PHAST_REVISION}:refs/tags/{PHAST_REVISION}\",\n", - " ],\n", + " [\"git\", \"-C\", str(checkout), \"fetch\", \"--depth\", \"1\",\n", + " \"origin\", \"refs/heads/main\"],\n", " check=True,\n", " )\n", " expected_commit = subprocess.check_output(\n", - " [\"git\", \"-C\", str(checkout), \"rev-list\", \"-n\", \"1\", PHAST_REVISION],\n", - " text=True,\n", + " [\"git\", \"-C\", str(checkout), \"rev-parse\", \"FETCH_HEAD\"], text=True\n", " ).strip()\n", " resolved_commit = subprocess.check_output(\n", - " [\"git\", \"-C\", str(checkout), \"rev-parse\", \"HEAD\"],\n", - " text=True,\n", + " [\"git\", \"-C\", str(checkout), \"rev-parse\", \"HEAD\"], text=True\n", " ).strip()\n", " tracked_changes = subprocess.check_output(\n", - " [\n", - " \"git\",\n", - " \"-C\",\n", - " str(checkout),\n", - " \"status\",\n", - " \"--porcelain\",\n", - " \"--untracked-files=no\",\n", - " ],\n", + " [\"git\", \"-C\", str(checkout), \"status\", \"--porcelain\", \"--untracked-files=no\"],\n", " text=True,\n", " ).strip()\n", " if resolved_commit != expected_commit or tracked_changes:\n", " raise RuntimeError(\n", - " \"Cached PhAST checkout does not match the documented release. \"\n", - " \"Restart the Colab runtime before continuing.\"\n", + " \"The cached checkout differs from public main. Restart the Colab \"\n", + " \"runtime rather than overwriting local changes.\"\n", " )\n", - "\n", - " print(f\"PhAST release: {PHAST_REVISION}\")\n", + " print(f\"Public source: {PHAST_REVISION} (mutable)\")\n", " print(f\"Resolved commit: {resolved_commit}\")\n", " subprocess.run(\n", - " [\n", - " sys.executable,\n", - " \"-m\",\n", - " \"pip\",\n", - " \"install\",\n", - " \"-q\",\n", - " \"-e\",\n", - " str(checkout),\n", - " \"meshio\",\n", - " \"matplotlib\",\n", - " \"zarr\",\n", - " \"h5py\",\n", - " \"pyyaml\",\n", - " ],\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"-e\", str(checkout), \"jupyterlab\"],\n", " check=True,\n", " )\n", " os.chdir(checkout)\n", "else:\n", - " print(\n", - " \"Local run: use an activated PhAST environment and start Jupyter \"\n", - " \"from the repository checkout.\"\n", - " )\n" + " print(\"Local/docs execution: using the current checkout; no packages installed.\")\n" ], - "id": "db9e1ad3" + "id": "db9e1ad3", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -230,21 +208,22 @@ "source": [ "## 2. Imports and working directory\n", "\n", - "All generated files go into `runs/notebook_sent/`. Keeping the generated geometry, mesh, configuration, and results in one directory makes the run easy to archive or remove." + "Generated geometry, mesh, configuration, and results share a new\n", + "`runs/notebook_sent/` directory. Existing runs are preserved by adding a\n", + "numeric suffix. Set `PHAST_NOTEBOOK_OUTPUT_ROOT` to place generated runs\n", + "elsewhere, for example during a documentation build.\n" ], "id": "6814b878" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "import json\n", "import shutil\n", - "import textwrap\n", "\n", "from PIL import Image as PILImage\n", + "import h5py\n", "import matplotlib.pyplot as plt\n", "import meshio\n", "import numpy as np\n", @@ -253,22 +232,44 @@ "here = Path.cwd().resolve()\n", "repo_root = next(\n", " (candidate for candidate in (here, *here.parents)\n", - " if (candidate / \"pyproject.toml\").is_file() and (candidate / \"src\" / \"phast\").is_dir()),\n", - " here,\n", + " if (candidate / \"pyproject.toml\").is_file()\n", + " and (candidate / \"src\" / \"phast\").is_dir()),\n", + " None,\n", ")\n", + "if repo_root is None:\n", + " raise RuntimeError(\"Start this notebook from the current PhAST source checkout.\")\n", "source_src = repo_root / \"src\"\n", - "if source_src.is_dir():\n", - " sys.path.insert(0, str(source_src))\n", - " os.environ[\"PYTHONPATH\"] = str(source_src) + os.pathsep + os.environ.get(\"PYTHONPATH\", \"\")\n", + "sys.path.insert(0, str(source_src))\n", + "os.environ[\"PYTHONPATH\"] = str(source_src) + os.pathsep + os.environ.get(\"PYTHONPATH\", \"\")\n", "\n", "import phast\n", "\n", - "run_dir = (repo_root / \"runs\" / \"notebook_sent\").resolve()\n", - "run_dir.mkdir(parents=True, exist_ok=True)\n", + "if not Path(phast.__file__).resolve().is_relative_to(source_src):\n", + " raise RuntimeError(\"Restart the kernel: PhAST was imported from a different checkout.\")\n", + "\n", + "plt.rcParams.update({\"font.family\": \"STIXGeneral\", \"mathtext.fontset\": \"stix\"})\n", + "\n", + "def require_finite(values, name):\n", + " \"\"\"Reject empty or non-finite data rather than disguising a failed solve.\"\"\"\n", + " array = np.asarray(values)\n", + " if array.size == 0 or not np.isfinite(array).all():\n", + " raise ValueError(\n", + " f\"Empty or non-finite values in {name}; inspect the solver log \"\n", + " \"before plotting or interpreting this run.\"\n", + " )\n", + " return array\n", + "\n", + "output_root = Path(os.environ.get(\"PHAST_NOTEBOOK_OUTPUT_ROOT\", repo_root / \"runs\"))\n", + "base = output_root.expanduser().resolve() / \"notebook_sent\"\n", + "run_dir = base\n", + "suffix = 2\n", + "while run_dir.exists():\n", + " run_dir = base.with_name(f\"{base.name}_{suffix}\")\n", + " suffix += 1\n", + "run_dir.mkdir(parents=True)\n", "\n", "geo_path = run_dir / \"mesh.geo\"\n", "mesh_path = run_dir / \"mesh.msh\"\n", - "spec_path = run_dir / \"authored_problem_spec.yaml\"\n", "config_path = run_dir / \"config.yaml\"\n", "output_dir = run_dir / \"results\"\n", "\n", @@ -276,7 +277,9 @@ "print(\"Repository root:\", repo_root)\n", "print(\"Working directory:\", run_dir)\n" ], - "id": "9b014033" + "id": "9b014033", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -293,16 +296,14 @@ "| `body` | 2D plate surface | material assignment |\n", "| `bottom` | bottom edge | fixed support |\n", "| `top` | top edge | prescribed vertical displacement |\n", - "| `notch` | embedded crack line | initial damage seed |\n", - "| `left`, `right` | side edges | optional inspection/output regions |" + "| `notch` | faces and tip of the geometric notch | optional initial damage seed |\n", + "| `left`, `right` | side edges | optional inspection/output regions |\n" ], "id": "fe0eaec7" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "L = 1.0 # plate width [mm]\n", "H = 1.0 # plate height [mm]\n", @@ -366,7 +367,9 @@ "print(geo_path)\n", "print(geo_text[:600] + \"\\n...\")" ], - "id": "4a44bef7" + "id": "4a44bef7", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -380,9 +383,7 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "fig, ax = plt.subplots(figsize=(6, 5))\n", "ax.plot([0, L, L, 0, 0], [0, 0, H, H, 0], color=\"0.15\", lw=2)\n", @@ -399,7 +400,9 @@ "fig.savefig(run_dir / \"geometry_preview.png\", dpi=180)\n", "plt.show()" ], - "id": "ec9c18d1" + "id": "ec9c18d1", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -413,9 +416,7 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "gmsh = shutil.which(\"gmsh\")\n", "if gmsh is None:\n", @@ -423,10 +424,12 @@ "\n", "cmd = [gmsh, \"-2\", str(geo_path), \"-format\", \"msh2\", \"-o\", str(mesh_path)]\n", "print(\" \".join(cmd))\n", - "subprocess.run(cmd, check=True)\n", - "print(mesh_path, mesh_path.stat().st_size, \"bytes\")" + "subprocess.run(cmd, check=True, timeout=60)\n", + "print(mesh_path, mesh_path.stat().st_size, \"bytes\")\n" ], - "id": "809ed54d" + "id": "809ed54d", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -440,9 +443,7 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "mesh_summary = phast.inspect_mesh(mesh_path)\n", "print(\"points:\", mesh_summary[\"n_points\"])\n", @@ -454,7 +455,9 @@ "if missing:\n", " raise RuntimeError(f\"Missing required physical groups: {sorted(missing)}\")" ], - "id": "0cfd3178" + "id": "0cfd3178", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -468,12 +471,10 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "mesh = meshio.read(mesh_path)\n", - "points = mesh.points[:, :2]\n", + "points = require_finite(mesh.points[:, :2], \"mesh coordinates\")\n", "\n", "triangles = []\n", "lines = []\n", @@ -506,9 +507,11 @@ "ax.set_title(\"Mesh with named physical curves\")\n", "fig.tight_layout()\n", "fig.savefig(run_dir / \"mesh_preview.png\", dpi=180)\n", - "plt.show()" + "plt.show()\n" ], - "id": "6e9d68bd" + "id": "6e9d68bd", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -524,9 +527,7 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "num_steps = 2 # quick tutorial run; increase for smoother damage evolution\n", "u_top = 0.0002 # prescribed final displacement [mm]\n", @@ -541,7 +542,7 @@ " .region(\"top\", from_mesh=\"top\")\n", " .region(\"notch\", from_mesh=\"notch\")\n", " .material(\n", - " \"glass\",\n", + " \"tutorial_material\",\n", " region=\"body\",\n", " E=210000.0,\n", " nu=0.3,\n", @@ -571,20 +572,18 @@ " static_tol=1.0e-7,\n", " damage_max_iter=500,\n", " static_max_iter=500,\n", - " fail_on_mechanics_nonconvergence=False,\n", - " fail_on_stagger_nonconvergence=False,\n", + " fail_on_mechanics_nonconvergence=True,\n", + " fail_on_stagger_nonconvergence=True,\n", " backend=\"auto\",\n", " device=\"cpu\",\n", " )\n", " .outputs(\n", - " fields=[{\"name\": \"trajectory\", \"every\": 1, \"format\": \"zarr\"}],\n", + " fields=[{\"name\": \"trajectory\", \"every\": 1, \"format\": \"h5\"}],\n", " histories=[{\"name\": \"reaction_force\", \"region\": \"bottom\", \"dof\": \"y\"}],\n", - " plots=True,\n", + " output_dir=str(output_dir),\n", + " plots=False, # Plot only after checking the stored numerical fields.\n", " profile=True,\n", - " gif=True,\n", - " gif_frames=24,\n", - " gif_fields=\"damage\",\n", - " animation_format=\"gif\",\n", + " gif=False,\n", " print_every=1,\n", " )\n", ")\n", @@ -592,25 +591,27 @@ "if enable_damage_preseed:\n", " problem.initial_condition(\"damage\", region=\"notch\", value=1.0)\n", "\n", - "problem.validate_setup()" + "problem.validate_setup()\n" ], - "id": "5b686441" + "id": "5b686441", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 9. Visualize supports, loading, and the damage seed\n", + "## 9. Visualise supports, loading, and the optional damage seed\n", "\n", - "`problem.plot_setup(...)` writes a static setup preview. The extra overlay below explicitly marks the prescribed displacement and the seeded crack so the notebook remains readable even if the default preview style changes." + "`problem.plot_setup(...)` writes a static setup preview. The notch exists in\n", + "the mesh even when damage pre-seeding is disabled. An initial value `d=1` is\n", + "applied only when `enable_damage_preseed` is explicitly enabled.\n" ], "id": "fe796e63" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "setup_preview = run_dir / \"initial_conditions.png\"\n", "problem.plot_setup(output=setup_preview)\n", @@ -623,7 +624,9 @@ "plt.show()\n", "print(setup_preview)" ], - "id": "72dc48ed" + "id": "72dc48ed", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -640,7 +643,7 @@ "| `solver_type` | `quasi_static`, `explicit` | Quasi-static solves coupled displacement/damage equilibrium at each load increment. Explicit dynamics advances the transient wave/crack problem with a stable time step. |\n", "| static vs dynamic | `quasi_static` vs `explicit` | Static/quasi-static cases ignore inertia; dynamic cases require density and time-step controls. |\n", "| implicit vs explicit | `quasi_static` uses iterative equilibrium solves; `explicit` uses time stepping | Current public examples promote quasi-static fracture and explicit dynamic fracture. Experimental or beta paths should stay clearly labelled. |\n", - "| trajectory format | `zarr`, `h5`, `both` | Zarr is preferred for public runs; HDF5 is retained for compatibility with older post-processing scripts. |\n", + "| trajectory format | `zarr`, `h5`, `both` | HDF5 is the default single-file format; Zarr or both formats require explicit selection. |\n", "\n", "For a paper result, keep these choices in YAML and report them in the run manifest. Do not rely on notebook state as the only record of a simulation." ], @@ -650,92 +653,39 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 11. Write the runnable YAML configuration\n", - "\n", - "The fluent `Problem` object is useful for authoring and setup validation. Its saved schema-v2 specification is an inspection representation and does not imply that every combination has a promoted execution adapter. This cell retains that specification separately, then writes the supported schema-v1 YAML fields used by the public fracture runner.\n" + "## 11. Save one runnable schema-v2 configuration\n", + "\n", + "`Problem.save(config_path)` retains the geometry, named regions, material,\n", + "boundary conditions, analysis step, solver settings, and output requests in\n", + "one YAML file. Validate and execute **that same file**, rather than maintaining\n", + "a second hand-written configuration.\n", + "\n", + "This example is restricted to the existing single-material, external-mesh,\n", + "quasi-static fracture adapter. It does not establish support for arbitrary\n", + "schema-v2 combinations. Schema validation does not solve the equations or\n", + "demonstrate convergence. Mechanics and staggered nonconvergence remain fatal;\n", + "do not disable these checks to obtain a plot.\n" ], "id": "655f169f" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ - "problem.save(spec_path)\n", - "\n", - "execution_config = {\n", - " \"schema_version\": 1,\n", - " \"problem\": {\n", - " \"name\": \"Notebook SENT workflow check\",\n", - " \"reference\": \"Educational setup; not a validation benchmark\",\n", - " },\n", - " \"geometry\": {\"mesh_path\": str(mesh_path)},\n", - " \"material\": {\n", - " \"E\": 210000.0,\n", - " \"nu\": 0.3,\n", - " \"Gc\": 2.7,\n", - " \"l0\": l0,\n", - " \"rho\": 7.8e-09,\n", - " \"eta_residual\": 1.0e-07,\n", - " \"energy_split\": \"spectral\",\n", - " \"pf_model\": \"AT2\",\n", - " \"plane_stress\": False,\n", - " },\n", - " \"boundary_conditions\": [\n", - " {\"nodes\": \"bottom\", \"type\": \"fix\", \"component\": 0, \"value\": 0.0},\n", - " {\"nodes\": \"bottom\", \"type\": \"fix\", \"component\": 1, \"value\": 0.0},\n", - " {\"nodes\": \"top\", \"type\": \"prescribe\", \"component\": 1, \"value\": 1.0},\n", - " ],\n", - " \"loading\": {\n", - " \"protocol\": \"simple\",\n", - " \"num_steps\": num_steps,\n", - " \"dt\": u_top / num_steps,\n", - " },\n", - " \"solver\": {\n", - " \"solver_type\": \"quasi_static\",\n", - " \"stagger_tol\": 1.0e-6,\n", - " \"max_stagger\": 50,\n", - " \"preconditioner\": \"jacobi\",\n", - " \"damage_tol\": 1.0e-5,\n", - " \"static_tol\": 1.0e-7,\n", - " \"damage_max_iter\": 500,\n", - " \"static_max_iter\": 500,\n", - " \"bounds_method\": \"post_clamp\",\n", - " \"fail_on_mechanics_nonconvergence\": False,\n", - " \"fail_on_stagger_nonconvergence\": False,\n", - " \"backend\": \"auto\",\n", - " },\n", - " \"output\": {\n", - " \"output_dir\": str(output_dir),\n", - " \"trajectory\": True,\n", - " \"trajectory_format\": \"zarr\",\n", - " \"h5_every\": 1,\n", - " \"plots\": True,\n", - " \"profile\": True,\n", - " \"gif\": False,\n", - " \"print_every\": 1,\n", - " \"reaction_node_set\": \"bottom\",\n", - " \"reaction_component\": 1,\n", - " },\n", - " \"device\": {\"device\": \"cpu\", \"compile\": False},\n", - "}\n", - "if enable_damage_preseed:\n", - " execution_config[\"initial_conditions\"] = {\n", - " \"preseed_notch_nodesets\": [\"notch\"],\n", - " \"preseed_damage\": 1.0,\n", - " }\n", - "\n", - "config_path.write_text(yaml.safe_dump(execution_config, sort_keys=False), encoding=\"utf-8\")\n", - "print(\"Authoring specification:\", spec_path)\n", - "print(\"Runnable configuration:\", config_path)\n", - "print(config_path.read_text(encoding=\"utf-8\")[:1600] + \"\\n...\")\n", + "problem.save(config_path)\n", + "saved_config = yaml.safe_load(config_path.read_text(encoding=\"utf-8\"))\n", + "if saved_config.get(\"schema_version\") != 2:\n", + " raise RuntimeError(\"This workflow requires the saved schema-v2 configuration.\")\n", + "print(\"Saved configuration used for validation and execution:\", config_path)\n", + "print(yaml.safe_dump(saved_config, sort_keys=False))\n", "\n", "validate_cmd = [sys.executable, \"-m\", \"phast\", \"run\", str(config_path), \"--validate-only\"]\n", "print(\" \".join(validate_cmd))\n", - "subprocess.run(validate_cmd, check=True, cwd=repo_root)\n" + "subprocess.run(validate_cmd, check=True, cwd=repo_root, timeout=60)\n" ], - "id": "29610eb8" + "id": "29610eb8", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -751,7 +701,8 @@ "\n", "After the run, compare these expectations with the printed route, manifest, and\n", "available artifacts. A completed short run is an execution check, not a\n", - "fracture-validation result.\n" + "fracture-validation result.\n", + "" ], "id": "setup-024" }, @@ -761,30 +712,31 @@ "source": [ "## 12. Run the bounded solver workflow\n", "\n", - "The command below executes the runnable schema-v1 configuration and writes artifacts to `runs/notebook_sent/results/`. It is a two-step CPU workflow check, not evidence of crack initiation, propagation, mesh convergence, or benchmark agreement.\n" + "The command executes the saved schema-v2 configuration and writes to the\n", + "selected run's `results/` directory. It is a two-step CPU workflow check,\n", + "not evidence of crack initiation, propagation, mesh convergence, or benchmark\n", + "agreement. A nonzero exit status stops the notebook.\n" ], "id": "53a58fcb" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "run_cmd = [\n", " sys.executable, \"-m\", \"phast\", \"run\", str(config_path),\n", " \"--output_dir\", str(output_dir),\n", "]\n", "print(\" \".join(run_cmd))\n", - "subprocess.run(run_cmd, check=True, cwd=repo_root)\n" + "subprocess.run(run_cmd, check=True, cwd=repo_root, timeout=120)\n" ], - "id": "237e74e7" + "id": "237e74e7", + "outputs": [], + "execution_count": null }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "# Inspect the output contract without assuming every optional writer was enabled.\n", "artifact_groups = {\n", @@ -793,8 +745,7 @@ " \"field_or_trajectory\": [\n", " \"damage_final.png\",\n", " \"displacement_final.png\",\n", - " \"trajectory.zarr\",\n", - " \"results.zarr\",\n", + " \"training_data.h5\",\n", " \"training_data.zarr\",\n", " ],\n", "}\n", @@ -809,9 +760,12 @@ " \"Interpretation: availability depends on the selected workflow and output \"\n", " \"settings. Inspect the run manifest before treating an absent optional artifact \"\n", " \"as a solver failure.\"\n", - ")\n" + ")\n", + "" ], - "id": "setup-027" + "id": "setup-027", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -825,157 +779,205 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "for path in sorted(output_dir.iterdir()):\n", - " if path.is_dir():\n", - " print(f\"{path.name}/\")\n", - " else:\n", - " print(path.name)\n", + " print(path.name + (\"/\" if path.is_dir() else \"\"))\n", "\n", "result = phast.load_result(output_dir)\n", "print(\"\\nmetadata keys:\", sorted(result.metadata().keys()))\n", "print(\"histories:\", result.history_names())\n", "print(\"fields:\", result.field_names())\n", - "print(\"visuals:\", result.visuals())" + "print(\"visuals:\", result.visuals())\n", + "\n", + "stored_steps = []\n", + "trajectory_path = output_dir / \"training_data.h5\"\n", + "if trajectory_path.is_file():\n", + " with h5py.File(trajectory_path, \"r\") as trajectory:\n", + " stored_steps = sorted(\n", + " int(key.rsplit(\"_\", 1)[-1])\n", + " for key in trajectory[\"simulation_data/steps\"]\n", + " if key.startswith(\"step_\")\n", + " )\n", + " if not stored_steps or stored_steps[-1] != num_steps - 1:\n", + " raise RuntimeError(\"The requested final step is missing from the HDF5 trajectory.\")\n", + " print(\"Stored solver steps:\", stored_steps)\n", + "else:\n", + " print(\"No HDF5 trajectory is available; field plots and animation will be omitted.\")\n" ], - "id": "0e7a8119" + "id": "0e7a8119", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 14. Plot histories and final fields\n", + "## 14. Plot available histories and final fields\n", "\n", - "The result API returns stored fields and histories. If a requested derived field was not stored directly, compute it during post-processing only when the required source fields are present." + "The result API exposes stored field names and CSV-backed history rows.\n", + "Displacement magnitude is derived from displacement; vertical strain and\n", + "stress use their stored in-plane components when available. This adapter\n", + "may omit optional strain or stress snapshots: missing output is reported,\n", + "not replaced with zeros or reconstructed without its constitutive inputs.\n", + "\n", + "Every plotted numerical array must be finite. Empty fields, NaNs, infinities,\n", + "or incompatible field shapes stop post-processing. Damage uses the fixed\n", + "`Reds` scale from 0 to 1.\n" ], "id": "43fb1ee4" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ - "if \"reaction_force\" in result.history_names():\n", - " rows = result.history(\"reaction_force\")\n", - "elif \"history\" in result.history_names():\n", - " rows = result.history(\"history\")\n", + "if \"load_displacement\" in result.history_names():\n", + " rows = result.history(\"load_displacement\")\n", + " if rows:\n", + " columns = set(rows[0])\n", + " if {\"applied_disp\", \"reaction_force\"} <= columns:\n", + " x_key, y_key, force_unit = \"applied_disp\", \"reaction_force\", \"N\"\n", + " elif {\"displacement\", \"reaction_kN\"} <= columns:\n", + " x_key, y_key, force_unit = \"displacement\", \"reaction_kN\", \"kN\"\n", + " else:\n", + " raise ValueError(f\"Unrecognised load-displacement columns: {sorted(columns)}\")\n", + " applied = require_finite(\n", + " np.asarray([row[x_key] for row in rows], dtype=float), x_key\n", + " )\n", + " reaction = require_finite(\n", + " np.asarray([row[y_key] for row in rows], dtype=float), y_key\n", + " )\n", + " fig, ax = plt.subplots(figsize=(6, 4))\n", + " ax.plot(applied, reaction, \"o-\")\n", + " ax.set(xlabel=\"Applied displacement [mm]\", ylabel=f\"Reaction [{force_unit}]\",\n", + " title=\"Two-step response, not a converged fracture curve\")\n", + " fig.tight_layout()\n", + " plt.show()\n", + " else:\n", + " print(\"The load-displacement history is empty; no curve is drawn.\")\n", "else:\n", - " rows = []\n", + " print(\"No load-displacement history was stored; no curve is fabricated.\")\n", "\n", - "if rows:\n", - " print(rows[:3])\n", "\n", - "def write_scalar_field_png(values, title, path, cmap=\"viridis\"):\n", - " arr = np.asarray(values)\n", - " if arr.ndim > 1:\n", - " arr = np.linalg.norm(arr, axis=-1)\n", - " arr = np.nan_to_num(arr, nan=0.0, posinf=0.0, neginf=0.0)\n", + "def write_scalar_field_png(values, title, path, cmap=\"viridis\", limits=None):\n", + " arr = require_finite(values, title)\n", + " if arr.ndim != 1 or arr.size not in (points.shape[0], triangles.shape[0]):\n", + " raise ValueError(f\"{title}: field shape {arr.shape} does not match this mesh\")\n", + " colour_limits = {} if limits is None else dict(vmin=limits[0], vmax=limits[1])\n", " fig, ax = plt.subplots(figsize=(6, 5))\n", " if arr.size == points.shape[0]:\n", - " im = ax.tripcolor(points[:, 0], points[:, 1], triangles, arr, shading=\"gouraud\", cmap=cmap)\n", - " elif arr.size == triangles.shape[0]:\n", - " im = ax.tripcolor(points[:, 0], points[:, 1], triangles, facecolors=arr, edgecolors=\"none\", cmap=cmap)\n", + " im = ax.tripcolor(\n", + " points[:, 0], points[:, 1], triangles, arr,\n", + " shading=\"gouraud\", cmap=cmap, **colour_limits,\n", + " )\n", " else:\n", - " plt.close(fig)\n", - " print(f\"Skipping {title}: field shape {values.shape} does not match nodes or elements\")\n", - " return None\n", - " ax.set_aspect(\"equal\")\n", - " ax.set_title(title)\n", - " ax.set_xlabel(\"x [mm]\")\n", - " ax.set_ylabel(\"y [mm]\")\n", + " im = ax.tripcolor(\n", + " points[:, 0], points[:, 1], triangles, facecolors=arr,\n", + " shading=\"flat\", cmap=cmap, **colour_limits,\n", + " )\n", + " ax.set(aspect=\"equal\", title=title, xlabel=\"x [mm]\", ylabel=\"y [mm]\")\n", " fig.colorbar(im, ax=ax, shrink=0.82)\n", " fig.tight_layout()\n", " fig.savefig(path, dpi=180)\n", " plt.close(fig)\n", " return path\n", "\n", - "for field_name, filename, title, cmap in [\n", - " (\"displacement\", \"displacement_final.png\", \"Final displacement magnitude\", \"magma\"),\n", - " (\"stress\", \"stress_final.png\", \"Final stress magnitude\", \"plasma\"),\n", - " (\"strain\", \"strain_final.png\", \"Final strain magnitude\", \"cividis\"),\n", - "]:\n", - " if result.has_field(field_name):\n", - " write_scalar_field_png(result.field(field_name, step=-1), title, output_dir / filename, cmap=cmap)\n", - "\n", - "candidate_images = [\n", - " output_dir / \"initial_conditions.png\",\n", - " run_dir / \"initial_conditions.png\",\n", - " output_dir / \"damage_final.png\",\n", - " output_dir / \"displacement_final.png\",\n", - " output_dir / \"stress_final.png\",\n", - " output_dir / \"strain_final.png\",\n", - "]\n", - "existing_images = [p for p in candidate_images if p.exists()]\n", "\n", - "if existing_images:\n", - " fig, axes = plt.subplots(1, len(existing_images), figsize=(5 * len(existing_images), 4))\n", - " axes = np.atleast_1d(axes)\n", - " for ax, path in zip(axes, existing_images):\n", + "checked_images = []\n", + "for field_name, title, cmap, component, limits in [\n", + " (\"damage\", \"Final phase-field damage, d [-]\", \"Reds\", None, (0.0, 1.0)),\n", + " (\"displacement\", \"Final displacement magnitude [mm]\", \"cividis\", \"magnitude\", None),\n", + " (\"stress\", \"Final in-plane stress, sigma_yy [MPa]\", \"RdBu_r\", 1, None),\n", + " (\"strain\", \"Final vertical strain, epsilon_yy [-]\", \"RdBu_r\", 1, None),\n", + "]:\n", + " if not stored_steps or not result.has_field(field_name):\n", + " print(f\"No stored {field_name} field; its plot is omitted.\")\n", + " continue\n", + " values = require_finite(result.field(field_name, step=stored_steps[-1]), field_name)\n", + " if component == \"magnitude\":\n", + " if values.ndim != 2 or values.shape[1] != 2:\n", + " raise ValueError(f\"Unexpected displacement shape: {values.shape}\")\n", + " values = np.linalg.norm(values, axis=1)\n", + " elif component is not None:\n", + " if values.ndim != 2 or values.shape[1] != 3:\n", + " raise ValueError(f\"Unexpected in-plane {field_name} shape: {values.shape}\")\n", + " values = values[:, component]\n", + " checked_images.append(write_scalar_field_png(\n", + " values, title, output_dir / f\"{field_name}_final.png\", cmap=cmap, limits=limits\n", + " ))\n", + "\n", + "if checked_images:\n", + " fig, axes = plt.subplots(\n", + " (len(checked_images) + 1) // 2, 2,\n", + " figsize=(11, 5 * ((len(checked_images) + 1) // 2)),\n", + " )\n", + " for ax in np.asarray(axes).flat:\n", + " ax.axis(\"off\")\n", + " for ax, path in zip(np.asarray(axes).flat, checked_images):\n", " ax.imshow(np.asarray(PILImage.open(path).convert(\"RGB\")))\n", " ax.set_title(path.name)\n", - " ax.axis(\"off\")\n", " fig.tight_layout()\n", " plt.show()\n", "else:\n", - " print(\"No standard PNG fields were generated for this short run.\")" + " print(\"No available finite trajectory fields to plot.\")\n" ], - "id": "aabc08a1" + "id": "aabc08a1", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 15. Create or view animations\n", + "## 15. Create an animation from stored damage\n", "\n", - "If the run generated `damage_evolution.gif` or `damage_evolution.mp4`, display it directly. For longer studies, prefer generating animations from the stored Zarr trajectory after the solve so rendering settings can be changed without rerunning the physics." + "Use the actual HDF5 snapshot indices, not the number of CSV history rows.\n", + "All selected damage snapshots are checked before rendering. Two frames\n", + "illustrate the output workflow; they do not demonstrate crack propagation.\n", + "For longer studies, render from the retained trajectory after solving.\n" ], "id": "d16a17db" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ - "from IPython.display import Image, Video, display\n", + "from IPython.display import Image, display\n", "\n", "gif_path = output_dir / \"damage_evolution.gif\"\n", - "mp4_path = output_dir / \"damage_evolution.mp4\"\n", - "\n", - "if not gif_path.exists() and result.has_field(\"damage\"):\n", - " history_len = len(result.history(\"results\")) if \"results\" in result.history_names() else num_steps\n", + "if stored_steps and result.has_field(\"damage\"):\n", + " damage_frames = [\n", + " require_finite(result.field(\"damage\", step=step), f\"damage at step {step}\")\n", + " for step in stored_steps\n", + " ]\n", + " if any(field.shape != (len(points),) for field in damage_frames):\n", + " raise ValueError(\"A damage snapshot does not match the mesh nodes.\")\n", " frames = []\n", - " for step_index in range(history_len):\n", - " damage = np.nan_to_num(result.field(\"damage\", step=step_index), nan=0.0, posinf=1.0, neginf=0.0)\n", + " for step_index, damage in zip(stored_steps, damage_frames):\n", " fig, ax = plt.subplots(figsize=(6, 5))\n", - " im = ax.tripcolor(points[:, 0], points[:, 1], triangles, damage, shading=\"gouraud\", cmap=\"inferno\", vmin=0.0, vmax=1.0)\n", - " ax.set_aspect(\"equal\")\n", - " ax.set_title(f\"Damage, step {step_index}\")\n", - " ax.set_xlabel(\"x [mm]\")\n", - " ax.set_ylabel(\"y [mm]\")\n", + " im = ax.tripcolor(\n", + " points[:, 0], points[:, 1], triangles, damage,\n", + " shading=\"gouraud\", cmap=\"Reds\", vmin=0.0, vmax=1.0,\n", + " )\n", + " ax.set(aspect=\"equal\", title=f\"Damage, step {step_index}\",\n", + " xlabel=\"x [mm]\", ylabel=\"y [mm]\")\n", " fig.colorbar(im, ax=ax, shrink=0.82)\n", " fig.tight_layout()\n", " fig.canvas.draw()\n", - " frames.append(np.asarray(fig.canvas.buffer_rgba())[:, :, :3].copy())\n", + " frames.append(PILImage.fromarray(\n", + " np.asarray(fig.canvas.buffer_rgba())[:, :, :3].copy()\n", + " ))\n", " plt.close(fig)\n", - " PILImage.fromarray(frames[0]).save(\n", - " gif_path, save_all=True,\n", - " append_images=[PILImage.fromarray(frame) for frame in frames[1:]],\n", - " duration=800, loop=0,\n", + " frames[0].save(\n", + " gif_path, save_all=True, append_images=frames[1:], duration=800, loop=0\n", " )\n", - "\n", - "if gif_path.exists():\n", " display(Image(filename=str(gif_path)))\n", - "elif mp4_path.exists():\n", - " display(Video(str(mp4_path), embed=True))\n", "else:\n", - " print(\"No damage animation could be generated because the damage trajectory is not available.\")" + " print(\"No stored damage trajectory; no animation is fabricated.\")\n" ], - "id": "794f9b25" + "id": "794f9b25", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -987,9 +989,9 @@ "2. Keep the `.geo`, `.msh`, `config.yaml`, `run_fluent.py`, setup preview, final field images, animations, and CSV histories together.\n", "3. Use a mesh size that resolves the phase-field length scale; a common starting point is several elements across `l0` near the crack path.\n", "4. Validate the YAML with `python -m phast run config.yaml --validate-only` before using HPC time.\n", - "5. For dynamic fracture, switch the step and solver to `explicit`, include density, and verify the stable time step.\n", + "5. For dynamic fracture, use a matched public dynamic example, include density, and verify the stable time step. Changing only the solver type does not define an equivalent problem.\n", "6. For quasi-static fracture, monitor staggered convergence and load-displacement response before trusting crack paths.\n", - "7. Archive the result directory, not only the notebook. The result directory is the reproducible simulation artifact." + "7. Archive the result directory, not only the notebook. The result directory is the reproducible simulation artifact.\n" ], "id": "bec30390" }, @@ -1029,28 +1031,17 @@ "4. What additional mesh, convergence, calibration, and comparison evidence\n", " would be required before reporting a fracture result?\n", "\n", - "If execution was unavailable, answer using the rendered outputs, then inspect\n", - "the [retained-results notebook](notebook_retained_results.ipynb). Continue with\n", + "If execution was unavailable, inspect the\n", + "[retained-results notebook](notebook_retained_results.ipynb) rather than\n", + "interpreting empty output cells. Continue with\n", "[From a tutorial to a first research study](06_first_research_study.md) before\n", - "adapting the example to a research problem.\n" + "adapting the example to a research problem.\n", + "\n", + "If a documented step fails, open a [GitHub issue](https://github.com/CEMS-Lab/PhAST/issues)\n", + "with the configuration, command, operating system, Python version, PhAST version\n", + "or commit, and complete error output.\n" ], "id": "setup-035" } - ], - "metadata": { - "colab": { - "provenance": [] - }, - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "name": "python", - "pygments_lexer": "ipython3" - } - }, - "nbformat": 4, - "nbformat_minor": 5 + ] } diff --git a/docs/tutorial/notebook_square_plate_fracture.ipynb b/docs/tutorial/notebook_square_plate_fracture.ipynb new file mode 100644 index 000000000..ea40302a5 --- /dev/null +++ b/docs/tutorial/notebook_square_plate_fracture.ipynb @@ -0,0 +1,795 @@ +{ + "nbformat": 4, + "nbformat_minor": 5, + "metadata": { + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "codemirror_mode": { + "name": "ipython", + "version": 3 + }, + "file_extension": ".py", + "mimetype": "text/x-python", + "name": "python", + "nbconvert_exporter": "python", + "pygments_lexer": "ipython3", + "version": "3.10.18" + } + }, + "cells": [ + { + "cell_type": "markdown", + "id": "422feac1", + "metadata": {}, + "source": [ + "# From geometry to crack propagation: a square-plate SENT simulation\n", + "\n", + "This tutorial performs a **fresh phase-field fracture calculation** with PhAST\n", + "in the conventional finite-element order:\n", + "\n", + "1. install and verify the software;\n", + "2. load the geometry;\n", + "3. generate and inspect the mesh and named boundaries;\n", + "4. define the material and phase-field model;\n", + "5. apply loads and boundary conditions;\n", + "6. select a supported analysis and solver route;\n", + "7. run the coupled problem with visible progress; and\n", + "8. inspect displacement, strain, stress, and damage and animate crack growth.\n", + "\n", + "The model is the 40 mm by 40 mm B3 single-edge-notched tension (SENT) plate. A\n", + "V-notch extends from the left boundary to \\(x=20\\) mm. This is a compact\n", + "teaching calculation derived from the public B3 input, not a new benchmark\n", + "validation or a mesh/time-step convergence study.\n", + "\n", + "The calculation uses a CPU; no GPU is required. Installation, meshing, solving,\n", + "and rendering have separate costs, and no portable runtime is claimed.\n", + "\n", + "The B3 input retains its **schema-v1 compatibility** format to preserve the\n", + "matched public example. For the single saved schema-v2 configuration workflow,\n", + "use the [standard problem-setup walkthrough](notebook_setup.ipynb).\n", + "This notebook does not extend the schema-v2 solver capability boundary.\n" + ] + }, + { + "cell_type": "markdown", + "id": "d229701b", + "metadata": {}, + "source": [ + "## 0. Install PhAST by the portable source route\n", + "\n", + "Use Python >=3.10 with compatible dependency wheels. For a new source checkout:\n", + "\n", + "~~~bash\n", + "git clone https://github.com/CEMS-Lab/PhAST.git\n", + "cd PhAST\n", + "python3 -m venv .venv\n", + "source .venv/bin/activate\n", + "python -m pip install --upgrade pip\n", + "python -m pip install -e . jupyterlab\n", + "python run_sanitizer.py\n", + "python -m phast doctor\n", + "jupyter lab docs/tutorial/notebook_square_plate_fracture.ipynb\n", + "~~~\n", + "\n", + "On Windows PowerShell, activate with .venv\\Scripts\\Activate.ps1.\n", + "Conda and Docker routes are in the [installation guide](../install.md). The base\n", + "CPU installation is sufficient; optional HPC backends are not required.\n", + "\n", + "For an existing checkout or a documentation build, use that checkout and its\n", + "prepared environment. Do not clone or install an older release over it. The\n", + "clone command above selects public `main`, which is mutable; local changes\n", + "are not assumed to be published there.\n" + ] + }, + { + "cell_type": "code", + "id": "8698f72e", + "metadata": {}, + "source": [ + "from __future__ import annotations\n", + "import copy\n", + "import os\n", + "from pathlib import Path\n", + "import re\n", + "import shutil\n", + "import subprocess\n", + "import sys\n", + "\n", + "from IPython.display import HTML, Image, Markdown, display\n", + "import matplotlib.pyplot as plt\n", + "import matplotlib.tri as mtri\n", + "from matplotlib.animation import FuncAnimation, PillowWriter\n", + "import numpy as np\n", + "import yaml\n", + "import h5py\n", + "\n", + "\n", + "def find_repository_root(start: Path) -> Path:\n", + " # Locate a source checkout from the notebook working directory.\n", + " start = start.resolve()\n", + " for candidate in (start, *start.parents):\n", + " if (candidate / \"pyproject.toml\").is_file() and (candidate / \"examples\").is_dir():\n", + " return candidate\n", + " raise RuntimeError(\n", + " \"Run this notebook from a cloned PhAST repository. \"\n", + " \"See the installation commands above.\"\n", + " )\n", + "\n", + "ROOT = find_repository_root(Path.cwd())\n", + "os.chdir(ROOT)\n", + "sys.path.insert(0, str(ROOT / \"src\"))\n", + "os.environ[\"PYTHONPATH\"] = str(ROOT / \"src\") + os.pathsep + os.environ.get(\"PYTHONPATH\", \"\")\n", + "\n", + "import phast\n", + "from phast.core.mesh import FEMMesh\n", + "from phast.physics.material import Material\n", + "\n", + "plt.rcParams.update({\"font.family\": \"STIXGeneral\", \"mathtext.fontset\": \"stix\"})\n", + "\n", + "def require_finite(values, name):\n", + " \"\"\"Reject empty or non-finite data rather than disguising a failed solve.\"\"\"\n", + " array = np.asarray(values)\n", + " if array.size == 0 or not np.isfinite(array).all():\n", + " raise ValueError(\n", + " f\"Empty or non-finite values in {name}; inspect the solver log \"\n", + " \"before plotting or interpreting this run.\"\n", + " )\n", + " return array\n", + "\n", + "output_root = Path(os.environ.get(\"PHAST_NOTEBOOK_OUTPUT_ROOT\", ROOT / \"runs\"))\n", + "base = output_root.expanduser().resolve() / \"tutorial_square_plate\"\n", + "RUN_DIR = base\n", + "suffix = 2\n", + "while RUN_DIR.exists():\n", + " RUN_DIR = Path(f\"{base}_{suffix}\")\n", + " suffix += 1\n", + "RUN_DIR.mkdir(parents=True)\n", + "\n", + "GEO_SOURCE = Path(\"examples/dynamic/B3_dynamic_sent/mesh.geo\")\n", + "BASE_CONFIG = Path(\"examples/dynamic/B3_dynamic_sent/config.yaml\")\n", + "GEO_PATH = RUN_DIR / \"mesh.geo\"\n", + "MESH_PATH = RUN_DIR / \"mesh.msh\"\n", + "CONFIG_PATH = RUN_DIR / \"config.yaml\"\n", + "\n", + "print(f\"Repository: {ROOT.name}\")\n", + "print(f\"Tutorial output: {RUN_DIR}\")\n", + "print(f\"PhAST import: {Path(phast.__file__).resolve().relative_to(ROOT)}\")\n" + ], + "outputs": [], + "execution_count": null + }, + { + "cell_type": "markdown", + "id": "166d2de2", + "metadata": {}, + "source": [ + "## 1. Load the geometry and identify its boundaries\n", + "\n", + "The checked-in Gmsh file defines the square, the left-edge notch, a refinement\n", + "line along the expected crack corridor, and named physical curves. The exterior\n", + "sides are top, bottom, left, and\n", + "right; the notch faces are notch_upper and\n", + "notch_lower. These names connect geometry to boundary conditions\n", + "without coordinate-based node selection." + ] + }, + { + "cell_type": "code", + "id": "d73c4108", + "metadata": {}, + "source": [ + "shutil.copy2(GEO_SOURCE, GEO_PATH)\n", + "geo_text = GEO_PATH.read_text(encoding=\"utf-8\")\n", + "print(f\"Loaded geometry: {GEO_PATH}\")\n", + "print(\"\\nGeometry entities and physical groups:\\n\")\n", + "for line in geo_text.splitlines():\n", + " stripped = line.strip()\n", + " if stripped.startswith((\"Point(\", \"Line(\", \"Physical Curve\", \"Physical Surface\")):\n", + " print(stripped)" + ], + "outputs": [], + "execution_count": null + }, + { + "cell_type": "markdown", + "id": "79db8119", + "metadata": {}, + "source": [ + "## 2. Generate and inspect the finite-element mesh\n", + "\n", + "Gmsh creates first-order triangles with refinement around the notch and expected\n", + "horizontal crack path. PhAST reads the mesh through meshio and\n", + "converts the physical curves into named node sets. Fracture resolution is\n", + "assessed relative to \\(\\ell_0\\), not only by visual appearance." + ] + }, + { + "cell_type": "code", + "id": "607c70cd", + "metadata": {}, + "source": [ + "gmsh_executable = shutil.which(\"gmsh\")\n", + "if gmsh_executable is None:\n", + " raise RuntimeError(\n", + " \"Gmsh was not found. Reinstall the PhAST environment or follow \"\n", + " \"the Gmsh recovery advice in docs/install.md.\"\n", + " )\n", + "\n", + "completed = subprocess.run(\n", + " [gmsh_executable, str(GEO_PATH), \"-2\", \"-format\", \"msh2\", \"-o\", str(MESH_PATH)],\n", + " cwd=ROOT,\n", + " text=True,\n", + " capture_output=True,\n", + " timeout=60,\n", + ")\n", + "if completed.returncode != 0:\n", + " raise RuntimeError(completed.stderr or completed.stdout)\n", + "\n", + "mesh = FEMMesh(str(MESH_PATH), device=\"cpu\")\n", + "nodes = require_finite(mesh.nodes.detach().cpu().numpy(), \"mesh coordinates\")\n", + "elements = mesh.elements.detach().cpu().numpy()\n", + "triangulation = mtri.Triangulation(nodes[:, 0], nodes[:, 1], elements)\n", + "\n", + "boundary_colours = {\n", + " \"top\": \"#2f6f9f\", \"bottom\": \"#2f6f9f\",\n", + " \"left\": \"#4f4f4f\", \"right\": \"#4f4f4f\",\n", + " \"notch_upper\": \"#b24a3b\", \"notch_lower\": \"#b24a3b\",\n", + "}\n", + "fig, ax = plt.subplots(figsize=(8.2, 7.0), constrained_layout=True)\n", + "ax.triplot(triangulation, color=\"#c8c8c8\", linewidth=0.35)\n", + "for name, colour in boundary_colours.items():\n", + " indices = mesh.node_sets[name].detach().cpu().numpy()\n", + " points = nodes[indices]\n", + " ax.scatter(points[:, 0], points[:, 1], s=13, color=colour, label=name, zorder=3)\n", + "ax.set(aspect=\"equal\", xlabel=\"x [mm]\", ylabel=\"y [mm]\",\n", + " title=\"Generated mesh and named boundary node sets\")\n", + "ax.legend(ncol=3, loc=\"upper center\", bbox_to_anchor=(0.5, -0.09), frameon=False)\n", + "plt.show()\n", + "print(mesh.summary())\n" + ], + "outputs": [], + "execution_count": null + }, + { + "cell_type": "markdown", + "id": "a7773021", + "metadata": {}, + "source": [ + "## 3. Define the material and phase-field model\n", + "\n", + "| Quantity | Symbol | Value |\n", + "|---|---:|---:|\n", + "| Young's modulus | \\(E\\) | 32,000 MPa |\n", + "| Poisson ratio | \\(\\nu\\) | 0.20 |\n", + "| Density | \\(\\rho\\) | \\(2.45\\times10^{-9}\\) tonne/mm\\(^3\\) |\n", + "| Critical fracture energy | \\(G_c\\) | 0.003 N/mm |\n", + "| Phase-field length | \\(\\ell_0\\) | 0.5 mm |\n", + "| Residual stiffness | \\(\\eta\\) | \\(10^{-7}\\) |\n", + "| Model and energy split | | AT2, spectral |\n", + "| Kinematics | | plane strain |\n", + "\n", + "Here \\(d=0\\) denotes intact material and \\(d=1\\) fully developed damage. These\n", + "parameters are retained for the teaching example; they are not calibration\n", + "recommendations for another material." + ] + }, + { + "cell_type": "code", + "id": "7942288a", + "metadata": {}, + "source": [ + "source_config = yaml.safe_load(BASE_CONFIG.read_text(encoding=\"utf-8\"))\n", + "m = source_config[\"material\"]\n", + "material = Material(\n", + " E=m[\"E\"], nu=m[\"nu\"], Gc=m[\"Gc\"], l0=m[\"l0\"], rho=m[\"rho\"],\n", + " eta_residual=m[\"eta_residual\"], energy_split=m[\"energy_split\"],\n", + " pf_model=m[\"pf_model\"], plane_stress=m.get(\"plane_stress\", False),\n", + ")\n", + "h_min = float(mesh.h_min)\n", + "print(material)\n", + "print(f\"h_min / l0 = {h_min / float(material.l0):.3f}\")" + ], + "outputs": [], + "execution_count": null + }, + { + "cell_type": "markdown", + "id": "2b72df06", + "metadata": {}, + "source": [ + "## 4. Apply loads and boundary conditions\n", + "\n", + "| Region | Condition |\n", + "|---|---|\n", + "| left | \\(u_x=0\\) |\n", + "| right | \\(u_x=0\\) |\n", + "| top | prescribed \\(u_y=+0.002\\) mm |\n", + "| bottom | prescribed \\(u_y=-0.002\\) mm |\n", + "| notch faces | traction-free geometric boundaries |\n", + "\n", + "The vertical displacement follows a smooth ramp over the first 20 microseconds\n", + "and is then held. The signs pull the upper and lower boundaries apart." + ] + }, + { + "cell_type": "code", + "id": "a5ed8e3a", + "metadata": {}, + "source": [ + "display(Markdown(\n", + " \"~~~yaml\\n\"\n", + " + yaml.safe_dump(\n", + " {\"boundary_conditions\": source_config[\"boundary_conditions\"],\n", + " \"loading\": source_config[\"loading\"]},\n", + " sort_keys=False,\n", + " )\n", + " + \"~~~\"\n", + "))" + ], + "outputs": [], + "execution_count": null + }, + { + "cell_type": "markdown", + "id": "4d7c6591", + "metadata": {}, + "source": [ + "## 5. Select the analysis and solver route\n", + "\n", + "Dynamic versus quasi-static describes treatment of inertia. Explicit versus\n", + "implicit describes how a subproblem is advanced or solved. They are not four\n", + "interchangeable choices.\n", + "\n", + "| Route | Current public status | Use here |\n", + "|---|---|---|\n", + "| Dynamic mechanics, explicit central difference | Supported | **Selected** |\n", + "| Quasi-static mechanics and damage solves | Supported in separate examples | Not selected |\n", + "| Implicit dynamic generalized-\\(\\alpha\\) mechanics | Not a production route | Not selectable |\n", + "| Fully explicit damage evolution | Not this classical route | Not selectable |\n", + "\n", + "Mechanics is advanced explicitly with a lumped mass matrix. At every time\n", + "increment, PhAST updates the tensile history and solves the current AT2 damage\n", + "equation with matrix-free, Jacobi-preconditioned conjugate gradients. This is an\n", + "implicit damage update, not implicit dynamics.\n", + "\n", + "For fixed history \\(H\\), the AT2 damage equation on this route is linear in\n", + "\\(d\\). The overall evolution remains coupled because mechanics changes \\(H\\)\n", + "and damage changes the degraded stiffness used next:\n", + "\n", + "\\[\n", + "(\\mathbf{u}_n,\\mathbf{v}_n,\\mathbf{a}_n,d_n)\n", + "\\rightarrow \\mathbf{u}_{n+1}\n", + "\\rightarrow H_{n+1}\n", + "\\rightarrow d_{n+1}\n", + "\\rightarrow (\\mathbf{v}_{n+1},\\mathbf{a}_{n+1}).\n", + "\\]\n", + "\n", + "This partitioned sequence differs from repeated alternate-minimization\n", + "iterations within a quasi-static load increment. The CFL condition controls\n", + "explicit time-step stability; the damage tolerance controls residual\n", + "convergence of the linear damage solve. One cannot replace the other." + ] + }, + { + "cell_type": "markdown", + "id": "5571152f", + "metadata": {}, + "source": [ + "## 6. Choose a CFL-safe step count and write the configuration\n", + "\n", + "Changing only the explicit step count while retaining an unrelated time\n", + "increment is unsafe. This notebook computes\n", + "\n", + "\\[\n", + "\\Delta t = 0.8\\,h_{\\min}/c_p,\n", + "\\]\n", + "\n", + "then selects 6,101 increments and sets the end time consistently. Final index\n", + "6,100 is divisible by the snapshot interval of 50, so the last stored field is\n", + "the actual final solver step. The portable Jacobi damage route requires no\n", + "optional sparse or HPC backend." + ] + }, + { + "cell_type": "code", + "id": "154c3939", + "metadata": {}, + "source": [ + "NUM_STEPS = 6101\n", + "SNAPSHOT_EVERY = 50\n", + "PRINT_EVERY = 100\n", + "DT_SAFETY = 0.8\n", + "\n", + "dt = DT_SAFETY * h_min / float(material.c_p)\n", + "t_total = NUM_STEPS * dt\n", + "assert (NUM_STEPS - 1) % SNAPSHOT_EVERY == 0\n", + "\n", + "config = copy.deepcopy(source_config)\n", + "config[\"problem\"][\"name\"] = \"Square-plate SENT: executable teaching calculation\"\n", + "config[\"geometry\"] = {\"mesh_path\": \"mesh.msh\"}\n", + "config[\"loading\"].update({\"num_steps\": NUM_STEPS, \"dt\": dt, \"t_total\": t_total})\n", + "config[\"solver\"].update({\n", + " \"solver_type\": \"explicit\",\n", + " \"time_integrator\": \"central_difference\",\n", + " \"dt_safety\": DT_SAFETY,\n", + " \"damage_every\": 1,\n", + " \"use_multigrid\": False,\n", + " \"preconditioner\": \"jacobi\",\n", + " \"damage_max_iter\": 1000,\n", + "})\n", + "config[\"output\"].update({\n", + " \"trajectory\": True,\n", + " \"h5\": True,\n", + " \"trajectory_format\": \"h5\",\n", + " \"h5_every\": SNAPSHOT_EVERY,\n", + " \"print_every\": PRINT_EVERY,\n", + " \"plots\": False,\n", + " \"gif\": False,\n", + " \"profile\": True,\n", + "})\n", + "config[\"device\"] = {\"device\": \"cpu\", \"compile\": False}\n", + "CONFIG_PATH.write_text(yaml.safe_dump(config, sort_keys=False), encoding=\"utf-8\")\n", + "\n", + "print(f\"Configuration: {CONFIG_PATH}\")\n", + "print(\"Selected route: dynamic / explicit mechanics / implicit AT2 damage\")\n", + "print(f\"Number of steps: {NUM_STEPS}\")\n", + "print(f\"Stable dt: {dt:.6e} s\")\n", + "print(f\"End time: {t_total * 1e6:.3f} microseconds\")\n", + "print(f\"Stored snapshots: {(NUM_STEPS - 1) // SNAPSHOT_EVERY + 1}\")" + ], + "outputs": [], + "execution_count": null + }, + { + "cell_type": "markdown", + "id": "1bcc0f0d", + "metadata": {}, + "source": [ + "## 7. Validate, then run with actual progress\n", + "\n", + "--validate-only checks the YAML schema; it does not solve the PDE\n", + "or establish scientific validity. The progress bar below is driven by actual\n", + "step lines emitted by PhAST, not an elapsed-time estimate. The log prints the\n", + "resolved device, integrator, phase-field model, history update, damage route,\n", + "bounds treatment, and preconditioner." + ] + }, + { + "cell_type": "code", + "id": "ec6274c1", + "metadata": {}, + "source": [ + "preflight = subprocess.run(\n", + " [sys.executable, \"-m\", \"phast\", \"run\", str(CONFIG_PATH), \"--validate-only\"],\n", + " cwd=ROOT, text=True, capture_output=True, timeout=60,\n", + ")\n", + "print(preflight.stdout, end=\"\")\n", + "print(preflight.stderr, end=\"\")\n", + "if preflight.returncode != 0:\n", + " raise RuntimeError(\"Configuration preflight failed.\")\n" + ], + "outputs": [], + "execution_count": null + }, + { + "cell_type": "code", + "id": "6cc1857e", + "metadata": {}, + "source": [ + "if any((RUN_DIR / name).exists() for name in (\"training_data.h5\", \"training_data.zarr\")):\n", + " raise RuntimeError(\n", + " f\"{RUN_DIR} already contains a trajectory. Restart the kernel to create \"\n", + " \"a new numbered directory rather than overwriting evidence.\"\n", + " )\n", + "\n", + "run_command = [\n", + " sys.executable, \"-m\", \"phast\", \"run\", str(CONFIG_PATH),\n", + " \"--device\", \"cpu\", \"--output_dir\", str(RUN_DIR),\n", + "]\n", + "progress = display(\n", + " HTML(f\" \"\n", + " f\"0 / {NUM_STEPS} steps\"),\n", + " display_id=True,\n", + ")\n", + "process = subprocess.Popen(\n", + " run_command, cwd=ROOT, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,\n", + " text=True, bufsize=1,\n", + ")\n", + "assert process.stdout is not None\n", + "for line in process.stdout:\n", + " print(line, end=\"\")\n", + " match = re.search(r\"Step\\s+(\\d+)\", line)\n", + " if match:\n", + " completed_step = int(match.group(1)) + 1\n", + " progress.update(\n", + " HTML(f\" \"\n", + " f\"{completed_step:,} / {NUM_STEPS:,} steps\")\n", + " )\n", + "return_code = process.wait()\n", + "if return_code != 0:\n", + " raise RuntimeError(f\"PhAST exited with status {return_code}.\")\n", + "progress.update(\n", + " HTML(f\" \"\n", + " f\"{NUM_STEPS:,} / {NUM_STEPS:,} steps complete\")\n", + ")" + ], + "outputs": [], + "execution_count": null + }, + { + "cell_type": "markdown", + "id": "a5cdd77f", + "metadata": {}, + "source": [ + "## 8. Load and check the stored fields\n", + "\n", + "Displacement and damage are nodal fields. Strain and stress, when stored, are\n", + "element fields. The checks require final stored step 6,100 and reject empty or\n", + "non-finite arrays before plotting. Missing optional strain or stress output\n", + "is reported, not replaced by a fabricated field.\n" + ] + }, + { + "cell_type": "code", + "id": "04a5c150", + "metadata": {}, + "source": [ + "result = phast.load_result(RUN_DIR)\n", + "print(\"Stored fields:\", result.field_names())\n", + "\n", + "final_step = NUM_STEPS - 1\n", + "final_fields = {}\n", + "for name in (\"displacement\", \"strain\", \"stress\", \"damage\"):\n", + " if not result.has_field(name):\n", + " if name in {\"displacement\", \"damage\"}:\n", + " raise RuntimeError(f\"Required {name} trajectory is missing.\")\n", + " print(f\"Optional {name} output was not stored; its plot will be omitted.\")\n", + " continue\n", + " field = require_finite(result.field(name, step=final_step), name)\n", + " final_fields[name] = field\n", + " print(f\"{name:12s} shape={field.shape}, min={field.min():.6g}, max={field.max():.6g}\")\n", + "\n", + "displacement = final_fields[\"displacement\"]\n", + "damage = final_fields[\"damage\"]\n", + "strain = final_fields.get(\"strain\")\n", + "stress = final_fields.get(\"stress\")\n", + "\n", + "with h5py.File(RUN_DIR / \"training_data.h5\", \"r\") as store:\n", + " simulation = store[\"simulation_data\"]\n", + " snapshots = simulation[\"steps\"]\n", + " step_names = sorted(snapshots, key=lambda name: int(name.rsplit(\"_\", 1)[-1]))\n", + " stored_steps = np.asarray([int(name.rsplit(\"_\", 1)[-1]) for name in step_names])\n", + " stored_times = require_finite(\n", + " np.asarray([snapshots[name].attrs[\"time_s\"] for name in step_names]),\n", + " \"snapshot times\",\n", + " )\n", + " coordinates = require_finite(\n", + " np.asarray(simulation[\"mesh\"][\"node_coordinates\"]), \"stored mesh coordinates\"\n", + " )\n", + " connectivity = np.asarray(simulation[\"mesh\"][\"element_connectivity\"])\n", + "if not len(stored_steps) or int(stored_steps[-1]) != final_step:\n", + " raise RuntimeError(\"The final solver step is not present in the trajectory.\")\n", + "if displacement.shape != (len(coordinates), 2) or damage.shape != (len(coordinates),):\n", + " raise ValueError(\"Stored nodal fields do not match the mesh.\")\n", + "for name, field in ((\"strain\", strain), (\"stress\", stress)):\n", + " if field is not None and field.shape != (len(connectivity), 3):\n", + " raise ValueError(f\"Unexpected in-plane {name} shape: {field.shape}\")\n", + "\n", + "plot_mesh = mtri.Triangulation(coordinates[:, 0], coordinates[:, 1], connectivity)\n" + ], + "outputs": [], + "execution_count": null + }, + { + "cell_type": "markdown", + "id": "a5b2949f", + "metadata": {}, + "source": [ + "## 9. Visualise the available final fields\n", + "\n", + "The views show displacement magnitude, vertical strain, an **in-plane\n", + "equivalent stress**, and phase-field damage. The stress scalar uses only the\n", + "stored \\((\\sigma_{xx},\\sigma_{yy},\\sigma_{xy})\\) components:\n", + "\n", + "\\[\n", + "\\sigma_{\\mathrm{eq,in\\mbox{-}plane}}\n", + "= \\sqrt{\\sigma_{xx}^{2}-\\sigma_{xx}\\sigma_{yy}\n", + " +\\sigma_{yy}^{2}+3\\sigma_{xy}^{2}}.\n", + "\\]\n", + "\n", + "This is **not the full three-dimensional von Mises stress for plane strain**.\n", + "The out-of-plane stress \\(\\sigma_{zz}\\) is not included in these stored fields;\n", + "it is not reconstructed here, particularly with the selected spectral\n", + "tension/compression split and damage degradation. This scalar is a labelled\n", + "visualisation, not a yield or failure criterion.\n", + "\n", + "Element fields are rendered elementwise. Both the static damage plot and the\n", + "animation use `Reds` with the fixed scale \\(0\\leq d\\leq1\\).\n" + ] + }, + { + "cell_type": "code", + "id": "5d69052b", + "metadata": {}, + "source": [ + "u_magnitude = require_finite(np.linalg.norm(displacement, axis=1), \"displacement magnitude\")\n", + "epsilon_yy = None if strain is None else strain[:, 1]\n", + "in_plane_equivalent_stress = None\n", + "if stress is not None:\n", + " sigma_xx, sigma_yy, sigma_xy = stress.T\n", + " in_plane_equivalent_stress = require_finite(\n", + " np.sqrt(np.maximum(\n", + " sigma_xx**2 - sigma_xx * sigma_yy + sigma_yy**2 + 3.0 * sigma_xy**2,\n", + " 0.0,\n", + " )),\n", + " \"in-plane equivalent stress\",\n", + " )\n", + "\n", + "fig, axes = plt.subplots(2, 2, figsize=(12, 9), constrained_layout=True)\n", + "specs = [\n", + " (\"Displacement magnitude, |u| [mm]\", u_magnitude, \"cividis\", \"nodal\"),\n", + " (\"Vertical strain, epsilon_yy [-]\", epsilon_yy, \"RdBu_r\", \"element\"),\n", + " (\"In-plane equivalent stress [MPa]\", in_plane_equivalent_stress, \"viridis\", \"element\"),\n", + " (\"Phase-field damage, d [-]\", damage, \"Reds\", \"nodal\"),\n", + "]\n", + "for ax, (title, field, cmap, location) in zip(axes.flat, specs):\n", + " if field is None:\n", + " ax.text(0.5, 0.5, f\"{title}\\nOptional field not stored\",\n", + " ha=\"center\", va=\"center\", transform=ax.transAxes)\n", + " ax.axis(\"off\")\n", + " continue\n", + " field = require_finite(field, title)\n", + " limits = dict(vmin=0.0, vmax=1.0) if cmap == \"Reds\" else {}\n", + " artist = (\n", + " ax.tripcolor(plot_mesh, field, shading=\"gouraud\", cmap=cmap, **limits)\n", + " if location == \"nodal\"\n", + " else ax.tripcolor(plot_mesh, facecolors=field, shading=\"flat\", cmap=cmap, **limits)\n", + " )\n", + " ax.set(aspect=\"equal\", xlabel=\"x [mm]\", ylabel=\"y [mm]\", title=title)\n", + " fig.colorbar(artist, ax=ax, shrink=0.82)\n", + "fig.suptitle(\n", + " f\"Square-plate SENT: step {final_step} at {stored_times[-1] * 1e6:.2f} microseconds\",\n", + " fontsize=14,\n", + ")\n", + "field_figure = RUN_DIR / \"final_fields.png\"\n", + "fig.savefig(field_figure, dpi=160)\n", + "plt.show()\n", + "print(f\"Saved: {field_figure}\")\n" + ], + "outputs": [], + "execution_count": null + }, + { + "cell_type": "markdown", + "id": "b8ae2b46", + "metadata": {}, + "source": [ + "## 10. Animate the stored damage evolution\n", + "\n", + "The geometric notch terminates at \\(x=20\\) mm. Inspect whether and where the\n", + "stored high-damage band advances. Every selected frame is checked for finite\n", + "values before rendering. An animation is not evidence of mesh convergence,\n", + "time-step convergence, or experimental agreement.\n" + ] + }, + { + "cell_type": "code", + "id": "8b62f6ea", + "metadata": {}, + "source": [ + "frame_indices = np.unique(np.linspace(0, len(stored_steps) - 1, 62, dtype=int))\n", + "damage_frames = [\n", + " require_finite(result.field(\"damage\", step=int(stored_steps[index])),\n", + " f\"damage at step {stored_steps[index]}\")\n", + " for index in frame_indices\n", + "]\n", + "if any(field.shape != (len(coordinates),) for field in damage_frames):\n", + " raise ValueError(\"A damage frame does not match the mesh nodes.\")\n", + "fig, ax = plt.subplots(figsize=(7.2, 6.2), constrained_layout=True)\n", + "artist = ax.tripcolor(\n", + " plot_mesh, damage_frames[0],\n", + " shading=\"gouraud\", cmap=\"Reds\", vmin=0.0, vmax=1.0,\n", + ")\n", + "ax.set(aspect=\"equal\", xlabel=\"x [mm]\", ylabel=\"y [mm]\")\n", + "fig.colorbar(artist, ax=ax).set_label(\"damage d\")\n", + "\n", + "def update_animation(frame_number: int):\n", + " index = frame_indices[frame_number]\n", + " artist.set_array(damage_frames[frame_number])\n", + " ax.set_title(\n", + " f\"Crack evolution: step {stored_steps[index]} | \"\n", + " f\"t = {stored_times[index] * 1e6:.2f} microseconds\"\n", + " )\n", + " return (artist,)\n", + "\n", + "animation = FuncAnimation(\n", + " fig, update_animation, frames=len(frame_indices), interval=100, blit=False\n", + ")\n", + "animation_path = RUN_DIR / \"crack_evolution.gif\"\n", + "animation.save(animation_path, writer=PillowWriter(fps=10), dpi=115)\n", + "plt.close(fig)\n", + "display(Image(filename=str(animation_path)))\n", + "print(f\"Saved: {animation_path}\")\n" + ], + "outputs": [], + "execution_count": null + }, + { + "cell_type": "markdown", + "id": "011ce49e", + "metadata": {}, + "source": [ + "## 11. Summarize and retain the result\n", + "\n", + "The \\(x\\)-extent of nodes with \\(d\\geq0.95\\) is descriptive. It does not replace\n", + "a crack-tip algorithm, energy balance, convergence study, or experiment." + ] + }, + { + "cell_type": "code", + "id": "08c600f6", + "metadata": {}, + "source": [ + "high_damage_nodes = coordinates[damage >= 0.95]\n", + "if len(high_damage_nodes):\n", + " print(\n", + " \"Nodes with d >= 0.95 span \"\n", + " f\"x = {high_damage_nodes[:, 0].min():.3f} to \"\n", + " f\"{high_damage_nodes[:, 0].max():.3f} mm.\"\n", + " )\n", + "print(\"\\nTop-level run artifacts:\")\n", + "for artifact in sorted(RUN_DIR.iterdir()):\n", + " if artifact.name != \"training_data.h5\":\n", + " print(f\" {artifact.name}\")\n", + "print(\" training_data.h5 (single-file reloadable trajectory)\")" + ], + "outputs": [], + "execution_count": null + }, + { + "cell_type": "markdown", + "id": "d32c4584", + "metadata": {}, + "source": [ + "## Interpretation and limitations\n", + "\n", + "Successful execution demonstrates this workflow for the selected configuration.\n", + "The cells report which fields were stored, check their finiteness, and print\n", + "the actual extent of nodes exceeding the stated damage threshold. Cleared\n", + "notebook outputs make no claim about a previously computed crack path.\n", + "\n", + "Do not infer more than that:\n", + "\n", + "- the mesh and time increment have not undergone a convergence study;\n", + "- the result is not newly compared with the Borden et al. benchmark data;\n", + "- the compact mesh is instructional, not a publication-quality prediction;\n", + "- local CPU timing is not a portable performance claim;\n", + "- changing \\(G_c\\), \\(\\ell_0\\), loading, or mesh defines a new study and\n", + " requires corresponding resolution and validation checks.\n", + "\n", + "For quasi-static fracture, use\n", + "examples/quasistatic/miehe_tension/config.yaml. Do not change only\n", + "the solver type here and assume the boundary-value problem remains equivalent.\n", + "\n", + "## Suggested student exercise\n", + "\n", + "Predict first, modify one item, and rerun into a new directory:\n", + "\n", + "- increase SNAPSHOT_EVERY to reduce stored trajectory size without\n", + " changing the solver update cadence; or\n", + "- refine the mesh and recompute the CFL increment before changing the step count.\n", + "\n", + "If installation, execution, or interpretation remains unclear, open a\n", + "[GitHub issue](https://github.com/CEMS-Lab/PhAST/issues) with the first error,\n", + "platform, Python version, command, and configuration. Questions, reproducible\n", + "bug reports, documentation corrections, and student contributions are welcome.\n" + ] + } + ] +} diff --git a/docs/tutorial/problem_setup_walkthrough.ipynb b/docs/tutorial/problem_setup_walkthrough.ipynb index c87acb78f..5f98de82a 100644 --- a/docs/tutorial/problem_setup_walkthrough.ipynb +++ b/docs/tutorial/problem_setup_walkthrough.ipynb @@ -1,4 +1,20 @@ { + "nbformat": 4, + "nbformat_minor": 5, + "metadata": { + "colab": { + "provenance": [] + }, + "kernelspec": { + "display_name": "Python 3", + "language": "python", + "name": "python3" + }, + "language_info": { + "name": "python", + "pygments_lexer": "ipython3" + } + }, "cells": [ { "cell_type": "markdown", @@ -11,7 +27,7 @@ "This notebook builds a small single-edge-notched tension problem from first\n", "principles. It creates and inspects the geometry and mesh, defines the material\n", "and boundary-value problem with the fluent Python API, writes a runnable\n", - "schema-v1 YAML configuration, performs a bounded two-step CPU solve, and\n", + "schema-v2 YAML configuration, performs a bounded two-step CPU solve, and\n", "inspects the resulting artifacts.\n", "\n", "Learning objectives:\n", @@ -20,8 +36,7 @@ "2. Verify physical groups before using them as PhAST regions.\n", "3. Apply material parameters, initial-condition choices, supports, and\n", " prescribed loading.\n", - "4. Distinguish the fluent authoring representation from the runnable YAML\n", - " contract.\n", + "4. Use one saved configuration for setup validation and solver execution.\n", "5. Run a short quasi-static phase-field workflow check and inspect the generated\n", " output directory.\n", "6. Locate final field images, histories, trajectory stores, and optional\n", @@ -37,8 +52,8 @@ " do not change all three at once.\n", "- **Explain:** state which discretization, constitutive, or loading choice\n", " changed and which output should respond.\n", - "- **Fallback:** if installation or execution is unavailable, use the rendered\n", - " cell outputs and continue with the retained-results notebook.\n", + "- **Fallback:** if installation or execution is unavailable, continue with the\n", + " retained-results notebook. Cleared output cells are not computed evidence.\n", "\n", "The default run is intentionally short and is not crack-growth validation. For\n", "a research calculation, start from the closest checked-in example, refine the\n", @@ -84,7 +99,8 @@ "\n", "**Predict before continuing:** Which named boundary should remove rigid vertical\n", "motion? Which boundary should carry the prescribed displacement? Where should\n", - "the initial notch appear in the setup plot?\n" + "the initial notch appear in the setup plot?\n", + "" ], "id": "setup-002" }, @@ -94,26 +110,33 @@ "source": [ "## 1. Install dependencies\n", "\n", - "Run this cell in Colab. In a local clone, install PhAST with\n", - "`pip install -e .` from the repository root and skip the Colab-specific\n", - "package installation if your environment is already configured.\n", + "Use Python >=3.10 with compatible dependency wheels. From the **current\n", + "repository checkout**, prepare a local environment and install JupyterLab:\n", + "\n", + "```bash\n", + "python -m pip install -e . jupyterlab\n", + "jupyter lab docs/tutorial/problem_setup_walkthrough.ipynb\n", + "```\n", + "\n", + "The cell below installs packages only in Colab. Local notebook execution and\n", + "documentation builds use the current checkout without changing the environment\n", + "or replacing its source with an older release.\n", "\n", - "The Colab route checks out the published\n", - "`v0.16.2-arxiv.2606.23458` release rather than the mutable default branch. It\n", - "rejects a cached checkout whose origin, commit, or tracked files do not match\n", - "the expected release and prints the resolved commit for the session record.\n", + "Colab uses the public `main` branch, which is **mutable**, and prints the\n", + "resolved commit. A local branch may contain changes not yet published on\n", + "`main`; use the notebook bundled with your selected checkout. The subsequent\n", + "configuration check and solve must succeed before interpreting any result.\n", + "This notebook does not establish that unpublished changes are available remotely.\n", "\n", - "The notebook uses Gmsh to create `mesh.msh`, MeshIO to inspect physical\n", - "groups, Matplotlib and Pillow for visual checks, and PhAST for solving and\n", - "result inspection.\n" + "Gmsh creates the mesh, MeshIO inspects physical groups, and Matplotlib and Pillow\n", + "provide visualisation. HDF5 stores the requested trajectory. See the\n", + "[installation guide](../install.md) for platform-specific Gmsh dependencies.\n" ], "id": "3e29f8e1" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "import os\n", "import sys\n", @@ -122,107 +145,62 @@ "\n", "IN_COLAB = \"google.colab\" in sys.modules\n", "PHAST_REPOSITORY = \"https://github.com/CEMS-Lab/PhAST.git\"\n", - "PHAST_REVISION = \"v0.16.2-arxiv.2606.23458\"\n", + "PHAST_REVISION = \"main\" # Mutable public branch, not an immutable release.\n", "\n", "if IN_COLAB:\n", " subprocess.run([\"apt-get\", \"update\", \"-qq\"], check=True)\n", - " subprocess.run([\"apt-get\", \"install\", \"-y\", \"-qq\", \"gmsh\", \"ffmpeg\"], check=True)\n", - "\n", - " checkout = Path(\"/content\") / f\"PhAST-{PHAST_REVISION}\"\n", + " subprocess.run([\"apt-get\", \"install\", \"-y\", \"-qq\", \"gmsh\"], check=True)\n", + " checkout = Path(\"/content/PhAST-main\")\n", " if checkout.exists():\n", " if not (checkout / \".git\").is_dir():\n", " raise RuntimeError(\n", - " f\"{checkout} exists but is not a Git checkout. \"\n", - " \"Restart the runtime or remove that directory explicitly.\"\n", + " f\"{checkout} is not a Git checkout. Restart the Colab runtime.\"\n", " )\n", " origin = subprocess.check_output(\n", " [\"git\", \"-C\", str(checkout), \"config\", \"--get\", \"remote.origin.url\"],\n", " text=True,\n", " ).strip()\n", " if origin != PHAST_REPOSITORY:\n", - " raise RuntimeError(\n", - " f\"Cached checkout origin is {origin!r}, expected {PHAST_REPOSITORY!r}.\"\n", - " )\n", + " raise RuntimeError(f\"Unexpected cached checkout origin: {origin!r}\")\n", " else:\n", " subprocess.run(\n", - " [\n", - " \"git\",\n", - " \"clone\",\n", - " \"--branch\",\n", - " PHAST_REVISION,\n", - " \"--depth\",\n", - " \"1\",\n", - " PHAST_REPOSITORY,\n", - " str(checkout),\n", - " ],\n", + " [\"git\", \"clone\", \"--branch\", PHAST_REVISION, \"--depth\", \"1\",\n", + " PHAST_REPOSITORY, str(checkout)],\n", " check=True,\n", " )\n", - "\n", " subprocess.run(\n", - " [\n", - " \"git\",\n", - " \"-C\",\n", - " str(checkout),\n", - " \"fetch\",\n", - " \"--depth\",\n", - " \"1\",\n", - " \"origin\",\n", - " f\"refs/tags/{PHAST_REVISION}:refs/tags/{PHAST_REVISION}\",\n", - " ],\n", + " [\"git\", \"-C\", str(checkout), \"fetch\", \"--depth\", \"1\",\n", + " \"origin\", \"refs/heads/main\"],\n", " check=True,\n", " )\n", " expected_commit = subprocess.check_output(\n", - " [\"git\", \"-C\", str(checkout), \"rev-list\", \"-n\", \"1\", PHAST_REVISION],\n", - " text=True,\n", + " [\"git\", \"-C\", str(checkout), \"rev-parse\", \"FETCH_HEAD\"], text=True\n", " ).strip()\n", " resolved_commit = subprocess.check_output(\n", - " [\"git\", \"-C\", str(checkout), \"rev-parse\", \"HEAD\"],\n", - " text=True,\n", + " [\"git\", \"-C\", str(checkout), \"rev-parse\", \"HEAD\"], text=True\n", " ).strip()\n", " tracked_changes = subprocess.check_output(\n", - " [\n", - " \"git\",\n", - " \"-C\",\n", - " str(checkout),\n", - " \"status\",\n", - " \"--porcelain\",\n", - " \"--untracked-files=no\",\n", - " ],\n", + " [\"git\", \"-C\", str(checkout), \"status\", \"--porcelain\", \"--untracked-files=no\"],\n", " text=True,\n", " ).strip()\n", " if resolved_commit != expected_commit or tracked_changes:\n", " raise RuntimeError(\n", - " \"Cached PhAST checkout does not match the documented release. \"\n", - " \"Restart the Colab runtime before continuing.\"\n", + " \"The cached checkout differs from public main. Restart the Colab \"\n", + " \"runtime rather than overwriting local changes.\"\n", " )\n", - "\n", - " print(f\"PhAST release: {PHAST_REVISION}\")\n", + " print(f\"Public source: {PHAST_REVISION} (mutable)\")\n", " print(f\"Resolved commit: {resolved_commit}\")\n", " subprocess.run(\n", - " [\n", - " sys.executable,\n", - " \"-m\",\n", - " \"pip\",\n", - " \"install\",\n", - " \"-q\",\n", - " \"-e\",\n", - " str(checkout),\n", - " \"meshio\",\n", - " \"matplotlib\",\n", - " \"zarr\",\n", - " \"h5py\",\n", - " \"pyyaml\",\n", - " ],\n", + " [sys.executable, \"-m\", \"pip\", \"install\", \"-q\", \"-e\", str(checkout), \"jupyterlab\"],\n", " check=True,\n", " )\n", " os.chdir(checkout)\n", "else:\n", - " print(\n", - " \"Local run: use an activated PhAST environment and start Jupyter \"\n", - " \"from the repository checkout.\"\n", - " )\n" + " print(\"Local/docs execution: using the current checkout; no packages installed.\")\n" ], - "id": "aee39d9c" + "id": "aee39d9c", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -230,21 +208,22 @@ "source": [ "## 2. Imports and working directory\n", "\n", - "All generated files go into `runs/notebook_sent/`. Keeping the generated geometry, mesh, configuration, and results in one directory makes the run easy to archive or remove." + "Generated geometry, mesh, configuration, and results share a new\n", + "`runs/notebook_sent/` directory. Existing runs are preserved by adding a\n", + "numeric suffix. Set `PHAST_NOTEBOOK_OUTPUT_ROOT` to place generated runs\n", + "elsewhere, for example during a documentation build.\n" ], "id": "c7721c3e" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "import json\n", "import shutil\n", - "import textwrap\n", "\n", "from PIL import Image as PILImage\n", + "import h5py\n", "import matplotlib.pyplot as plt\n", "import meshio\n", "import numpy as np\n", @@ -253,22 +232,44 @@ "here = Path.cwd().resolve()\n", "repo_root = next(\n", " (candidate for candidate in (here, *here.parents)\n", - " if (candidate / \"pyproject.toml\").is_file() and (candidate / \"src\" / \"phast\").is_dir()),\n", - " here,\n", + " if (candidate / \"pyproject.toml\").is_file()\n", + " and (candidate / \"src\" / \"phast\").is_dir()),\n", + " None,\n", ")\n", + "if repo_root is None:\n", + " raise RuntimeError(\"Start this notebook from the current PhAST source checkout.\")\n", "source_src = repo_root / \"src\"\n", - "if source_src.is_dir():\n", - " sys.path.insert(0, str(source_src))\n", - " os.environ[\"PYTHONPATH\"] = str(source_src) + os.pathsep + os.environ.get(\"PYTHONPATH\", \"\")\n", + "sys.path.insert(0, str(source_src))\n", + "os.environ[\"PYTHONPATH\"] = str(source_src) + os.pathsep + os.environ.get(\"PYTHONPATH\", \"\")\n", "\n", "import phast\n", "\n", - "run_dir = (repo_root / \"runs\" / \"notebook_sent\").resolve()\n", - "run_dir.mkdir(parents=True, exist_ok=True)\n", + "if not Path(phast.__file__).resolve().is_relative_to(source_src):\n", + " raise RuntimeError(\"Restart the kernel: PhAST was imported from a different checkout.\")\n", + "\n", + "plt.rcParams.update({\"font.family\": \"STIXGeneral\", \"mathtext.fontset\": \"stix\"})\n", + "\n", + "def require_finite(values, name):\n", + " \"\"\"Reject empty or non-finite data rather than disguising a failed solve.\"\"\"\n", + " array = np.asarray(values)\n", + " if array.size == 0 or not np.isfinite(array).all():\n", + " raise ValueError(\n", + " f\"Empty or non-finite values in {name}; inspect the solver log \"\n", + " \"before plotting or interpreting this run.\"\n", + " )\n", + " return array\n", + "\n", + "output_root = Path(os.environ.get(\"PHAST_NOTEBOOK_OUTPUT_ROOT\", repo_root / \"runs\"))\n", + "base = output_root.expanduser().resolve() / \"notebook_sent\"\n", + "run_dir = base\n", + "suffix = 2\n", + "while run_dir.exists():\n", + " run_dir = base.with_name(f\"{base.name}_{suffix}\")\n", + " suffix += 1\n", + "run_dir.mkdir(parents=True)\n", "\n", "geo_path = run_dir / \"mesh.geo\"\n", "mesh_path = run_dir / \"mesh.msh\"\n", - "spec_path = run_dir / \"authored_problem_spec.yaml\"\n", "config_path = run_dir / \"config.yaml\"\n", "output_dir = run_dir / \"results\"\n", "\n", @@ -276,7 +277,9 @@ "print(\"Repository root:\", repo_root)\n", "print(\"Working directory:\", run_dir)\n" ], - "id": "243f4e66" + "id": "243f4e66", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -293,16 +296,14 @@ "| `body` | 2D plate surface | material assignment |\n", "| `bottom` | bottom edge | fixed support |\n", "| `top` | top edge | prescribed vertical displacement |\n", - "| `notch` | embedded crack line | initial damage seed |\n", - "| `left`, `right` | side edges | optional inspection/output regions |" + "| `notch` | faces and tip of the geometric notch | optional initial damage seed |\n", + "| `left`, `right` | side edges | optional inspection/output regions |\n" ], "id": "1e8eb1de" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "L = 1.0 # plate width [mm]\n", "H = 1.0 # plate height [mm]\n", @@ -366,7 +367,9 @@ "print(geo_path)\n", "print(geo_text[:600] + \"\\n...\")" ], - "id": "8ea4683d" + "id": "8ea4683d", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -380,9 +383,7 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "fig, ax = plt.subplots(figsize=(6, 5))\n", "ax.plot([0, L, L, 0, 0], [0, 0, H, H, 0], color=\"0.15\", lw=2)\n", @@ -399,7 +400,9 @@ "fig.savefig(run_dir / \"geometry_preview.png\", dpi=180)\n", "plt.show()" ], - "id": "f12e814f" + "id": "f12e814f", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -413,9 +416,7 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "gmsh = shutil.which(\"gmsh\")\n", "if gmsh is None:\n", @@ -423,10 +424,12 @@ "\n", "cmd = [gmsh, \"-2\", str(geo_path), \"-format\", \"msh2\", \"-o\", str(mesh_path)]\n", "print(\" \".join(cmd))\n", - "subprocess.run(cmd, check=True)\n", - "print(mesh_path, mesh_path.stat().st_size, \"bytes\")" + "subprocess.run(cmd, check=True, timeout=60)\n", + "print(mesh_path, mesh_path.stat().st_size, \"bytes\")\n" ], - "id": "e485d7cd" + "id": "e485d7cd", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -440,9 +443,7 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "mesh_summary = phast.inspect_mesh(mesh_path)\n", "print(\"points:\", mesh_summary[\"n_points\"])\n", @@ -454,7 +455,9 @@ "if missing:\n", " raise RuntimeError(f\"Missing required physical groups: {sorted(missing)}\")" ], - "id": "0a50a71b" + "id": "0a50a71b", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -468,12 +471,10 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "mesh = meshio.read(mesh_path)\n", - "points = mesh.points[:, :2]\n", + "points = require_finite(mesh.points[:, :2], \"mesh coordinates\")\n", "\n", "triangles = []\n", "lines = []\n", @@ -506,9 +507,11 @@ "ax.set_title(\"Mesh with named physical curves\")\n", "fig.tight_layout()\n", "fig.savefig(run_dir / \"mesh_preview.png\", dpi=180)\n", - "plt.show()" + "plt.show()\n" ], - "id": "6177458f" + "id": "6177458f", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -524,9 +527,7 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "num_steps = 2 # quick tutorial run; increase for smoother damage evolution\n", "u_top = 0.0002 # prescribed final displacement [mm]\n", @@ -541,7 +542,7 @@ " .region(\"top\", from_mesh=\"top\")\n", " .region(\"notch\", from_mesh=\"notch\")\n", " .material(\n", - " \"glass\",\n", + " \"tutorial_material\",\n", " region=\"body\",\n", " E=210000.0,\n", " nu=0.3,\n", @@ -571,20 +572,18 @@ " static_tol=1.0e-7,\n", " damage_max_iter=500,\n", " static_max_iter=500,\n", - " fail_on_mechanics_nonconvergence=False,\n", - " fail_on_stagger_nonconvergence=False,\n", + " fail_on_mechanics_nonconvergence=True,\n", + " fail_on_stagger_nonconvergence=True,\n", " backend=\"auto\",\n", " device=\"cpu\",\n", " )\n", " .outputs(\n", - " fields=[{\"name\": \"trajectory\", \"every\": 1, \"format\": \"zarr\"}],\n", + " fields=[{\"name\": \"trajectory\", \"every\": 1, \"format\": \"h5\"}],\n", " histories=[{\"name\": \"reaction_force\", \"region\": \"bottom\", \"dof\": \"y\"}],\n", - " plots=True,\n", + " output_dir=str(output_dir),\n", + " plots=False, # Plot only after checking the stored numerical fields.\n", " profile=True,\n", - " gif=True,\n", - " gif_frames=24,\n", - " gif_fields=\"damage\",\n", - " animation_format=\"gif\",\n", + " gif=False,\n", " print_every=1,\n", " )\n", ")\n", @@ -592,25 +591,27 @@ "if enable_damage_preseed:\n", " problem.initial_condition(\"damage\", region=\"notch\", value=1.0)\n", "\n", - "problem.validate_setup()" + "problem.validate_setup()\n" ], - "id": "5c070ebe" + "id": "5c070ebe", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 9. Visualize supports, loading, and the damage seed\n", + "## 9. Visualise supports, loading, and the optional damage seed\n", "\n", - "`problem.plot_setup(...)` writes a static setup preview. The extra overlay below explicitly marks the prescribed displacement and the seeded crack so the notebook remains readable even if the default preview style changes." + "`problem.plot_setup(...)` writes a static setup preview. The notch exists in\n", + "the mesh even when damage pre-seeding is disabled. An initial value `d=1` is\n", + "applied only when `enable_damage_preseed` is explicitly enabled.\n" ], "id": "461aaf82" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "setup_preview = run_dir / \"initial_conditions.png\"\n", "problem.plot_setup(output=setup_preview)\n", @@ -623,7 +624,9 @@ "plt.show()\n", "print(setup_preview)" ], - "id": "4baaaf99" + "id": "4baaaf99", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -640,7 +643,7 @@ "| `solver_type` | `quasi_static`, `explicit` | Quasi-static solves coupled displacement/damage equilibrium at each load increment. Explicit dynamics advances the transient wave/crack problem with a stable time step. |\n", "| static vs dynamic | `quasi_static` vs `explicit` | Static/quasi-static cases ignore inertia; dynamic cases require density and time-step controls. |\n", "| implicit vs explicit | `quasi_static` uses iterative equilibrium solves; `explicit` uses time stepping | Current public examples promote quasi-static fracture and explicit dynamic fracture. Experimental or beta paths should stay clearly labelled. |\n", - "| trajectory format | `zarr`, `h5`, `both` | Zarr is preferred for public runs; HDF5 is retained for compatibility with older post-processing scripts. |\n", + "| trajectory format | `zarr`, `h5`, `both` | HDF5 is the default single-file format; Zarr or both formats require explicit selection. |\n", "\n", "For a paper result, keep these choices in YAML and report them in the run manifest. Do not rely on notebook state as the only record of a simulation." ], @@ -650,92 +653,39 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## 11. Write the runnable YAML configuration\n", - "\n", - "The fluent `Problem` object is useful for authoring and setup validation. Its saved schema-v2 specification is an inspection representation and does not imply that every combination has a promoted execution adapter. This cell retains that specification separately, then writes the supported schema-v1 YAML fields used by the public fracture runner.\n" + "## 11. Save one runnable schema-v2 configuration\n", + "\n", + "`Problem.save(config_path)` retains the geometry, named regions, material,\n", + "boundary conditions, analysis step, solver settings, and output requests in\n", + "one YAML file. Validate and execute **that same file**, rather than maintaining\n", + "a second hand-written configuration.\n", + "\n", + "This example is restricted to the existing single-material, external-mesh,\n", + "quasi-static fracture adapter. It does not establish support for arbitrary\n", + "schema-v2 combinations. Schema validation does not solve the equations or\n", + "demonstrate convergence. Mechanics and staggered nonconvergence remain fatal;\n", + "do not disable these checks to obtain a plot.\n" ], "id": "2e749550" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ - "problem.save(spec_path)\n", - "\n", - "execution_config = {\n", - " \"schema_version\": 1,\n", - " \"problem\": {\n", - " \"name\": \"Notebook SENT workflow check\",\n", - " \"reference\": \"Educational setup; not a validation benchmark\",\n", - " },\n", - " \"geometry\": {\"mesh_path\": str(mesh_path)},\n", - " \"material\": {\n", - " \"E\": 210000.0,\n", - " \"nu\": 0.3,\n", - " \"Gc\": 2.7,\n", - " \"l0\": l0,\n", - " \"rho\": 7.8e-09,\n", - " \"eta_residual\": 1.0e-07,\n", - " \"energy_split\": \"spectral\",\n", - " \"pf_model\": \"AT2\",\n", - " \"plane_stress\": False,\n", - " },\n", - " \"boundary_conditions\": [\n", - " {\"nodes\": \"bottom\", \"type\": \"fix\", \"component\": 0, \"value\": 0.0},\n", - " {\"nodes\": \"bottom\", \"type\": \"fix\", \"component\": 1, \"value\": 0.0},\n", - " {\"nodes\": \"top\", \"type\": \"prescribe\", \"component\": 1, \"value\": 1.0},\n", - " ],\n", - " \"loading\": {\n", - " \"protocol\": \"simple\",\n", - " \"num_steps\": num_steps,\n", - " \"dt\": u_top / num_steps,\n", - " },\n", - " \"solver\": {\n", - " \"solver_type\": \"quasi_static\",\n", - " \"stagger_tol\": 1.0e-6,\n", - " \"max_stagger\": 50,\n", - " \"preconditioner\": \"jacobi\",\n", - " \"damage_tol\": 1.0e-5,\n", - " \"static_tol\": 1.0e-7,\n", - " \"damage_max_iter\": 500,\n", - " \"static_max_iter\": 500,\n", - " \"bounds_method\": \"post_clamp\",\n", - " \"fail_on_mechanics_nonconvergence\": False,\n", - " \"fail_on_stagger_nonconvergence\": False,\n", - " \"backend\": \"auto\",\n", - " },\n", - " \"output\": {\n", - " \"output_dir\": str(output_dir),\n", - " \"trajectory\": True,\n", - " \"trajectory_format\": \"zarr\",\n", - " \"h5_every\": 1,\n", - " \"plots\": True,\n", - " \"profile\": True,\n", - " \"gif\": False,\n", - " \"print_every\": 1,\n", - " \"reaction_node_set\": \"bottom\",\n", - " \"reaction_component\": 1,\n", - " },\n", - " \"device\": {\"device\": \"cpu\", \"compile\": False},\n", - "}\n", - "if enable_damage_preseed:\n", - " execution_config[\"initial_conditions\"] = {\n", - " \"preseed_notch_nodesets\": [\"notch\"],\n", - " \"preseed_damage\": 1.0,\n", - " }\n", - "\n", - "config_path.write_text(yaml.safe_dump(execution_config, sort_keys=False), encoding=\"utf-8\")\n", - "print(\"Authoring specification:\", spec_path)\n", - "print(\"Runnable configuration:\", config_path)\n", - "print(config_path.read_text(encoding=\"utf-8\")[:1600] + \"\\n...\")\n", + "problem.save(config_path)\n", + "saved_config = yaml.safe_load(config_path.read_text(encoding=\"utf-8\"))\n", + "if saved_config.get(\"schema_version\") != 2:\n", + " raise RuntimeError(\"This workflow requires the saved schema-v2 configuration.\")\n", + "print(\"Saved configuration used for validation and execution:\", config_path)\n", + "print(yaml.safe_dump(saved_config, sort_keys=False))\n", "\n", "validate_cmd = [sys.executable, \"-m\", \"phast\", \"run\", str(config_path), \"--validate-only\"]\n", "print(\" \".join(validate_cmd))\n", - "subprocess.run(validate_cmd, check=True, cwd=repo_root)\n" + "subprocess.run(validate_cmd, check=True, cwd=repo_root, timeout=60)\n" ], - "id": "e614aef0" + "id": "e614aef0", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -751,7 +701,8 @@ "\n", "After the run, compare these expectations with the printed route, manifest, and\n", "available artifacts. A completed short run is an execution check, not a\n", - "fracture-validation result.\n" + "fracture-validation result.\n", + "" ], "id": "setup-024" }, @@ -761,30 +712,31 @@ "source": [ "## 12. Run the bounded solver workflow\n", "\n", - "The command below executes the runnable schema-v1 configuration and writes artifacts to `runs/notebook_sent/results/`. It is a two-step CPU workflow check, not evidence of crack initiation, propagation, mesh convergence, or benchmark agreement.\n" + "The command executes the saved schema-v2 configuration and writes to the\n", + "selected run's `results/` directory. It is a two-step CPU workflow check,\n", + "not evidence of crack initiation, propagation, mesh convergence, or benchmark\n", + "agreement. A nonzero exit status stops the notebook.\n" ], "id": "341e3fbf" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "run_cmd = [\n", " sys.executable, \"-m\", \"phast\", \"run\", str(config_path),\n", " \"--output_dir\", str(output_dir),\n", "]\n", "print(\" \".join(run_cmd))\n", - "subprocess.run(run_cmd, check=True, cwd=repo_root)\n" + "subprocess.run(run_cmd, check=True, cwd=repo_root, timeout=120)\n" ], - "id": "6726b954" + "id": "6726b954", + "outputs": [], + "execution_count": null }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "# Inspect the output contract without assuming every optional writer was enabled.\n", "artifact_groups = {\n", @@ -793,8 +745,7 @@ " \"field_or_trajectory\": [\n", " \"damage_final.png\",\n", " \"displacement_final.png\",\n", - " \"trajectory.zarr\",\n", - " \"results.zarr\",\n", + " \"training_data.h5\",\n", " \"training_data.zarr\",\n", " ],\n", "}\n", @@ -809,9 +760,12 @@ " \"Interpretation: availability depends on the selected workflow and output \"\n", " \"settings. Inspect the run manifest before treating an absent optional artifact \"\n", " \"as a solver failure.\"\n", - ")\n" + ")\n", + "" ], - "id": "setup-027" + "id": "setup-027", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -825,157 +779,205 @@ }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ "for path in sorted(output_dir.iterdir()):\n", - " if path.is_dir():\n", - " print(f\"{path.name}/\")\n", - " else:\n", - " print(path.name)\n", + " print(path.name + (\"/\" if path.is_dir() else \"\"))\n", "\n", "result = phast.load_result(output_dir)\n", "print(\"\\nmetadata keys:\", sorted(result.metadata().keys()))\n", "print(\"histories:\", result.history_names())\n", "print(\"fields:\", result.field_names())\n", - "print(\"visuals:\", result.visuals())" + "print(\"visuals:\", result.visuals())\n", + "\n", + "stored_steps = []\n", + "trajectory_path = output_dir / \"training_data.h5\"\n", + "if trajectory_path.is_file():\n", + " with h5py.File(trajectory_path, \"r\") as trajectory:\n", + " stored_steps = sorted(\n", + " int(key.rsplit(\"_\", 1)[-1])\n", + " for key in trajectory[\"simulation_data/steps\"]\n", + " if key.startswith(\"step_\")\n", + " )\n", + " if not stored_steps or stored_steps[-1] != num_steps - 1:\n", + " raise RuntimeError(\"The requested final step is missing from the HDF5 trajectory.\")\n", + " print(\"Stored solver steps:\", stored_steps)\n", + "else:\n", + " print(\"No HDF5 trajectory is available; field plots and animation will be omitted.\")\n" ], - "id": "73679bd5" + "id": "73679bd5", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 14. Plot histories and final fields\n", + "## 14. Plot available histories and final fields\n", "\n", - "The result API returns stored fields and histories. If a requested derived field was not stored directly, compute it during post-processing only when the required source fields are present." + "The result API exposes stored field names and CSV-backed history rows.\n", + "Displacement magnitude is derived from displacement; vertical strain and\n", + "stress use their stored in-plane components when available. This adapter\n", + "may omit optional strain or stress snapshots: missing output is reported,\n", + "not replaced with zeros or reconstructed without its constitutive inputs.\n", + "\n", + "Every plotted numerical array must be finite. Empty fields, NaNs, infinities,\n", + "or incompatible field shapes stop post-processing. Damage uses the fixed\n", + "`Reds` scale from 0 to 1.\n" ], "id": "07b762e2" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ - "if \"reaction_force\" in result.history_names():\n", - " rows = result.history(\"reaction_force\")\n", - "elif \"history\" in result.history_names():\n", - " rows = result.history(\"history\")\n", + "if \"load_displacement\" in result.history_names():\n", + " rows = result.history(\"load_displacement\")\n", + " if rows:\n", + " columns = set(rows[0])\n", + " if {\"applied_disp\", \"reaction_force\"} <= columns:\n", + " x_key, y_key, force_unit = \"applied_disp\", \"reaction_force\", \"N\"\n", + " elif {\"displacement\", \"reaction_kN\"} <= columns:\n", + " x_key, y_key, force_unit = \"displacement\", \"reaction_kN\", \"kN\"\n", + " else:\n", + " raise ValueError(f\"Unrecognised load-displacement columns: {sorted(columns)}\")\n", + " applied = require_finite(\n", + " np.asarray([row[x_key] for row in rows], dtype=float), x_key\n", + " )\n", + " reaction = require_finite(\n", + " np.asarray([row[y_key] for row in rows], dtype=float), y_key\n", + " )\n", + " fig, ax = plt.subplots(figsize=(6, 4))\n", + " ax.plot(applied, reaction, \"o-\")\n", + " ax.set(xlabel=\"Applied displacement [mm]\", ylabel=f\"Reaction [{force_unit}]\",\n", + " title=\"Two-step response, not a converged fracture curve\")\n", + " fig.tight_layout()\n", + " plt.show()\n", + " else:\n", + " print(\"The load-displacement history is empty; no curve is drawn.\")\n", "else:\n", - " rows = []\n", + " print(\"No load-displacement history was stored; no curve is fabricated.\")\n", "\n", - "if rows:\n", - " print(rows[:3])\n", "\n", - "def write_scalar_field_png(values, title, path, cmap=\"viridis\"):\n", - " arr = np.asarray(values)\n", - " if arr.ndim > 1:\n", - " arr = np.linalg.norm(arr, axis=-1)\n", - " arr = np.nan_to_num(arr, nan=0.0, posinf=0.0, neginf=0.0)\n", + "def write_scalar_field_png(values, title, path, cmap=\"viridis\", limits=None):\n", + " arr = require_finite(values, title)\n", + " if arr.ndim != 1 or arr.size not in (points.shape[0], triangles.shape[0]):\n", + " raise ValueError(f\"{title}: field shape {arr.shape} does not match this mesh\")\n", + " colour_limits = {} if limits is None else dict(vmin=limits[0], vmax=limits[1])\n", " fig, ax = plt.subplots(figsize=(6, 5))\n", " if arr.size == points.shape[0]:\n", - " im = ax.tripcolor(points[:, 0], points[:, 1], triangles, arr, shading=\"gouraud\", cmap=cmap)\n", - " elif arr.size == triangles.shape[0]:\n", - " im = ax.tripcolor(points[:, 0], points[:, 1], triangles, facecolors=arr, edgecolors=\"none\", cmap=cmap)\n", + " im = ax.tripcolor(\n", + " points[:, 0], points[:, 1], triangles, arr,\n", + " shading=\"gouraud\", cmap=cmap, **colour_limits,\n", + " )\n", " else:\n", - " plt.close(fig)\n", - " print(f\"Skipping {title}: field shape {values.shape} does not match nodes or elements\")\n", - " return None\n", - " ax.set_aspect(\"equal\")\n", - " ax.set_title(title)\n", - " ax.set_xlabel(\"x [mm]\")\n", - " ax.set_ylabel(\"y [mm]\")\n", + " im = ax.tripcolor(\n", + " points[:, 0], points[:, 1], triangles, facecolors=arr,\n", + " shading=\"flat\", cmap=cmap, **colour_limits,\n", + " )\n", + " ax.set(aspect=\"equal\", title=title, xlabel=\"x [mm]\", ylabel=\"y [mm]\")\n", " fig.colorbar(im, ax=ax, shrink=0.82)\n", " fig.tight_layout()\n", " fig.savefig(path, dpi=180)\n", " plt.close(fig)\n", " return path\n", "\n", - "for field_name, filename, title, cmap in [\n", - " (\"displacement\", \"displacement_final.png\", \"Final displacement magnitude\", \"magma\"),\n", - " (\"stress\", \"stress_final.png\", \"Final stress magnitude\", \"plasma\"),\n", - " (\"strain\", \"strain_final.png\", \"Final strain magnitude\", \"cividis\"),\n", - "]:\n", - " if result.has_field(field_name):\n", - " write_scalar_field_png(result.field(field_name, step=-1), title, output_dir / filename, cmap=cmap)\n", - "\n", - "candidate_images = [\n", - " output_dir / \"initial_conditions.png\",\n", - " run_dir / \"initial_conditions.png\",\n", - " output_dir / \"damage_final.png\",\n", - " output_dir / \"displacement_final.png\",\n", - " output_dir / \"stress_final.png\",\n", - " output_dir / \"strain_final.png\",\n", - "]\n", - "existing_images = [p for p in candidate_images if p.exists()]\n", "\n", - "if existing_images:\n", - " fig, axes = plt.subplots(1, len(existing_images), figsize=(5 * len(existing_images), 4))\n", - " axes = np.atleast_1d(axes)\n", - " for ax, path in zip(axes, existing_images):\n", + "checked_images = []\n", + "for field_name, title, cmap, component, limits in [\n", + " (\"damage\", \"Final phase-field damage, d [-]\", \"Reds\", None, (0.0, 1.0)),\n", + " (\"displacement\", \"Final displacement magnitude [mm]\", \"cividis\", \"magnitude\", None),\n", + " (\"stress\", \"Final in-plane stress, sigma_yy [MPa]\", \"RdBu_r\", 1, None),\n", + " (\"strain\", \"Final vertical strain, epsilon_yy [-]\", \"RdBu_r\", 1, None),\n", + "]:\n", + " if not stored_steps or not result.has_field(field_name):\n", + " print(f\"No stored {field_name} field; its plot is omitted.\")\n", + " continue\n", + " values = require_finite(result.field(field_name, step=stored_steps[-1]), field_name)\n", + " if component == \"magnitude\":\n", + " if values.ndim != 2 or values.shape[1] != 2:\n", + " raise ValueError(f\"Unexpected displacement shape: {values.shape}\")\n", + " values = np.linalg.norm(values, axis=1)\n", + " elif component is not None:\n", + " if values.ndim != 2 or values.shape[1] != 3:\n", + " raise ValueError(f\"Unexpected in-plane {field_name} shape: {values.shape}\")\n", + " values = values[:, component]\n", + " checked_images.append(write_scalar_field_png(\n", + " values, title, output_dir / f\"{field_name}_final.png\", cmap=cmap, limits=limits\n", + " ))\n", + "\n", + "if checked_images:\n", + " fig, axes = plt.subplots(\n", + " (len(checked_images) + 1) // 2, 2,\n", + " figsize=(11, 5 * ((len(checked_images) + 1) // 2)),\n", + " )\n", + " for ax in np.asarray(axes).flat:\n", + " ax.axis(\"off\")\n", + " for ax, path in zip(np.asarray(axes).flat, checked_images):\n", " ax.imshow(np.asarray(PILImage.open(path).convert(\"RGB\")))\n", " ax.set_title(path.name)\n", - " ax.axis(\"off\")\n", " fig.tight_layout()\n", " plt.show()\n", "else:\n", - " print(\"No standard PNG fields were generated for this short run.\")" + " print(\"No available finite trajectory fields to plot.\")\n" ], - "id": "af680eaf" + "id": "af680eaf", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", "metadata": {}, "source": [ - "## 15. Create or view animations\n", + "## 15. Create an animation from stored damage\n", "\n", - "If the run generated `damage_evolution.gif` or `damage_evolution.mp4`, display it directly. For longer studies, prefer generating animations from the stored Zarr trajectory after the solve so rendering settings can be changed without rerunning the physics." + "Use the actual HDF5 snapshot indices, not the number of CSV history rows.\n", + "All selected damage snapshots are checked before rendering. Two frames\n", + "illustrate the output workflow; they do not demonstrate crack propagation.\n", + "For longer studies, render from the retained trajectory after solving.\n" ], "id": "94044365" }, { "cell_type": "code", - "execution_count": null, "metadata": {}, - "outputs": [], "source": [ - "from IPython.display import Image, Video, display\n", + "from IPython.display import Image, display\n", "\n", "gif_path = output_dir / \"damage_evolution.gif\"\n", - "mp4_path = output_dir / \"damage_evolution.mp4\"\n", - "\n", - "if not gif_path.exists() and result.has_field(\"damage\"):\n", - " history_len = len(result.history(\"results\")) if \"results\" in result.history_names() else num_steps\n", + "if stored_steps and result.has_field(\"damage\"):\n", + " damage_frames = [\n", + " require_finite(result.field(\"damage\", step=step), f\"damage at step {step}\")\n", + " for step in stored_steps\n", + " ]\n", + " if any(field.shape != (len(points),) for field in damage_frames):\n", + " raise ValueError(\"A damage snapshot does not match the mesh nodes.\")\n", " frames = []\n", - " for step_index in range(history_len):\n", - " damage = np.nan_to_num(result.field(\"damage\", step=step_index), nan=0.0, posinf=1.0, neginf=0.0)\n", + " for step_index, damage in zip(stored_steps, damage_frames):\n", " fig, ax = plt.subplots(figsize=(6, 5))\n", - " im = ax.tripcolor(points[:, 0], points[:, 1], triangles, damage, shading=\"gouraud\", cmap=\"inferno\", vmin=0.0, vmax=1.0)\n", - " ax.set_aspect(\"equal\")\n", - " ax.set_title(f\"Damage, step {step_index}\")\n", - " ax.set_xlabel(\"x [mm]\")\n", - " ax.set_ylabel(\"y [mm]\")\n", + " im = ax.tripcolor(\n", + " points[:, 0], points[:, 1], triangles, damage,\n", + " shading=\"gouraud\", cmap=\"Reds\", vmin=0.0, vmax=1.0,\n", + " )\n", + " ax.set(aspect=\"equal\", title=f\"Damage, step {step_index}\",\n", + " xlabel=\"x [mm]\", ylabel=\"y [mm]\")\n", " fig.colorbar(im, ax=ax, shrink=0.82)\n", " fig.tight_layout()\n", " fig.canvas.draw()\n", - " frames.append(np.asarray(fig.canvas.buffer_rgba())[:, :, :3].copy())\n", + " frames.append(PILImage.fromarray(\n", + " np.asarray(fig.canvas.buffer_rgba())[:, :, :3].copy()\n", + " ))\n", " plt.close(fig)\n", - " PILImage.fromarray(frames[0]).save(\n", - " gif_path, save_all=True,\n", - " append_images=[PILImage.fromarray(frame) for frame in frames[1:]],\n", - " duration=800, loop=0,\n", + " frames[0].save(\n", + " gif_path, save_all=True, append_images=frames[1:], duration=800, loop=0\n", " )\n", - "\n", - "if gif_path.exists():\n", " display(Image(filename=str(gif_path)))\n", - "elif mp4_path.exists():\n", - " display(Video(str(mp4_path), embed=True))\n", "else:\n", - " print(\"No damage animation could be generated because the damage trajectory is not available.\")" + " print(\"No stored damage trajectory; no animation is fabricated.\")\n" ], - "id": "d2a39581" + "id": "d2a39581", + "outputs": [], + "execution_count": null }, { "cell_type": "markdown", @@ -987,9 +989,9 @@ "2. Keep the `.geo`, `.msh`, `config.yaml`, `run_fluent.py`, setup preview, final field images, animations, and CSV histories together.\n", "3. Use a mesh size that resolves the phase-field length scale; a common starting point is several elements across `l0` near the crack path.\n", "4. Validate the YAML with `python -m phast run config.yaml --validate-only` before using HPC time.\n", - "5. For dynamic fracture, switch the step and solver to `explicit`, include density, and verify the stable time step.\n", + "5. For dynamic fracture, use a matched public dynamic example, include density, and verify the stable time step. Changing only the solver type does not define an equivalent problem.\n", "6. For quasi-static fracture, monitor staggered convergence and load-displacement response before trusting crack paths.\n", - "7. Archive the result directory, not only the notebook. The result directory is the reproducible simulation artifact." + "7. Archive the result directory, not only the notebook. The result directory is the reproducible simulation artifact.\n" ], "id": "55cc69f0" }, @@ -1029,28 +1031,17 @@ "4. What additional mesh, convergence, calibration, and comparison evidence\n", " would be required before reporting a fracture result?\n", "\n", - "If execution was unavailable, answer using the rendered outputs, then inspect\n", - "the [retained-results notebook](notebook_retained_results.ipynb). Continue with\n", + "If execution was unavailable, inspect the\n", + "[retained-results notebook](notebook_retained_results.ipynb) rather than\n", + "interpreting empty output cells. Continue with\n", "[From a tutorial to a first research study](06_first_research_study.md) before\n", - "adapting the example to a research problem.\n" + "adapting the example to a research problem.\n", + "\n", + "If a documented step fails, open a [GitHub issue](https://github.com/CEMS-Lab/PhAST/issues)\n", + "with the configuration, command, operating system, Python version, PhAST version\n", + "or commit, and complete error output.\n" ], "id": "setup-035" } - ], - "metadata": { - "colab": { - "provenance": [] - }, - "kernelspec": { - "display_name": "Python 3", - "language": "python", - "name": "python3" - }, - "language_info": { - "name": "python", - "pygments_lexer": "ipython3" - } - }, - "nbformat": 4, - "nbformat_minor": 5 + ] } diff --git a/docs/user_guide/capability_matrix.md b/docs/user_guide/capability_matrix.md index 8d7c8eb76..ee1df5081 100644 --- a/docs/user_guide/capability_matrix.md +++ b/docs/user_guide/capability_matrix.md @@ -1,19 +1,20 @@ # Capability Matrix -This capability matrix defines the documented evidence boundaries of PhAST. It -separates supported and benchmarked pathways from beta, experimental, -optional-backend, scaffold, and unsupported features. +This capability matrix states which PhAST features are supported and how far +they have been tested. It distinguishes established use from beta, +experimental, optional-backend, scaffold, and unsupported features. -For the current plasticity, cohesive interface, and PF-CZM technical-preview boundaries, see the [plasticity/interface beta workflow](../supported_workflows/plasticity_interface_beta.md). +For the present scope of plasticity, cohesive-interface, and PF-CZM support, +see the [plasticity and interface beta workflow](../supported_workflows/plasticity_interface_beta.md). ## Status Definitions | Status | Meaning | |---|---| -| **Supported** | Implemented in the public execution pathway and represented by checked-in tests or a reproducible example. The cited evidence remains specific to the documented problem class. | +| **Supported** | Implemented in the documented solver interface and covered by repository tests or a reproducible example. Support remains specific to the stated problem class. | | **Beta** | Mathematically implemented and functional, but robustness or full-domain validation is still under review. | | **Experimental** | Active research pathway with insufficient evidence for general research claims. | -| **Optional backend** | Code path exists but requires external solver libraries or specific HPC hardware environments. | +| **Optional backend** | Implemented but requires external solver libraries or a compatible computing environment. | | **Scaffold** | Foundational data structures or kernels exist, but the feature is not yet coupled into the global solve. | | **Unsupported** | Feature is mathematically or computationally unsupported. | @@ -21,41 +22,43 @@ For the current plasticity, cohesive interface, and PF-CZM technical-preview bou | Capability | Status | Public Statement | |---|---|---| -| Small-strain 2D linear elasticity | Supported | Exercised through the core mechanics kernels and documented static and quasi-static examples. | +| Small-strain 2D linear elasticity | Supported | Covered by the core mechanics tests and documented static and quasi-static examples. | | Small-strain 1D axial elasticity | Beta | Separate CPU float64 Python API: `line_mesh`, `LineMesh`, and `solve_bar`. Uniform material/area, one left displacement constraint and a right-end force; analytical fields and first-order gradients are tested. See the [1D bar API](one_dimensional_bar.md). | | Brittle phase-field fracture, AT2 | Supported | Available for explicit dynamics and staggered quasi-static/static solves within the documented examples. | -| Brittle phase-field fracture, AT1 | Beta | Supported via projected damage solves and AT1 threshold fields; benchmark coverage is expanding. | +| Brittle phase-field fracture, AT1 | Beta | Available through projected damage solves and AT1 threshold fields. Validation coverage is narrower than for AT2. | | Heterogeneous elastic fields `E(x)` | Supported programmatic path | Per-element fields support structural inclusions and weak/strong bands. The element ordering and low-level authoring route are demonstrated in the [heterogeneous-fields teaching example](https://github.com/CEMS-Lab/PhAST/tree/main/examples/heterogeneous_fields); arbitrary field maps are not currently a general YAML feature. | | Heterogeneous fracture fields `Gc(x)` | Supported programmatic path | Per-element fields support weak zones and microstructure-style forward studies through the same [heterogeneous-fields teaching example](https://github.com/CEMS-Lab/PhAST/tree/main/examples/heterogeneous_fields). The example is not a coupled benchmark or material-calibration claim. | -| Diffuse interface fracture | Beta | Solver-driven weak-interface deflection and strong-interface penetration examples use spatial `E(x)`/`Gc(x)` fields plus AT2 damage solves; discrete cohesive and PF-CZM calibration remain separate. | +| Schema-2 multi-material quasi-static fracture | Beta | DCB and heterogeneous SENT use a structured T3 rectangle, CPU float64, elementwise `E`/`Gc`, common `nu`/`l0`, shared Amor AT2 settings, and Dirichlet conditions. Centroid-based bulk assignments do not provide an independent interface law. | +| Schema-2 dynamic multi-material fracture | Unsupported | A common input layout and a single-material dynamic adapter do not provide dynamic heterogeneous execution. Do not switch the DCB input to `explicit`. | +| Diffuse-interface fracture | Beta | Weak-interface deflection and strong-interface penetration examples use spatial `E(x)`/`Gc(x)` fields with AT2 damage solves. Discrete cohesive and PF-CZM formulations are separate models. | | Plane strain | Supported | Default 2D constitutive setting. | -| Plane stress | Beta | Available via `material.plane_stress`; formal benchmark coverage is narrower than plane strain. | -| Spectral / Amor / isotropic energy splits | Supported | Available through `material.energy_split` for brittle phase-field workflows. Plane-stress `spectral` is a reduced 2D in-plane projection; prefer plane-strain `spectral` or plane-stress `amor` where benchmark evidence is required. | +| Plane stress | Beta | Legacy inputs use `material.plane_stress`; schema-2 inputs use the named material's `parameters.plane_stress`, with common settings on the multi-material route. Formal benchmark coverage is narrower than plane strain. | +| Spectral / Amor / isotropic energy splits | Supported, route-specific | Legacy inputs select `material.energy_split`. The documented schema-2 multi-material route requires common `parameters.energy_split: amor`. Plane-stress `spectral` is a reduced 2D in-plane projection; do not infer every split is supported by every adapter. | | `spectral_stress` split | Experimental | Opt-in comparison pathway; do not present it as a generally supported formulation. | | Monolithic `(u,d)` L-BFGS solve | Experimental | Research comparison only until the bound-constrained irreversibility algorithms are formalized. | -| Sparse quasi-static J2 elastoplasticity | Beta | Per-element state, return mapping, commit/rollback, internal force, sparse dispatch, and plastic-work accounting are available; large-mesh backend promotion remains gated. | -| Ductile PF-plasticity | Beta | Elastic tensile energy plus accumulated plastic-work coupling is implemented, featuring bounded AT2 damage, separated energy ledgers, and guarded staggered support. Benchmark-matched ductile fracture remains gated. | -| Cohesive elements / discrete CZM | Beta | Stateful true-bilinear cohesive residual/tangent assembly, dissipated-energy history, optional normal-contact penalty, and single-block meshio cohesive-layer insertion are available. ASTM-calibrated structural delamination remains gated. | -| Coupled brittle PF + cohesive elements | Beta | Staggered AT2 matrix damage plus zero-thickness cohesive-interface delamination exists with matrix notch damage, convergence telemetry, and visual manifests. Calibrated PF-CZM structural validation studies remain gated. | -| PF-CZM | Beta | Wu PF-CZM is available via `pf_model: PFCZM` for forward nonlinear damage solves with tensile-strength-calibrated rational degradation and uniaxial validation. Structural crack-growth and PF-plasticity-cohesive coupling remain gated. | -| Coupled PF + plasticity + cohesive interfaces | Unsupported | Not currently supported within the public workflow surface. | +| Sparse quasi-static J2 elastoplasticity | Beta | Per-element state variables, return mapping, state commit/rollback, internal force, sparse solver selection, and plastic-work accounting are available. Large-mesh backend validation is incomplete. | +| Ductile PF-plasticity | Beta | Elastic tensile energy and accumulated plastic work can drive bounded AT2 damage in a staggered solve. Validation against established ductile-fracture benchmarks is incomplete. | +| Cohesive elements / discrete CZM | Beta | True-bilinear cohesive residual and tangent assembly, dissipated-energy history, optional normal-contact penalty, and single-block meshio cohesive-layer insertion are available. Validation for calibrated structural delamination is incomplete. | +| Coupled brittle PF + cohesive elements | Beta | Staggered AT2 matrix damage can be combined with zero-thickness cohesive-interface delamination. Calibrated structural validation remains incomplete. | +| PF-CZM | Beta | Wu PF-CZM is available through `pf_model: PFCZM` for nonlinear forward damage solves with tensile-strength-calibrated rational degradation and uniaxial tests. Structural crack-growth validation is incomplete, and PF-plasticity-cohesive coupling is not supported. | +| Coupled PF + plasticity + cohesive interfaces | Unsupported | This combined formulation is not available through the documented solver interface. | | Learned damage proposal | Experimental | A user-supplied predictor may provide a projected initial guess; the classical damage solve remains authoritative. No trained model is distributed. | | Audited learned damage replacement | Experimental | A predicted damage state may replace one damage solve only after bound, irreversibility, phase-field boundary-condition, and projected-residual checks. Rejection uses the classical fallback by default. | | 3D fracture | Unsupported | The documented fracture element pathways are two-dimensional. | | P2 / Q8 / Q9 element primitives | Scaffold | Shape functions, quadrature, and single-element stiffness tests exist for higher-order families; global solver dispatch is not supported. | -| Native Q4 isotropic mechanics + AT2 damage | Beta | Structured Q4 mesh helpers, native Q4 mesh admission, 2x2-Gauss isotropic mechanics, SciPy/MUMPS sparse-direct stiffness assembly, and matrix-free Q4 AT2 damage are tested. Q4 PF-CZM, AT1, and plasticity remain gated. | +| Native Q4 isotropic mechanics + AT2 damage | Beta | Structured Q4 mesh helpers, native Q4 mesh input, 2x2-Gauss isotropic mechanics, SciPy/MUMPS sparse-direct stiffness assembly, and matrix-free Q4 AT2 damage are tested. Q4 PF-CZM, AT1, and plasticity are not supported. | ## Solvers and Backends | Capability | Status | Public Statement | |---|---|---| | Explicit dynamics, Velocity Verlet | Supported | Principal documented pathway for dynamic impact and fracture simulations. | -| Staggered quasi-static/static solve | Supported | Principal documented implicit brittle-fracture pathway, using `jacobi` as the conservative damage preconditioner. Matrix-free CG and sparse-direct mechanics backends are available. | +| Staggered quasi-static/static solve | Supported | Main documented implicit brittle-fracture algorithm. It uses `jacobi` as the default damage preconditioner; matrix-free CG and sparse-direct mechanics solvers are available. | | Rotation-free connectors in `quasi_static` | Beta | The staggered call forwards active connectors to the existing reduced mechanics solve. CPU float64 isotropic elastic tests check connector kinematics, reaction and moment balance. Nonlinear fracture trajectories require separate case-specific verification. | -| `quasi_static_legacy` secant path | Beta | Retained strictly for compatibility and selected MPC/frozen-secant workflows. | +| `quasi_static_legacy` secant path | Beta | Available for compatibility and selected MPC or frozen-secant calculations. | | SciPy SuperLU sparse direct baseline | Supported | Portable sparse-direct baseline when SciPy is installed. | -| PETSc/MUMPS | Optional backend | Runtime-guarded. When available, `backend='auto'` prioritizes this for CPU sparse-direct mechanics. | -| cuDSS / nvmath | Optional backend | Runtime-guarded. GPU sparse-direct path requires current nvmath/cuDSS validation on the target hardware stack. | +| PETSc/MUMPS | Optional backend | When available, `backend='auto'` prioritises this backend for CPU sparse-direct mechanics. | +| cuDSS / nvmath | Optional backend | GPU sparse-direct solution requires a compatible nvmath/cuDSS installation and validation on the target hardware. | | AMG / AmgX / GMG damage preconditioning | Experimental | Performance-oriented pathways for quasi-static fracture; use Jacobi unless the alternative preconditioner is itself part of the study. | | Anderson acceleration | Beta | Available for staggered iterations; use only with benchmark-specific validation. | @@ -78,24 +81,42 @@ the complete companion archive is prepared. | Capability | Status | Public Statement | |---|---|---| | YAML problem definition | Supported | Primary execution entry point (e.g., `python -m phast run config.yaml`). | -| YAML schema validation | Supported | `--validate-only` enforces schema compliance and reports line-numbered semantic errors. | -| `explain-config` review | Supported | Prints selected physics, solver paths, provenance, and setup warnings without initiating meshing or solving. | -| `schema_version` | Supported | Current runnable configs declare `schema_version: 1`; legacy files trigger review warnings. | -| Resolved run lockfile | Supported | Execution generates `run_lockfile.json` capturing the config hash, resolved objects, CLI arguments, and Git state. | +| YAML input validation | Supported within each adapter | `run CONFIG --validate-only` checks implemented schema/workflow constraints without solving. The multi-material route constructs the geometric mesh to check selections and assignments. It is not numerical or scientific validation. | +| `explain-config` review | Supported for the standard examples | Explains legacy and schema-2 inputs without solving. Explanation does not establish numerical convergence or validate a physical model. | +| `schema_version` | Supported, route-specific | Existing schema-1 benchmarks retain their layout. Standard schema-2 inputs use explicit regions/materials/assignments, analysis steps, and outputs; a common layout does not establish an execution adapter. | +| Small single-material standard exercises | Supported | `examples/standard_workflow/quasistatic_sent/config.yaml` and `examples/standard_workflow/dynamic_sent/config.yaml` execute through the existing quasi-static and explicit-dynamic runners. These short setup exercises are not crack-growth benchmarks. | +| Resolved run record | Supported, route-specific content | Runs write provenance/lockfile records; recorded fields depend on the adapter. A configuration hash or later public-availability fingerprint does not establish missing historical generating-source identity. | | Built-in geometry generators | Supported | Available through `geometry.type` and `geometry.parameters`. | | External meshes | Beta | Supported via `geometry.mesh_path`; node-set capability relies on the specific mesh format standard. | | Declarative primitive geometry DSL | Beta | Parsed by selected benchmark configs; broader geometry coverage remains under evaluation. | | Config inheritance / sweeps | Unsupported | Parameter sweeps currently require external scripting or duplicated declarative files. | | JSON Schema export / IDE autocomplete | Supported | `python -m phast schema` exports the schema used for editor assistance and external validation. | +New YAML/README/tutorial authors must follow the +{download}`configuration style guide <../../CONFIGURATION_STYLE.md>` and +[standard simulation tutorial](../tutorial/07_standard_simulation_workflow.md). +Legacy `precheck` is not a universal schema-2 command. Quasi-static analysis +omits inertia; dynamics includes density and physical time, and explicit +integration has an additional CFL restriction. A smaller step is not validation. + +Retained DCB evidence shows qualitative layered-material interaction: no +seed-connected nodes with `d >= 0.80` enter the disk, and both the tough +disk and no-contrast disk control fork early. Neither completed bypass nor +experimental/interface-law validation is demonstrated. Independent review +of the fixed stored fields found numerical acceptability, not general model +validation; input guards and integrated command checks remain separate. + +Frozen course assets and separate 3D research are not automatically migrated +into the public schema; their adapters and evidence must exist first. + ## Outputs and Validation Artifacts | Capability | Status | Public Statement | |---|---|---| -| Zarr trajectory stores | Supported | Principal high-fidelity format for trajectory workflows; chunked and appendable. | -| HDF5 snapshots | Legacy | Maintained for backward compatibility and benchmark extraction; deprecated for new large-scale training corpora. | +| HDF5 snapshots | Supported | Default single-file format for new trajectory workflows. | +| Zarr trajectory stores | Supported | Explicit opt-in for directory-based trajectory storage; existing stores remain readable. | | VTU / PyVista-style visualization | Beta | Available via declarative output settings; format fidelity relies on optional visualization dependencies. | | Automated visualization generation | Beta | Generates documentation-ready GIFs and plots; artifacts must be manually verified before academic publication. | | Reaction-force logging | Supported | Available for load-displacement verification through `output.reaction_node_set` and `output.reaction_component`. | -| Strict-parity benchmark scripts | Beta | `compare.py` routines available for selected examples to verify tolerances against reference literature. | +| Benchmark comparison scripts | Beta | Selected examples include `compare.py` routines that evaluate stated tolerances against published reference results. | | CPU execution and optional accelerator use | Supported | Core CPU execution is exercised by public checks. Practical device choice for larger simulations depends on mesh size, precision, backend availability, and the documented workflow. | diff --git a/docs/user_guide/example_contract.md b/docs/user_guide/example_contract.md index 4937779ce..e699ee95a 100644 --- a/docs/user_guide/example_contract.md +++ b/docs/user_guide/example_contract.md @@ -19,6 +19,11 @@ its capability boundary. This page supersedes the older scattered checklists in Those files remain machine-readable manifests, but this page is the human-facing source of truth. +New YAML examples, READMEs, and tutorials must follow the mandatory +{download}`configuration authoring rules <../../CONFIGURATION_STYLE.md>`. +The [standard simulation tutorial](../tutorial/07_standard_simulation_workflow.md) +is the student-facing companion, not a claim that every adapter is verified. + ## Example tiers | Tier | Command shape | Public meaning | @@ -89,7 +94,7 @@ release checks without reverse-engineering a solver scratch directory. | `energy.csv` | fracture/dynamic runners | energy plots, validation review | Required when an energy plot or claim is presented. | | `solver_telemetry.csv` | iterative solvers | convergence review | Required when convergence behavior is part of the example. | | `timing_per_step.csv` | runner/profiler | performance review | Required when timing claims are made. | -| `training_data.zarr` | trajectory writer | restart, postprocess, ML consumers | Keep out of git unless published as an external release artifact. | +| `training_data.h5` | trajectory writer | restart, postprocess, ML consumers | Default single-file format; keep out of git unless published as an external release artifact. | | PNG/GIF visuals | plot/postprocess layer | docs gallery, review packets | Governed by `visual_manifest.json` and this contract. | Inspect completed runs through `phast.load_result(path)`. Stored raw fields are @@ -125,10 +130,28 @@ For public YAML examples, `config.yaml` is the exact declarative configuration. checked in and runnable from the repository root: ```bash +python -m phast explain-config examples///config.yaml python -m phast run examples///config.yaml --validate-only python -m phast run examples///config.yaml --output_dir runs/ ``` +Replace bracketed path components with real names and check all three commands +for the selected schema/adapter before promotion. Legacy `precheck --config` +is not a universal schema-2 substitute. + +New standard inputs use schema 2 in the order `schema_version`, `name`, +`reference`, `geometry`, `regions`, `materials`, `assignments`, +`initial_conditions`, `boundary_conditions`, `analysis_steps`, `solver`, +`outputs`. Omit unused optional sections rather than adding placeholders. +Preserve numerical values during writing-only changes; do not migrate +schema-1 benchmarks or frozen course inputs merely for style consistency. + +Complete compact comparison YAMLs are allowed under an example's +`comparisons/` directory. They duplicate model data, not solver code. +Use the common CLI with different output directories and state precisely +what changes and what stays fixed. The DCB coarse matched pair is separate +from its fine reference; no comparison-specific driver is needed. + The YAML must document or encode: - schema version and problem type; @@ -146,6 +169,13 @@ The YAML must document or encode: Use the fluent `phast.Problem` API to author new models when convenient, but the curated example is reproduced through the saved YAML configuration. +Explain geometry/mesh/selector dependencies, independent `E` and `Gc` +edits, units, and the meaning of `h/l0` without a universal convergence +guarantee. Separate analysis physics from integration, final time from a +step cap, and solver iterations from saved-output cadence. Label a short +setup exercise separately from a completed crack-growth calculation; +seeded `damage = 1` alone is not new growth. + ## Script-contract rules Script-contract examples must be explicit about why they are not YAML-first. @@ -292,6 +322,18 @@ or the comparison. It should not be decoration. - Include enough frames to show setup, crack initiation, crack interaction, and final state. +Online retained results must use MyST image/figure paths that Sphinx can +collect from the repository, with alternative text, the displayed time/load +interval, and a static fallback. Do not use an HTML image path outside the +copied asset tree or an unverified public raw URL. Check the built page before +publication; a local README preview is not proof of a working hosted image. + +Keep essential scientific limitations in captions. The DCB images demonstrate +qualitative layered-material interaction, not completed inclusion bypass. +A matched control, stored-field audit, independent review, and physical +validation are distinct evidence. Do not add large raw HDF5 stores to make +an online tutorial self-contained. + ### Curves and diagnostics - `load_displacement.png` or `response.png` when loading is controlled; @@ -326,8 +368,11 @@ reason to differ. Use trajectory stores only when they are needed for replay, ML, restart, derived fields, or high-fidelity post-processing. -- New trajectory/dataset workflows should prefer Zarr. -- Legacy H5 remains compatibility input/output for old artifacts. +- New trajectory/dataset workflows must default to HDF5 (`training_data.h5`). +- Zarr is an explicit opt-in for workflows that require directory-based stores; + existing Zarr artifacts remain supported and must not be renamed or deleted. +- Example configurations, notebooks, and output manifests must agree on the + selected format. Do not fall back silently from HDF5 to Zarr. - Tutorial-ready examples should document how to regenerate trajectory stores locally when field-level replay is needed. - VTU/PVD remains the ParaView-native visualization path. diff --git a/docs/user_guide/glossary.md b/docs/user_guide/glossary.md index b63333998..26cb64318 100644 --- a/docs/user_guide/glossary.md +++ b/docs/user_guide/glossary.md @@ -26,6 +26,6 @@ **Tangent** A local derivative of a residual or constitutive update with respect to an increment. -**Trajectory** A stored sequence of field snapshots, in the preferred Zarr or legacy H5 format when enabled. +**Trajectory** A stored sequence of field snapshots, in HDF5 format by default when enabled; Zarr requires explicit selection. **Weak form** An integral statement obtained by testing the strong form and integrating by parts. diff --git a/docs/user_guide/overview.md b/docs/user_guide/overview.md index b8526010e..38c75e9ea 100644 --- a/docs/user_guide/overview.md +++ b/docs/user_guide/overview.md @@ -87,7 +87,7 @@ workflows use two-dimensional triangulated meshes. |---|---| | Forward solver | Run explicit dynamic or staggered static/quasistatic phase-field fracture simulations from YAML. | | Quasistatic benchmarks | Reproduce and compare benchmark cases using standard configs, compare scripts, and documented output conventions. | -| Trajectory datasets | Write Zarr-first trajectory and visualization outputs from reproducible forward runs. | +| Trajectory datasets | Write single-file HDF5 trajectories by default, alongside visualization outputs from reproducible forward runs. | ## Solver Coupling diff --git a/docs/user_guide/results_visualization.md b/docs/user_guide/results_visualization.md index 2d3397d0a..8e7877799 100644 --- a/docs/user_guide/results_visualization.md +++ b/docs/user_guide/results_visualization.md @@ -10,8 +10,8 @@ A run directory can contain: | `run_metadata.json` | Run, mesh, device, and provenance metadata when written. | | `run_manifest.json` | Artifact-oriented manifest; older runs may use metadata. | | CSV histories | Scalar response, energy, telemetry, or timing rows. | -| Zarr trajectory | Preferred reloadable field snapshots when requested. | -| H5 trajectory | Legacy-compatible trajectory format when requested. | +| HDF5 trajectory | Default reloadable field snapshots in `training_data.h5` when requested. | +| Zarr trajectory | Directory-based trajectory format, available by explicit selection. | | PNG/VTU/MP4 and visual manifest | Human-facing visual outputs and their descriptions. | The exact contents depend on the configuration and execution route. An output request is not a guarantee that an unsupported field or postprocessor will be created. diff --git a/docs/user_guide/setup_problems.md b/docs/user_guide/setup_problems.md index 950e43706..1326bd9a5 100644 --- a/docs/user_guide/setup_problems.md +++ b/docs/user_guide/setup_problems.md @@ -4,10 +4,54 @@ This page explains the pieces of a PhAST forward model: geometry or mesh, regions, materials, initial conditions, boundary conditions, analysis steps, solver controls, outputs, validation, and result inspection. -Use the fluent `phast.Problem` API while designing a new setup. Use YAML configurations -for reproducible public examples, shared runs, CI, and HPC submission. +Start with the [standard simulation tutorial](../tutorial/07_standard_simulation_workflow.md) +for the student YAML route: small quasi-static SENT, small dynamic SENT, then +full layered DCB. Use `phast.Problem` for programmatic construction and a +complete YAML for shared runs. New adapter checks remain a promotion gate. -## FEM Workflow Map +## Standard schema-2 setup + +Use the order `schema_version`, `name`, `reference`, `geometry`, +`regions`, `materials`, `assignments`, `initial_conditions`, +`boundary_conditions`, `analysis_steps`, `solver`, `outputs`. +The {download}`configuration authoring rules <../../CONFIGURATION_STYLE.md>` +are mandatory for new YAML/README/tutorial contributions. + +| Edit | Input location | Dependency or interpretation | +|---|---|---| +| Rectangle dimensions | `geometry.parameters.length`, `height`, `origin` | Update coordinate-based boundaries, layer/disk regions, and crack selectors. | +| Structured mesh | `geometry.parameters.nx`, `ny` | Check non-empty selections and material-boundary resolution, not only `h/l0`. | +| Inclusion geometry | `regions` | Match circle and complementary selectors; assignments cover all elements without overlap. | +| Stiffness | `materials..parameters.E` | Changes elastic response and energy; it is not toughness. | +| Fracture resistance | `materials..parameters.Gc` | Vary separately from `E` for a controlled comparison. | +| Material placement | `assignments` | Refer to declared element regions, not support node sets. | +| Starter crack | `initial_conditions` and its region | Maintained prescribed damage on this route, not a prescribed future path. | +| Loading | `boundary_conditions`, `analysis_steps[].active_boundary_conditions` | Check selected nodes, directions, values, signs, and active names. | +| Quasi-static increments | `analysis_steps[].controls.number_of_steps` | Includes zero on the multi-material route; cutbacks can increase the accepted count. | +| Numerical acceptance | `solver` | Tolerances and iteration limits, not experimental validity. | +| Saved fields | `outputs.fields` | Use a trajectory request with `format: h5`; PNG/GIF alone is not reloadable field data. | + +The documented multi-material route is structured T3 rectangles, CPU float64, +quasi-static Amor AT2, elementwise `E`/`Gc`, common `nu`/`l0`, +shared constitutive settings, and Dirichlet conditions. It is not dynamic +multi-material or an independent interface law. The other geometry recipes +below belong to their own documented adapters, not automatically to this one. + +Quasi-static analysis omits inertia. Dynamics includes density and physical +time; explicit integration additionally needs a CFL-limited time step. +Final time, maximum steps, iteration limits, and output cadence are different +controls. Smaller steps or a particular `h/l0` are not validation guarantees. +A short setup exercise may not propagate a crack; seeded `damage = 1` +is not evidence of new growth. + +Frozen course inputs and separate 3D research retain their own scope until +adapters and evidence exist. + +## Fluent and legacy FEM workflow map + +The YAML column below describes the compatibility layout used by existing +schema-1 examples. Use the mapping above for new standard schema-2 inputs; +do not mix singular and plural sections. If you are coming from Abaqus, COMSOL, FEniCS, deal.II, or another FEM code, the PhAST workflow is the same sequence with different names: @@ -19,7 +63,7 @@ the PhAST workflow is the same sequence with different names: | Imported mesh | Mesh file / imported mesh | `.mesh("mesh.msh")` | `geometry.mesh_path` | | Named selections | Sets / physical groups / boundaries | `.region(...)` | geometry groups and node sets | | Material definition | Material card | `.material(...)` | `material:` | -| Material assignment | Section assignment / domain material | `.material(..., region="body")` | material plus region/node-set references | +| Material assignment | Section assignment / domain material | `.material(..., region="body")` | schema 1 is single-material; schema 2 uses `assignments` above | | Initial crack/notch state | Initial field / predefined field | `.initial_condition("damage", ...)` | `initial_conditions:` | | Supports | Dirichlet BC / fixed constraint | `.fix(...)` or `.boundary_condition("fix", ...)` | `boundary_conditions:` | | Prescribed displacement | Displacement BC | `.prescribe(...)` or `.boundary_condition("displacement", ...)` | `boundary_conditions:` | @@ -36,9 +80,10 @@ workflows. It does not compile arbitrary weak forms from user text. ## Units -For bare numerical values, PhAST uses the documented reference convention -shown below. Supported quoted unit strings are converted at the configuration -boundary, but all values in one model must still be dimensionally consistent: +Use a dimensionally consistent system for all values. Unit-string conversion +is route-specific: the schema-2 teaching inputs use bare numbers, and +`geometry.units` does not convert arbitrary material/loading values. +Common coherent conventions are: | Quantity | SI example | mm-N-MPa style example | |---|---|---| @@ -54,6 +99,10 @@ loads, density, fracture energy, and time-step controls are all expressed in the same system. The result manifests record the inputs; they do not infer or repair inconsistent units. +The quasi-static density is illustrative because inertia is omitted. Do not +reuse it as measured density in dynamics. State out-of-plane thickness and +reaction conventions when comparing forces. + ## Setup Checklist | Step | Question to answer | PhAST surface | @@ -404,7 +453,7 @@ comparison artifact. ## What Makes a Good Public Example? -Each public example should be boringly predictable: +Each public example should have a consistent, inspectable structure: - one `config.yaml` declarative configuration, - one optional `run_fluent.py` companion when the fluent path is promoted, @@ -418,3 +467,7 @@ Each public example should be boringly predictable: Examples that still need large raw trajectories, unpublished HPC provenance, or custom one-off scripts should stay out of the public examples tree until they are promoted. + +If an input choice or documented command is unclear, +[open a GitHub issue](https://github.com/CEMS-Lab/PhAST/issues/new/choose) +with the configuration, command, OS, Python/PhAST version, and full error. diff --git a/docs/user_guide/yaml_workflow.md b/docs/user_guide/yaml_workflow.md index 2d88dd4cb..f2360c188 100644 --- a/docs/user_guide/yaml_workflow.md +++ b/docs/user_guide/yaml_workflow.md @@ -1,178 +1,185 @@ -# Declarative YAML Workflows +# Declarative YAML workflows -YAML is the primary configuration format for reproducible simulations in -PhAST. Declarative configurations record the geometric, physical, numerical, -and output choices needed to review and repeat an academic simulation. +YAML records the geometry, mesh, materials, constraints, loading, numerical +controls, and outputs needed to share a PhAST model. Start with the +[standard simulation tutorial](../tutorial/07_standard_simulation_workflow.md) +for source installation and the three-problem student route: small +quasi-static SENT, small dynamic SENT, and full layered DCB. -The fluent `phast.Problem` API is useful for programmatic model construction; -YAML is preferred when a complete setup must be shared and reviewed. +The fluent `phast.Problem` API remains useful for programmatic authoring. +Neither a common input format nor a Python object makes unsupported physics +available. -YAML is the public reproduction format because it is explicit, machine-readable, -and stable across reruns. A validated configuration makes it possible to -recreate the same geometry, material parameters, loading history, and output -contract without reinterpreting interactive Python state. +## Explain, check, run -## Configuration Scope - -A declarative YAML configuration explicitly defines: -- **Geometry**: Built-in generators or paths to external meshes. The - declarative primitive DSL is a beta capability with limited supported - combinations; it is not an arbitrary geometry compiler. -- **Constitutive Models**: Material definitions, physics presets, and specific parameters. -- **Boundary Conditions**: Kinematic constraints and loading protocols. -- **Solver Execution**: Mathematical backend, temporal discretization, tolerances, and hardware device. -- **Artifact Generation**: Desired volumetric fields, CSV histories, visualization rendering, and trajectory storage formats. - -## Execution Workflow - -PhAST provides three primary CLI entry points for interacting with YAML configurations: +Run from the installed repository root. Replace `CONFIG` with a complete +YAML path and `RUN` with a new result directory. ```bash -# 1. Validate schema and workflow-contract constraints only; do not solve -python -m phast run examples/quasistatic/notched_holed_plate/config.yaml --validate-only - -# 2. Inspect the parsed configuration graph and hardware placement -python -m phast explain-config examples/quasistatic/notched_holed_plate/config.yaml - -# 3. Execute the simulation and specify an artifact output directory -python -m phast run examples/quasistatic/notched_holed_plate/config.yaml --output_dir runs/notched_holed_plate +python -m phast explain-config CONFIG +python -m phast run CONFIG --validate-only +python -m phast run CONFIG --output_dir RUN ``` -`--validate-only` parses the YAML and applies the available schema/workflow -checks, then exits before configuration resolution, factory imports, checkpoint -loading, mesh generation, or solving. It is a preflight check, not runtime, -mathematical, or scientific validation. - -This matters because the same configuration file can be shared across local -development, continuous integration, and HPC submission workflows without -changing the physics definition. - -## Schema Structure - -```yaml -problem: - name: notched_holed_plate - -geometry: - mesh_path: mesh.msh - -material: - preset: miehe_tension - overrides: - l0: 0.015 - pf_model: AT2 - -boundary_conditions: - - {nodes: bottom, type: fix, component: 0} - - {nodes: bottom, type: fix, component: 1} - - {nodes: top, type: prescribe, component: 1, value: 0.001} +The first command explains the input, the second checks the implemented +schema/workflow constraints without solving, and the third executes it. +Schema-2 explanation dispatch and the new single-material adapters require +combined CLI checks before the new sequences are labelled verified. +Legacy `precheck --config` is not a universal schema-2 replacement. -loading: - protocol: simple - num_steps: 10 +For the full DCB reference: -solver: - solver_type: quasi_static - backend: auto - preconditioner: jacobi - -output: - plots: true - trajectory: true - trajectory_format: zarr +```bash +python -m phast explain-config examples/two_material_dcb_beta/config.yaml +python -m phast run examples/two_material_dcb_beta/config.yaml --validate-only +python -m phast run examples/two_material_dcb_beta/config.yaml --output_dir runs/dcb_fine_reference ``` -Public examples contain the keys required by their documented execution -pathways. Begin with the nearest example and modify one physical or numerical -choice at a time. +Preflight stops before meshing and solving. It does not establish non-empty +mesh selections, numerical convergence, crack growth, mesh independence, or +experimental agreement. Use the selected runner's documented scope. -## Runnable Decks, Templates, And Contracts +## Schema-2 order -Not every YAML file in the repository represents one solver problem: +New standard-workflow inputs must follow the +{download}`configuration authoring rules <../../CONFIGURATION_STYLE.md>`: -| File class | Directly runnable? | Interpretation | +| Order | Key | Contents | |---|---|---| -| `examples///config.yaml` | Yes | Complete example-local solver input. | -| `configs/benchmarks//.yaml` | Yes | Complete benchmark solver input. | -| `configs/REFERENCE.yaml` | No | Annotated field reference and template. | -| `examples/PUBLIC_EXAMPLES_CONTRACT.yaml` | No | Example documentation and artifact inventory. | -| `configs/benchmarks/plasticity_interface/reproducibility_contracts.yaml` | Only with `--validation-id` | Dispatcher manifest for beta validation programs. | - -Contracts and manifests describe a collection of programs or expected -artifacts. They are not interchangeable with a single fracture `config.yaml`. - -## External Meshes and Provenance - -For built-in examples, structural geometry can be declared directly in YAML and -PhAST can generate the underlying computational mesh via Gmsh. The -declarative primitive DSL is beta and only selected combinations are supported; -consult the capability matrix before using boolean operations. For custom -domains, generate a format-compliant mesh (e.g., `.msh`) and reference it: +| 1 | `schema_version` | `2` for this layout. | +| 2 | `name` | Descriptive problem name. | +| 3 | `reference` | Source or teaching scope, when applicable. | +| 4 | `geometry` | Generator and supported mesh parameters. | +| 5 | `regions` | Named node and element selections. | +| 6 | `materials` | Named models and material parameters. | +| 7 | `assignments` | Material-to-element-region mapping. | +| 8 | `initial_conditions` | Initial fields or route-specific maintained damage. | +| 9 | `boundary_conditions` | Named constraints and prescribed values. | +| 10 | `analysis_steps` | Physical analysis, active conditions, loading controls. | +| 11 | `solver` | Numerical algorithm, tolerances, iteration limits. | +| 12 | `outputs` | Directory, fields, histories, visuals. | + +Use the {download}`complete DCB input <../../examples/two_material_dcb_beta/config.yaml>` +or {download}`heterogeneous SENT input <../../examples/heterogeneous_sent_beta/config.yaml>`, +not a mixture of unrelated partial examples. The companion single-material +inputs under `examples/standard_workflow/` require their documented adapter +checks before promotion. + +### Geometry and regions + +The documented multi-material route uses `geometry.type: structured_rectangle` +with `length`, `height`, `origin`, `nx`, and `ny` in +`geometry.parameters`. Cells are divided into T3 triangles. Material regions +select element centroids; crack constraints and supports select nodes. + +Changing dimensions does not automatically move boundaries, cracks, layers, +or complementary disk selectors. Update those dependencies together and +cover every element exactly once. Mesh changes can make a narrow node +selection empty or alter an inclusion's discrete boundary. + +### Materials and analysis + +`materials..parameters.E` controls stiffness; +`materials..parameters.Gc` controls fracture resistance. Vary them +independently before attributing a response change to one property. +Use a coherent unit system; `geometry.units` does not convert arbitrary +bare material/loading numbers. + +Quasi-static analysis omits inertia. The DCB +`analysis_steps[0].controls.number_of_steps: 121` gives 121 nominal levels +including zero: 120 nominal increments, with more possible after cutbacks. +`solver` separately controls convergence. + +Dynamics includes density and physical time. Explicit integration needs a +CFL-limited time step. Final time, maximum steps, solver iterations, and +saved-output cadence are different controls; use the actual adapter keys. +Neither a smaller step nor one `h/l0` ratio establishes validation. + +## Compatibility layouts and capability limits + +Schema-1 benchmarks retain singular `material`, `loading`, and `output` +sections and `solver.solver_type`. Schema 2 uses `materials`, +`assignments`, `analysis_steps`, `outputs`, and `solver.type`. +Do not mix layouts or migrate by changing only the version number. + +The documented multi-material scope is structured T3 rectangles, CPU float64, +quasi-static Amor AT2, elementwise `E`/`Gc`, shared `nu`/`l0` and +constitutive settings, and Dirichlet conditions. It does not cover dynamic +multi-material execution or independent interface laws. Other legacy +generators and imported meshes belong to their specific documented routes, +not automatically to this one. Consult the [capability matrix](capability_matrix.md). + +Frozen course inputs and separate 3D research remain separate until adapters +and evidence exist. A common writing style is not a migration instruction. + +## Inputs, templates, and complete comparison decks + +| File class | Interpretation | +|---|---| +| Example `config.yaml` | Solver input for its documented adapter/status, not proof of a completed run. | +| DCB `comparisons/tough_region.yaml` and `uniform_layer.yaml` | Complete coarse inputs for the same CLI; only disk `Gc` differs between the pair. | +| Benchmark input under `configs/benchmarks/` | Follow its exact schema and example command. | +| `configs/REFERENCE.yaml` | Annotated compatibility reference, not a universal schema-2 input. | +| `examples/PUBLIC_EXAMPLES_CONTRACT.yaml` | Artifact inventory, not a solver problem. | +| Plasticity/interface reproduction contract | Dispatcher manifest; follow its documented `--validation-id` route. | + +Compact complete comparison decks duplicate model data, not solver code. +The [standard tutorial](../tutorial/07_standard_simulation_workflow.md) +provides exact coarse-pair commands and distinguishes their results from +the fine DCB reference. Use separate output directories. + +## HDF5 trajectories + +This **partial schema-2 excerpt** adds a trajectory request to the existing +`outputs.fields` list; preserve the other outputs: ```yaml -geometry: - mesh_path: meshes/custom_domain.msh -``` - -External meshes must preserve named physical groups for every boundary or domain referenced in the YAML configuration. You can inspect parsed mesh groups programmatically: - -```python -import phast - -summary = phast.inspect_mesh("meshes/custom_domain.msh") -print(summary["named_groups"]) +outputs: + fields: + - {name: trajectory, format: h5, every: 1} ``` -## High-Fidelity Volumetric Storage +HDF5 writes `training_data.h5`. The multi-material runner supports HDF5 +only and refuses to overwrite an existing trajectory. DCB requests it; +heterogeneous SENT leaves it opt-in. -PhAST defaults to chunked, parallel-friendly `zarr` stores for recording volumetric field trajectories. The legacy `h5` format is maintained strictly for compatibility with older external post-processing scripts. +The **legacy schema-1** equivalent uses different keys: ```yaml output: trajectory: true - trajectory_format: zarr # Options: zarr, h5, both + trajectory_format: h5 h5_every: 5 ``` -Trajectory formats can also be dynamically overridden via the CLI without modifying the underlying configuration file: - -```bash -python -m phast run config.yaml --trajectory --trajectory-format zarr -``` - -## Standardized Artifact Directory - -A successfully executed configuration writes an artifact directory such as -`runs/notched_holed_plate/`. Depending on the selected output settings and -runner, the directory may include: -- The exact `config.yaml` used for execution. -- `run_lockfile.json` capturing the parsed state, Git hashes, and dependencies. -- CSV histories (response, kinetic energy, nonlinear convergence). -- High-fidelity Zarr trajectories when trajectory output is enabled. -- Visual manifests and pre-rendered plots. +Legacy routes that support `zarr` or `both` require explicit selection; +do not assume those formats work in every schema-2 adapter. No format is a +silent fallback. Existing stores remain unchanged. Close a file before +transferring it; a single file does not make concurrent synchronised writes +safe. Keep large raw stores out of public example payloads. -## Result Inspection +## Inspect results -The public `Result` interface treats the existing artifact directory as -read-only and can be queried programmatically: +A successful run writes requested artifacts to `RUN`: configuration and +provenance, manifests, histories, lightweight visuals, and requested fields, +as supported by the route. Inspect the manifest rather than assuming every +small exercise produces a propagating crack. ```python import phast -result = phast.load_result("runs/notched_holed_plate") +result = phast.load_result("runs/dcb_fine_reference") print(result.metadata()) print(result.history_names()) - +print(result.visuals()) if result.has_field("damage"): damage = result.field("damage", step=-1) ``` -The `Result` object exposes only quantities that were explicitly written during the simulation; it does not silently synthesize derived fields. - -## Extensibility Boundary +The result interface reads stored quantities. A PNG is not a field +trajectory; retained evidence is not a new run. See the +[example contract](example_contract.md). -YAML configurations route to explicitly implemented PhAST execution pathways. -They do not compile arbitrary weak-form PDEs. The capability matrix defines the -documented support boundary. Schema validation detects unsupported combinations -that are represented in the validator, but it is not a substitute for checking -the numerical evidence associated with a model. +If a documented step fails, +[open a GitHub issue](https://github.com/CEMS-Lab/PhAST/issues/new/choose) +with the configuration, exact command, OS, Python/PhAST version, and full error. diff --git a/docs/verify-install.md b/docs/verify-install.md index 07eb5e585..cc86c452f 100644 --- a/docs/verify-install.md +++ b/docs/verify-install.md @@ -1,8 +1,8 @@ # Verify Install -## Verification ladder +## Verification sequence -Use the checks in this order. Each rung is stronger and more expensive than +Use the checks in this order. Each check exercises more of the software than the previous one: 1. **Doctor** reports what the current environment can provide. @@ -10,9 +10,9 @@ the previous one: 3. **Validate-only** checks a public YAML configuration without solving it. 4. **Completed run** executes the selected example and produces a result bundle. -Passing a lower rung does not certify the next one. In particular, -`--validate-only` is schema and path preflight; it is not runtime or scientific -validation. +Passing one check does not guarantee that the next check will pass. In +particular, `--validate-only` checks the schema and referenced paths; it does +not test solver execution or establish scientific validity. ## Quick single-element sanitizer @@ -32,9 +32,9 @@ wall-clock guarantee: Python and PyTorch cold imports vary across operating systems and machines. The reported kernel-and-plot time excludes imports. Use this page after installation, on a new workstation, or after loading a new -HPC environment. The goal is to confirm that PhAST can import, see the expected -optional backends, and validate a public configuration before launching a full -solve. +HPC environment. The goal is to confirm that PhAST imports correctly, detects +the expected optional backends, and accepts an example configuration before a +full simulation. ## Environment Doctor @@ -99,7 +99,7 @@ python -m phast explain-config examples/dynamic/B2_kalthoff_winkler/config.yaml ``` Use this output to confirm the material, geometry, solver type, output settings, -and `device.compile` policy before running a costly simulation. +and `device.compile` setting before running a larger simulation. ## Common Outcomes diff --git a/examples/PUBLIC_EXAMPLES_CONTRACT.yaml b/examples/PUBLIC_EXAMPLES_CONTRACT.yaml index d7c4c6890..f981b52ce 100644 --- a/examples/PUBLIC_EXAMPLES_CONTRACT.yaml +++ b/examples/PUBLIC_EXAMPLES_CONTRACT.yaml @@ -28,6 +28,70 @@ tiers: contract: Developer evidence only; do not promote as a public example without a manifest update. public_gallery: false families: +- id: standard_workflow + tier: yaml_first + examples: + - id: quasistatic_sent_setup + path: examples/standard_workflow/quasistatic_sent + tutorial_ready: true + role: Small schema-v2 quasi-static setup exercise, not crack-growth validation. + required_artifacts: + - README.md + - config.yaml + - id: dynamic_sent_setup + path: examples/standard_workflow/dynamic_sent + tutorial_ready: true + role: Small schema-v2 explicit-dynamic setup exercise, not crack-growth validation. + required_artifacts: + - README.md + - config.yaml +- id: heterogeneous_fracture + tier: yaml_first + examples: + - id: heterogeneous_sent_setup + path: examples/heterogeneous_sent_beta + tutorial_ready: false + role: Beta multi-material setup; retained DCB results do not validate this geometry. + required_artifacts: + - README.md + - config.yaml + - id: two_material_dcb_phase_field + path: examples/two_material_dcb_beta + kind: heterogeneous_phase_field_teaching + tutorial_ready: true + tutorial_blockers: [] + workflow_entrypoint: examples/two_material_dcb_beta/config.yaml + workflow_command: python -m phast run examples/two_material_dcb_beta/config.yaml --output_dir runs/two_material_dcb + retained_result: examples/two_material_dcb_beta/results + role: Executed beta bulk-layer crack-interaction illustration with HDF5 output and a matched toughness comparison; not completed bypass, penetration, interface debonding, or a validated fracture benchmark. + required_artifacts: + - README.md + - config.yaml + - comparisons/tough_region.yaml + - comparisons/uniform_layer.yaml + - compare_results.py + - results/README.md + - results/summary.json + - results/numerical_review.json + - results/history.csv + - results/material_fields.png + - results/initial_conditions.png + - results/damage_final.png + - results/displacement_final.png + - results/strain_final.png + - results/stress_final.png + - results/damage_evolution.gif + - results/load_displacement.png + - results/matched_control_comparison.png + - results/matched_control_damage.png + - results/matched_control_review.json + - results/coarse_tough_history.csv + - results/uniform_layer_history.csv + - results/matched_control_fields.csv.gz + - results/matched_control_elements.csv.gz + - results/comparison_provenance.json + - results/run_manifest.json + - results/visual_manifest.json - id: dynamic tier: yaml_first examples: diff --git a/examples/README.md b/examples/README.md index 62eef7ecd..481c3c3c6 100644 --- a/examples/README.md +++ b/examples/README.md @@ -125,7 +125,7 @@ outputs, and validation notes are added. | `--output_dir DIR` | Write results to a custom directory. | | `--plots` | Generate PNG figures when supported. | | `--gif` | Generate an animated GIF when supported. | -| `--trajectory --trajectory-format zarr` | Write a Zarr trajectory store for inspection or reuse. | +| `--trajectory --trajectory-format h5` | Write the default single-file HDF5 trajectory for inspection or reuse. | | `--device cpu/cuda` | Select the compute device. | ## Expected Folder Contents diff --git a/examples/dynamic/B2_kalthoff_winkler/run_fluent.py b/examples/dynamic/B2_kalthoff_winkler/run_fluent.py index 1269679e5..78bbb4ea7 100644 --- a/examples/dynamic/B2_kalthoff_winkler/run_fluent.py +++ b/examples/dynamic/B2_kalthoff_winkler/run_fluent.py @@ -74,7 +74,7 @@ def build_problem(num_steps: int | None = None) -> phast.Problem: problem.config.output = OutputConfig( trajectory=True, h5=True, - trajectory_format="zarr", + trajectory_format="h5", h5_every=50, fast=True, print_every=100, diff --git a/examples/dynamic/B3_dynamic_sent/config.yaml b/examples/dynamic/B3_dynamic_sent/config.yaml index 94d91b313..a4d76b123 100644 --- a/examples/dynamic/B3_dynamic_sent/config.yaml +++ b/examples/dynamic/B3_dynamic_sent/config.yaml @@ -63,7 +63,7 @@ solver: dt_safety: 0.8 output: trajectory: true - trajectory_format: zarr + trajectory_format: h5 h5_every: 20 fast: true print_every: 100 diff --git a/examples/dynamic/B3_dynamic_sent/run_fluent.py b/examples/dynamic/B3_dynamic_sent/run_fluent.py index a3431432b..3b699447f 100644 --- a/examples/dynamic/B3_dynamic_sent/run_fluent.py +++ b/examples/dynamic/B3_dynamic_sent/run_fluent.py @@ -65,7 +65,7 @@ def build_problem(num_steps: int | None = None) -> phast.Problem: problem.config.output = OutputConfig( trajectory=True, h5=True, - trajectory_format="zarr", + trajectory_format="h5", h5_every=20, fast=True, print_every=100, diff --git a/examples/dynamic/B5_pmma_branching/config.yaml b/examples/dynamic/B5_pmma_branching/config.yaml index b1384ecd9..25366a355 100644 --- a/examples/dynamic/B5_pmma_branching/config.yaml +++ b/examples/dynamic/B5_pmma_branching/config.yaml @@ -70,7 +70,7 @@ solver: damage_every: 1 output: trajectory: true - trajectory_format: zarr + trajectory_format: h5 h5_every: 20 fast: true print_every: 100 diff --git a/examples/dynamic/B5_pmma_branching/run_fluent.py b/examples/dynamic/B5_pmma_branching/run_fluent.py index d870dce07..479207dc6 100644 --- a/examples/dynamic/B5_pmma_branching/run_fluent.py +++ b/examples/dynamic/B5_pmma_branching/run_fluent.py @@ -70,7 +70,7 @@ def build_problem(num_steps: int | None = None) -> phast.Problem: problem.config.output = OutputConfig( trajectory=True, h5=True, - trajectory_format="zarr", + trajectory_format="h5", h5_every=20, fast=True, print_every=100, diff --git a/examples/dynamic/B6_perforated_30holes/config.yaml b/examples/dynamic/B6_perforated_30holes/config.yaml index 20697b07f..cba6d24e8 100644 --- a/examples/dynamic/B6_perforated_30holes/config.yaml +++ b/examples/dynamic/B6_perforated_30holes/config.yaml @@ -38,7 +38,7 @@ solver: dt_safety: 0.8 output: trajectory: true - trajectory_format: zarr + trajectory_format: h5 h5_every: 20 fast: true print_every: 100 diff --git a/examples/dynamic/B6_perforated_30holes/run_fluent.py b/examples/dynamic/B6_perforated_30holes/run_fluent.py index d8b9bd39b..82a2d9901 100644 --- a/examples/dynamic/B6_perforated_30holes/run_fluent.py +++ b/examples/dynamic/B6_perforated_30holes/run_fluent.py @@ -59,7 +59,7 @@ def build_problem(num_steps: int | None = None) -> phast.Problem: problem.config.output = OutputConfig( trajectory=True, h5=True, - trajectory_format="zarr", + trajectory_format="h5", h5_every=20, fast=True, print_every=100, diff --git a/examples/dynamic/B7_dynamic_crack_branching_comsol/config.yaml b/examples/dynamic/B7_dynamic_crack_branching_comsol/config.yaml index b48a38b86..40c5f2d16 100644 --- a/examples/dynamic/B7_dynamic_crack_branching_comsol/config.yaml +++ b/examples/dynamic/B7_dynamic_crack_branching_comsol/config.yaml @@ -180,7 +180,7 @@ solver: output: trajectory: true - trajectory_format: zarr + trajectory_format: h5 h5_every: 50 fast: true print_every: 200 diff --git a/examples/dynamic/B7_dynamic_crack_branching_comsol/run_fluent.py b/examples/dynamic/B7_dynamic_crack_branching_comsol/run_fluent.py index 973dc2f2c..b26568fc5 100644 --- a/examples/dynamic/B7_dynamic_crack_branching_comsol/run_fluent.py +++ b/examples/dynamic/B7_dynamic_crack_branching_comsol/run_fluent.py @@ -35,7 +35,7 @@ def build_problem(num_steps: int | None = None) -> phast.Problem: "required_outputs": [ "run_lockfile.json", "config.yaml", - "training_data.zarr", + "training_data.h5", "energy.csv", "crack_tip.csv", "compare_report.txt", @@ -124,7 +124,7 @@ def build_problem(num_steps: int | None = None) -> phast.Problem: problem.config.output = OutputConfig( trajectory=True, h5=True, - trajectory_format="zarr", + trajectory_format="h5", h5_every=50, fast=True, print_every=200, diff --git a/examples/heterogeneous_sent_beta/README.md b/examples/heterogeneous_sent_beta/README.md new file mode 100644 index 000000000..4a3efa0d8 --- /dev/null +++ b/examples/heterogeneous_sent_beta/README.md @@ -0,0 +1,123 @@ +# Heterogeneous single-edge-notched tension + +This beta schema-2 example pulls a square plate with a horizontal starter +crack and a circular tougher bulk region. It uses the same section order and +CLI as the layered DCB, without a problem-specific solver loop. Its numerical +values are teaching choices, not a calibrated crack-deflection benchmark. + +See the [standard simulation tutorial](../../docs/tutorial/07_standard_simulation_workflow.md) +for Python 3.10+ source installation on macOS/Linux or Windows, and the +[configuration style](../../CONFIGURATION_STYLE.md) for authoring rules. +The primary teaching route uses the two short single-material SENT exercises +before the full DCB; this is an additional multi-material setup. + +## Run from the repository root + +```bash +python -m phast explain-config examples/heterogeneous_sent_beta/config.yaml +python -m phast run examples/heterogeneous_sent_beta/config.yaml --validate-only +python -m phast run examples/heterogeneous_sent_beta/config.yaml --output_dir runs/heterogeneous_sent +``` + +Schema-2 explanation dispatch requires the combined CLI check before this +sequence is labelled verified. Legacy `precheck --config` is not a +universal schema-2 command. Preflight does not mesh or solve. Use a new +output directory for a changed case. + +## Read the configuration + +The section order is `schema_version`, `name`, `reference`, `geometry`, +`regions`, `materials`, `assignments`, `initial_conditions`, +`boundary_conditions`, `analysis_steps`, `solver`, `outputs`. + +| Input | Meaning | +|---|---| +| Geometry and mesh | A 1 mm square, `40 x 40` cells split into T3 elements. | +| Starter crack | From `(0, 0.50)` to `(0.40, 0.50) mm`; prescribed `damage = 1`. | +| Inclusion | Circle centred at `(0.65, 0.50) mm`, radius `0.12 mm`. | +| Common elastic properties | `E = 210 MPa`, `nu = 0.30`; plane stress. | +| Fracture resistance | Matrix `Gc = 0.0027 N/mm`; inclusion `Gc = 0.0081 N/mm`. | +| Regularisation | Common `l0 = 0.05 mm`, Amor split, AT2. | +| Mechanical support | Bottom `uy = 0`; bottom-left `ux = 0` removes horizontal rigid translation. | +| Loading | Top `uy` ramps to `0.012 mm`. | +| Load levels | 61 including zero: 60 nominal increments, with extra increments possible after cutbacks. | +| Damage boundary assumption | Top and bottom remain at `damage = 0`; the initial crack remains at `damage = 1`. | + +The undamaged top/bottom constraints suppress boundary damage. They are a +stated modelling choice, not the natural phase-field condition. The selected +final displacement does not guarantee a particular crack path or stopping +event. + +## Make one controlled edit + +| Edit | What to check | +|---|---| +| Rectangle dimensions/origin | Update top/bottom boundary coordinates, the anchor, crack, and disk. | +| `nx` or `ny` | Keep selected nodes/elements non-empty; a narrow crack mask can miss a changed mesh. | +| Disk centre/radius | Update both `circle` and `outside_circle` selectors identically. | +| A material's `E` | Stiffness and stress/energy redistribution change; this does not independently increase toughness. | +| A material's `Gc` | Fracture resistance changes; keep `E` and other inputs fixed to isolate that effect. | +| Top displacement | Check strain/rotation assumptions, convergence, and the response before extending the run. | + +Element-centroid selection approximates the material boundary rather than +creating a conforming circle. Use positive `E`/`Gc` and only the damage +initial conditions and history requests accepted by this route. Define `h` +when reporting `h/l0`, and +compare mesh and load-increment sensitivity; no single ratio guarantees +convergence. The starter crack already has maximum damage one, so that +maximum alone is not evidence of propagation. + +Quasi-static analysis omits inertia; load factor is not physical time and the +illustrative density is not dynamic material data. Explicit dynamics needs +consistent density/time and a CFL-limited step, but dynamic multi-material +execution is not supported by this route. A smaller step is not physical +validation. + +## Outputs and optional trajectory + +The runner produces CSV histories and nodal/element fields, setup/material +and final-field PNGs, `damage_evolution.gif`, `final_fields.vtu`, a summary, +and run/visual manifests. The input does **not** request a trajectory. +If field-level replay is needed, add this entry to its existing +`outputs.fields` list in a working copy, retaining the other output requests: + +```yaml +- {name: trajectory, format: h5, every: 1} +``` + +This is a list-entry excerpt, not a complete configuration. HDF5 is the +default trajectory format on this route; use a new directory because its +writer refuses to overwrite `training_data.h5`. Keep large raw stores local. + +```python +import phast + +result = phast.load_result("runs/heterogeneous_sent") +print(result.metadata()) +print(result.history_names()) +print(result.visuals()) +if result.has_field("damage"): + damage = result.field("damage", step=-1) +``` + +## Evidence and limits + +No completed-run result bundle is retained in this example folder. Do not +treat the input or the chosen endpoint as verified crack-deflection evidence. +Interpret penetration, shielding, arrest, or deflection only after checking +seed-connected growth, fields, reaction history, convergence, and sensitivity. + +The documented multi-material scope is a structured T3 rectangle, CPU +float64, elementwise `E`/`Gc`, common `nu`/`l0` and shared Amor AT2 +settings, with prescribed-value constraints. It is bulk phase-field fracture, +not interfacial debonding, a cohesive law, or PF-CZM. Frozen historical course +inputs and separate 3D research are not part of this adapter. + +Baseline topology references, not validation data for this heterogeneous case: + +- [Miehe, Hofacker, and Welschinger (2010)](https://doi.org/10.1016/j.cma.2010.04.011) +- [PhaseFieldX single-edge-notched tension example](https://phasefieldx.readthedocs.io/en/latest/auto_examples/PhaseFieldFracture/plot_1711.html) + +If a step is unclear, +[open a GitHub issue](https://github.com/CEMS-Lab/PhAST/issues/new/choose) +with the input, exact command, OS, Python/PhAST version, and full error. diff --git a/examples/heterogeneous_sent_beta/config.yaml b/examples/heterogeneous_sent_beta/config.yaml new file mode 100644 index 000000000..28a9ecd26 --- /dev/null +++ b/examples/heterogeneous_sent_beta/config.yaml @@ -0,0 +1,97 @@ +# Standard order: CONFIGURATION_STYLE.md at the repository root. +# 1. Identity and evidence boundary; beta teaching input, not physical validation. +schema_version: 2 +name: Heterogeneous single-edge-notched tension with a tough inclusion +reference: Adapted teaching calculation based on the Miehe single-edge-notched tension topology +# 2. Geometry [mm] and mesh: nx/ny count cells split into T3 triangles. +# Dimension changes require corresponding boundary/crack/material-selector edits. +geometry: + type: structured_rectangle + units: mm + parameters: {length: 1.0, height: 1.0, origin: [0.0, 0.0], nx: 40, ny: 40} +# 3. Materials select element centroids; constraints select nodes. +# Keep circle and all complementary outside_circle selectors consistent. +# Crack thickness is a selection distance, not a physical opening. +regions: + matrix_region: {kind: element_region, type: outside_circle, center: [0.65, 0.50], radius: 0.12} + inclusion_region: {kind: element_region, type: circle, center: [0.65, 0.50], radius: 0.12} + initial_crack: {kind: node_region, type: line_segment, from: [0.0, 0.50], to: [0.40, 0.50], thickness: 0.013} + bottom: {kind: node_region, type: boundary, axis: y, value: 0.0, tolerance: 1.0e-8} + bottom_left: {kind: node_region, type: boundary_segment, axis: x, value: 0.0, bounds: {y: [0.0, 0.0]}, tolerance: 1.0e-8} + top: {kind: node_region, type: boundary, axis: y, value: 1.0, tolerance: 1.0e-8} + damage_exclusion: + kind: node_region + type: any_of + selectors: + - {type: boundary, axis: y, value: 0.0, tolerance: 1.0e-8} + - {type: boundary, axis: y, value: 1.0, tolerance: 1.0e-8} +# 4. E [MPa] is stiffness; Gc [N/mm] is fracture resistance; l0 [mm]. +# Equal E isolates toughness contrast. This route varies elementwise E/Gc only. +# Keep nu/l0/model/split/plane-stress and shared settings consistent. +# rho is illustrative: quasi-static equilibrium omits inertia. +materials: + matrix: + model: phase_field + parameters: {E: 210.0, nu: 0.30, Gc: 0.0027, l0: 0.05, rho: 1.0, eta_residual: 1.0e-6, energy_split: amor, pf_model: AT2, plane_stress: true} + tough_inclusion: + model: phase_field + parameters: {E: 210.0, nu: 0.30, Gc: 0.0081, l0: 0.05, rho: 1.0, eta_residual: 1.0e-6, energy_split: amor, pf_model: AT2, plane_stress: true} +# 5. Every element receives one material: no gaps or overlaps. +assignments: + - {material: matrix, region: matrix_region} + - {material: tough_inclusion, region: inclusion_region} +# 6. Prescribed damage values are maintained; no future crack path is imposed. +initial_conditions: + - {field: damage, region: initial_crack, value: 1.0} + - {field: damage, region: damage_exclusion, value: 0.0} +# 7. Dirichlet conditions prescribe displacements [mm] or fix components. +boundary_conditions: + - {name: bottom_x, type: fix, region: bottom_left, dof: x} + - {name: bottom_y, type: fix, region: bottom, dof: y} + - {name: top_y, type: prescribe, region: top, dof: y, value: 0.012} +# 8. Quasi-static load levels, not physical time; the count includes zero. +analysis_steps: + - name: tension + type: quasi_static + active_boundary_conditions: [bottom_x, bottom_y, top_y] + # 61 levels include zero: 60 nominal increments before any cutbacks. + controls: {number_of_steps: 61} +# 9. CPU float64 staggered Amor AT2 controls. Iterations are not load steps. +# Algebraic convergence and h/l0 alone do not establish physical validation. +solver: + type: quasi_static + mechanics_backend: auto + mechanics_tolerance: 1.0e-9 + mechanics_relative_tolerance: 1.0e-8 + mechanics_max_iterations: 30 + damage_tolerance: 1.0e-8 + damage_max_iterations: 500 + damage_bounds_method: projected_cg + maximum_staggered_iterations: 500 + staggered_damage_tolerance: 1.0e-5 + projected_residual_tolerance: 1.0e-5 + damage_relaxation: 0.70 + automatic_cutback: true + minimum_load_increment: 0.0005 + maximum_cutbacks: 20 + crack_front_threshold: 0.80 +# 10. Output requests. Use a fresh directory for every comparison. +# HDF5 is the default when a trajectory is requested; keep raw stores local. +outputs: + # No trajectory is requested in this input; PNG/GIF is not stored field history. + directory: runs/heterogeneous_sent + fields: + - {name: displacement} + - {name: strain} + - {name: stress} + - {name: damage} + - {name: vtu} + history: + - {name: reaction_force, region: top, dof: y} + - {name: max_damage} + - {name: solver_telemetry} + - {name: timing_per_step} + visuals: + initial_conditions: true + plots: true + animation: {field: damage} diff --git a/examples/plasticity_interface_beta/_promoted_result_utils.py b/examples/plasticity_interface_beta/_promoted_result_utils.py index c7a579669..edad7f75f 100644 --- a/examples/plasticity_interface_beta/_promoted_result_utils.py +++ b/examples/plasticity_interface_beta/_promoted_result_utils.py @@ -3,6 +3,7 @@ import csv import json +from contextlib import nullcontext from pathlib import Path from typing import Mapping @@ -20,6 +21,57 @@ def write_csv_rows(path: Path, rows: list[Mapping[str, object]]) -> None: writer.writerows(rows) +def write_trajectory( + output_dir: Path, + *, + nodes: np.ndarray, + elements: np.ndarray, + snapshots: list[tuple[int, Mapping[str, np.ndarray]]], + metadata: Mapping[str, object], + trajectory_format: str = "h5", +) -> Path: + """Write HDF5 by default, or Zarr when explicitly requested. + + Both formats retain the same per-step field layout. The HDF5 handle is + closed before returning so the completed file can be copied or synced. + """ + if trajectory_format not in ("h5", "zarr"): + raise ValueError("trajectory_format must be h5 or zarr") + path = output_dir / f"training_data.{trajectory_format}" + if trajectory_format == "h5": + import h5py + + store = h5py.File(path, "w") + else: + import zarr + + store = nullcontext(zarr.open_group(str(path), mode="w")) + + with store as root: + root.attrs["format"] = f"phast.trajectory.{trajectory_format}" + root.attrs["writer"] = "examples.plasticity_interface_beta._promoted_result_utils" + + sim = root.create_group("simulation_data") + mesh = sim.create_group("mesh") + mesh.create_dataset("node_coordinates", data=np.asarray(nodes, dtype=np.float64)) + mesh.create_dataset("element_connectivity", data=np.asarray(elements, dtype=np.int64)) + meta = sim.create_group("metadata") + for key, value in metadata.items(): + meta.attrs[key] = value + + steps = sim.create_group("steps") + for step, arrays in snapshots: + group = steps.create_group(f"step_{int(step):04d}") + for name, array in arrays.items(): + data = np.asarray(array) + compression = ( + {"compression": "gzip", "compression_opts": 4} + if trajectory_format == "h5" and data.ndim > 0 else {} + ) + group.create_dataset(name, data=data, **compression) + return path + + def write_zarr_trajectory( output_dir: Path, *, @@ -28,28 +80,11 @@ def write_zarr_trajectory( snapshots: list[tuple[int, Mapping[str, np.ndarray]]], metadata: Mapping[str, object], ) -> Path: - """Write a compact PhAST-compatible Zarr trajectory store.""" - import zarr - - zarr_path = output_dir / "training_data.zarr" - root = zarr.open_group(str(zarr_path), mode="w") - root.attrs["format"] = "phast.trajectory.zarr" - root.attrs["writer"] = "examples.plasticity_interface_beta._promoted_result_utils" - - sim = root.create_group("simulation_data") - mesh = sim.create_group("mesh") - mesh.create_dataset("node_coordinates", data=np.asarray(nodes, dtype=np.float64)) - mesh.create_dataset("element_connectivity", data=np.asarray(elements, dtype=np.int64)) - meta = sim.create_group("metadata") - for key, value in metadata.items(): - meta.attrs[key] = value - - steps = sim.create_group("steps") - for step, arrays in snapshots: - group = steps.create_group(f"step_{int(step):04d}") - for name, array in arrays.items(): - group.create_dataset(name, data=np.asarray(array)) - return zarr_path + """Compatibility entry point for callers explicitly requesting Zarr.""" + return write_trajectory( + output_dir, nodes=nodes, elements=elements, snapshots=snapshots, + metadata=metadata, trajectory_format="zarr", + ) def merge_run_manifest_artifacts(output_dir: Path, required_names: list[str]) -> None: diff --git a/examples/plasticity_interface_beta/run_j2_validation.py b/examples/plasticity_interface_beta/run_j2_validation.py index 36b5c9323..864a77c57 100644 --- a/examples/plasticity_interface_beta/run_j2_validation.py +++ b/examples/plasticity_interface_beta/run_j2_validation.py @@ -26,7 +26,7 @@ from examples.plasticity_interface_beta._promoted_result_utils import ( merge_run_manifest_artifacts, write_csv_rows, - write_zarr_trajectory, + write_trajectory, ) from phast.material import Material from phast.plasticity import J2Plasticity, J2State @@ -401,7 +401,7 @@ def run_validation(output_dir: Path, *, n_load: int = 48, {"step": r["step"], "elapsed_s": r["elapsed_s"]} for r in rows ]) - write_zarr_trajectory( + write_trajectory( output_dir, nodes=nodes, elements=elements, @@ -434,7 +434,7 @@ def run_validation(output_dir: Path, *, n_load: int = 48, merge_run_manifest_artifacts(output_dir, [ "summary.json", "config.yaml", "run_lockfile.json", "run_metadata.json", "run_manifest.json", "run.log", - "training_data.zarr", "j2_stress_strain.csv", "j2_stress_strain.png", + "training_data.h5", "j2_stress_strain.csv", "j2_stress_strain.png", "stress_strain.png", "results.csv", "history.csv", "solver_telemetry.csv", "timing_per_step.csv", "initial_conditions.png", "equivalent_plastic_strain.png", diff --git a/examples/plasticity_interface_beta/run_pfczm_uniaxial_strength_validation.py b/examples/plasticity_interface_beta/run_pfczm_uniaxial_strength_validation.py index 8df119183..4dd51f19d 100644 --- a/examples/plasticity_interface_beta/run_pfczm_uniaxial_strength_validation.py +++ b/examples/plasticity_interface_beta/run_pfczm_uniaxial_strength_validation.py @@ -32,7 +32,7 @@ import torch from PIL import Image -from examples.plasticity_interface_beta._promoted_result_utils import write_zarr_trajectory +from examples.plasticity_interface_beta._promoted_result_utils import write_trajectory from phast.damage_solver import PhaseFieldDamageSolver from phast.fem_operators import FEMOperators from phast.material import Material @@ -517,7 +517,7 @@ def run_validation(output_dir: Path, *, for r in rows ]) visual_manifest = _write_plots(output_dir, nodes, elements, rows, frames) - write_zarr_trajectory( + write_trajectory( output_dir, nodes=nodes, elements=elements, @@ -546,7 +546,7 @@ def run_validation(output_dir: Path, *, manifest_paths = [ "summary.json", "config.yaml", "run_lockfile.json", "run_metadata.json", "run_manifest.json", "run.log", "mesh.geo", - "mesh.msh", "training_data.zarr", "results.csv", "history.csv", "energy.csv", + "mesh.msh", "training_data.h5", "results.csv", "history.csv", "energy.csv", "solver_telemetry.csv", "timing_per_step.csv", "damage_final.png", "initial_conditions.png", "load_displacement.png", "damage_history.png", "energy_split.png", "convergence.png", "mesh_deformed.png", diff --git a/examples/plasticity_interface_beta/run_structural_dcb_cohesive_benchmark.py b/examples/plasticity_interface_beta/run_structural_dcb_cohesive_benchmark.py index c1ece2f64..1f31a1743 100644 --- a/examples/plasticity_interface_beta/run_structural_dcb_cohesive_benchmark.py +++ b/examples/plasticity_interface_beta/run_structural_dcb_cohesive_benchmark.py @@ -29,7 +29,7 @@ from examples.plasticity_interface_beta._promoted_result_utils import ( merge_run_manifest_artifacts, write_csv_rows, - write_zarr_trajectory, + write_trajectory, ) from phast.cohesive_elements import ( BilinearCohesiveLaw, @@ -694,7 +694,7 @@ def run_benchmark( {"step": row["step"], "elapsed_s": row["elapsed_s"]} for row in rows ]) - write_zarr_trajectory( + write_trajectory( output_dir, nodes=nodes, elements=mesh.elements.cpu().numpy(), @@ -720,7 +720,7 @@ def run_benchmark( output_dir / "energy.csv", output_dir / "solver_telemetry.csv", output_dir / "timing_per_step.csv", - output_dir / "training_data.zarr", + output_dir / "training_data.h5", *image_paths, output_dir / "visual_manifest.json", ] diff --git a/examples/quasistatic/_run_utils.py b/examples/quasistatic/_run_utils.py index 3582a5ffa..b24712422 100644 --- a/examples/quasistatic/_run_utils.py +++ b/examples/quasistatic/_run_utils.py @@ -18,7 +18,7 @@ @dataclass class TrajectoryWriter: - """Small adapter hiding legacy H5 vs Zarr trajectory writers.""" + """Small adapter for HDF5 and explicitly selected Zarr trajectories.""" root: object kind: str @@ -38,16 +38,17 @@ def close(self, num_steps: int) -> None: self.root.attrs["num_steps"] = int(num_steps) -def open_trajectory_writers(output_dir, mesh, material, enabled, fmt="zarr"): +def open_trajectory_writers(output_dir, mesh, material, enabled, fmt="h5"): """Open requested trajectory stores. The public benchmark flag is ``--trajectory``. The old ``--h5`` spelling - remains as a backwards-compatible alias, but the default archived store is - Zarr. Use ``--trajectory_format h5`` or ``both`` only for explicit legacy - needs. + remains as a backwards-compatible alias. HDF5 is the default; choose + ``zarr`` or ``both`` explicitly when a directory-based store is required. """ if not enabled: return [] + if fmt not in ("h5", "zarr", "both"): + raise ValueError("trajectory format must be one of: h5, zarr, both") writers = [] if fmt in ("zarr", "both"): path = os.path.join(output_dir, "training_data.zarr") diff --git a/examples/quasistatic/miehe_tension/README.md b/examples/quasistatic/miehe_tension/README.md index 73f72295c..7dd1a9231 100644 --- a/examples/quasistatic/miehe_tension/README.md +++ b/examples/quasistatic/miehe_tension/README.md @@ -167,7 +167,7 @@ result = ( preconditioner="jacobi", backend="auto", fail_on_mechanics_nonconvergence=False) .outputs( - fields=[{"name": "trajectory", "every": 1, "format": "zarr"}], + fields=[{"name": "trajectory", "every": 1, "format": "h5"}], histories=[{"name": "reaction_force", "region": "bottom", "dof": "y"}], plots=True, gif=True, diff --git a/examples/quasistatic/miehe_tension/config.yaml b/examples/quasistatic/miehe_tension/config.yaml index 654ec207e..984262c54 100644 --- a/examples/quasistatic/miehe_tension/config.yaml +++ b/examples/quasistatic/miehe_tension/config.yaml @@ -91,7 +91,7 @@ output: output_dir: null h5: true trajectory: true - trajectory_format: zarr + trajectory_format: h5 h5_every: 1 plots: true profile: true diff --git a/examples/quasistatic/miehe_tension/run_fluent.py b/examples/quasistatic/miehe_tension/run_fluent.py index 7bab51e1a..45e945337 100644 --- a/examples/quasistatic/miehe_tension/run_fluent.py +++ b/examples/quasistatic/miehe_tension/run_fluent.py @@ -91,7 +91,7 @@ def build_problem(num_steps: int) -> phast.Problem: eta_residual=1.0e-07, ) .outputs( - fields=[{"name": "trajectory", "every": 1, "format": "zarr"}], + fields=[{"name": "trajectory", "every": 1, "format": "h5"}], histories=[{"name": "reaction_force", "region": "bottom", "dof": "y"}], plots=True, profile=True, diff --git a/examples/quasistatic/notched_holed_plate/config.yaml b/examples/quasistatic/notched_holed_plate/config.yaml index 6d5323a5b..cb99fbf54 100644 --- a/examples/quasistatic/notched_holed_plate/config.yaml +++ b/examples/quasistatic/notched_holed_plate/config.yaml @@ -187,7 +187,7 @@ output: output_dir: null h5: true trajectory: true - trajectory_format: zarr + trajectory_format: h5 h5_every: 5 gif: false gif_frames: 200 diff --git a/examples/quasistatic/notched_holed_plate/run_fluent.py b/examples/quasistatic/notched_holed_plate/run_fluent.py index c3e32bc69..ee7868da8 100644 --- a/examples/quasistatic/notched_holed_plate/run_fluent.py +++ b/examples/quasistatic/notched_holed_plate/run_fluent.py @@ -168,7 +168,7 @@ def build_problem(num_steps: int) -> phast.Problem: problem.config.output = OutputConfig( h5=True, trajectory=True, - trajectory_format="zarr", + trajectory_format="h5", h5_every=5, gif=False, gif_frames=200, diff --git a/examples/quasistatic/reproducibility_catalog.yaml b/examples/quasistatic/reproducibility_catalog.yaml index da63af87a..a4f102608 100644 --- a/examples/quasistatic/reproducibility_catalog.yaml +++ b/examples/quasistatic/reproducibility_catalog.yaml @@ -5,7 +5,7 @@ source: examples/quasistatic defaults: mode: direct_yaml working_dir: repository_root - trajectory_format: zarr + trajectory_format: h5 runs: - id: miehe_tension diff --git a/examples/standard_workflow/README.md b/examples/standard_workflow/README.md new file mode 100644 index 000000000..3be1dbbcc --- /dev/null +++ b/examples/standard_workflow/README.md @@ -0,0 +1,65 @@ +# One configuration sequence for a first simulation + +These small examples teach the same PhAST input structure with two analysis +choices. They exercise the installation and solution sequence; they are not +crack-growth benchmarks or a comparison of dynamic and quasi-static results. + +Install PhAST from the repository root with `python -m pip install -e .`. +The [installation guide](https://cems-lab.github.io/PhAST/install.html) explains +environment creation on Linux, macOS, and Windows. + +## Choose an analysis + +| Input | Physical approximation | Numerical solution | +| --- | --- | --- | +| [Quasi-static SENT](quasistatic_sent/config.yaml) | Inertia is neglected. | Alternate displacement equilibrium and an implicit damage solution within each load increment. | +| [Dynamic SENT](dynamic_sent/config.yaml) | Inertia is retained. | Explicit mechanical time integration and an implicit damage update. | + +SENT means single-edge-notched tension. Both inputs use the same ordered +configuration sections, explained in +[CONFIGURATION_STYLE.md](../../CONFIGURATION_STYLE.md). +Choose the closest physical example before changing parameters. Changing only +a solver label is not sufficient to convert a loading experiment into a +different analysis. + +## Check and run + +Run these commands from the PhAST repository root: + +```bash +# Describe the selected formulation without running a simulation. +python -m phast explain-config examples/standard_workflow/quasistatic_sent/config.yaml + +# Check whether the input is accepted by this execution interface. +python -m phast run examples/standard_workflow/quasistatic_sent/config.yaml --validate-only + +# Solve and keep the new result in its own directory. +python -m phast run examples/standard_workflow/quasistatic_sent/config.yaml --output_dir runs/first_quasistatic + +# The dynamic example uses exactly the same command structure. +python -m phast run examples/standard_workflow/dynamic_sent/config.yaml --output_dir runs/first_dynamic +``` + +Configuration validation is not a numerical convergence or experimental +validation test. Inspect the run log and recorded outputs after a solve. + +## Change one physical choice at a time + +Copy a configuration, give the copy a descriptive name, and choose a new output +directory. Keep units consistent when changing material or geometric values. +After changing geometry, update affected boundary and material regions and +inspect the new mesh. After changing the mesh or phase-field length, reassess +spatial resolution. A finer dynamic mesh may also require a smaller time step. + +For a complete retained crack-growth illustration, use the +[layered DCB example](../two_material_dcb_beta/README.md). DCB means +double-cantilever beam. Its README distinguishes the observed response from +unverified penetration, bypass, or interface-debonding claims. + +The [standard simulation tutorial](https://cems-lab.github.io/PhAST/tutorial/07_standard_simulation_workflow.html) +explains the input sections, result inspection, and controlled student +exercises. No custom solver loop is needed for either example. + +If a documented step fails, [open an issue](https://github.com/CEMS-Lab/PhAST/issues) +with the input, command, operating system, Python version, PhAST revision, +and complete error output. diff --git a/examples/standard_workflow/dynamic_sent/README.md b/examples/standard_workflow/dynamic_sent/README.md new file mode 100644 index 000000000..aea466d51 --- /dev/null +++ b/examples/standard_workflow/dynamic_sent/README.md @@ -0,0 +1,18 @@ +# Dynamic single-edge-notched tension: setup exercise + +This small input introduces the same configuration sequence with inertia, +explicit mechanical time integration, and an implicit damage update. +Its short duration checks execution; it does not establish a complete crack +trajectory or a mesh- and time-step-converged dynamic solution. + +From the repository root: + +```bash +python -m phast run examples/standard_workflow/dynamic_sent/config.yaml --validate-only +python -m phast run examples/standard_workflow/dynamic_sent/config.yaml --output_dir runs/first_dynamic +``` + +Edit [config.yaml](config.yaml), following the +[common instructions](../README.md). Density, loading time, mesh size, and +time-step stability all matter. Do not reuse a quasi-static load increment +as a physical time step without examining these choices. diff --git a/examples/standard_workflow/dynamic_sent/config.yaml b/examples/standard_workflow/dynamic_sent/config.yaml new file mode 100644 index 000000000..1c2f62401 --- /dev/null +++ b/examples/standard_workflow/dynamic_sent/config.yaml @@ -0,0 +1,84 @@ +# 1. Identify a short, editable single-edge-notched tension (SENT) calculation. +# Run from the repository root: python -m phast run examples/standard_workflow/dynamic_sent/config.yaml +# This is a setup exercise, not the B3 benchmark or evidence of crack growth. +schema_version: 2 +name: Educational dynamic SENT +reference: Small phase-field precrack variant with the public B3 opening constraints + +# 2. Generate an 8 by 8 grid, split into 128 linear triangles; no Gmsh needed. +# Coordinates are mm. The internal crack occupies x = 0..2 at y = 2 mm. +# The deliberately broad length scale gives h/l0 = 0.5 on this teaching mesh. +geometry: + type: rectangular_sent_liu_structured + units: mm + parameters: {W: 4.0, H: 4.0, a: 2.0, l0: 1.0, h_crack: 0.5} + +# 3. Name the full material domain and aliases for the generated mesh groups. +regions: + body: {kind: domain} + left_edge: {kind: node_set, from_mesh: left} + right_edge: {kind: node_set, from_mesh: right} + upper_edge: {kind: node_set, from_mesh: top} + lower_edge: {kind: node_set, from_mesh: bottom} + initial_crack: {kind: node_set, from_mesh: crack} + +# 4. Set a single brittle material: E in N/mm^2, Gc in N/mm, l0 in mm, +# rho in tonne/mm^3, and time in seconds. nu and eta_residual are dimensionless. +# Glass-like B3 constants are retained, but geometry and l0 are educational. +materials: + glass: + model: phase_field + parameters: {E: 32000.0, nu: 0.20, Gc: 0.003, l0: 1.0, rho: 2.45e-9, eta_residual: 1.0e-7, energy_split: spectral, pf_model: AT2, plane_stress: false} +assignments: + - {material: glass, region: body} + +# 5. Initialise damage and retain the pre-existing crack through a damage BC. +initial_conditions: + - {field: damage, region: initial_crack, value: 1.0} + +# 6. Prevent lateral displacement; open the upper and lower edges symmetrically. +# Prescribed values are mm, multiplied by the dimensionless loading ramp. +boundary_conditions: + - {name: restrain_left, type: fix, region: left_edge, dof: x} + - {name: restrain_right, type: fix, region: right_edge, dof: x} + - {name: open_upper, type: prescribe, region: upper_edge, dof: y, value: 2.0e-6} + - {name: open_lower, type: prescribe, region: lower_edge, dof: y, value: -2.0e-6} + - {name: retain_crack, type: pf_dirichlet, region: initial_crack, value: 1.0} + +# 7. Use four fixed time steps. dt and t_ramp are seconds, not load increments. +# Reassess the CFL limit when editing mesh/material data; this dt is conservative. +# For automatic CFL stepping, replace num_steps/dt with t_total and set dt_safety. +analysis_steps: + - name: opening + type: explicit + active_boundary_conditions: [restrain_left, restrain_right, open_upper, open_lower, retain_crack] + controls: {protocol: simple, num_steps: 4, dt: 1.0e-8, ramp_type: smooth_step, t_ramp: 2.0e-8} + +# 8. Select existing Velocity-Verlet mechanics and the classical AT2 damage solve. +# No quasi-static Newton backend, learned model, or three-dimensional route is used. +solver: + type: explicit + device: cpu + time_integrator: central_difference + damage_every: 1 + preconditioner: jacobi + bounds_method: projected_cg + damage_tol: 1.0e-8 + damage_max_iter: 500 + +# 9. Save one HDF5 trajectory plus the existing per-step CSV histories. +# Fields share trajectory cadence. Setup and final-damage images are automatic. +# The low load and short duration demonstrate execution, not crack propagation. +outputs: + directory: runs/standard_dynamic_sent + fields: + - {name: trajectory, format: h5, every: 1} + - {name: displacement, every: 1} + - {name: damage, every: 1} + - {name: velocity, every: 1} + history: + - {name: reaction_force, region: upper_edge, dof: y} + - {name: energy} + - {name: solver_telemetry} + - {name: timing_per_step} + visuals: {initial_conditions: true, damage_final: true} diff --git a/examples/standard_workflow/quasistatic_sent/README.md b/examples/standard_workflow/quasistatic_sent/README.md new file mode 100644 index 000000000..521163077 --- /dev/null +++ b/examples/standard_workflow/quasistatic_sent/README.md @@ -0,0 +1,17 @@ +# Quasi-static single-edge-notched tension: setup exercise + +This small input introduces the standard configuration sequence for a +quasi-static phase-field calculation. It neglects inertia and uses a staggered +displacement-damage solution. The short loading sequence is an execution +exercise, not a fracture-validation result. + +From the repository root: + +```bash +python -m phast run examples/standard_workflow/quasistatic_sent/config.yaml --validate-only +python -m phast run examples/standard_workflow/quasistatic_sent/config.yaml --output_dir runs/first_quasistatic +``` + +Edit [config.yaml](config.yaml), following the +[common instructions](../README.md). Use a new output directory for each +variation and keep the configuration with the resulting fields and histories. diff --git a/examples/standard_workflow/quasistatic_sent/config.yaml b/examples/standard_workflow/quasistatic_sent/config.yaml new file mode 100644 index 000000000..aba582444 --- /dev/null +++ b/examples/standard_workflow/quasistatic_sent/config.yaml @@ -0,0 +1,86 @@ +# 1. Identify a short, editable single-edge-notched tension (SENT) calculation. +# Run from the repository root: python -m phast run examples/standard_workflow/quasistatic_sent/config.yaml +# This is a setup exercise, not a benchmark or evidence of crack propagation. +schema_version: 2 +name: Educational quasi-static SENT +reference: Small phase-field precrack variant with symmetric displacement-controlled opening + +# 2. Generate an 8 by 8 grid, split into 128 linear triangles; no Gmsh needed. +# Coordinates are mm. The internal crack occupies x = 0..2 at y = 2 mm. +# The deliberately broad length scale gives h/l0 = 0.5 on this teaching mesh. +geometry: + type: rectangular_sent_liu_structured + units: mm + parameters: {W: 4.0, H: 4.0, a: 2.0, l0: 1.0, h_crack: 0.5} + +# 3. Name the full material domain and aliases for the generated mesh groups. +regions: + body: {kind: domain} + left_edge: {kind: node_set, from_mesh: left} + right_edge: {kind: node_set, from_mesh: right} + upper_edge: {kind: node_set, from_mesh: top} + lower_edge: {kind: node_set, from_mesh: bottom} + initial_crack: {kind: node_set, from_mesh: crack} + +# 4. Set a single brittle material: E in N/mm^2, Gc in N/mm, l0 in mm, +# rho in tonne/mm^3. Density is retained for shared input style, not QS inertia. +# The isotropic split follows the existing small-strain quasi-static pathway. +materials: + glass: + model: phase_field + parameters: {E: 32000.0, nu: 0.20, Gc: 0.003, l0: 1.0, rho: 2.45e-9, eta_residual: 1.0e-7, energy_split: isotropic, pf_model: AT2, plane_stress: false} +assignments: + - {material: glass, region: body} + +# 5. Initialise damage and retain the pre-existing crack through a damage BC. +initial_conditions: + - {field: damage, region: initial_crack, value: 1.0} + +# 6. Prevent lateral displacement; open the upper and lower edges symmetrically. +# Prescribed values are mm, multiplied by the dimensionless loading factor. +boundary_conditions: + - {name: restrain_left, type: fix, region: left_edge, dof: x} + - {name: restrain_right, type: fix, region: right_edge, dof: x} + - {name: open_upper, type: prescribe, region: upper_edge, dof: y, value: 2.0e-6} + - {name: open_lower, type: prescribe, region: lower_edge, dof: y, value: -2.0e-6} + - {name: retain_crack, type: pf_dirichlet, region: initial_crack, value: 1.0} + +# 7. Use four equilibrium increments at load factors 0.25, 0.50, 0.75, and 1. +# Here dt is a dimensionless load-factor increment, not a physical time step. +analysis_steps: + - name: opening + type: quasi_static + active_boundary_conditions: [restrain_left, restrain_right, open_upper, open_lower, retain_crack] + controls: {protocol: simple, num_steps: 4, dt: 0.25} + +# 8. Select existing staggered equilibrium/damage solves with SciPy mechanics. +# Tolerances control the existing solvers; no dynamics or learned model is used. +solver: + type: quasi_static + device: cpu + backend: scipy + preconditioner: jacobi + bounds_method: projected_cg + static_tol: 1.0e-8 + static_max_iter: 50 + stagger_tol: 1.0e-6 + max_stagger: 100 + damage_tol: 1.0e-8 + damage_max_iter: 500 + +# 9. Save one HDF5 trajectory plus the existing per-step CSV histories. +# Fields share trajectory cadence. Setup and final-damage images are automatic. +# The retained DCB example, rather than this low-load setup, demonstrates growth. +outputs: + directory: runs/standard_quasistatic_sent + fields: + - {name: trajectory, format: h5, every: 1} + - {name: displacement, every: 1} + - {name: damage, every: 1} + - {name: strain, every: 1} + history: + - {name: reaction_force, region: upper_edge, dof: y} + - {name: energy} + - {name: solver_telemetry} + - {name: timing_per_step} + visuals: {initial_conditions: true, damage_final: true} diff --git a/examples/two_material_dcb_beta/README.md b/examples/two_material_dcb_beta/README.md new file mode 100644 index 000000000..3a88454ec --- /dev/null +++ b/examples/two_material_dcb_beta/README.md @@ -0,0 +1,255 @@ +# DCB-Style Fracture With A Toughened Bulk Layer + +This beta teaching example uses the standard PhAST schema-v2 workflow. +Change `config.yaml` to define the geometry, materials, loading, solver, and +outputs; no problem-specific solver loop is required. + +Use the [standard simulation tutorial](../../docs/tutorial/07_standard_simulation_workflow.md) +for Python 3.10+ source installation on macOS/Linux or Windows, and follow +the [configuration style](../../CONFIGURATION_STYLE.md). The folder name is +historical: the input contains three bulk regions, not an independent +two-material interface law. + +## Run The Example + +From an installed PhAST source checkout: + +```bash +# Explain the input; schema-2 dispatch requires the combined CLI release check. +python -m phast explain-config examples/two_material_dcb_beta/config.yaml + +# Check the declarative problem before solving it. +python -m phast run examples/two_material_dcb_beta/config.yaml --validate-only + +# Run on the CPU and retain a separate result directory. +python -m phast run examples/two_material_dcb_beta/config.yaml \ + --output_dir runs/two_material_dcb +``` + +Choose a new output directory for a subsequent run. The trajectory writer +refuses to overwrite an existing `training_data.h5` file. + +Schema-2 explanation and new adapter checks are separate from the retained +results. Do not label the common command sequence verified until those checks +pass. Legacy `precheck --config` is not a universal schema-2 replacement. + +## Edit The Same Sections + +Use the order `schema_version`, `name`, `reference`, `geometry`, +`regions`, `materials`, `assignments`, `initial_conditions`, +`boundary_conditions`, `analysis_steps`, `solver`, `outputs`. + +| Edit | Dependency or effect | +|---|---| +| `geometry.parameters.length/height/origin` | Update clamp coordinates, loading bounds, both layer rectangles, and disk/crack positions. | +| `geometry.parameters.nx/ny` | Check non-empty selections and mesh resolution of the material boundary. | +| Disk centre/radius in `regions` | Change the circle and every `outside_circle` selector together; check clearance from outer regions. | +| `materials..parameters.E` | Changes stiffness and stress/energy redistribution, not toughness. | +| `materials..parameters.Gc` | Changes fracture resistance; hold `E`, mesh, geometry, loading, and tolerances fixed for a toughness study. | +| `open_upper.value` / `open_lower.value` | Check signs, total opening, and small-strain/rotation assumptions. | +| `analysis_steps[0].controls.number_of_steps` | Includes zero; cutbacks can add increments. It is not elapsed time or an iteration cap. | + +`initial_crack.thickness` is a node-selection distance, not a physical +opening. A mesh edit can leave a narrow selection empty. Material regions +select element centroids rather than generating conforming circular edges. +Keep shared `nu`, `l0`, Amor/AT2, plane-stress, and other common settings +consistent. Use positive `E` and `Gc` and only the initial/history fields +accepted by this adapter; the multi-material initial conditions are damage +constraints, not arbitrary initial fields. Dynamic multi-material execution +is outside this route. + +Quasi-static analysis omits inertia; its illustrative density is not dynamic +material data. Explicit dynamics additionally needs consistent density/time +and a CFL-limited integration step. Neither a smaller step nor a particular +`h/l0` is a universal validation criterion. + +## Physical Model + +The rectangular specimen is 6.0 mm long and 1.2 mm high. Opposite vertical +displacements open its upper and lower left-edge loading regions; the right +edge is clamped. A prescribed initial phase-field crack extends from +`x = 0` to `x = 1.5 mm` on the mid-plane. + +Three bulk regions share `E = 5000 MPa`, `nu = 0.30`, and +`l0 = 0.10 mm`, with plane stress and the Amor energy split: + +| Region | Geometry | Fracture toughness Gc [N/mm] | +|---|---|---| +| Material 1 | Fracture-resistant outer regions | 1.00 | +| Weak layer | `-0.30 <= y <= 0.30 mm`, excluding Material 2 | 0.04 | +| Material 2 | Circle centred at `(2.2, 0.0) mm`, radius `0.20 mm` | 0.12 | + +Material 2 is three times tougher than the weak layer, but less tough than +the outer regions. Equal elastic properties isolate a contrast in fracture +resistance; this is not a stiffness-inclusion example. The weak region +occupies half the specimen height and is a finite-thickness bulk material, +not a thin adhesive or a zero-thickness cohesive interface. + +The final upper and lower displacements are `+0.15 mm` and `-0.15 mm`. +The total opening is therefore `0.30 mm`. The configured 121 load levels +include zero and give 120 nominal increments, with automatic cutbacks if a +trial increment fails to converge. Load factor is not physical time. + +## Numerical Model + +The calculation uses T3 elements, small-strain mechanics, and bounded AT2 +phase-field damage. Each load increment alternates mechanical equilibrium +and damage solves; a final mechanical equilibrium solve follows the accepted +damage update. The solver checks the subproblems, damage increment, and +projected damage residual. + +The `160 x 48` mesh has a maximum triangle-edge length of approximately +`0.0451 mm`, below `l0 / 2 = 0.05 mm`. This is a resolution criterion, +not proof of mesh-independent forces or crack trajectories. Material +boundaries are represented by element-centroid assignments on a structured +mesh, rather than by a geometrically conforming circular mesh. + +The initial crack is maintained by a damage constraint. No damaged path is +prescribed through or around Material 2. Penetration, deflection, branching, +or arrest must be identified from the computed fields rather than assumed. + +## Standard Results + +Retained lightweight evidence is in [results/README.md](results/README.md). +It is not a new run of the documentation commands: + +![Retained final damage at 0.30 mm opening; no seed-connected crack enters the disk at damage at least 0.80.](results/damage_final.png) + +![Retained damage evolution over load factors zero to one, with material boundaries outlined.](results/damage_evolution.gif) + +The static image is the animation fallback. Neither penetration nor completed +bypass is demonstrated. These are qualitative layered-material results, +not calibrated inclusion-bypass predictions. The retained coarse tough-region +run did not write HDF5; the retained uniform-layer control did. Its stored +mesh supplies the original triangle connectivity for the comparison plots. +Both new coarse reproduction inputs request HDF5. + +A new run produces the following files. The checked-in results retain only +the compact subset described in [results/README.md](results/README.md): + +- `training_data.h5`: initial and accepted displacement, strain, stress, + damage, and history fields in float64, with mesh and material fields. +- `history.csv`: opening, reaction, connected crack front, and region damage. +- `solver_telemetry.csv` and `timing_per_step.csv`: convergence and timing. +- `final_fields.vtu`: final nodal and element fields for ParaView. +- `initial_conditions.png` and `material_fields.png`: inspectable model setup. +- `damage_final.png`, `displacement_final.png`, `strain_final.png`, and + `stress_final.png`: final fields with material-boundary outlines. +- `damage_evolution.gif`: crack evolution; grey outlines show material boundaries. +- `load_displacement.png` and `convergence_and_crack_front.png`: response histories. +- `summary.json` and run/visual manifests: numerical summary and provenance. + +Trajectory output is requested in the same configuration: + +```yaml +outputs: + fields: + - {name: trajectory, format: h5, every: 1} +``` + +This heterogeneous route currently writes HDF5 trajectories. Omitting +`format` selects HDF5; requesting an unsupported format raises an error. + +Reload fields with the standard PhAST result API: + +```python +import phast + +result = phast.load_result("runs/two_material_dcb") +damage = result.field("damage") # Final nodal damage +displacement = result.field("displacement") +strain = result.field("strain") # Element strain components +stress = result.field("stress") # Element stress components +print(result.field_names()) +``` + +The reported crack front is the furthest node with `d >= 0.80` connected +to the seeded crack through damaged mesh edges. A large maximum x-coordinate +alone does not establish traversal of the inclusion: inspect connectivity, +material membership, and the trajectory together. + +## Interpretation And Limitations + +This is a confined-layer DCB-style teaching model, not an ASTM D5528 test, +a pin-loaded specimen, a calibrated bimaterial benchmark, or a validated +crack-deflection prediction. The inclusion radius is only `2 l0`, and its +clearance from the fracture-resistant outer regions is `l0`. Confinement and +regularisation therefore influence the possible paths. + +Convergence of the algebraic solves does not establish physical validity or +mesh/load-step convergence. A quantitative study requires an independently +specified reference, mesh and increment sensitivity, and an assessment of +whether small strains and rotations remain appropriate. A matched control +is needed before attributing a measured resistance change solely to the +inclusion. + +## Reproduce The Separate Coarse Comparison + +Keep this folder's `config.yaml` at `160 x 48` for the fine reference. +Two complete compact model inputs are provided under `comparisons/`: + +- [tough_region.yaml](comparisons/tough_region.yaml): same physics/settings, + with `nx: 120` and `ny: 48`. +- [uniform_layer.yaml](comparisons/uniform_layer.yaml): that same coarse + input with only `materials.material_2.parameters.Gc` changed from + `0.12` to `0.04 N/mm`. + +The control retains the weak layer and resistant outer regions: it is not +a homogeneous specimen. Both files retain the reference metadata/default +output path; use the separate overrides below. This is model-data duplication, +not solver-code duplication; no new driver is required. + +```bash +python -m phast explain-config examples/two_material_dcb_beta/comparisons/tough_region.yaml +python -m phast run examples/two_material_dcb_beta/comparisons/tough_region.yaml --validate-only +python -m phast run examples/two_material_dcb_beta/comparisons/tough_region.yaml --output_dir runs/dcb_coarse_tough_region + +python -m phast explain-config examples/two_material_dcb_beta/comparisons/uniform_layer.yaml +python -m phast run examples/two_material_dcb_beta/comparisons/uniform_layer.yaml --validate-only +python -m phast run examples/two_material_dcb_beta/comparisons/uniform_layer.yaml --output_dir runs/dcb_coarse_uniform_layer +``` + +The retained fine run has 120 accepted increments, no cutbacks, maximum +projected damage residual `6.91e-6`, and final reaction `0.61495` in the +recorded unit-thickness convention. The separate coarse matched pair gives +`0.60938` versus `0.45847` reactions and `2.10` versus `2.40 mm` +connected fronts for tough disk versus control. Both fork early, so the +disk cannot be credited with causing initial branching. Cutbacks differ +despite matched solver settings. See the retained results for the full record; +these new comparison files have not been rerun in this documentation pass. + +## Replot Compact Retained Evidence + +This command only postprocesses stored comparison data; it does not rerun FEM: + +```bash +python examples/two_material_dcb_beta/compare_results.py --output-dir runs/dcb_comparison_replot +``` + +It reads `results/coarse_tough_history.csv`, +`results/uniform_layer_history.csv`, `results/matched_control_fields.csv.gz`, +`results/matched_control_elements.csv.gz`, and +`results/comparison_provenance.json`. It writes +`matched_control_comparison.png` and `matched_control_damage.png` to the +requested directory without raw HDF5. A separate executable replot check +regenerated both PNGs from 250532 bytes of compact data; it was not a FEM run. +Historical source identity is unknown where not recorded; a later public +fingerprint is not evidence of prior generation. Histories have different +accepted load grids, so compare at common opening rather than common row number. + +## Further Limitations And Help + +Earlier, thinner-layer parameter sets produced transverse arm failure or +partial penetration. They are not evidence of successful traversal and +should not be confused with this revised, layer-contained inclusion model. + +Independent stored-field checks found the fixed calculations numerically +acceptable; they are not an independent solver rerun or experimental +validation. Input-guard and publication checks remain separate. The historical +generating source fingerprint was not recorded at runtime; a later +public-availability fingerprint cannot establish historical source identity. + +[Open a GitHub issue](https://github.com/CEMS-Lab/PhAST/issues/new/choose) +if a configuration section, convergence message, output, or limitation is +unclear. Include the config, exact command, OS, Python/PhAST version, and +complete error output. diff --git a/examples/two_material_dcb_beta/compare_results.py b/examples/two_material_dcb_beta/compare_results.py new file mode 100644 index 000000000..a7edac300 --- /dev/null +++ b/examples/two_material_dcb_beta/compare_results.py @@ -0,0 +1,139 @@ +"""Replot retained DCB comparison data without running the FEM solver. + +The archived pair has a common mesh but different accepted load increments. +Each response is therefore plotted against its own opening displacement. +""" +from __future__ import annotations + +import argparse +import hashlib +import json +from pathlib import Path + +import matplotlib + +matplotlib.use("Agg") +import matplotlib.pyplot as plt +import matplotlib.tri as mtri +from matplotlib.patches import Circle +import numpy as np + + +def main() -> int: + """Check the compact data and write the two comparison figures.""" + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "--output-dir", type=Path, default=Path("runs/dcb_comparison_replot"), + help="New plot directory; the retained input data are not modified.", + ) + args = parser.parse_args() + data_dir = Path(__file__).resolve().parent / "results" + record = json.loads((data_dir / "comparison_provenance.json").read_text()) + for name, expected in record["files"].items(): + digest = hashlib.sha256((data_dir / name).read_bytes()).hexdigest() + if digest != expected["sha256"]: + raise ValueError(f"Retained comparison data changed: {name}") + + tough = np.genfromtxt( + data_dir / "coarse_tough_history.csv", delimiter=",", names=True, + ) + uniform = np.genfromtxt( + data_dir / "uniform_layer_history.csv", delimiter=",", names=True, + ) + fields = np.genfromtxt( + data_dir / "matched_control_fields.csv.gz", delimiter=",", names=True, + ) + elements = np.loadtxt( + data_dir / "matched_control_elements.csv.gz", + delimiter=",", skiprows=1, dtype=np.int64, + ) + for history in (tough, uniform): + for name in ("opening", "reaction_force", "connected_crack_front_x"): + if not np.isfinite(history[name]).all(): + raise ValueError(f"Non-finite retained history: {name}") + if np.any(np.diff(history["opening"]) < 0): + raise ValueError("Retained accepted openings are not monotonic.") + for name in fields.dtype.names or (): + if not np.isfinite(fields[name]).all(): + raise ValueError(f"Non-finite retained final field: {name}") + if not np.array_equal(fields["node"], np.arange(len(fields))): + raise ValueError("Final fields do not follow the stored node numbering.") + if elements.ndim != 2 or elements.shape[1] != 3: + raise ValueError("Expected the original three-node triangle connectivity.") + if elements.min() < 0 or elements.max() >= len(fields): + raise ValueError("Connectivity contains an out-of-range node index.") + for name in ("damage_tough", "damage_uniform"): + if np.any((fields[name] < 0) | (fields[name] > 1)): + raise ValueError(f"Retained damage is outside [0, 1]: {name}") + + args.output_dir.mkdir(parents=True, exist_ok=True) + plt.style.use("default") + plt.rcParams.update({ + "font.family": "serif", "mathtext.fontset": "stix", + "figure.facecolor": "white", "axes.facecolor": "white", + }) + labels = ("Tough circular region", "Uniform weak layer") + colours = ("#9f3b31", "#285f87") + styles = ("-", "--") + figure, axes = plt.subplots(1, 2, figsize=(11, 4), constrained_layout=True) + for history, label, colour, style in zip( + (tough, uniform), labels, colours, styles, + ): + axes[0].plot( + history["opening"], history["reaction_force"], + linestyle=style, color=colour, label=label, + ) + axes[1].plot( + history["opening"], history["connected_crack_front_x"], + linestyle=style, color=colour, label=label, + ) + axes[0].set_ylabel("Opening reaction per unit thickness [N/mm]") + axes[1].set_ylabel("Maximum connected x at d >= 0.80 [mm]") + axes[1].axhline(2.0, color="0.5", linestyle=":", linewidth=1) + axes[1].text(0.01, 2.02, "Left edge of circular region", fontsize=9) + for axis in axes: + axis.set_xlabel("Opening displacement [mm]") + axis.grid(alpha=0.2) + axis.legend(frameon=False) + figure.suptitle( + "Retained coarse-mesh comparison: identical prescribed loading, " + "separate accepted increments", + fontsize=11, + ) + figure.savefig(args.output_dir / "matched_control_comparison.png", dpi=160) + plt.close(figure) + + triangulation = mtri.Triangulation(fields["x_mm"], fields["y_mm"], elements) + figure, axes = plt.subplots(2, 1, figsize=(10, 5), constrained_layout=True) + for axis, name, label, history in zip( + axes, ("damage_tough", "damage_uniform"), labels, (tough, uniform), + ): + artist = axis.tripcolor( + triangulation, fields[name], shading="gouraud", + cmap="Reds", vmin=0, vmax=1, + ) + # Geometry belongs to the frozen comparison, not an edited new input. + axis.add_patch(Circle((2.2, 0), 0.2, fill=False, linestyle="--", color="0.25")) + axis.axhline(-0.3, color="0.6", linestyle=":", linewidth=0.8) + axis.axhline(0.3, color="0.6", linestyle=":", linewidth=0.8) + axis.set( + aspect="equal", xlabel="x [mm]", ylabel="y [mm]", + title=f"{label}; final opening {history['opening'][-1]:.2f} mm", + ) + figure.colorbar(artist, ax=axis, label="Damage d", shrink=0.8) + figure.suptitle( + "Final nodal damage on the original shared mesh; interpolated for display", + fontsize=11, + ) + figure.savefig(args.output_dir / "matched_control_damage.png", dpi=160) + plt.close(figure) + print(f"Replotted retained data in {args.output_dir}") + print( + "These figures show a qualitative confined-layer comparison. " + "They do not establish penetration, completed bypass, or physical validation." + ) + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/examples/two_material_dcb_beta/comparisons/tough_region.yaml b/examples/two_material_dcb_beta/comparisons/tough_region.yaml new file mode 100644 index 000000000..fb493797a --- /dev/null +++ b/examples/two_material_dcb_beta/comparisons/tough_region.yaml @@ -0,0 +1,109 @@ +# Complete coarse matched input: full reference physics/settings, nx reduced to 120. +# Use --output_dir runs/dcb_coarse_tough_region, not the inherited default. +# Standard order: CONFIGURATION_STYLE.md at the repository root. +# 1. Identity and evidence boundary; beta teaching input, not physical validation. +schema_version: 2 +name: DCB-style opening with a tough inclusion inside a weak bulk layer +reference: Qualitative confined-layer AT2 teaching model; not experimental calibration or a cohesive-interface model +# 2. Geometry [mm] and mesh: nx/ny count cells split into T3 triangles. +# Dimension changes require corresponding boundary/crack/material-selector edits. +geometry: + type: structured_rectangle + units: mm + parameters: {length: 6.0, height: 1.2, origin: [0.0, -0.6], nx: 120, ny: 48} +# 3. Materials select element centroids; constraints select nodes. +# Keep circle and all complementary outside_circle selectors consistent. +# Crack thickness is a selection distance, not a physical opening. +regions: + material_1_region: + kind: element_region + type: all_of + selectors: + - {type: outside_circle, center: [2.2, 0.0], radius: 0.20} + - type: not + selector: {type: rectangle, origin: [0.0, -0.30], size: [6.0, 0.60]} + weak_midline_region: + kind: element_region + type: all_of + selectors: + - {type: rectangle, origin: [0.0, -0.30], size: [6.0, 0.60]} + - {type: outside_circle, center: [2.2, 0.0], radius: 0.20} + material_2_region: {kind: element_region, type: circle, center: [2.2, 0.0], radius: 0.20} + initial_crack: {kind: node_region, type: line_segment, from: [0.0, 0.0], to: [1.5, 0.0], thickness: 0.012} + right_clamp: {kind: node_region, type: boundary, side: right, tolerance: 1.0e-8} + upper_load: {kind: node_region, type: boundary_segment, axis: x, value: 0.0, bounds: {y: [0.30, 0.60]}, tolerance: 1.0e-8} + lower_load: {kind: node_region, type: boundary_segment, axis: x, value: 0.0, bounds: {y: [-0.60, -0.30]}, tolerance: 1.0e-8} +# 4. E [MPa] is stiffness; Gc [N/mm] is fracture resistance; l0 [mm]. +# Equal E isolates toughness contrast. This route varies elementwise E/Gc only. +# Keep nu/l0/model/split/plane-stress and shared settings consistent. +# rho is illustrative: quasi-static equilibrium omits inertia. +materials: + material_1: + model: phase_field + parameters: {E: 5000.0, nu: 0.30, Gc: 1.0, l0: 0.10, rho: 1.0, eta_residual: 1.0e-6, energy_split: amor, pf_model: AT2, plane_stress: true} + weak_midline: + model: phase_field + parameters: {E: 5000.0, nu: 0.30, Gc: 0.04, l0: 0.10, rho: 1.0, eta_residual: 1.0e-6, energy_split: amor, pf_model: AT2, plane_stress: true} + material_2: + model: phase_field + parameters: {E: 5000.0, nu: 0.30, Gc: 0.12, l0: 0.10, rho: 1.0, eta_residual: 1.0e-6, energy_split: amor, pf_model: AT2, plane_stress: true} +# 5. Every element receives one material: no gaps or overlaps. +assignments: + - {material: material_1, region: material_1_region} + - {material: weak_midline, region: weak_midline_region} + - {material: material_2, region: material_2_region} +# 6. Prescribed damage values are maintained; no future crack path is imposed. +initial_conditions: + - {field: damage, region: initial_crack, value: 1.0} +# 7. Dirichlet conditions prescribe displacements [mm] or fix components. +boundary_conditions: + - {name: clamp_x, type: fix, region: right_clamp, dof: x} + - {name: clamp_y, type: fix, region: right_clamp, dof: y} + - {name: open_upper, type: prescribe, region: upper_load, dof: y, value: 0.15} + - {name: open_lower, type: prescribe, region: lower_load, dof: y, value: -0.15} +# 8. Quasi-static load levels, not physical time; the count includes zero. +analysis_steps: + - name: opening + type: quasi_static + active_boundary_conditions: [clamp_x, clamp_y, open_upper, open_lower] + # 121 levels include zero: 120 nominal increments before any cutbacks. + controls: {number_of_steps: 121} +# 9. CPU float64 staggered Amor AT2 controls. Iterations are not load steps. +# Algebraic convergence and h/l0 alone do not establish physical validation. +solver: + type: quasi_static + mechanics_backend: auto + mechanics_tolerance: 1.0e-9 + mechanics_relative_tolerance: 1.0e-8 + mechanics_max_iterations: 30 + damage_tolerance: 1.0e-8 + damage_max_iterations: 500 + damage_bounds_method: projected_cg + maximum_staggered_iterations: 500 + staggered_damage_tolerance: 1.0e-5 + projected_residual_tolerance: 1.0e-5 + damage_relaxation: 0.70 + automatic_cutback: true + minimum_load_increment: 0.00025 + maximum_cutbacks: 40 + crack_front_threshold: 0.80 +# 10. Output requests. Use a fresh directory for every comparison. +# HDF5 is the default when a trajectory is requested; keep raw stores local. +outputs: + directory: runs/two_material_dcb + fields: + - {name: trajectory, format: h5, every: 1} + - {name: displacement} + - {name: strain} + - {name: stress} + - {name: damage} + - {name: vtu} + history: + - {name: reaction_force, region: upper_load, dof: y} + - {name: max_damage} + - {name: solver_telemetry} + - {name: timing_per_step} + visuals: + initial_conditions: true + plots: true + animation: {field: damage} diff --git a/examples/two_material_dcb_beta/comparisons/uniform_layer.yaml b/examples/two_material_dcb_beta/comparisons/uniform_layer.yaml new file mode 100644 index 000000000..0aac79b3c --- /dev/null +++ b/examples/two_material_dcb_beta/comparisons/uniform_layer.yaml @@ -0,0 +1,110 @@ +# Complete coarse control: only disk Gc changes from 0.12 to layer Gc 0.04. +# The outer regions remain distinct; this is not a homogeneous whole specimen. +# Use --output_dir runs/dcb_coarse_uniform_layer, not the inherited default. +# Standard order: CONFIGURATION_STYLE.md at the repository root. +# 1. Identity and evidence boundary; beta teaching input, not physical validation. +schema_version: 2 +name: DCB-style opening with a tough inclusion inside a weak bulk layer +reference: Qualitative confined-layer AT2 teaching model; not experimental calibration or a cohesive-interface model +# 2. Geometry [mm] and mesh: nx/ny count cells split into T3 triangles. +# Dimension changes require corresponding boundary/crack/material-selector edits. +geometry: + type: structured_rectangle + units: mm + parameters: {length: 6.0, height: 1.2, origin: [0.0, -0.6], nx: 120, ny: 48} +# 3. Materials select element centroids; constraints select nodes. +# Keep circle and all complementary outside_circle selectors consistent. +# Crack thickness is a selection distance, not a physical opening. +regions: + material_1_region: + kind: element_region + type: all_of + selectors: + - {type: outside_circle, center: [2.2, 0.0], radius: 0.20} + - type: not + selector: {type: rectangle, origin: [0.0, -0.30], size: [6.0, 0.60]} + weak_midline_region: + kind: element_region + type: all_of + selectors: + - {type: rectangle, origin: [0.0, -0.30], size: [6.0, 0.60]} + - {type: outside_circle, center: [2.2, 0.0], radius: 0.20} + material_2_region: {kind: element_region, type: circle, center: [2.2, 0.0], radius: 0.20} + initial_crack: {kind: node_region, type: line_segment, from: [0.0, 0.0], to: [1.5, 0.0], thickness: 0.012} + right_clamp: {kind: node_region, type: boundary, side: right, tolerance: 1.0e-8} + upper_load: {kind: node_region, type: boundary_segment, axis: x, value: 0.0, bounds: {y: [0.30, 0.60]}, tolerance: 1.0e-8} + lower_load: {kind: node_region, type: boundary_segment, axis: x, value: 0.0, bounds: {y: [-0.60, -0.30]}, tolerance: 1.0e-8} +# 4. E [MPa] is stiffness; Gc [N/mm] is fracture resistance; l0 [mm]. +# Equal E isolates toughness contrast. This route varies elementwise E/Gc only. +# Keep nu/l0/model/split/plane-stress and shared settings consistent. +# rho is illustrative: quasi-static equilibrium omits inertia. +materials: + material_1: + model: phase_field + parameters: {E: 5000.0, nu: 0.30, Gc: 1.0, l0: 0.10, rho: 1.0, eta_residual: 1.0e-6, energy_split: amor, pf_model: AT2, plane_stress: true} + weak_midline: + model: phase_field + parameters: {E: 5000.0, nu: 0.30, Gc: 0.04, l0: 0.10, rho: 1.0, eta_residual: 1.0e-6, energy_split: amor, pf_model: AT2, plane_stress: true} + material_2: + model: phase_field + parameters: {E: 5000.0, nu: 0.30, Gc: 0.04, l0: 0.10, rho: 1.0, eta_residual: 1.0e-6, energy_split: amor, pf_model: AT2, plane_stress: true} +# 5. Every element receives one material: no gaps or overlaps. +assignments: + - {material: material_1, region: material_1_region} + - {material: weak_midline, region: weak_midline_region} + - {material: material_2, region: material_2_region} +# 6. Prescribed damage values are maintained; no future crack path is imposed. +initial_conditions: + - {field: damage, region: initial_crack, value: 1.0} +# 7. Dirichlet conditions prescribe displacements [mm] or fix components. +boundary_conditions: + - {name: clamp_x, type: fix, region: right_clamp, dof: x} + - {name: clamp_y, type: fix, region: right_clamp, dof: y} + - {name: open_upper, type: prescribe, region: upper_load, dof: y, value: 0.15} + - {name: open_lower, type: prescribe, region: lower_load, dof: y, value: -0.15} +# 8. Quasi-static load levels, not physical time; the count includes zero. +analysis_steps: + - name: opening + type: quasi_static + active_boundary_conditions: [clamp_x, clamp_y, open_upper, open_lower] + # 121 levels include zero: 120 nominal increments before any cutbacks. + controls: {number_of_steps: 121} +# 9. CPU float64 staggered Amor AT2 controls. Iterations are not load steps. +# Algebraic convergence and h/l0 alone do not establish physical validation. +solver: + type: quasi_static + mechanics_backend: auto + mechanics_tolerance: 1.0e-9 + mechanics_relative_tolerance: 1.0e-8 + mechanics_max_iterations: 30 + damage_tolerance: 1.0e-8 + damage_max_iterations: 500 + damage_bounds_method: projected_cg + maximum_staggered_iterations: 500 + staggered_damage_tolerance: 1.0e-5 + projected_residual_tolerance: 1.0e-5 + damage_relaxation: 0.70 + automatic_cutback: true + minimum_load_increment: 0.00025 + maximum_cutbacks: 40 + crack_front_threshold: 0.80 +# 10. Output requests. Use a fresh directory for every comparison. +# HDF5 is the default when a trajectory is requested; keep raw stores local. +outputs: + directory: runs/two_material_dcb + fields: + - {name: trajectory, format: h5, every: 1} + - {name: displacement} + - {name: strain} + - {name: stress} + - {name: damage} + - {name: vtu} + history: + - {name: reaction_force, region: upper_load, dof: y} + - {name: max_damage} + - {name: solver_telemetry} + - {name: timing_per_step} + visuals: + initial_conditions: true + plots: true + animation: {field: damage} diff --git a/examples/two_material_dcb_beta/config.yaml b/examples/two_material_dcb_beta/config.yaml new file mode 100644 index 000000000..475854972 --- /dev/null +++ b/examples/two_material_dcb_beta/config.yaml @@ -0,0 +1,107 @@ +# Standard order: CONFIGURATION_STYLE.md at the repository root. +# 1. Identity and evidence boundary; beta teaching input, not physical validation. +schema_version: 2 +name: DCB-style opening with a tough inclusion inside a weak bulk layer +reference: Qualitative confined-layer AT2 teaching model; not experimental calibration or a cohesive-interface model +# 2. Geometry [mm] and mesh: nx/ny count cells split into T3 triangles. +# Dimension changes require corresponding boundary/crack/material-selector edits. +geometry: + type: structured_rectangle + units: mm + parameters: {length: 6.0, height: 1.2, origin: [0.0, -0.6], nx: 160, ny: 48} +# 3. Materials select element centroids; constraints select nodes. +# Keep circle and all complementary outside_circle selectors consistent. +# Crack thickness is a selection distance, not a physical opening. +regions: + material_1_region: + kind: element_region + type: all_of + selectors: + - {type: outside_circle, center: [2.2, 0.0], radius: 0.20} + - type: not + selector: {type: rectangle, origin: [0.0, -0.30], size: [6.0, 0.60]} + weak_midline_region: + kind: element_region + type: all_of + selectors: + - {type: rectangle, origin: [0.0, -0.30], size: [6.0, 0.60]} + - {type: outside_circle, center: [2.2, 0.0], radius: 0.20} + material_2_region: {kind: element_region, type: circle, center: [2.2, 0.0], radius: 0.20} + initial_crack: {kind: node_region, type: line_segment, from: [0.0, 0.0], to: [1.5, 0.0], thickness: 0.012} + right_clamp: {kind: node_region, type: boundary, side: right, tolerance: 1.0e-8} + upper_load: {kind: node_region, type: boundary_segment, axis: x, value: 0.0, bounds: {y: [0.30, 0.60]}, tolerance: 1.0e-8} + lower_load: {kind: node_region, type: boundary_segment, axis: x, value: 0.0, bounds: {y: [-0.60, -0.30]}, tolerance: 1.0e-8} +# 4. E [MPa] is stiffness; Gc [N/mm] is fracture resistance; l0 [mm]. +# Equal E isolates toughness contrast. This route varies elementwise E/Gc only. +# Keep nu/l0/model/split/plane-stress and shared settings consistent. +# rho is illustrative: quasi-static equilibrium omits inertia. +materials: + material_1: + model: phase_field + parameters: {E: 5000.0, nu: 0.30, Gc: 1.0, l0: 0.10, rho: 1.0, eta_residual: 1.0e-6, energy_split: amor, pf_model: AT2, plane_stress: true} + weak_midline: + model: phase_field + parameters: {E: 5000.0, nu: 0.30, Gc: 0.04, l0: 0.10, rho: 1.0, eta_residual: 1.0e-6, energy_split: amor, pf_model: AT2, plane_stress: true} + material_2: + model: phase_field + parameters: {E: 5000.0, nu: 0.30, Gc: 0.12, l0: 0.10, rho: 1.0, eta_residual: 1.0e-6, energy_split: amor, pf_model: AT2, plane_stress: true} +# 5. Every element receives one material: no gaps or overlaps. +assignments: + - {material: material_1, region: material_1_region} + - {material: weak_midline, region: weak_midline_region} + - {material: material_2, region: material_2_region} +# 6. Prescribed damage values are maintained; no future crack path is imposed. +initial_conditions: + - {field: damage, region: initial_crack, value: 1.0} +# 7. Dirichlet conditions prescribe displacements [mm] or fix components. +boundary_conditions: + - {name: clamp_x, type: fix, region: right_clamp, dof: x} + - {name: clamp_y, type: fix, region: right_clamp, dof: y} + - {name: open_upper, type: prescribe, region: upper_load, dof: y, value: 0.15} + - {name: open_lower, type: prescribe, region: lower_load, dof: y, value: -0.15} +# 8. Quasi-static load levels, not physical time; the count includes zero. +analysis_steps: + - name: opening + type: quasi_static + active_boundary_conditions: [clamp_x, clamp_y, open_upper, open_lower] + # 121 levels include zero: 120 nominal increments before any cutbacks. + controls: {number_of_steps: 121} +# 9. CPU float64 staggered Amor AT2 controls. Iterations are not load steps. +# Algebraic convergence and h/l0 alone do not establish physical validation. +solver: + type: quasi_static + mechanics_backend: auto + mechanics_tolerance: 1.0e-9 + mechanics_relative_tolerance: 1.0e-8 + mechanics_max_iterations: 30 + damage_tolerance: 1.0e-8 + damage_max_iterations: 500 + damage_bounds_method: projected_cg + maximum_staggered_iterations: 500 + staggered_damage_tolerance: 1.0e-5 + projected_residual_tolerance: 1.0e-5 + damage_relaxation: 0.70 + automatic_cutback: true + minimum_load_increment: 0.00025 + maximum_cutbacks: 40 + crack_front_threshold: 0.80 +# 10. Output requests. Use a fresh directory for every comparison. +# HDF5 is the default when a trajectory is requested; keep raw stores local. +outputs: + directory: runs/two_material_dcb + fields: + - {name: trajectory, format: h5, every: 1} + - {name: displacement} + - {name: strain} + - {name: stress} + - {name: damage} + - {name: vtu} + history: + - {name: reaction_force, region: upper_load, dof: y} + - {name: max_damage} + - {name: solver_telemetry} + - {name: timing_per_step} + visuals: + initial_conditions: true + plots: true + animation: {field: damage} diff --git a/examples/two_material_dcb_beta/results/.gitattributes b/examples/two_material_dcb_beta/results/.gitattributes new file mode 100644 index 000000000..23d8b698a --- /dev/null +++ b/examples/two_material_dcb_beta/results/.gitattributes @@ -0,0 +1,2 @@ +# Preserve the recorded CSV checksums across platform checkout defaults. +*.csv text eol=lf diff --git a/examples/two_material_dcb_beta/results/README.md b/examples/two_material_dcb_beta/results/README.md new file mode 100644 index 000000000..8936a3afd --- /dev/null +++ b/examples/two_material_dcb_beta/results/README.md @@ -0,0 +1,167 @@ +# Recorded DCB-Style Teaching Calculation + +These retained figures and summaries describe the DCB model whose numerical +inputs are documented by the [schema-v2 configuration](../config.yaml). +The fine trajectory can be regenerated locally as HDF5; no large raw +trajectory is retained here. + +These are retained records, not a new calculation from this documentation +update. The [online tutorial](../../../docs/tutorial/07_standard_simulation_workflow.md) +embeds the compact figures directly from the repository; raw HDF5 is not a +public documentation dependency. The generating source fingerprint was not +recorded at runtime and remains unknown. A later public-availability +fingerprint does not establish which source generated historical outputs. + +## What The Calculation Demonstrates + +At a total opening of 0.30 mm, the seeded crack bifurcates within the weak +bulk layer and advances towards the circular region's flanks. The outer +fracture-resistant regions retain the load path. + +**Neither penetration through Material 2 nor completed bypass is demonstrated.** +No seed-connected path with `d >= 0.80` enters the circular region in the +recorded reference run. The fact that the front's x-coordinate overlaps the +circle's x-extent is not evidence of penetration. + +![Retained final damage at 0.30 mm opening, with a forked crack in the weak layer and no seed-connected disk entry at damage at least 0.80.](damage_final.png) + +![Retained damage evolution over load factors zero to one, ending at 0.30 mm total opening.](damage_evolution.gif) + +The static image is the animation fallback. The displayed progression is +quasi-static load factor, not physical time. + +## Numerical Evidence + +| Quantity | Recorded reference value | +|---|---| +| Structured mesh | 160 x 48 cells, split into T3 elements | +| Nominal accepted increments | 120, without cutbacks | +| Final total opening | 0.30 mm | +| Maximum projected damage residual | 6.91e-6 | +| Stored damage range | 0 to 1 | +| Detected damage/history decrease | None in the saved snapshots | +| Maximum triangle edge divided by l0 | 0.4507 | +| Final seed-connected front at d >= 0.80 | 2.0625 mm | +| Final seed-connected front at d >= 0.90 | 2.0625 mm | +| Final reaction, unit-thickness model | 0.61495 | +| Recorded CPU elapsed time | About 968 s; not a portable performance benchmark | + +The initial HDF5 frame contains the prescribed starting state. It is not +counted among the 120 converged load increments. + +The `120 x 48` calculation with the same physical parameters gives a final +front of 2.10 mm and a reaction of 0.60938. The reaction difference is about +0.9%; the front difference is one fine-mesh x interval. This is a two-mesh +comparison, not a formal convergence study. + +See [numerical_review.json](numerical_review.json) for the stored-field checks +and [summary.json](summary.json) for the solver-reported summary. + +## Matched Toughness Comparison + +A separate pair of calculations uses the same `120 x 48` mesh, loading, +constitutive parameters, solver tolerances, and nominal increments. The only +physical input changed is Material 2 toughness: + +| Quantity at 0.30 mm opening | Tough circular region | No-contrast control | +|---|---|---| +| Material 2 Gc [N/mm] | 0.12 | 0.04 | +| Weak-layer Gc [N/mm] | 0.04 | 0.04 | +| Connected front [mm] | 2.10 | 2.40 | +| Reaction, unit-thickness model | 0.60938 | 0.45847 | +| Accepted increments | 120 | 123 | +| Automatic cutbacks | 0 | 3 | + +The no-contrast control is uniform only within the weak layer; the outer +regions remain different bulk material. It is not a homogeneous specimen. +The same prescribed loading and nominal settings do not mean an identical +accepted load grid: the control has three cutbacks. The retained coarse +tough-region run did not write HDF5. The retained uniform-layer control did, +and its stored mesh supplies the original triangle connectivity for the +comparison plots. Both new reproduction inputs request HDF5; full trajectory +files are not included in these compact public results. + +In this discrete comparison, the tougher region reduces crack advance and +increases the final reaction by approximately 33%. Both cases bifurcate, so +the initial branching must not be attributed solely to the circular region. +The circular outline in the control identifies the same geometric footprint; +it is not a material contrast in that calculation. + +![Matched damage fields](matched_control_damage.png) + +![Matched response and crack-front histories](matched_control_comparison.png) + +The comparison input check and measured values are recorded in +[matched_control_review.json](matched_control_review.json). + +To reproduce the pair, use the complete +[tough-region input](../comparisons/tough_region.yaml) and +[uniform-layer input](../comparisons/uniform_layer.yaml). They preserve the +full DCB settings on `120 x 48` cells and differ only in disk `Gc`. +The fine [reference input](../config.yaml) remains `160 x 48`. + +```bash +python -m phast explain-config examples/two_material_dcb_beta/comparisons/tough_region.yaml +python -m phast run examples/two_material_dcb_beta/comparisons/tough_region.yaml --validate-only +python -m phast run examples/two_material_dcb_beta/comparisons/tough_region.yaml --output_dir runs/dcb_coarse_tough_region + +python -m phast explain-config examples/two_material_dcb_beta/comparisons/uniform_layer.yaml +python -m phast run examples/two_material_dcb_beta/comparisons/uniform_layer.yaml --validate-only +python -m phast run examples/two_material_dcb_beta/comparisons/uniform_layer.yaml --output_dir runs/dcb_coarse_uniform_layer +``` + +These files duplicate compact model data, not solver code; both use the +common runner and HDF5 output. Their new exact-command checks, including +schema-2 explanation, remain part of the combined release checks. The table +above records the existing runs, not a rerun of the newly named input files. +Use the explicit directories rather than their inherited output default. + +## Replot Compact Retained Evidence + +This command only postprocesses stored comparison data; it does not rerun FEM: + +```bash +python examples/two_material_dcb_beta/compare_results.py --output-dir runs/dcb_comparison_replot +``` + +It reads `coarse_tough_history.csv`, +`uniform_layer_history.csv`, `matched_control_fields.csv.gz`, +`matched_control_elements.csv.gz`, and +`comparison_provenance.json`. It writes +`matched_control_comparison.png` and `matched_control_damage.png` to the +requested directory without raw HDF5. A separate executable replot check +regenerated both PNGs from 250532 bytes of compact data; it was not a FEM run. +Historical source identity is unknown where not recorded; a later public +fingerprint is not evidence of prior generation. Histories have different +accepted load grids, so compare at common opening rather than common row number. + + +## Fields And Interpretation + +- [Displacement magnitude](displacement_final.png) +- [Strain tensor norm](strain_final.png) +- [Von Mises stress](stress_final.png) +- [Phase-field damage](damage_final.png) +- [Geometry and loading](initial_conditions.png) +- [Material properties](material_fields.png) +- [Convergence and connected crack advance](convergence_and_crack_front.png) + +Large strain values in the heavily damaged crack band represent the smeared +displacement jump and must not be interpreted as intact-material strains. +In the relatively intact outer regions, the final strain-norm maximum is +approximately 1.67%, and the 95th-percentile infinitesimal rotation is about +4.9 degrees. These values warrant retaining the small-strain/rotation +approximation caveat rather than claiming geometric-nonlinear validity. + +Independent stored-field review found the fixed calculations numerically +acceptable, with bounded, irreversible damage/history. Recomputing history +from final displacement gave maximum projected residuals of 6.97e-6 for the +fine case and 5.23e-6 for the control. These are separate final-state checks, +not replacements for the solver-recorded maxima over accepted increments. +The review was not an independent solver rerun or experimental validation; +input-guard checks and publication checks remain separate. + +The inclusion radius is `2 l0` and its clearance from the outer regions is +`l0`. Confinement, regularisation, the structured material-boundary +approximation, and load-increment sensitivity remain relevant. No experimental, +ASTM, interface-law, or material calibration claim is made. diff --git a/examples/two_material_dcb_beta/results/coarse_tough_history.csv b/examples/two_material_dcb_beta/results/coarse_tough_history.csv new file mode 100644 index 000000000..cede95acf --- /dev/null +++ b/examples/two_material_dcb_beta/results/coarse_tough_history.csv @@ -0,0 +1,121 @@ +accepted_step,attempt,load_factor,opening,reaction_force,maximum_damage,connected_crack_front_x,mechanics_iterations,mechanics_residual,damage_iterations,staggered_iterations,damage_increment,projected_damage_residual,cutbacks_so_far,wall_seconds,mean_damage_material_1,mean_damage_weak_midline,mean_damage_material_2 +1,1,0.008333333333333333,0.0025,0.5467058518220571,1.0,1.5,1,2.767929171799135e-14,30,26,9.292839206365144e-06,5.9490183593538526e-08,0,3.319690708000053,0.0003450881101986241,0.08294401767151116,0.0001581609717421036 +2,2,0.016666666666666666,0.005,0.505120713909225,1.0,1.5,1,6.171753089724826e-14,20,40,8.54109439907269e-06,6.514465874206399e-08,0,4.058930500001225,0.000366950111278062,0.08488991021589001,0.00015883321790180813 +3,3,0.025,0.0075,0.4222620410539321,1.0,1.5,1,9.853646291025202e-14,20,41,8.995478800510881e-06,7.459944817607422e-08,0,4.051571915999375,0.00038544724369670255,0.08654190293817747,0.0001621981996794159 +4,4,0.03333333333333333,0.01,0.3702649312006062,1.0,1.5,1,1.3464362567188815e-13,20,41,8.991561478044474e-06,7.91438170867631e-08,0,4.093663666999419,0.0004017889703738182,0.08794563394313226,0.0001755087514259916 +5,5,0.041666666666666664,0.012499999999999999,0.33796756323576516,1.0,1.5,1,1.7780545528688518e-13,10,41,9.285751564669376e-06,8.453610526176769e-08,0,3.980008458998782,0.00041711390343020883,0.08916533020370403,0.00021064609607497487 +6,6,0.05,0.015,0.32162553603579946,1.0,1.5,1,2.212993117751622e-13,10,38,9.16255632132934e-06,8.219220227340118e-08,0,3.193356915999175,0.00043240119388384394,0.09021261284888454,0.00027777510060251565 +7,7,0.058333333333333334,0.017499999999999998,0.31845541445610037,1.0,1.5,1,2.9606177248035966e-13,10,35,8.152468195410378e-06,7.531137928215581e-08,0,3.105962042000101,0.00044844169581888867,0.09110486905224033,0.00037915803356812104 +8,8,0.06666666666666667,0.02,0.32487781695519685,1.0,1.5,1,3.460248348454481e-13,10,32,9.984327777101676e-06,8.82030244953036e-08,0,2.6491266659995745,0.00046592643746637993,0.09188141391838607,0.0005110852246390698 +9,9,0.075,0.0225,0.3376513863978826,1.0,1.5,1,3.556528945327719e-13,10,28,9.581458343732585e-06,8.981803145333145e-08,0,2.2862685410000267,0.0004852893374085127,0.09258528532830011,0.0006689832473301348 +10,10,0.08333333333333333,0.024999999999999998,0.3545200870848956,1.0,1.5,1,3.6722679866772724e-13,10,26,8.428186129783022e-06,7.741502286093271e-08,0,2.2583482089994504,0.0005068058841950188,0.093250603542431,0.0008492786182202587 +11,11,0.09166666666666666,0.027499999999999997,0.37399365806969914,1.0,1.5,1,4.643573570633288e-13,10,25,7.517488727071253e-06,6.369267309402904e-08,0,2.080206291999275,0.0005304951076907685,0.09389999573755313,0.0010495865779627652 +12,12,0.1,0.03,0.3951027401934408,1.0,1.5,1,4.656529763806984e-13,10,22,8.879878880763137e-06,8.688572650933368e-08,0,1.8512678339993727,0.0005563864735179398,0.09454859381595626,0.0012683609100484347 +13,13,0.10833333333333334,0.0325,0.4172299300042056,1.0,1.5,1,5.21788878944333e-13,10,21,8.408164353879144e-06,7.585033993603996e-08,0,1.6902569589983614,0.0005844092682577498,0.09520511599273282,0.0015045147065559355 +14,14,0.11666666666666667,0.034999999999999996,0.43994830694460474,1.0,1.5,1,5.620760679903426e-13,10,19,9.238367135289138e-06,9.698701866622805e-08,0,1.4994763340000645,0.000614449332438772,0.09587685240881359,0.0017570022938493194 +15,15,0.125,0.0375,0.46296763505293026,1.0,1.5,1,6.268326754606758e-13,10,18,9.798709889152768e-06,8.843342816367006e-08,0,1.412624083000992,0.0006464625899909879,0.09656797637806766,0.0020249590481072827 +16,16,0.13333333333333333,0.04,0.4860585442511325,1.0,1.5,1,6.816462573451796e-13,10,18,6.88046923214003e-06,6.688237567248345e-08,0,1.4556126670013327,0.0006803999059982622,0.0972825721026186,0.0023076689913267786 +17,17,0.14166666666666666,0.042499999999999996,0.5090384247344427,1.0,1.5,1,6.924938510517529e-13,10,16,9.764247822174887e-06,1.0804743877379508e-07,0,1.3319504159990174,0.0007162220365117094,0.09802387173380567,0.002604405555109766 +18,18,0.15,0.045,0.5317427650409021,1.0,1.5,1,7.479756014860949e-13,10,16,6.774904559470052e-06,7.246298207308488e-08,0,1.3188122079991444,0.0007537723337682588,0.09879512240819394,0.0029147514411076627 +19,19,0.15833333333333333,0.047499999999999994,0.5540404687514606,1.0,1.5,1,7.824276247823022e-13,10,15,8.842876384029807e-06,8.484041709444501e-08,0,1.1668856249998498,0.000792940269960034,0.09959765844815902,0.003238122232559812 +20,20,0.16666666666666666,0.049999999999999996,0.5758076811976225,1.0,1.5,1,7.473404904354739e-13,10,15,7.686874624268647e-06,6.831402186296964e-08,0,1.1342817080003442,0.0008336290954827648,0.10043282529854221,0.00357419530589531 +21,21,0.175,0.0525,0.5969335997806307,1.0,1.5,1,5.575103616292594e-10,10,15,6.977578656641725e-06,6.690005196693938e-08,0,1.1868363749999844,0.0008757293941514092,0.10130194239110529,0.003922507474857902 +22,22,0.18333333333333332,0.05499999999999999,0.6173103082404244,1.0,1.5,1,8.665082356348086e-13,10,15,7.081044016699067e-06,6.837179158253326e-08,0,1.2820190000002185,0.0009191246905311915,0.10220660036557758,0.00428265136882096 +23,23,0.19166666666666665,0.057499999999999996,0.6368291128657193,1.0,1.5,1,9.364085789217837e-13,10,15,9.632608477749827e-06,7.457108407160629e-08,0,1.1744972920005239,0.0009636769767225096,0.10314776121712221,0.004654296428534489 +24,24,0.2,0.06,0.6553701978614256,1.0,1.5,1,1.0274342439832508e-12,10,16,9.64947703607777e-06,5.6265252713905145e-08,0,1.3279218329989817,0.001009233090313755,0.1041267561729056,0.005037324461598715 +25,25,0.20833333333333334,0.0625,0.6727983831712316,1.0,1.5,1,1.0610882910732721e-12,10,18,7.541475907646422e-06,3.316906223294058e-08,0,1.3102930829991237,0.001055610573072368,0.10514528651017863,0.005431760083610787 +26,26,0.21666666666666667,0.065,0.6889524317125102,1.0,1.5,1,1.0955092008993862e-12,10,20,7.3499114884301164e-06,2.4339721169108763e-08,0,1.4975762909998593,0.0011025981717285444,0.10620588212489368,0.005837920696514452 +27,27,0.225,0.0675,0.7036280227280356,1.0,1.5,1,1.1796494662666172e-12,10,22,9.871808195449638e-06,2.2527915144454624e-08,0,1.5626386250005453,0.0011499292456938193,0.10731163753321736,0.006256871628858457 +28,28,0.23333333333333334,0.06999999999999999,0.7165184562316465,1.0,1.5,1,1.2141806974046491e-12,10,27,9.046072368179559e-06,2.5850489877160543e-08,0,1.8479166249999253,0.0011972386175989982,0.10846814859530908,0.006691080947823839 +29,29,0.24166666666666667,0.0725,0.7271757280662765,1.0,1.5,1,1.2574063773524943e-12,1,34,9.072792464537294e-06,1.9402818165928197e-07,0,2.3678702079996583,0.0012441172872616618,0.10968202866315512,0.007142691353165698 +30,30,0.25,0.075,0.7341846650307811,1.0,1.5,1,1.3037743049391947e-12,1,71,8.76671440264154e-06,1.8037502626136286e-07,0,12.187994832998811,0.001289154802680088,0.11098837530966359,0.007633875880397949 +31,31,0.2583333333333333,0.07749999999999999,0.7035540843189492,1.0,1.55,1,1.3227191551767075e-12,1,159,2.3268853489577523e-06,3.698039598432068e-07,0,15.92002445900107,0.0013401552335224735,0.11373889109834613,0.008404871793269071 +32,32,0.26666666666666666,0.08,0.6745816770382399,1.0,1.55,1,1.4705987136815749e-12,1,145,9.992756488830246e-06,2.500724437487327e-07,0,10.62893350000013,0.001396571517528884,0.11603894387791308,0.00890002778184045 +33,33,0.275,0.0825,0.6003439887729758,1.0,1.6,1,1.3725350857227422e-12,1,116,1.5264343973253602e-06,2.6202804977344674e-07,0,10.233872499999052,0.0015049313164615412,0.11954849510326244,0.009423336937531815 +34,34,0.2833333333333333,0.08499999999999999,0.5894049057021435,1.0,1.6,1,1.4845247170641e-12,4,60,7.977666547587248e-06,4.911006950695032e-07,0,4.726975333000155,0.0015587389427106607,0.12060415534561963,0.00969094263602635 +35,35,0.2916666666666667,0.08750000000000001,0.5638913073241498,1.0,1.6500000000000001,1,1.6046201553986494e-12,1,112,2.425669464845015e-06,4.823619040167371e-07,0,8.662341041999753,0.0016319171038219524,0.12215084594025073,0.010138003586304243 +36,36,0.3,0.09,0.5596467939178257,1.0,1.6500000000000001,1,1.610528905034188e-12,1,50,4.389955951755731e-06,3.80409790978406e-07,0,4.042405124999277,0.0016819197202599472,0.12289218956158365,0.010466073511402225 +37,37,0.30833333333333335,0.0925,0.5602057401662583,1.0,1.6500000000000001,1,1.593498050187334e-12,1,46,8.32644188208942e-06,2.563085509041385e-07,0,3.9174842089996673,0.0017276587442716321,0.123454778458616,0.010785984667556236 +38,38,0.31666666666666665,0.09499999999999999,0.5600158424098411,1.0,1.6500000000000001,1,1.5890260674690344e-12,10,79,9.69164105169007e-06,5.424254776419113e-08,0,5.37177304099896,0.0017754470108236524,0.12404862171646099,0.011158562594977267 +39,39,0.325,0.0975,0.5487908839596777,1.0,1.7000000000000002,1,1.663230815064799e-12,1,88,2.096711410048968e-07,6.435844674725077e-07,0,6.895170290999886,0.0018408077628954541,0.12497265153222775,0.011635756849999776 +40,40,0.3333333333333333,0.09999999999999999,0.5490820258065212,1.0,1.7000000000000002,1,1.7847294652093319e-12,10,55,9.444297146998792e-06,6.333055036639168e-08,0,4.030068124999161,0.0018899828478962535,0.12551548094723913,0.01205880297746324 +41,41,0.3416666666666667,0.1025,0.5520486383955961,1.0,1.7000000000000002,1,1.806359797292971e-12,10,52,8.959031266186912e-06,4.446195599194791e-08,0,3.630728750000344,0.0019360056911190233,0.1259773481728588,0.012483873890151726 +42,42,0.35,0.105,0.5535452439619644,1.0,1.7000000000000002,1,1.842921286759054e-12,10,82,9.560361648008886e-06,5.515110984219418e-08,0,5.29365583300023,0.001984848526293815,0.12650269141513917,0.012971827206065788 +43,43,0.35833333333333334,0.1075,0.5470849761690969,1.0,1.75,1,1.934495486002014e-12,10,114,9.54346589499e-06,8.685532327731837e-08,0,7.876221458998771,0.0020482946822277487,0.12727273927420993,0.013613069083262024 +44,44,0.36666666666666664,0.10999999999999999,0.5471451809706628,1.0,1.75,1,1.8636867733308318e-12,1,57,9.940481187409311e-06,4.5124458898291014e-07,0,3.9936506249996455,0.0021003918697049023,0.12781288803003232,0.014176684260231104 +45,45,0.375,0.11249999999999999,0.5504006186820899,1.0,1.75,1,2.0837750851344204e-12,1,61,9.615435776155756e-06,3.314094610044438e-07,0,4.295204457999716,0.0021486123324071793,0.12825555306321013,0.014710145153717335 +46,46,0.3833333333333333,0.11499999999999999,0.5539552664355337,1.0,1.75,1,1.9952500039743165e-12,1,38,3.5026809830362993e-07,7.585383882324423e-07,0,2.8663937080000323,0.0021979429677075773,0.12869283506327442,0.015251977855464975 +47,47,0.39166666666666666,0.1175,0.5560819752068211,1.0,1.75,1,2.0594563949172225e-12,2,70,9.938301272605088e-06,7.435384681911406e-08,0,4.52740191599878,0.0022514532171132367,0.12916754970842684,0.01582819734396672 +48,48,0.4,0.12,0.5526287261079521,1.0,1.8,1,2.1526149653625907e-12,1,131,9.811566599848831e-06,3.565141926003851e-07,0,8.090645416999905,0.002316479098003782,0.12978243746441342,0.01653088638483098 +49,49,0.4083333333333333,0.1225,0.5514593031637082,1.0,1.8,1,2.217916068747788e-12,1,67,8.673658851043875e-06,4.581288370583193e-07,0,4.8732019160015625,0.0023790627161216025,0.13037895257364915,0.01724127217174022 +50,50,0.4166666666666667,0.125,0.5541552551427087,1.0,1.8,1,2.481990117884847e-12,1,59,9.751081207820533e-06,3.998826719567327e-07,0,4.151388709000457,0.0024362031897025935,0.13094513968623855,0.01788555816758818 +51,51,0.425,0.1275,0.5575496033670866,1.0,1.8,1,2.467548237380406e-12,10,52,9.17703894798283e-06,4.667314276729506e-08,0,3.7278285000011238,0.002492847084563648,0.1315255772783348,0.01856454712526602 +52,52,0.43333333333333335,0.13,0.560348369834366,1.0,1.8,1,2.776175781354119e-12,1,48,1.2597466958474968e-07,1.0193507617630576e-06,0,3.330173250000371,0.002549707429303008,0.13214570297167647,0.01928365943885986 +53,53,0.44166666666666665,0.13249999999999998,0.5476749521294626,1.0,1.85,1,2.7337133560037116e-12,1,164,9.931334608359599e-06,1.1977990687327134e-06,0,16.45187666700076,0.0026384078654573817,0.13319172966865067,0.021076121788518257 +54,54,0.45,0.135,0.5475211709193214,1.0,1.85,1,2.7985738774071268e-12,1,89,9.55959084236735e-06,3.515397720473684e-07,0,5.618150000000242,0.002696300368794903,0.13377835163920854,0.02214453928584285 +55,55,0.4583333333333333,0.13749999999999998,0.5505791173558561,1.0,1.85,1,2.766392171452376e-12,1,39,5.0210682280837915e-06,7.793876196371397e-07,0,2.8076795829983894,0.0027496277749016872,0.13437886537495014,0.02296617131208513 +56,56,0.4666666666666667,0.13999999999999999,0.553781225508019,1.0,1.85,1,2.805271397259925e-12,1,61,9.945335143646261e-06,2.555603578753389e-07,0,3.9428802500005986,0.002802823951233395,0.13500511385804462,0.02378667218279666 +57,57,0.475,0.1425,0.5565751995479015,1.0,1.85,1,2.897801087773775e-12,1,66,9.883339191829599e-06,3.7233760803565994e-07,0,4.134221290998539,0.002856050389241213,0.13567973216082782,0.024614688248382356 +58,58,0.48333333333333334,0.145,0.5565988980106324,1.0,1.85,1,2.649564695438626e-12,1,462,9.998634861285716e-06,2.56104928666903e-07,0,24.109029084000213,0.0029128142811354948,0.13648568833823008,0.02579465369129072 +59,59,0.49166666666666664,0.1475,0.5420993666162471,1.0,1.9000000000000001,1,3.02493606699938e-12,1,91,2.238723206815507e-09,2.669279958698867e-06,0,9.255233083000348,0.003011939216612131,0.13758647645764566,0.028853627353347684 +60,60,0.5,0.15,0.5446807999814021,1.0,1.9000000000000001,1,2.9086318310364726e-12,1,79,9.871908029146503e-06,1.923092732327434e-07,0,4.908165042001201,0.0030583498972172594,0.138145460621629,0.029850004406916198 +61,61,0.5083333333333333,0.1525,0.5122112217993702,1.0,1.9000000000000001,1,3.09721038652367e-12,1,150,7.338790880662138e-06,4.752844198170148e-07,0,32.577368000000206,0.003349416243752935,0.14337813053009382,0.029993961007747476 +62,62,0.5166666666666666,0.15499999999999997,0.5179340465956523,1.0,1.9000000000000001,1,3.1454282578327776e-12,1,35,9.28298325286736e-06,5.196687395839315e-07,0,2.408049125000616,0.003386345011971191,0.14370766832110726,0.030012595204775724 +63,63,0.525,0.1575,0.5236921331510423,1.0,1.9000000000000001,1,3.0014483437343195e-12,1,92,9.904707987451467e-06,3.097988807466707e-07,0,5.347506082998734,0.003423543323917197,0.1440454884348643,0.030038094736253417 +64,64,0.5333333333333333,0.16,0.5288082636963128,1.0,1.9000000000000001,1,3.0807889962909024e-12,1,101,9.946122904502808e-06,4.588330246863145e-07,0,6.204828334000922,0.0034649634959711064,0.14446331762558773,0.030074277459797436 +65,65,0.5416666666666666,0.16249999999999998,0.5335333013292511,1.0,1.9000000000000001,1,3.1386680052162854e-12,1,118,9.618682385914568e-06,3.7894418676928535e-07,0,7.214985791999425,0.003510535503614221,0.14491597824959637,0.030116823891269767 +66,66,0.55,0.165,0.5386584298496363,1.0,1.9000000000000001,1,3.0384721522906838e-12,1,82,9.753364230702388e-06,4.6229886985628237e-07,0,5.2267915419997735,0.0035535780353269718,0.14531465998032728,0.03015964070362242 +67,67,0.5583333333333333,0.1675,0.5444785743429372,1.0,1.9000000000000001,1,3.0648761303082057e-12,1,36,4.658476715491133e-09,1.172048573337052e-06,0,2.861973458000648,0.00359147231147974,0.1456316135184153,0.03020014911885417 +68,68,0.5666666666666667,0.16999999999999998,0.5499304657603513,1.0,1.9000000000000001,1,3.2834020883389598e-12,1,89,9.635765330751056e-06,3.855418608424545e-07,0,5.829493166000248,0.0036363491103053934,0.14596947142604888,0.030266084772089398 +69,69,0.575,0.1725,0.5545230556939533,1.0,1.9000000000000001,1,3.2099925529939625e-12,1,66,9.331524565059368e-06,4.784332489446322e-07,0,4.713937625001563,0.0036872633702020514,0.1463370676849561,0.030410101935224566 +70,70,0.5833333333333334,0.17500000000000002,0.5578829282117039,1.0,1.9000000000000001,1,3.2294025584288253e-12,1,162,9.832478622850971e-06,3.374634195997528e-07,0,9.598484000000099,0.0037438848532802054,0.14680173182424555,0.030649180609470947 +71,71,0.5916666666666667,0.1775,0.5604208801074277,1.0,1.9000000000000001,1,3.304970509756317e-12,1,105,9.001524921226078e-06,4.681097015300827e-07,0,7.337247875000685,0.0038053350433962393,0.1473555174941762,0.030943364994636114 +72,72,0.6,0.18,0.5631643179506248,1.0,1.9000000000000001,1,3.2133380895429853e-12,1,43,5.9385909026987704e-06,1.6599072890401134e-06,0,3.014706792000652,0.0038632002869615763,0.14780438583696554,0.031329949577992795 +73,73,0.6083333333333333,0.18249999999999997,0.5659268062002833,1.0,1.9000000000000001,1,3.1609667079105606e-12,1,102,9.58095292846739e-06,4.2298444370900937e-07,0,6.592270833998555,0.0039223352633423695,0.14824993517381918,0.03174587266967416 +74,74,0.6166666666666667,0.185,0.5685419198072847,1.0,1.9000000000000001,1,3.3007260191684853e-12,1,46,1.0080426550151955e-06,6.625148290747044e-07,0,3.4506460419997893,0.00398175701169486,0.14867210658755894,0.03222959621403681 +75,75,0.625,0.1875,0.5709434252688925,1.0,1.9000000000000001,1,3.4200725938233594e-12,1,81,1.7126958296032058e-08,6.935692429792663e-07,0,4.938295500000095,0.004042218703892738,0.1491048480348766,0.032771152681841456 +76,76,0.6333333333333333,0.18999999999999997,0.5729727600320522,1.0,1.9000000000000001,1,3.2733582072843834e-12,1,74,4.1904900083267194e-07,6.067082600362322e-07,0,5.176444458998958,0.004102911937120561,0.14955830205524104,0.03341333500271897 +77,77,0.6416666666666666,0.19249999999999998,0.5580737212821928,1.0,1.9500000000000002,1,3.2788620358244128e-12,2,139,6.987195721452899e-06,2.930970388441423e-06,0,15.554327667001417,0.004199243539726701,0.15054587932170785,0.03727901970339085 +78,78,0.65,0.195,0.5598423584112697,1.0,1.9500000000000002,1,3.5258150493826886e-12,1,42,1.1123376458810341e-06,1.5063039451590488e-06,0,2.970456708000711,0.00424607750664707,0.1508523443254257,0.03836683116402072 +79,79,0.6583333333333333,0.19749999999999998,0.5618743832146078,1.0,1.9500000000000002,1,3.2882353332121743e-12,1,33,6.889592678471779e-06,2.2104478378422165e-06,0,2.3906400420000864,0.004303727836274187,0.15126351793166848,0.03917648593781089 +80,80,0.6666666666666666,0.19999999999999998,0.5638285697935205,1.0,1.9500000000000002,1,3.446651979321349e-12,1,43,7.588356609744551e-10,1.9753383132242036e-06,0,3.2187195839997003,0.0043648821783173735,0.1517051070773386,0.03989594644998484 +81,81,0.675,0.2025,0.5657039449109611,1.0,1.9500000000000002,0,3.6116305754792982e-12,1,36,2.2071233729548112e-13,1.6631326760940162e-06,0,3.0836545000001934,0.004427105111457869,0.15213664681451952,0.040580374175972586 +82,82,0.6833333333333333,0.205,0.5671877134001893,1.0,1.9500000000000002,1,3.597122225986034e-12,1,35,5.93420617267526e-06,1.7910447507544364e-06,0,2.5493267080000805,0.004489697404070516,0.15256583656640677,0.04132394038206184 +83,83,0.6916666666666667,0.2075,0.5676932327834372,1.0,1.9500000000000002,1,4.009497394426922e-12,12,69,8.507774084343112e-06,1.944582959715474e-06,0,5.413732375000109,0.004556743046218927,0.1530701117800767,0.042201508081674194 +84,84,0.7,0.21,0.5685819587052945,1.0,1.9500000000000002,1,3.7306095872088015e-12,1,170,7.129055441756904e-06,2.41114331964859e-06,0,12.273065792000125,0.004643444466510336,0.15397221694573637,0.042682754996410444 +85,85,0.7083333333333334,0.2125,0.5693610008394956,1.0,1.9500000000000002,1,3.806853055890881e-12,1,61,5.104941373734739e-06,1.9929844560402643e-06,0,4.5002715829996305,0.004711679026720814,0.15453690876543244,0.04342765070743632 +86,86,0.7166666666666667,0.215,0.5703770996729471,1.0,2.0,1,3.96005913295306e-12,1,48,4.0284199431805945e-06,2.2061657781735633e-06,0,3.568860625000525,0.004775498578568084,0.15502118814913193,0.04425499003383057 +87,87,0.725,0.2175,0.5715727312621122,1.0,2.0,1,3.894065060559963e-12,1,103,9.079730235228567e-06,2.0505183266159716e-06,0,7.064316709000195,0.004844774895778301,0.15560972831842126,0.04510206705717091 +88,88,0.7333333333333333,0.21999999999999997,0.5729718293768554,1.0,2.0,1,4.083298578687893e-12,1,174,3.587954962247508e-06,1.4613281497957665e-06,0,11.796924415999456,0.004928536980252721,0.15650577534131282,0.04578133414981149 +89,89,0.7416666666666667,0.2225,0.5747095247447216,1.0,2.0,1,3.834438444629288e-12,1,49,9.390396231934162e-06,3.7446799119808527e-06,0,3.969712250000157,0.0049921587208303034,0.15700264447874476,0.04658091551151464 +90,90,0.75,0.22499999999999998,0.5766916678276355,1.0,2.0,1,4.23026621440176e-12,2,62,5.300261530005734e-06,2.964076745463548e-06,0,4.303243667000061,0.005054396256637677,0.15748760139331322,0.04743527423716315 +91,91,0.7583333333333333,0.22749999999999998,0.5783880878069451,1.0,2.0,1,4.12804418775596e-12,1,156,3.5165337599618596e-06,2.239237331657165e-06,0,10.64950033399873,0.005133777974253328,0.15828465648696538,0.048374206981940816 +92,92,0.7666666666666666,0.22999999999999998,0.5801933984659762,1.0,2.0,1,4.4615639145668764e-12,1,153,7.386022134681092e-06,7.871854129752609e-07,0,10.258090875000562,0.00521070996363017,0.15901559917882874,0.0494006751210179 +93,93,0.775,0.23249999999999998,0.5822886940936323,1.0,2.0,1,4.279225016794655e-12,1,49,2.6316871027942668e-06,3.9281926893994235e-06,0,3.708273416999873,0.005272060386419037,0.15944780297390576,0.05037037013817366 +94,94,0.7833333333333333,0.235,0.5843457611264068,1.0,2.0,1,4.440276000212027e-12,1,111,2.0733724515054064e-07,1.5706208941305977e-06,0,7.30614766600047,0.005338733182531676,0.15998448836274012,0.05148601356866564 +95,95,0.7916666666666666,0.2375,0.5858709828114985,1.0,2.0,1,4.816767692218426e-12,2,122,4.738601663722974e-06,4.167975134094365e-06,0,9.330524416998742,0.005422183438354911,0.16082173785961365,0.052971952274717675 +96,96,0.8,0.24,0.5880198016222311,1.0,2.0,1,4.7655511929223615e-12,1,65,2.779132324270961e-07,3.6384325979854637e-06,0,4.924106458000097,0.0054884692285232526,0.16133488788644118,0.05424648797935087 +97,97,0.8083333333333333,0.2425,0.5900633337422735,1.0,2.0,1,4.7373527064706225e-12,1,111,2.8932666221725967e-06,1.3982133319628831e-06,0,7.299333458000547,0.005550868233642668,0.16177257020098512,0.05555095483314328 +98,98,0.8166666666666667,0.245,0.5917830673874646,1.0,2.0,1,4.540921559665766e-12,1,91,5.283325789195992e-06,1.515381457387055e-06,0,6.490845750000517,0.005615103748159666,0.16224842827464428,0.057056009252388934 +99,99,0.825,0.24749999999999997,0.5934258517913271,1.0,2.0,1,4.720571566349393e-12,1,339,9.898527197793605e-06,3.153139880201811e-07,0,20.451530083000762,0.0056980254400903875,0.16301974712172587,0.05919734224585201 +100,100,0.8333333333333334,0.25,0.5952147189009664,1.0,2.0,1,4.7919077463768405e-12,1,153,6.520083432159929e-06,2.5904058980887e-07,0,9.302394250000361,0.005761321900253632,0.1634622128753949,0.060848597555556924 +101,101,0.8416666666666667,0.2525,0.5929165766453486,1.0,2.0,1,4.9733891029441765e-12,1,150,6.234740708377373e-06,4.976336772275283e-06,0,9.13163537500077,0.005829598605060293,0.1638877607495111,0.06309124888262804 +102,102,0.85,0.255,0.5875776738059676,1.0,2.0500000000000003,1,4.990772205227142e-12,1,251,9.926272171445483e-06,3.9504165696600205e-07,0,15.295509999999922,0.00590741515616532,0.16430586841043318,0.06584594054022275 +103,103,0.8583333333333333,0.25749999999999995,0.5889370853847085,1.0,2.0500000000000003,1,4.7180821632203225e-12,1,114,9.904374187463816e-06,3.532574382124863e-07,0,6.94898029199976,0.005963442396674367,0.16464676072508247,0.06745966801641662 +104,104,0.8666666666666667,0.26,0.5909343362611041,1.0,2.0500000000000003,1,4.989820548205603e-12,1,116,9.919431150251512e-06,3.6932227269801223e-07,0,6.990330667000308,0.00601990067923276,0.16500520245669173,0.06911243781493215 +105,105,0.875,0.2625,0.5930591382153558,1.0,2.0500000000000003,1,5.355200942668775e-12,1,273,2.712215472100432e-06,8.564323021442027e-07,0,16.351916707999408,0.0060833991634545006,0.16548167233392608,0.07115535060856233 +106,106,0.8833333333333333,0.26499999999999996,0.5951931693158985,1.0,2.0500000000000003,1,5.1073483889853946e-12,1,160,6.121909466472175e-06,5.916418930242834e-07,0,10.121496167001169,0.006150272639304313,0.16598480852633393,0.07346646822375635 +107,107,0.8916666666666666,0.26749999999999996,0.5975497116396827,1.0,2.0500000000000003,1,5.327232197536682e-12,1,185,9.89230482539849e-06,3.827846280848868e-07,0,10.52241233299901,0.006207730559731539,0.16632280484499842,0.07526426743128838 +108,108,0.9,0.27,0.5999837011548174,1.0,2.0500000000000003,1,5.3966823505292014e-12,1,104,9.580972519684927e-06,5.074513349486495e-07,0,6.738146165998842,0.006265493944230302,0.1666110771848846,0.07689473985340738 +109,109,0.9083333333333333,0.27249999999999996,0.6024806357980769,1.0,2.0500000000000003,1,5.746339834119976e-12,1,112,9.728585012469537e-06,5.144676107886206e-07,0,7.18426937500044,0.006322767132034707,0.16688432570554101,0.07851266737247833 +110,110,0.9166666666666666,0.27499999999999997,0.6049719643998659,1.0,2.0500000000000003,1,5.324196104061508e-12,1,86,9.689518997935131e-06,5.700568564415143e-07,0,5.427605541999583,0.00638023041449962,0.1671582071730285,0.08019938252976265 +111,111,0.9249999999999999,0.27749999999999997,0.6073878720956813,1.0,2.0500000000000003,1,5.921855620738003e-12,1,156,1.4845021101272948e-07,4.577288326769761e-07,0,9.117943875000492,0.0064392964650365325,0.167457112629923,0.08210312714893354 +112,112,0.9333333333333333,0.27999999999999997,0.6096081810926186,1.0,2.0500000000000003,1,5.7200315645167236e-12,1,41,5.382635228423638e-06,5.882919996523864e-06,0,3.3093759160001355,0.00649888435535857,0.1677658405863317,0.08412177451287459 +113,113,0.9416666666666667,0.2825,0.6117260760203298,1.0,2.0500000000000003,1,5.69282048688726e-12,1,161,5.474978217456794e-07,1.8735933998361592e-06,0,10.185945958000957,0.006568739873142114,0.16820698857622518,0.08702112723309284 +114,114,0.95,0.285,0.6137727932133288,1.0,2.0500000000000003,1,5.90911667402301e-12,1,90,5.910867749703286e-06,1.2388681695825335e-06,0,6.065622000000076,0.006630689584126107,0.16853042825456815,0.0893541802190448 +115,115,0.9583333333333334,0.2875,0.6155706681280546,1.0,2.0500000000000003,1,6.220918179712316e-12,1,47,5.44674746372209e-06,2.7079756703925813e-06,0,3.5798470839999936,0.006687162211397418,0.1687928176068375,0.09120450265111012 +116,116,0.9666666666666667,0.29,0.601245098817498,1.0,2.1,1,5.781816175299811e-12,1,183,4.255392514806999e-06,3.912964262425128e-06,0,18.68040154099981,0.006814346723839291,0.1694941437461332,0.09749678630333049 +117,117,0.975,0.2925,0.602472259770293,1.0,2.1,1,6.337373290224859e-12,1,55,1.1321801593466851e-06,3.240454571287136e-06,0,3.9310389580004994,0.006860636498172411,0.1696665134528633,0.09900337165740485 +118,118,0.9833333333333333,0.295,0.6046520852355842,1.0,2.1,1,5.92929481731593e-12,1,26,8.78326543818364e-06,3.781101458495695e-06,0,1.999261666998791,0.0069079177790746064,0.16986587455511573,0.10049926263225759 +119,119,0.9916666666666667,0.2975,0.6069426536919967,1.0,2.1,0,6.068944633944885e-12,1,24,4.596323321948148e-14,5.323066679094324e-06,0,1.810926666999876,0.006960096275648683,0.17008055764565919,0.10224135081813808 +120,120,1.0,0.3,0.6093834373135423,1.0,2.1,1,6.2767840413886295e-12,1,27,4.133615145729408e-06,3.72342551287658e-06,0,2.2490996249998716,0.0070113411313292885,0.17028763974365224,0.10388189510477479 diff --git a/examples/two_material_dcb_beta/results/comparison_provenance.json b/examples/two_material_dcb_beta/results/comparison_provenance.json new file mode 100644 index 000000000..a9e97f78e --- /dev/null +++ b/examples/two_material_dcb_beta/results/comparison_provenance.json @@ -0,0 +1,50 @@ +{ + "schema_version": 1, + "purpose": "Compact numerical data for replotting the retained coarse DCB toughness comparison", + "mesh": { + "nx": 120, + "ny": 48, + "nodes": 5929, + "elements": 11520, + "element_family": "T3", + "coordinate_units": "mm" + }, + "data_sources": { + "tough": "Original coarse inclusion run: accepted-step history and final nodal CSV", + "uniform": "Original uniform-layer control: accepted-step history and final nodal CSV; connectivity from its HDF5 mesh" + }, + "checks": [ + "Matching node numbering and coordinates in both final CSVs", + "Coordinates match control HDF5 mesh", + "Finite final fields and damage in [0, 1]", + "Original element connectivity retained without remeshing" + ], + "history_alignment": "The prescribed load schedule is the same, but accepted openings differ because the control required cutbacks. Plot against each run's own opening; do not subtract by row index.", + "generating_source_revision": null, + "generating_source_identity": "Not recorded at run time; exact historical source identity cannot be independently attested.", + "available_source_snapshot": { + "path": "src/phast/workflow/multimaterial_fracture.py", + "sha256": "842cbf56edba462d0a2177b67fbe71e507af2b0e3c31700869c90c1e6d8cf2b5", + "scope": "Available development source inspected before input-validation repairs on 2026-10-08, not a runtime source attestation." + }, + "replot_command": "python examples/two_material_dcb_beta/compare_results.py --output-dir runs/dcb_comparison_replot", + "files": { + "coarse_tough_history.csv": { + "sha256": "e2bdf7ddf6fc8a6a4fdf79255a7e30d63a447ba535cce8fd22145031c6161a07", + "bytes": 26971 + }, + "uniform_layer_history.csv": { + "sha256": "a95695a7a761d45ab2a5558af96cdee99969f441a8c8ba9010a06eb745097a33", + "bytes": 27314 + }, + "matched_control_fields.csv.gz": { + "sha256": "c2138d1149b78cc28ed11948d13b87f09be933fe7018e99d7088ee205f3d9bfc", + "bytes": 151289 + }, + "matched_control_elements.csv.gz": { + "sha256": "7b4f2a9be47c569762f8b85bd4441213f2de3f275c807cd6bfd3827f81061f17", + "bytes": 44958 + } + }, + "scientific_scope": "Numerical teaching comparison; not experimental validation, mesh independence, penetration, or completed bypass." +} diff --git a/examples/two_material_dcb_beta/results/convergence_and_crack_front.png b/examples/two_material_dcb_beta/results/convergence_and_crack_front.png new file mode 100644 index 000000000..b5e3a6698 Binary files /dev/null and b/examples/two_material_dcb_beta/results/convergence_and_crack_front.png differ diff --git a/examples/two_material_dcb_beta/results/damage_evolution.gif b/examples/two_material_dcb_beta/results/damage_evolution.gif new file mode 100644 index 000000000..f1ffd33f7 Binary files /dev/null and b/examples/two_material_dcb_beta/results/damage_evolution.gif differ diff --git a/examples/two_material_dcb_beta/results/damage_final.png b/examples/two_material_dcb_beta/results/damage_final.png new file mode 100644 index 000000000..6f6661552 Binary files /dev/null and b/examples/two_material_dcb_beta/results/damage_final.png differ diff --git a/examples/two_material_dcb_beta/results/displacement_final.png b/examples/two_material_dcb_beta/results/displacement_final.png new file mode 100644 index 000000000..dc741220d Binary files /dev/null and b/examples/two_material_dcb_beta/results/displacement_final.png differ diff --git a/examples/two_material_dcb_beta/results/history.csv b/examples/two_material_dcb_beta/results/history.csv new file mode 100644 index 000000000..1ed004167 --- /dev/null +++ b/examples/two_material_dcb_beta/results/history.csv @@ -0,0 +1,121 @@ +accepted_step,attempt,load_factor,opening,reaction_force,maximum_damage,connected_crack_front_x,mechanics_iterations,mechanics_residual,damage_iterations,staggered_iterations,damage_increment,projected_damage_residual,cutbacks_so_far,wall_seconds,mean_damage_material_1,mean_damage_weak_midline,mean_damage_material_2 +1,1,0.008333333333333333,0.0025,0.5533917988858841,1.0,1.5,1,2.471965849654138e-14,40,27,9.201172787132172e-06,4.4305694903677695e-08,0,4.582337832998746,0.00034458098276918844,0.08277310424551054,0.00015293880791718964 +2,2,0.016666666666666666,0.005,0.5072992447672328,1.0,1.5,1,5.649702052211171e-14,20,43,8.543476709199638e-06,5.2823389733516746e-08,0,6.227193708999039,0.00036658509550023733,0.08474929164333846,0.00015356830421929153 +3,3,0.025,0.0075,0.42358038032697987,1.0,1.5,1,8.74464524482703e-14,20,42,8.60775324618146e-06,5.2983325747602006e-08,0,5.83590733300116,0.00038513152980939,0.08640634846181765,0.00015672171426264742 +4,4,0.03333333333333333,0.01,0.3713054357546079,1.0,1.5,1,1.306582321633013e-13,20,42,9.743426096053831e-06,6.462357398685781e-08,0,5.9206174579994695,0.00040149380021105497,0.08781257472850873,0.0001694173985741829 +5,5,0.041666666666666664,0.012499999999999999,0.33881415497503076,1.0,1.5,1,1.570155458274593e-13,10,42,9.866764148602769e-06,6.51286633738396e-08,0,5.812644249999721,0.0004168226455306757,0.08903489169143729,0.00020327475437920126 +6,6,0.05,0.015,0.32233662230700105,1.0,1.5,1,2.046163993901864e-13,10,41,9.47889343416719e-06,6.43214134333353e-08,0,5.297800750000533,0.00043210435449029676,0.09008531563165467,0.0002682879986903697 +7,7,0.058333333333333334,0.017499999999999998,0.3189432474596542,1.0,1.5,1,2.3943771984735074e-13,10,37,8.520103638165466e-06,5.614817250726434e-08,0,4.772635082999841,0.00044812191679725736,0.09098179342658079,0.0003669430492880106 +8,8,0.06666666666666667,0.02,0.3251654360677777,1.0,1.5,1,3.2446671037569644e-13,10,33,9.43043843948388e-06,6.30973285148384e-08,0,4.323163375000149,0.00046556663050488896,0.09176208653950015,0.0004956593445671929 +9,9,0.075,0.0225,0.3377855110091509,1.0,1.5,1,3.254849540229653e-13,10,29,9.849527874306041e-06,7.037797052598938e-08,0,3.6253258750002715,0.00048487999089693635,0.09246886048261348,0.0006498879242782804 +10,10,0.08333333333333333,0.024999999999999998,0.35452356223910575,1.0,1.5,1,3.4054574101122515e-13,10,27,9.192237961253014e-06,6.502182967917103e-08,0,3.457967042000746,0.0005063393508745242,0.0931364254001594,0.0008261160209981162 +11,11,0.09166666666666666,0.027499999999999997,0.37387435048761036,1.0,1.5,1,3.7924171027655087e-13,10,25,9.052306278345412e-06,6.457623332595253e-08,0,2.884716958998979,0.0005299643310949154,0.09378773382720505,0.001022029945828315 +12,12,0.1,0.03,0.39486551126805236,1.0,1.5,1,4.36710312875025e-13,10,23,9.1098232473108e-06,6.749993143075061e-08,0,2.663210083001104,0.000555771916521628,0.09443759353456531,0.00123614908727024 +13,13,0.10833333333333334,0.0325,0.41686719982612574,1.0,1.5,1,4.945245778606552e-13,10,22,7.805346782685518e-06,5.379918191321387e-08,0,2.3562138750003214,0.0005837118953551905,0.09509574514944621,0.0014674046366377844 +14,14,0.11666666666666667,0.034999999999999996,0.43945541906912783,1.0,1.5,1,5.562004761279795e-13,10,21,7.672895619537101e-06,5.575692913276087e-08,0,2.340355582999109,0.0006136520415947529,0.09576846760998592,0.0017148655426822805 +15,15,0.125,0.0375,0.4623317616799028,1.0,1.5,1,5.801044460256976e-13,10,19,9.67012949848467e-06,6.98777536303069e-08,0,2.108667833999789,0.0006455432021589263,0.09646039182647882,0.001977721256982277 +16,16,0.13333333333333333,0.04,0.4852652658573392,1.0,1.5,1,6.317895309286856e-13,10,18,9.33697833316316e-06,7.378705014007836e-08,0,2.14193033400079,0.0006793383271067246,0.09717596092916642,0.0022552463335297535 +17,17,0.14166666666666666,0.042499999999999996,0.5080784782274869,1.0,1.5,1,6.18267209958402e-13,10,18,7.251609378755575e-06,5.137079532591127e-08,0,2.0483260829987557,0.0007149961713680512,0.09791844880037422,0.0025467790774321925 +18,18,0.15,0.045,0.5306250543587661,1.0,1.5,1,6.90505928569309e-13,10,17,8.323704767110307e-06,6.376851062819822e-08,0,1.9729321249997156,0.0007523791663300532,0.09868976962818772,0.0028516754078369835 +19,19,0.15833333333333333,0.047499999999999994,0.5527761897679547,1.0,1.5,1,7.168024232128417e-13,10,16,9.669787993438206e-06,8.065736599102702e-08,0,1.7203318329993635,0.0007913713970937408,0.09949152202808145,0.0031694282945463003 +20,20,0.16666666666666666,0.049999999999999996,0.5744075641777051,1.0,1.5,1,7.022376149312872e-13,10,16,8.033485487390912e-06,6.256023999881566e-08,0,1.6341972919999534,0.0008318731149092749,0.1003253901190429,0.0034996197415259386 +21,21,0.175,0.0525,0.595408246435652,1.0,1.5,1,7.345259417575159e-13,10,16,7.219336429997725e-06,5.181513212937361e-08,0,1.8529796669990901,0.0008737808594474716,0.10119268943130058,0.003841743943673167 +22,22,0.18333333333333332,0.05499999999999999,0.6156669127711139,1.0,1.5,1,7.929950378024708e-13,10,16,7.133916329560286e-06,4.8959689722544164e-08,0,1.7977804590009328,0.0009169750701265522,0.10209511376106534,0.004195362311152285 +23,23,0.19166666666666665,0.057499999999999996,0.6350734138401555,1.0,1.5,1,8.708310333287051e-13,10,16,8.605794389771049e-06,5.567113577076288e-08,0,1.703026167000644,0.000961322928670805,0.10303349577074072,0.004560108182407945 +24,24,0.2,0.06,0.6535088167710217,1.0,1.5,1,9.262615076977822e-13,10,17,8.13876208471953e-06,4.483371921631951e-08,0,1.783319041998766,0.0010066720599821906,0.10400909692414215,0.0049357345452280005 +25,25,0.20833333333333334,0.0625,0.6708420411685755,1.0,1.5,1,9.061355811002471e-13,10,18,8.82725541195839e-06,4.080413161869356e-08,0,1.9287019160001364,0.0010528507745965424,0.10502357542836882,0.005321998651266455 +26,26,0.21666666666666667,0.065,0.6869159724761715,1.0,1.5,1,9.772802802526274e-13,10,20,7.767931700985997e-06,2.9778168628841195e-08,0,2.188428124998609,0.0010996499381808384,0.10607888429931624,0.005718994362049958 +27,27,0.225,0.0675,0.7015076226978421,1.0,1.5,1,1.0431356013579828e-12,10,22,8.372640236786744e-06,2.6161137221814013e-08,0,2.399428999999145,0.0011468092694670877,0.10717881612054907,0.006127123254388212 +28,28,0.23333333333333334,0.06999999999999999,0.7143460322101634,1.0,1.5,1,1.166538670415136e-12,10,26,9.084947365400886e-06,2.003374549586212e-08,0,2.7797357920007926,0.0011939976152344572,0.10832726696171863,0.006547561625279616 +29,29,0.24166666666666667,0.0725,0.7250085370816229,1.0,1.5,1,1.1582241841766366e-12,10,35,9.925665861221233e-06,3.618818109583921e-08,0,3.600220291000369,0.0012407653973463522,0.10953081026639838,0.006982782253867692 +30,30,0.25,0.075,0.7323661421008307,1.0,1.5,1,1.1532907849288148e-12,2,78,9.936239969698946e-06,5.1665056475863266e-08,0,12.791105708000032,0.001286278108279112,0.11081007146635949,0.0074386116577324505 +31,31,0.2583333333333333,0.07749999999999999,0.702775994192576,1.0,1.5374999999999999,1,1.2639203694506379e-12,2,325,6.302673721814145e-07,1.9994910733329638e-07,0,35.63877033300014,0.0013380314460672818,0.11342691258810385,0.008070979896506288 +32,32,0.26666666666666666,0.08,0.5943246583190243,1.0,1.575,1,1.2370385992612582e-12,1,163,6.724967358540113e-07,2.1068534829596364e-07,0,20.806073791000017,0.0014745012050007467,0.1181139916705261,0.008526983057241914 +33,33,0.275,0.0825,0.5610176944623879,1.0,1.6125,1,1.349705093110291e-12,2,135,9.717079549553809e-06,5.084844957561934e-08,0,14.935870749999594,0.0015551350510203603,0.11979643569062316,0.00880214278088311 +34,34,0.2833333333333333,0.08499999999999999,0.5573342922712226,1.0,1.6125,1,1.3955919434292583e-12,1,61,7.405843534757928e-06,1.857959288836049e-07,0,7.083451500000592,0.0016041928139892273,0.12046444248163396,0.008992304067816174 +35,35,0.2916666666666667,0.08750000000000001,0.5568253278026112,1.0,1.6125,1,1.423430248528836e-12,2,62,9.79097739295387e-06,5.0330456045910577e-08,0,6.483243207998385,0.001651460025566112,0.12101974700964929,0.009194412686429877 +36,36,0.3,0.09,0.5521783732579221,1.0,1.65,1,1.4466896107761295e-12,2,116,9.98549693953521e-06,5.7522441231277544e-08,0,11.483933417001026,0.0017055840215010412,0.12168628913958489,0.009442010710577427 +37,37,0.30833333333333335,0.0925,0.5490393888290118,1.0,1.65,1,1.4789046436007674e-12,1,70,3.5523711747753595e-06,1.447184035433636e-07,0,8.089395708000666,0.0017595081519982622,0.12227716565531437,0.009697684806237167 +38,38,0.31666666666666665,0.09499999999999999,0.5517367309920698,1.0,1.65,1,1.5064656042764592e-12,1,52,9.682362876350936e-06,2.3910768981936484e-07,0,5.426095875000101,0.0018057037263635393,0.12270666387623155,0.00996330427258054 +39,39,0.325,0.0975,0.555222339997381,1.0,1.65,1,1.5173041160823685e-12,1,46,1.8768970889704306e-06,5.953448134320832e-07,0,5.274045541000305,0.0018513170931016244,0.12312830885886769,0.010261415223129516 +40,40,0.3333333333333333,0.09999999999999999,0.5554093169460855,1.0,1.6875,1,1.5460657221969754e-12,1,79,9.653605573700652e-06,2.864201288385555e-07,0,8.095746832999794,0.0019029235970109582,0.12364552985841694,0.010600021985128265 +41,41,0.3416666666666667,0.1025,0.5558410238452784,1.0,1.6875,1,1.5180568597935647e-12,10,64,9.427875115042283e-06,6.598176729294414e-08,0,7.250881957999809,0.0019561159131804852,0.12414281410526622,0.010952707740758072 +42,42,0.35,0.105,0.5589768339678414,1.0,1.6875,1,1.680815804705562e-12,2,53,6.766808599567575e-06,2.5832537470238393e-08,0,5.383868582999639,0.0020059727708216027,0.12455583813366704,0.011297732356854079 +43,43,0.35833333333333334,0.1075,0.5627613276380592,1.0,1.6875,1,1.738315591678441e-12,1,48,2.3619141509279018e-07,4.0813778303186443e-07,0,5.303190041999187,0.002055739241126498,0.12495289506589587,0.011650173307681397 +44,44,0.36666666666666664,0.10999999999999999,0.565046125326023,1.0,1.7249999999999999,1,1.8150599410001395e-12,2,70,8.410635924160914e-06,4.211569908758265e-08,0,6.979605292000997,0.0021095905488553667,0.1253992016743424,0.012032256308300971 +45,45,0.375,0.11249999999999999,0.5663087388163022,1.0,1.7249999999999999,1,1.917652237148821e-12,1,64,9.134648746744745e-06,2.0819244906999457e-07,0,6.2902103750002425,0.002166136090189013,0.12587953116705558,0.012437790983786183 +46,46,0.3833333333333333,0.11499999999999999,0.5690686338616644,1.0,1.7249999999999999,1,1.9707390929207137e-12,1,40,7.726516689454677e-06,9.109029858109241e-07,0,4.554145416999745,0.002223218987049487,0.12639542272502058,0.012844384031749118 +47,47,0.39166666666666666,0.1175,0.5727904807916284,1.0,1.7249999999999999,1,1.929043898508014e-12,1,53,9.493371620483693e-06,3.338604225336893e-07,0,5.457107750000432,0.0022817442198951442,0.12697278900237405,0.01324980713384879 +48,48,0.4,0.12,0.5765168811774894,1.0,1.7249999999999999,1,1.99766335752365e-12,2,38,7.29035001667544e-06,1.0194528481536139e-06,0,4.145912542000588,0.002339562629482435,0.12759091162017083,0.013679202702844144 +49,49,0.4083333333333333,0.1225,0.5771688250939306,1.0,1.7625,1,2.0329576911840505e-12,1,167,9.663395439174494e-06,2.7327518846786774e-07,0,14.014746417000424,0.0023997790444826844,0.12830164316209933,0.014214171982239688 +50,50,0.4166666666666667,0.125,0.5716976175660694,1.0,1.7625,1,2.2181974420970047e-12,1,119,9.723855719623309e-06,3.3880974424022937e-07,0,12.140315709000788,0.0024719531910788795,0.12911074124093866,0.014942010062758724 +51,51,0.425,0.1275,0.573423452024537,1.0,1.7625,1,2.2139746481085525e-12,1,79,9.92698909196843e-06,3.2036898478421155e-07,0,7.410220208999817,0.00252949135561083,0.1298057792588947,0.01545134478169659 +52,52,0.43333333333333335,0.13,0.5760871828025006,1.0,1.7625,1,2.2801020178103613e-12,1,33,6.962176946068155e-09,6.114799099210186e-07,0,4.370681624999634,0.002584120589027056,0.1305515093394477,0.01589272727487047 +53,53,0.44166666666666665,0.13249999999999998,0.5344572124484224,1.0,1.7625,1,2.354015095662247e-12,2,166,9.057271175061388e-06,6.924013809172722e-07,0,62.36951233400032,0.0028602373745809603,0.13575353343463734,0.016018035572567937 +54,54,0.45,0.135,0.541250000405416,1.0,1.7625,1,2.296519967132858e-12,3,30,2.6728195970937563e-06,7.440525390048358e-07,0,3.7377212080009485,0.0028972613832001547,0.136061371336784,0.016032008130938826 +55,55,0.4583333333333333,0.13749999999999998,0.5482044498213643,1.0,1.7625,1,2.3866846652527884e-12,1,60,8.638294346496878e-06,2.632233954459346e-07,0,5.6286481249990175,0.002934082198364254,0.13635968271467797,0.01604861193456912 +56,56,0.4666666666666667,0.13999999999999999,0.55490658128399,1.0,1.7625,1,2.339582591779286e-12,2,64,5.589361636637591e-06,8.865253952848595e-07,0,6.0509827910009335,0.0029715593904751703,0.13669577102843483,0.01607118281982779 +57,57,0.475,0.1425,0.5605313707140771,1.0,1.7625,1,2.446617985665161e-12,1,66,9.843853284730031e-06,4.95985006859431e-07,0,6.392320832999758,0.003016409960746414,0.13711801912768654,0.016103667026211677 +58,58,0.48333333333333334,0.145,0.5668122810460876,1.0,1.7625,1,2.484741295623894e-12,1,48,7.677834881869572e-06,5.052451650816863e-07,0,5.106676749999679,0.003058521902547231,0.13747629919289894,0.016139108804366777 +59,59,0.49166666666666664,0.1475,0.5735815707991534,1.0,1.7625,1,2.4492214557455266e-12,1,40,4.0645391807814235e-07,4.829211337963545e-07,0,4.044269792000705,0.0030984991302852607,0.1377900253893554,0.016180355877928224 +60,60,0.5,0.15,0.5803870265933047,1.0,1.7625,1,2.5228332722428817e-12,1,38,4.566470619082885e-06,6.506226703545566e-07,0,3.9556952080001793,0.003142145365516467,0.13808824503830644,0.016230907184912435 +61,61,0.5083333333333333,0.1525,0.585689263852326,1.0,1.7625,1,2.5927491985189846e-12,1,39,1.568937831764039e-06,8.19386583539479e-07,0,3.6656686249989434,0.0031996682699399074,0.1384399401976409,0.016313628596474273 +62,62,0.5166666666666666,0.15499999999999997,0.5895184518273429,1.0,1.7625,1,2.802975388773389e-12,1,50,9.16646799264953e-06,7.151209962374255e-07,0,5.190479999999297,0.0032598925951487106,0.1388711784600587,0.016439200620471002 +63,63,0.525,0.1575,0.5922658543110723,1.0,1.7625,1,2.8194920479399896e-12,1,51,1.8653364602938538e-06,1.0381337899323384e-06,0,5.077234291000423,0.0033216915997962863,0.13936252575844163,0.016609550215034876 +64,64,0.5333333333333333,0.16,0.5943940191121716,1.0,1.7999999999999998,1,2.7522170175048135e-12,1,66,9.560082673276682e-07,3.1966804339353394e-07,0,5.863287833000868,0.003383136846283821,0.13986433996124745,0.016832485836165086 +65,65,0.5416666666666666,0.16249999999999998,0.5848578075107803,1.0,1.7999999999999998,0,5.2968174361880404e-12,1,123,1.198152688175469e-12,1.3631085063331438e-06,0,14.869680249999874,0.0034575233246827122,0.1406740702759643,0.017561075838197913 +66,66,0.55,0.165,0.5860780431439877,1.0,1.7999999999999998,1,2.7726712107557516e-12,1,97,9.768687471045645e-06,4.109527740725331e-07,0,8.091594125000483,0.003517338000624215,0.1411378240768148,0.017941027222302192 +67,67,0.5583333333333333,0.1675,0.5882864265866095,1.0,1.7999999999999998,1,2.9520352289759334e-12,1,50,9.264140470255366e-06,4.488882744925417e-07,0,4.874440624998897,0.0035768597295122878,0.14158008374786055,0.01829061803261413 +68,68,0.5666666666666667,0.16999999999999998,0.5906221487037696,1.0,1.7999999999999998,1,2.844979360337641e-12,1,58,9.782245173672877e-06,4.733833785796899e-07,0,5.144228375000239,0.003637890870796039,0.14201749240669773,0.018652810024729804 +69,69,0.575,0.1725,0.5928969634347168,1.0,1.8375,1,2.8276505268190637e-12,1,92,9.633052818758259e-06,3.4805649455052403e-07,0,7.722460124999998,0.0037007687768014614,0.14245913571477148,0.019019738147659823 +70,70,0.5833333333333334,0.17500000000000002,0.5949993146657782,1.0,1.8375,1,2.849717572468838e-12,1,71,9.748763643679936e-06,5.150098000493398e-07,0,6.228418334001617,0.0037648291219536095,0.14290234321143602,0.019381273850901947 +71,71,0.5916666666666667,0.1775,0.5967264304073824,1.0,1.8375,1,2.968896534708143e-12,1,49,6.2340545122774316e-06,9.845263780886482e-07,0,4.770256167001207,0.0038301558464794157,0.14335628388054011,0.019743939493818835 +72,72,0.6,0.18,0.5980178695433769,1.0,1.8375,1,3.06092315149861e-12,1,43,2.9787448629914337e-07,1.181581423688303e-06,0,4.110404999999446,0.0038962162213951866,0.14381755988423783,0.020152142590973036 +73,73,0.6083333333333333,0.18249999999999997,0.5989751249068973,1.0,1.8375,1,3.0906105319703128e-12,1,41,1.124610815583793e-08,1.0627258166390208e-06,0,4.400540500000716,0.003962598479954,0.14430972034917375,0.020606060795538117 +74,74,0.6166666666666667,0.185,0.5995673987007972,1.0,1.8375,0,5.194908378341001e-10,1,101,1.1582679260158102e-10,9.744653977506595e-07,0,13.302836292001302,0.0040320162879036855,0.14488908482477686,0.021057813696919093 +75,75,0.625,0.1875,0.59909908743519,1.0,1.8375,1,3.1209837011126484e-12,1,60,7.565406605514191e-06,8.173158607672993e-07,0,5.600187665999329,0.004102233021738731,0.14548689246076288,0.021554735650293293 +76,76,0.6333333333333333,0.18999999999999997,0.5961385323739923,1.0,1.875,1,3.136918210983087e-12,13,114,6.9926416095267285e-06,1.7872173125772772e-06,0,13.116283666999152,0.004177677318609986,0.14610300347158522,0.022327140177956353 +77,77,0.6416666666666666,0.19249999999999998,0.5956129482486011,1.0,1.875,1,2.9953864949889263e-12,1,45,7.293847809064502e-06,2.8765046558298923e-06,0,6.445241209001324,0.004244235791163588,0.14663459995900194,0.022990562534345293 +78,78,0.65,0.195,0.596049475670907,1.0,1.875,1,3.1760343944570917e-12,1,53,2.1223410695547784e-08,1.6471786964582583e-06,0,6.115897749999931,0.004309715834087228,0.1471719341754491,0.02361560763483519 +79,79,0.6583333333333333,0.19749999999999998,0.5974668706271511,1.0,1.875,1,3.114811799116131e-12,1,125,2.7821658824533912e-06,1.1934947025931536e-06,0,11.7766067499997,0.004381908018977116,0.14784471242431524,0.024084563467039383 +80,80,0.6666666666666666,0.19999999999999998,0.5988073203387128,1.0,1.875,1,3.08348750493577e-12,1,94,9.146128680859178e-06,1.1845012437318447e-06,0,9.057770625000558,0.0044503519988202825,0.14845529196349191,0.024607014044050867 +81,81,0.675,0.2025,0.5995159888042496,1.0,1.875,1,3.23261327949755e-12,1,50,3.941506644178361e-06,1.886553577310282e-06,0,4.584158208999725,0.004515168754564138,0.14900914939926682,0.025225653541161314 +82,82,0.6833333333333333,0.205,0.5981396370088243,1.0,1.875,1,3.3465957332809187e-12,4,70,6.897134218530887e-06,1.8930986992789917e-06,0,7.190534208000827,0.00458735289289316,0.14965513875506806,0.026054647613557816 +83,83,0.6916666666666667,0.2075,0.5955553569913274,1.0,1.9124999999999999,1,3.417538847698526e-12,1,149,9.988816395356537e-06,3.510622167056344e-07,0,12.915413707998596,0.004666693864875459,0.1503511368707335,0.027104306557265912 +84,84,0.7,0.21,0.5958613761271063,1.0,1.9124999999999999,1,3.5593378501067237e-12,1,209,5.528766301443611e-07,7.140161951428223e-07,0,16.170580333000544,0.004737242833791961,0.15097612521941375,0.027892507003751732 +85,85,0.7083333333333334,0.2125,0.5970008593893656,1.0,1.9124999999999999,1,3.753215194334971e-12,1,104,7.262385298245633e-06,6.562508747800719e-07,0,8.897172290999151,0.00480315953118583,0.15154244099934513,0.02862850606343865 +86,86,0.7166666666666667,0.215,0.598583822428311,1.0,1.9124999999999999,1,3.56963316760119e-12,1,133,5.633505521629445e-06,1.9632509060084347e-06,0,11.375495541999044,0.0048722215591420846,0.1521840492669233,0.029354350712242464 +87,87,0.725,0.2175,0.6005492831414638,1.0,1.9124999999999999,1,3.538910558242415e-12,1,146,4.888197802088712e-08,1.7000964278625352e-06,0,12.411774458001673,0.004945697002986931,0.15289802492358875,0.03012731504305342 +88,88,0.7333333333333333,0.21999999999999997,0.6021680513510502,1.0,1.9124999999999999,1,3.5611557433609e-12,1,100,6.4646917089516975e-06,1.4687257690968597e-06,0,8.511208375000933,0.005010382281148432,0.15344584916717513,0.03094876102435099 +89,89,0.7416666666666667,0.2225,0.6040267484601519,1.0,1.9124999999999999,1,3.9174866355614285e-12,2,154,9.12254080331909e-06,2.2550303851644887e-06,0,13.702393125000526,0.005083744646685527,0.15414095039056178,0.031896782577907505 +90,90,0.75,0.22499999999999998,0.6059479667399242,1.0,1.9124999999999999,1,3.8610382652293225e-12,1,128,4.0368457754347276e-06,1.4049896494873482e-06,0,11.148899957999674,0.005157195554100271,0.15481408442794609,0.03292059325834493 +91,91,0.7583333333333333,0.22749999999999998,0.6069810384313153,1.0,1.9124999999999999,1,3.806348018127352e-12,2,60,9.956527823207217e-06,2.113362450779227e-06,0,5.810399624999263,0.00522044078476711,0.15532180225746864,0.03390954318296935 +92,92,0.7666666666666666,0.22999999999999998,0.6063879086943166,1.0,1.9124999999999999,1,3.668491739818838e-12,9,79,7.157841741212145e-06,1.7079553553219677e-06,0,10.50846779099993,0.005290105913814686,0.15592209382996558,0.035174638114701354 +93,93,0.775,0.23249999999999998,0.6041333804043969,1.0,1.95,1,3.97993523743824e-12,1,58,2.227142914534852e-09,4.323647900348476e-06,0,8.681622833000802,0.005370285409227287,0.15659422276568302,0.03680330664434551 +94,94,0.7833333333333333,0.235,0.6029594278437137,1.0,1.95,1,4.077410319216243e-12,1,79,3.013902305282201e-06,5.000546445485283e-07,0,9.7174398749994,0.005442010448832206,0.15716242331027966,0.03825304091183539 +95,95,0.7916666666666666,0.2375,0.6038266152729367,1.0,1.95,1,3.854427344712778e-12,1,44,4.164065031786457e-06,2.182743439554588e-06,0,6.194925333000356,0.00550426770067944,0.1576188885826899,0.03949858997200687 +96,96,0.8,0.24,0.6054737499424375,1.0,1.95,1,4.308344943938823e-12,1,187,1.9762766000352983e-06,8.86609071435937e-07,0,16.9898885420007,0.0055696835138066714,0.15815738186703035,0.040862434077006335 +97,97,0.8083333333333333,0.2425,0.6073036305721832,1.0,1.95,1,4.261193229532386e-12,1,128,8.90540858833333e-08,2.6484142129738764e-06,0,13.941432707999411,0.005639233911095747,0.15876022271941953,0.042433466841444646 +98,98,0.8166666666666667,0.245,0.6090426624162427,1.0,1.95,1,4.278694428240636e-12,2,106,8.348484021536429e-06,1.8706748569097828e-06,0,11.0156418330007,0.005701598903336401,0.15922770318249024,0.043833207981510115 +99,99,0.825,0.24749999999999997,0.6106265338245493,1.0,1.95,1,4.1685595866362444e-12,1,52,3.2038041900550596e-06,2.2523236176859307e-06,0,4.918824541999129,0.005762075638261045,0.15963673387529606,0.045152510802668924 +100,100,0.8333333333333334,0.25,0.6114850222250194,1.0,1.95,1,4.249273181126579e-12,1,52,1.5261165664526288e-08,3.182609690784849e-06,0,5.276689958000134,0.005826843457011181,0.16010687758613096,0.0468109323556636 +101,101,0.8416666666666667,0.2525,0.6108237567875826,1.0,1.95,1,4.324769412083111e-12,9,79,5.419455873623136e-06,2.0727122028360025e-06,0,12.095806334000372,0.005897108441475551,0.1606567542749377,0.04877569837688547 +102,102,0.85,0.255,0.6063069754615376,1.0,1.9874999999999998,1,4.363023260941581e-12,1,275,3.492212212741208e-07,1.0087276483349656e-06,0,27.50792625000031,0.005981794690957191,0.1612249012297744,0.05123476978916281 +103,103,0.8583333333333333,0.25749999999999995,0.6070329589101835,1.0,1.9874999999999998,0,3.942705156244482e-11,1,39,6.860290113763767e-12,2.514146057591704e-06,0,4.167666375000408,0.0060390419510717155,0.1615865180608487,0.05269351138136202 +104,104,0.8666666666666667,0.26,0.6081807029500733,1.0,1.9874999999999998,1,4.4497830213973455e-12,1,40,6.4329497008186465e-06,1.7522826269598599e-06,0,4.798025124999185,0.006099658852268678,0.161962426075216,0.054353156917562345 +105,105,0.875,0.2625,0.6100291620859952,1.0,1.9874999999999998,0,4.205851335737439e-10,1,29,1.1435341562560097e-10,4.040927125816517e-06,0,4.582452499998908,0.00615413650521674,0.1622814593352192,0.05577430822257198 +106,106,0.8833333333333333,0.26499999999999996,0.6114837480623468,1.0,1.9874999999999998,1,4.607797193624043e-12,1,56,3.322646602299528e-10,2.810954778784472e-06,0,7.254809750000277,0.006213518311016875,0.16265830563620118,0.05751556442634966 +107,107,0.8916666666666666,0.26749999999999996,0.6128934921592164,1.0,1.9874999999999998,1,4.826906023135322e-12,1,82,7.698665038802233e-10,3.61251529724764e-06,0,11.479302833000474,0.00628054778029924,0.1631192723151224,0.05978296058586423 +108,108,0.9,0.27,0.6139925015940074,1.0,1.9874999999999998,1,4.76076547017878e-12,1,133,4.812205587567675e-06,1.2811183637781464e-06,0,11.847045041999081,0.006346563128013759,0.16355396620281343,0.06197838545525772 +109,109,0.9083333333333333,0.27249999999999996,0.6090154814710109,1.0,2.025,1,5.061894385886235e-12,1,174,3.0057484461387673e-06,3.9843828056156105e-06,0,22.780144250000376,0.0064269256063190705,0.16402935834378704,0.06468559392060216 +110,110,0.9166666666666666,0.27499999999999997,0.6083891015510041,1.0,2.025,1,4.964890843001429e-12,1,59,4.5707963209906666e-06,4.168801511938991e-06,0,6.1736252089995105,0.006488726856677633,0.16436477807668048,0.06657855380216363 +111,111,0.9249999999999999,0.27749999999999997,0.6095280341226788,1.0,2.025,1,5.133996639892446e-12,1,50,1.721271326804441e-06,2.3805924969604172e-06,0,4.972795166999276,0.0065444176617650476,0.16464359152203914,0.06819018178438607 +112,112,0.9333333333333333,0.27999999999999997,0.6113097992552372,1.0,2.025,1,5.258783457440601e-12,1,36,1.2240919067263434e-07,1.6888895974196154e-06,0,3.9996390839987725,0.006599228376118813,0.1649088716833652,0.06978217023115953 +113,113,0.9416666666666667,0.2825,0.6133438781743092,1.0,2.025,1,5.0649271005515225e-12,1,33,3.971617035247732e-09,2.7808926221957464e-06,0,4.25285279200034,0.0066527428969390305,0.16516204477230034,0.07131560533621234 +114,114,0.95,0.285,0.6151863285269097,1.0,2.025,1,5.30000484830846e-12,1,27,8.262729071728536e-06,3.902966167160238e-06,0,2.602844875000301,0.006709527439186454,0.16543392395841583,0.07307149515985728 +115,115,0.9583333333333334,0.2875,0.6160722775702054,1.0,2.025,1,5.381579302968701e-12,1,105,4.776804662931511e-08,1.1514475800423812e-06,0,9.063034165999852,0.006772743176582327,0.16579082768021286,0.07543974457627942 +116,116,0.9666666666666667,0.29,0.6161221089599799,1.0,2.025,1,5.551737381285586e-12,1,49,3.988529299392418e-06,6.910926739149559e-06,0,5.192292375000761,0.006837638863429042,0.16616055916414943,0.07792278259344493 +117,117,0.975,0.2925,0.6104819988224952,1.0,2.0625,1,5.309595937084654e-12,1,136,1.111603576742226e-06,4.260757913120139e-06,0,19.16852370900051,0.006927839488323305,0.16665043322337658,0.08162923146826927 +118,118,0.9833333333333333,0.295,0.6112218661259186,1.0,2.0625,1,5.631384715982953e-12,1,158,3.623804287755661e-06,6.504801234734109e-07,0,13.157035374999396,0.006988873500738328,0.16695835643815898,0.0837993232222959 +119,119,0.9916666666666667,0.2975,0.6129770075573348,1.0,2.0625,1,5.2699873703099044e-12,1,62,9.47110678362062e-06,2.165654936230781e-06,0,5.571646833001068,0.007045480577189274,0.1672292214337301,0.08566142814897315 +120,120,1.0,0.3,0.6149522713694282,1.0,2.0625,1,5.41084607446851e-12,1,60,5.289284087051094e-06,2.1898844705147205e-06,0,7.0892967079998925,0.007104852664792971,0.16748947282210294,0.08757634113250168 diff --git a/examples/two_material_dcb_beta/results/initial_conditions.png b/examples/two_material_dcb_beta/results/initial_conditions.png new file mode 100644 index 000000000..b7180b5e0 Binary files /dev/null and b/examples/two_material_dcb_beta/results/initial_conditions.png differ diff --git a/examples/two_material_dcb_beta/results/load_displacement.png b/examples/two_material_dcb_beta/results/load_displacement.png new file mode 100644 index 000000000..819d08df5 Binary files /dev/null and b/examples/two_material_dcb_beta/results/load_displacement.png differ diff --git a/examples/two_material_dcb_beta/results/matched_control_comparison.png b/examples/two_material_dcb_beta/results/matched_control_comparison.png new file mode 100644 index 000000000..63bcf6efd Binary files /dev/null and b/examples/two_material_dcb_beta/results/matched_control_comparison.png differ diff --git a/examples/two_material_dcb_beta/results/matched_control_damage.png b/examples/two_material_dcb_beta/results/matched_control_damage.png new file mode 100644 index 000000000..0d2c4a56a Binary files /dev/null and b/examples/two_material_dcb_beta/results/matched_control_damage.png differ diff --git a/examples/two_material_dcb_beta/results/matched_control_elements.csv.gz b/examples/two_material_dcb_beta/results/matched_control_elements.csv.gz new file mode 100644 index 000000000..a99464a13 Binary files /dev/null and b/examples/two_material_dcb_beta/results/matched_control_elements.csv.gz differ diff --git a/examples/two_material_dcb_beta/results/matched_control_fields.csv.gz b/examples/two_material_dcb_beta/results/matched_control_fields.csv.gz new file mode 100644 index 000000000..3f5f08e0b Binary files /dev/null and b/examples/two_material_dcb_beta/results/matched_control_fields.csv.gz differ diff --git a/examples/two_material_dcb_beta/results/matched_control_review.json b/examples/two_material_dcb_beta/results/matched_control_review.json new file mode 100644 index 000000000..0a2a09ecb --- /dev/null +++ b/examples/two_material_dcb_beta/results/matched_control_review.json @@ -0,0 +1,22 @@ +{ + "matched_physical_inputs_except_material_2_Gc": true, + "mesh": [ + 120, + 48 + ], + "total_opening_mm": 0.3, + "Gc_layer": 0.04, + "Gc_inclusion_case": 0.12, + "Gc_control": 0.04, + "inclusion_case_final_front_mm": 2.1, + "control_final_front_mm": 2.4000000000000004, + "inclusion_case_final_reaction": 0.6093834373135423, + "control_final_reaction": 0.4584674467512238, + "relative_reaction_increase": 0.3291749318991657, + "inclusion_case_converged": true, + "control_converged": true, + "control_accepted_steps": 123, + "control_cutbacks": 3, + "control_maximum_projected_damage_residual": 5.160024657651502e-06, + "scope": "Controlled comparison of discrete teaching models, not experimental validation" +} diff --git a/examples/two_material_dcb_beta/results/material_fields.png b/examples/two_material_dcb_beta/results/material_fields.png new file mode 100644 index 000000000..ceffcad21 Binary files /dev/null and b/examples/two_material_dcb_beta/results/material_fields.png differ diff --git a/examples/two_material_dcb_beta/results/numerical_review.json b/examples/two_material_dcb_beta/results/numerical_review.json new file mode 100644 index 000000000..e1f48c56e --- /dev/null +++ b/examples/two_material_dcb_beta/results/numerical_review.json @@ -0,0 +1,44 @@ +{ + "scope": "Numerical teaching-case checks, not experimental or mesh-convergence validation", + "accepted_steps": 120, + "all_steps_converged": true, + "finite_stored_fields": true, + "damage_minimum": 0.0, + "damage_maximum": 1.0, + "maximum_damage_decrease": 0.0, + "maximum_history_decrease": 0.0, + "maximum_projected_damage_residual": 6.910926739149559e-06, + "maximum_edge_over_l0": 0.4506939094330038, + "material_2_x_extent_mm": [ + 2.0, + 2.4 + ], + "first_seed_connected_disk_entry": null, + "first_seed_connected_growth_beyond_disk_plus_l0": null, + "final_connected_front_mm_by_damage_threshold": { + "0.6": 2.1, + "0.8": 2.0625, + "0.9": 2.0625 + }, + "final_seed_to_front_path_minimum_distance_from_disk_centre_mm": 0.2850438562747846, + "final_seed_to_front_path_enters_inner_half_of_disk": false, + "final_intact_outer_region_strain_norm_95th_percentile": 0.007138165412266952, + "final_intact_outer_region_strain_norm_maximum": 0.016670813369898608, + "final_intact_outer_region_infinitesimal_rotation_95th_percentile_rad": 0.08542793207622856, + "trajectory": "training_data.h5", + "second_mesh_comparison": { + "coarse_mesh": [ + 120, + 48 + ], + "reference_mesh": [ + 160, + 48 + ], + "coarse_final_connected_front_mm": 2.1, + "reference_final_connected_front_mm": 2.0625, + "coarse_final_reaction": 0.6093834373135423, + "reference_final_reaction": 0.6149522713694282, + "interpretation": "Two spatial resolutions only; not a convergence study" + } +} diff --git a/examples/two_material_dcb_beta/results/run_manifest.json b/examples/two_material_dcb_beta/results/run_manifest.json new file mode 100644 index 000000000..a8fba7eac --- /dev/null +++ b/examples/two_material_dcb_beta/results/run_manifest.json @@ -0,0 +1,33 @@ +{ + "schema_version": 1, + "example": "two_material_dcb_phase_field", + "command": "python -m phast run examples/two_material_dcb_beta/config.yaml --output_dir runs/two_material_dcb", + "config_sha256": "d781c4d858f3cc1295f2e871012cffd13a2baee73e32042810001001db37fe1e", + "status": "Executed qualitative beta teaching calculation; not a validated fracture benchmark", + "trajectory": { + "format": "h5", + "filename": "training_data.h5", + "retained_in_repository": false, + "regeneration": "Run the command above to generate the float64 field trajectory." + }, + "files": [ + "README.md", + "initial_conditions.png", + "material_fields.png", + "damage_final.png", + "displacement_final.png", + "strain_final.png", + "stress_final.png", + "load_displacement.png", + "convergence_and_crack_front.png", + "damage_evolution.gif", + "summary.json", + "numerical_review.json", + "history.csv", + "matched_control_comparison.png", + "matched_control_damage.png", + "matched_control_review.json", + "visual_manifest.json", + "run_manifest.json" + ] +} diff --git a/examples/two_material_dcb_beta/results/strain_final.png b/examples/two_material_dcb_beta/results/strain_final.png new file mode 100644 index 000000000..004f8ef62 Binary files /dev/null and b/examples/two_material_dcb_beta/results/strain_final.png differ diff --git a/examples/two_material_dcb_beta/results/stress_final.png b/examples/two_material_dcb_beta/results/stress_final.png new file mode 100644 index 000000000..c457ea97b Binary files /dev/null and b/examples/two_material_dcb_beta/results/stress_final.png differ diff --git a/examples/two_material_dcb_beta/results/summary.json b/examples/two_material_dcb_beta/results/summary.json new file mode 100644 index 000000000..5577bd50b --- /dev/null +++ b/examples/two_material_dcb_beta/results/summary.json @@ -0,0 +1,28 @@ +{ + "schema_version": 2, + "problem": "DCB-style opening with a tough inclusion inside a weak bulk layer", + "solver_path": "schema-v2 heterogeneous staggered quasi-static AT2", + "materials": [ + "material_1", + "weak_midline", + "material_2" + ], + "n_nodes": 7889, + "n_elements": 15360, + "l0": 0.1, + "maximum_element_size": 0.017430609056700283, + "maximum_element_size_over_l0": 0.17430609056700283, + "maximum_element_edge_length": 0.04506939094330038, + "maximum_element_edge_length_over_l0": 0.4506939094330038, + "trajectory_format": "h5", + "accepted_steps": 120, + "cutbacks": 0, + "final_opening": 0.3, + "final_reaction_force": 0.6149522713694282, + "final_connected_crack_front_x": 2.0625, + "final_maximum_damage": 1.0, + "maximum_projected_damage_residual": 6.910926739149559e-06, + "all_steps_converged": true, + "runtime_seconds": 968.4388255419999, + "scope": "heterogeneous E/Gc AT2 teaching calculation; not ASTM D5528 or a calibrated bimaterial benchmark" +} diff --git a/examples/two_material_dcb_beta/results/uniform_layer_history.csv b/examples/two_material_dcb_beta/results/uniform_layer_history.csv new file mode 100644 index 000000000..0ada40378 --- /dev/null +++ b/examples/two_material_dcb_beta/results/uniform_layer_history.csv @@ -0,0 +1,124 @@ +accepted_step,attempt,load_factor,opening,reaction_force,maximum_damage,connected_crack_front_x,mechanics_iterations,mechanics_residual,damage_iterations,staggered_iterations,damage_increment,projected_damage_residual,cutbacks_so_far,wall_seconds,mean_damage_material_1,mean_damage_weak_midline,mean_damage_material_2 +1,1,0.008333333333333333,0.0025,0.5467058413510059,1.0,1.5,1,2.6446363768270565e-14,30,26,9.292839612262682e-06,5.949018653909899e-08,0,3.3112597910003387,0.0003451407509125937,0.08295023687417372,0.0002654012870438557 +2,2,0.016666666666666666,0.005,0.5051206524412047,1.0,1.5,1,6.117395405391955e-14,20,40,8.541102585080118e-06,6.514472831661844e-08,0,4.055774208998628,0.0003670029858512824,0.08489615443061624,0.00026656169407545825 +3,3,0.025,0.0075,0.42226176957641526,1.0,1.5,1,9.189115482428337e-14,20,41,8.99555677913444e-06,7.460016274510317e-08,0,4.214549874999648,0.0003855013581257977,0.08654826412588097,0.00027255496989943864 +4,4,0.03333333333333333,0.01,0.3702641396004126,1.0,1.5,1,1.499466681639148e-13,20,41,8.991886904397006e-06,7.914649837945098e-08,0,4.166834583000309,0.00040184827968040016,0.08795240681518604,0.0002974717556217821 +5,5,0.041666666666666664,0.012499999999999999,0.33796569602572823,1.0,1.5,1,1.6700567630074832e-13,10,41,9.28666572319603e-06,8.454388431694548e-08,0,4.13432633299999,0.00041718720654610977,0.08917313093596327,0.00036467690671985765 +6,6,0.05,0.015,0.3216217889383532,1.0,1.5,1,2.1434647744561176e-13,10,38,9.163893866070971e-06,8.22028197074165e-08,0,3.5837137080015964,0.00043250134649302466,0.09022233371388146,0.0004941906835484662 +7,7,0.058333333333333334,0.017499999999999998,0.3184488363026632,1.0,1.5,1,2.9750977886881085e-13,10,35,8.154578001184909e-06,7.532831333006973e-08,0,3.259172000000035,0.00044858225865407054,0.09111745880816234,0.0006906326416883879 +8,8,0.06666666666666667,0.02,0.3248673490465505,1.0,1.5,1,3.163470406733497e-13,10,32,9.98837755883386e-06,8.824491032517756e-08,0,2.746967333001521,0.00046611919015894255,0.09189771425251668,0.0009468871895238444 +9,9,0.075,0.0225,0.3376359837408113,1.0,1.5,1,3.7105634139825766e-13,10,28,9.583005605939832e-06,8.984179940621506e-08,0,2.438903707999998,0.0004855439711274739,0.09260601342167034,0.0012540916923781179 +10,10,0.08333333333333333,0.024999999999999998,0.3544986761844601,1.0,1.5,1,3.5524323756074265e-13,10,26,8.429824285838272e-06,7.744013776414538e-08,0,2.240482291999797,0.0005071303713449713,0.09327637471178912,0.0016053041566953222 +11,11,0.09166666666666666,0.027499999999999997,0.37396506173869826,1.0,1.5,1,4.70070785485371e-13,10,25,7.523022284794401e-06,6.375069117742216e-08,0,2.094952542000101,0.0005308963294144678,0.09393136106264084,0.001995935146046444 +12,12,0.1,0.03,0.39506574559796437,1.0,1.5,1,4.615685992556158e-13,10,22,8.886650901374082e-06,8.693585060864928e-08,0,1.8948683329999767,0.0005568702458022115,0.09458606240694767,0.002423027737936586 +13,13,0.10833333333333334,0.0325,0.41718325942687406,1.0,1.5,1,5.39413636919816e-13,10,21,8.395905097158263e-06,7.576116750791784e-08,0,1.7378842500002065,0.0005849810976813355,0.0952491700075095,0.00288452136589854 +14,14,0.11666666666666667,0.034999999999999996,0.4398907213807471,1.0,1.5,1,6.056613573633065e-13,10,19,9.161497209086988e-06,9.62231392377666e-08,0,1.4985428330001014,0.0006151138925676661,0.09592794019866666,0.0033784628796826367 +15,15,0.125,0.0375,0.46289794174503285,1.0,1.5,1,6.059713292361414e-13,10,18,9.80416164508835e-06,8.846239173132542e-08,0,1.4901912080003967,0.0006472239699708169,0.09662651839203511,0.003903239468402658 +16,16,0.13333333333333333,0.04,0.4859754639770622,1.0,1.5,1,7.077317995080731e-13,10,18,6.882584365763833e-06,6.693084989711773e-08,0,1.3689659169995139,0.0006812614923475944,0.0973489687795218,0.004457542087609807 +17,17,0.14166666666666666,0.042499999999999996,0.5089406633540043,1.0,1.5,1,7.062786310840025e-13,10,16,9.76076006875548e-06,1.0805771231275907e-07,0,1.2387347919993772,0.0007171868731324614,0.09809850803430428,0.0050400769627682186 +18,18,0.15,0.045,0.5316290372022051,1.0,1.5,1,7.10206650982665e-13,10,16,6.776936117613985e-06,7.24613354007031e-08,0,1.3017684160004137,0.0007548433258835851,0.09887836861790465,0.005650098961778043 +19,19,0.15833333333333333,0.047499999999999994,0.5539094838912731,1.0,1.5,1,7.756523561934801e-13,10,15,8.847595889482918e-06,8.485718237111195e-08,0,1.193583291998948,0.0007941195229540373,0.09968986669366561,0.0062866143168578284 +20,20,0.16666666666666666,0.049999999999999996,0.5756581325220642,1.0,1.5,1,7.38126489448214e-13,10,15,7.690637712665094e-06,6.838557922717037e-08,0,1.1909767080014717,0.000834918377814305,0.10053434345129311,0.006949093105975018 +21,21,0.175,0.0525,0.5967642402810536,1.0,1.5,1,8.413977809296738e-13,10,15,6.979935791684433e-06,6.696393443916815e-08,0,1.1287881249991187,0.0008771299327931825,0.10141309499471232,0.007636773233009604 +22,22,0.18333333333333332,0.05499999999999999,0.6171198842809534,1.0,1.5,1,8.627604337267898e-13,10,15,7.101684181276546e-06,6.843995039446105e-08,0,1.2834917079999286,0.0009206372853361505,0.10232770714617272,0.008348993072585563 +23,23,0.19166666666666665,0.057499999999999996,0.6366163843537569,1.0,1.5,1,9.52202450786011e-13,10,15,9.763129877549126e-06,7.429088496810343e-08,0,1.2798043330003566,0.0009653019525510088,0.10327913027646356,0.009085255587596593 +24,24,0.2,0.06,0.6551337494049283,1.0,1.5,1,9.391741248749793e-13,10,16,9.708667286889572e-06,5.636482318382985e-08,0,1.3055403749985999,0.0010109701209757335,0.10426870375023489,0.009845461457197785 +25,25,0.20833333333333334,0.0625,0.6725366737793241,1.0,1.5,1,1.1081662104062059e-12,10,18,7.638035179113878e-06,3.344195809856787e-08,0,1.4293719589986722,0.0010574587670393522,0.10529813153136472,0.010629850182650684 +26,26,0.21666666666666667,0.065,0.6886634331583895,1.0,1.5,1,1.1003020466583063e-12,10,20,7.433072118701034e-06,2.446922591631262e-08,0,1.5537193330001173,0.001104555709681329,0.10636996478771495,0.01143925811892018 +27,27,0.225,0.0675,0.703307681636336,1.0,1.5,1,1.0780432281440058e-12,10,23,7.410861510015465e-06,1.657088537915241e-08,0,1.805659707999439,0.0011519904850523194,0.10748743419581407,0.012276133584911007 +28,28,0.23333333333333334,0.06999999999999999,0.7161650376392227,1.0,1.5,1,1.2943472550488664e-12,10,27,9.280439901560023e-06,2.6443372191584102e-08,0,2.0918606669984,0.001199403464653694,0.10865605528153487,0.013145391594281271 +29,29,0.24166666666666667,0.0725,0.7267725946671,1.0,1.5,1,1.1881042530665534e-12,1,36,8.918723739204104e-06,1.6366245267503653e-07,0,2.786522458000036,0.0012463617115787075,0.1098831385666082,0.014053114789325956 +30,30,0.25,0.075,0.7336347365015847,1.0,1.5,1,1.3605539177915862e-12,1,80,7.89117268662487e-06,1.078979377610971e-07,0,12.884441041000173,0.00129141459700921,0.11120645209930045,0.015043187808114733 +31,31,0.2583333333333333,0.07749999999999999,0.7026179049337722,1.0,1.55,1,1.3762616792560375e-12,1,170,9.933116204341452e-06,2.0583683553443682e-07,0,15.279753875000097,0.0013428753176158014,0.11399163169236191,0.016582751234127027 +32,32,0.26666666666666666,0.08,0.6744953079967473,1.0,1.55,1,1.4187692589392789e-12,1,135,6.401028620484084e-07,3.092873487701986e-07,0,10.793888582998989,0.0013987173572027666,0.11627712342943652,0.017549780635876353 +33,33,0.275,0.0825,0.6003860889783856,1.0,1.6,1,1.5992036252951998e-12,1,117,6.544221264337402e-06,2.069352608106284e-07,0,11.010307333001037,0.001506868788634703,0.11980498586453019,0.018466352251016185 +34,34,0.2833333333333333,0.08499999999999999,0.5891643889982614,1.0,1.6,1,1.4846372645255545e-12,1,97,9.78458392264514e-06,1.548691364462295e-07,0,7.3722804589997395,0.001560880933737382,0.12088452887323481,0.018966163438743282 +35,35,0.2916666666666667,0.08750000000000001,0.5625990233503255,1.0,1.6500000000000001,1,1.5682903708881892e-12,1,109,9.671380648557104e-07,4.106121309008226e-07,0,9.300827417000619,0.00163538577431395,0.12247779674088201,0.019771248833011717 +36,36,0.3,0.09,0.5592441751512953,1.0,1.6500000000000001,1,1.5430582744219305e-12,1,46,9.177423577755306e-06,3.536928441278016e-07,0,4.049525250000443,0.0016842633230396474,0.12319873445166807,0.02037461491319978 +37,37,0.30833333333333335,0.0925,0.5597836394268546,1.0,1.6500000000000001,1,1.6922546927699627e-12,1,49,8.89390394309686e-06,2.6099753676902214e-07,0,4.379109040999538,0.0017300479837589044,0.12377211893168402,0.0209834346662924 +38,38,0.31666666666666665,0.09499999999999999,0.5593016548596447,1.0,1.6500000000000001,1,1.6686802564692017e-12,1,68,4.37704219480306e-06,7.057399613041859e-07,0,5.468812666000304,0.001778037185344858,0.12438401626748868,0.021687579084506393 +39,39,0.325,0.0975,0.5478176912249819,1.0,1.7000000000000002,1,1.7664352295461384e-12,1,85,4.300714145255569e-06,3.109789045684097e-07,0,7.097698917001253,0.0018442307138577608,0.12533021899483707,0.02255396756404131 +40,40,0.3333333333333333,0.09999999999999999,0.5483849693002646,1.0,1.7000000000000002,1,1.649941044882424e-12,10,54,9.770538067499501e-06,6.404739429088924e-08,0,3.9559329170006095,0.0018929272991234016,0.12587642108010136,0.023347820635156284 +41,41,0.3416666666666667,0.1025,0.5512929747622929,1.0,1.7000000000000002,1,1.687180536638997e-12,2,55,8.794969960201904e-06,4.435322935973109e-08,0,4.074770125000214,0.0019390038034429644,0.12635311876517807,0.024161306535888664 +42,42,0.35,0.105,0.5523229563152522,1.0,1.7000000000000002,1,1.8537490400373104e-12,2,89,9.827695725328489e-06,5.811549514512333e-08,0,5.9205255409997335,0.001988512922596774,0.1269094677582936,0.02510157904523086 +43,43,0.35833333333333334,0.1075,0.5453872178541291,1.0,1.75,1,1.981122617138723e-12,1,108,9.475459258223573e-06,3.652077404355588e-07,0,7.662291667000318,0.0020526289362583017,0.1277113010708084,0.02627504922146951 +44,44,0.36666666666666664,0.10999999999999999,0.5459817438559581,1.0,1.75,1,1.959711405606957e-12,1,46,2.2362620479832174e-06,8.181351249872404e-07,0,3.385681542000384,0.0021040667815130053,0.12825334728662158,0.027331100989040666 +45,45,0.375,0.11249999999999999,0.5492762232979571,1.0,1.75,1,2.2247034766825532e-12,1,56,9.230405464744074e-06,3.6420561393479887e-07,0,4.319274958001188,0.002152154454628799,0.1287115199613025,0.028351003642285613 +46,46,0.3833333333333333,0.11499999999999999,0.5527157067297384,1.0,1.75,1,2.0868690966937598e-12,1,54,9.60966714147471e-06,3.991968402131227e-07,0,3.7629658749992814,0.002201614044633607,0.12916962468815654,0.029398083688055607 +47,47,0.39166666666666666,0.1175,0.5546592365819377,1.0,1.75,1,2.293461092516798e-12,1,58,9.020249431168637e-06,3.5729562017071414e-07,0,4.698509125000783,0.002255106607321159,0.12966609837572685,0.030492820821866076 +48,48,0.4,0.12,0.550523159856692,1.0,1.8,1,2.21453256588028e-12,2,119,9.875945389370422e-06,8.670324708537412e-08,0,8.053103250000277,0.002321932845457249,0.13032290632999866,0.03182350573368042 +49,49,0.4083333333333333,0.1225,0.5495770850426726,1.0,1.8,1,2.174558349812658e-12,1,71,9.568040410856682e-06,4.4029416979674647e-07,0,5.275057333001314,0.00238283847332303,0.13092418993179916,0.03315053004124854 +50,50,0.4166666666666667,0.125,0.5521631858597003,1.0,1.8,1,2.458789860415048e-12,1,56,9.616632898001853e-06,4.3455730964900774e-07,0,4.156649333999667,0.002439767550354552,0.1315140805451172,0.03441289265047502 +51,51,0.425,0.1275,0.555153840724693,1.0,1.8,1,2.350736201361405e-12,1,61,9.823886982007757e-06,3.872079810072213e-07,0,4.180301042000792,0.002496104001576147,0.13212720630192476,0.0357530860156059 +52,52,0.43333333333333335,0.13,0.5562241107918946,1.0,1.8,1,2.619572971961281e-12,1,81,8.296021988041247e-06,7.248291739384016e-07,0,5.58603787499851,0.00255415485088261,0.1328198130557294,0.03740769933106997 +53,53,0.44166666666666665,0.13249999999999998,0.5415253074344977,1.0,1.85,1,2.516289391061417e-12,1,140,9.922165754128187e-06,3.399168409138698e-07,0,15.91212183299831,0.0026485025674555553,0.13399495793357555,0.040940469773963095 +54,54,0.45,0.135,0.5435011360769028,1.0,1.85,1,2.6567611938479023e-12,1,55,9.773280021607711e-06,4.847761246118756e-07,0,3.9873795000003156,0.002699380946137384,0.13452922904971543,0.042800571594022396 +55,55,0.4583333333333333,0.13749999999999998,0.5463992559885965,1.0,1.85,1,2.821822049404879e-12,1,38,7.924608605991423e-07,1.1942217733587265e-06,0,2.7100630830009322,0.0027523324495507327,0.13515672192604988,0.0445259682032054 +56,56,0.4666666666666667,0.13999999999999999,0.5484870025650264,1.0,1.85,1,2.6172679793752582e-12,1,48,5.9686425859517556e-06,1.2663239635527998e-06,0,3.6993688340007793,0.0028066830292637684,0.13583868707969945,0.046492457001917266 +57,57,0.475,0.1425,0.5300727187317065,1.0,1.9000000000000001,1,2.890717698297391e-12,1,151,5.157167586866684e-06,2.025601402650453e-07,0,17.062879875000363,0.0029151427478443116,0.13727388894529638,0.05298080585902291 +58,58,0.48333333333333334,0.145,0.5317068617708915,1.0,1.9000000000000001,0,2.6633948163138988e-12,1,42,6.983302824892235e-14,1.976714353257858e-06,0,8.14820191599938,0.002961395048202641,0.1377389017675851,0.055758850801999056 +59,59,0.49166666666666664,0.1475,0.5338459063884923,1.0,1.9000000000000001,1,3.071105430717017e-12,1,113,9.840511889014358e-06,2.6600299461891695e-07,0,6.627101000000039,0.0030134180153642046,0.13836637227549523,0.05833314809698667 +60,60,0.5,0.15,0.5344867951934951,1.0,1.9000000000000001,1,2.9740732867790082e-12,1,143,6.126399825001627e-06,1.5772265796708262e-07,0,8.22998833299971,0.0030684774269388354,0.139096842808116,0.06153707758118101 +61,61,0.5083333333333333,0.1525,0.516839126261113,1.0,1.9500000000000002,1,2.93001589057015e-12,1,120,4.020113430813765e-06,6.846306846244616e-07,0,11.628193958998963,0.003176326336783666,0.1404724723770221,0.07132856652671728 +62,62,0.5166666666666666,0.15499999999999997,0.5186316063814331,1.0,1.9500000000000002,1,3.099301356752764e-12,1,70,9.721712658450343e-06,3.88812830806525e-07,0,4.445707041000787,0.0032213803995237776,0.14090687982783562,0.07527594083388632 +63,63,0.525,0.1575,0.5200906592469146,1.0,1.9500000000000002,1,3.206561764145238e-12,1,93,6.892688937831792e-06,5.059320740910685e-07,0,5.647028957999282,0.0032719172652179713,0.14155706068722407,0.07891600225156589 +64,64,0.5333333333333333,0.16,0.5025308037043568,1.0,2.0,1,3.141746291437226e-12,1,238,9.957224773038398e-06,2.926716993762856e-07,0,20.701434249998783,0.0033827109358760556,0.1429028306478569,0.0931448931458299 +65,65,0.5416666666666666,0.16249999999999998,0.5039060263261541,1.0,2.0,0,7.218188391987038e-10,1,40,1.9263179940054442e-10,1.417739449387223e-06,0,7.168919040999754,0.0034268324624213828,0.1433112394861463,0.09826695691263052 +66,66,0.55,0.165,0.5053614543966591,1.0,2.0,1,3.5226335511054893e-12,1,106,9.765012033757792e-06,2.569479451802162e-07,0,6.142440624998926,0.0034747782216446826,0.1439236282230139,0.10280313759832276 +67,67,0.5583333333333333,0.1675,0.4774110684813001,1.0,2.0,1,3.128727437103602e-12,1,197,7.066008336664709e-06,3.411226297732274e-07,0,16.120275375000347,0.0037878757808729774,0.14940948918101235,0.1030604766185794 +68,68,0.5666666666666667,0.16999999999999998,0.48259276373394877,1.0,2.0,1,3.1611861244345307e-12,1,32,8.234736277201726e-06,9.186728573878965e-07,0,2.3685233329997573,0.0038217047017136277,0.14970071282903655,0.10309080328993593 +69,69,0.575,0.1725,0.48779727314437105,1.0,2.0,1,3.3492517893337305e-12,1,93,9.637287691988128e-06,3.098769534036255e-07,0,5.310325166999974,0.0038570106982651225,0.15000008680424384,0.10313197255936289 +70,70,0.5833333333333334,0.17500000000000002,0.4927742072555567,1.0,2.0,1,3.4263189853114123e-12,1,140,9.773159040382673e-06,3.549607910098931e-07,0,7.884007874999952,0.003893292595791928,0.15034394093956774,0.10318642846353489 +71,71,0.5916666666666667,0.1775,0.49715061673860095,1.0,2.0,1,3.2949119872536295e-12,1,132,9.976931901967134e-06,3.9265702984282356e-07,0,7.499569333000181,0.0039359551512766116,0.15076687760102683,0.10325876157774248 +72,72,0.6,0.18,0.5014404675330424,1.0,2.0,1,3.2961171060494455e-12,1,96,9.564592281297024e-06,4.895702261303674e-07,0,5.8584717080011615,0.003980051295269508,0.15119374805970767,0.10333941870977731 +73,73,0.6083333333333333,0.18249999999999997,0.5064013241639702,1.0,2.0,1,3.4457797635466647e-12,1,55,8.695771586797463e-06,5.415329314910182e-07,0,3.3340697920011735,0.004018362039067259,0.15152297214138388,0.10341638120112574 +74,74,0.6166666666666667,0.185,0.5112057275350419,1.0,2.0,1,3.5536822309094554e-12,1,90,9.856652940509747e-06,4.375975067258419e-07,0,5.288777707999543,0.004061728482636874,0.1518371724040261,0.10355712375803906 +75,75,0.625,0.1875,0.5155586165405235,1.0,2.0,1,3.668122431736894e-12,1,76,9.725172562147222e-06,5.709235600764276e-07,0,4.838439249999283,0.004108613292562768,0.15216037227022805,0.10390048964940139 +76,76,0.6333333333333333,0.18999999999999997,0.5187139956504009,1.0,2.0,1,3.4084193543827346e-12,1,80,9.691068126538305e-06,4.983299108759153e-07,0,5.07356400000026,0.004158023995386317,0.15253612996522767,0.10480327396590262 +77,77,0.6416666666666666,0.19249999999999998,0.5203690405653273,1.0,2.0,1,3.4956814782970813e-12,1,129,9.992609965370214e-06,3.639525047581147e-07,0,7.560751667000659,0.004211342396123438,0.1530028166414523,0.10650272662749515 +78,78,0.65,0.195,0.5062797616413095,1.0,2.0500000000000003,1,3.613978574838785e-12,1,155,9.231668773534984e-06,1.6364527190173943e-07,0,13.041474416999336,0.004299384982875997,0.1539001443572031,0.11858907464659252 +79,79,0.6583333333333333,0.19749999999999998,0.5082102169963181,1.0,2.0500000000000003,1,3.4184091701180427e-12,1,38,1.5562674829938672e-06,1.080997621278972e-06,0,2.62910783299958,0.004335980464950754,0.15419734740701918,0.12181369400400144 +80,80,0.6666666666666666,0.19999999999999998,0.5099785945278807,1.0,2.0500000000000003,1,3.6021677238647714e-12,1,197,9.675852237989169e-06,3.962067497723055e-07,0,11.137493000000177,0.004393313727394757,0.1547312096669516,0.12396543047249119 +81,81,0.675,0.2025,0.5119341933875268,1.0,2.0500000000000003,1,3.874216464689625e-12,1,60,8.747108463547093e-06,4.529726313970417e-07,0,4.683572375000949,0.004447801939043127,0.1552030777410343,0.1262882461156969 +82,82,0.6833333333333333,0.205,0.5136912826664021,1.0,2.0500000000000003,1,3.495238733030518e-12,1,91,9.858984673871696e-06,4.531339670392346e-07,0,5.282297125000696,0.004501027235503798,0.15564706140358547,0.1291044589469352 +83,83,0.6916666666666667,0.2075,0.512935403274607,1.0,2.0500000000000003,1,3.9131490943157e-12,1,268,3.49622142870043e-06,2.346881889344829e-06,0,15.227755457999592,0.004557298463602049,0.15615512230185447,0.13475526473488525 +84,84,0.7,0.21,0.49906410990231215,1.0,2.1,1,3.931651931732225e-12,1,166,9.833573895945413e-06,3.500687115482869e-07,0,15.094565166999018,0.0046540650843657685,0.1570947484338054,0.15219408322104075 +85,85,0.7083333333333334,0.2125,0.5011828698337661,1.0,2.1,1,3.9049595445413795e-12,1,37,6.170203907140959e-06,1.6103940717343708e-06,0,2.570711750000555,0.004688553413683145,0.15735077883067555,0.15622088290711855 +86,86,0.7166666666666667,0.215,0.5027905163271618,1.0,2.1,1,4.505508853363398e-12,1,96,9.978217559658553e-06,3.722723990938438e-07,0,5.838931874999616,0.004740540523562107,0.15775951041852188,0.1599132418671611 +87,87,0.725,0.2175,0.5040310485812259,1.0,2.1,1,4.215919594937579e-12,1,126,9.945745926609462e-06,2.820465188504528e-07,0,7.199959375000617,0.00479460366414573,0.1581928755460448,0.16398136960340257 +88,88,0.7333333333333333,0.21999999999999997,0.48848118987461364,1.0,2.15,1,4.374853656830719e-12,1,151,4.9877431129718985e-06,2.136152157800053e-06,0,14.062655499999892,0.004900626904429011,0.15923891184413944,0.18552881314993266 +89,89,0.7416666666666667,0.2225,0.4902306095354102,1.0,2.15,1,4.243273940332283e-12,1,46,8.249585459196851e-10,2.2238679970067177e-06,0,3.623089208998863,0.0049306726087521196,0.1594819007015489,0.19007828218590198 +90,90,0.75,0.22499999999999998,0.491669636077661,1.0,2.15,1,4.167448871887475e-12,1,95,9.80292808838712e-06,2.9804385819694364e-07,0,5.627705916000195,0.004982183453401115,0.15987814310290197,0.19416818238566363 +91,91,0.7583333333333333,0.22749999999999998,0.4931015791597162,1.0,2.15,1,4.496720654509335e-12,1,49,7.2616195866404e-06,1.8275886885278647e-07,0,3.1964172499992856,0.0050361396694392465,0.16031286513881116,0.1977068519231828 +92,93,0.7625,0.22874999999999998,0.49349921895507737,1.0,2.15,1,4.5074161318424384e-12,1,71,4.398792705306853e-06,1.0957284793172359e-07,1,4.428344792000644,0.005063922154197118,0.1605448911478429,0.19984026246007813 +93,95,0.7645833333333333,0.22937499999999997,0.49336221908598454,1.0,2.15,1,4.120676772267855e-12,1,232,9.999380120584433e-06,2.3535963916335298e-07,2,12.249859708001168,0.005078188462617666,0.1606701735076259,0.2013668568761578 +94,96,0.7666666666666666,0.22999999999999998,0.4916717696531827,1.0,2.15,1,4.539593751288735e-12,1,221,8.095780580474887e-06,3.1097772023088582e-06,2,11.90254433300106,0.005094732722494135,0.1608411162156299,0.20464276759140165 +95,97,0.775,0.23249999999999998,0.4795218676928701,1.0,2.2,1,4.843187952924977e-12,1,90,6.482911152017046e-06,1.955569233377547e-06,2,11.01428762499927,0.00518969447361476,0.16181509312525105,0.22233046317266267 +96,98,0.7833333333333333,0.235,0.4808896327372585,1.0,2.2,1,4.6371678690784795e-12,1,129,9.998918585329974e-06,3.017689006513968e-07,2,7.2768074159994285,0.005225108895368841,0.1621208138359499,0.22691536821674 +97,99,0.7916666666666666,0.2375,0.4823701618480524,1.0,2.2,1,4.180009876156326e-12,1,129,9.950476981601675e-06,5.118929494914983e-07,2,7.244017041999541,0.005278916717264096,0.16257323747113836,0.22971225075539933 +98,100,0.8,0.24,0.4834098756958472,1.0,2.2,1,4.834475417609194e-12,1,153,9.991854500346342e-06,2.33642966607049e-07,2,8.54650891700112,0.005333249598337268,0.16303848766849585,0.23313187514596956 +99,101,0.8083333333333333,0.2425,0.46914069931328284,1.0,2.25,1,4.7534206934254556e-12,1,254,9.928087070676384e-06,3.043438488845756e-07,2,19.158669624999675,0.005440706689960115,0.16430411555920738,0.25094073054492083 +100,102,0.8166666666666667,0.245,0.4709956619600605,1.0,2.25,1,4.562195326970274e-12,6,37,9.733669862677097e-06,2.905272108574483e-06,2,2.761252209000304,0.005466305946417912,0.16456255243912185,0.25406988142566267 +101,103,0.825,0.24749999999999997,0.47214569995941963,1.0,2.25,1,4.927116285007663e-12,1,69,8.352296130276216e-06,3.351395753599666e-07,2,4.165357166000831,0.005517465217095491,0.16502065373966787,0.2572172037117685 +102,104,0.8333333333333334,0.25,0.4733446551908206,1.0,2.25,1,4.608969910443576e-12,1,112,9.830189886428364e-06,5.822258577930551e-07,2,6.1586120419997314,0.005571101431050209,0.1655207539017307,0.25975996739940554 +103,105,0.8416666666666667,0.2525,0.47372431115331765,1.0,2.25,1,5.103363813760633e-12,1,127,3.7171420591564086e-06,1.1265628232139807e-06,2,7.1663480829993205,0.00562898099019256,0.1661206563788382,0.2626385077633063 +104,106,0.85,0.255,0.46139237395794486,1.0,2.3000000000000003,0,6.224439617845882e-10,1,122,7.314981953499e-11,3.617800436901686e-06,2,11.386763124999561,0.0057285176299430455,0.1674508497482111,0.27476971886903856 +105,107,0.8583333333333333,0.25749999999999995,0.462807381421848,1.0,2.3000000000000003,1,4.8340161456165165e-12,1,45,4.5145109872635203e-10,3.3413191865188166e-06,2,3.299430208000558,0.00575995813037626,0.1678011774134136,0.2773964321748688 +106,108,0.8666666666666667,0.26,0.4637331645805311,1.0,2.3000000000000003,1,5.5740832629147385e-12,1,114,3.976904203284448e-06,5.160024657651502e-06,2,8.001729332998366,0.005830204253057735,0.1685281317163356,0.27887078362758405 +107,109,0.875,0.2625,0.4654203459161029,1.0,2.3000000000000003,1,5.3994019713809105e-12,1,136,6.668363746853423e-06,5.382642374318625e-07,2,8.597293249998984,0.005894934437946285,0.16914669437380847,0.2798332863441037 +108,110,0.8833333333333333,0.26499999999999996,0.4669092907302289,1.0,2.3000000000000003,1,4.89197397905925e-12,1,43,7.717633111803401e-06,2.793569128650388e-06,2,2.9555387910004356,0.005942319716499147,0.16961611573950788,0.2813304102634668 +109,111,0.8916666666666666,0.26749999999999996,0.46761858150126084,1.0,2.3000000000000003,1,5.470779212969422e-12,1,125,7.671083200877504e-07,8.348815435306228e-07,2,7.090179917000569,0.006000055306649753,0.17021905217400218,0.2834097225991624 +110,112,0.9,0.27,0.4550474207631008,1.0,2.35,1,5.69898240777146e-12,1,205,9.15983366733819e-06,1.0143013553415335e-06,2,13.83438366700102,0.006104689894313289,0.17176818939005237,0.29206446218639687 +111,113,0.9083333333333333,0.27249999999999996,0.45646977514347997,1.0,2.35,1,5.694028236971357e-12,1,48,9.128382843170968e-06,1.3793448787671747e-06,2,3.056948082999952,0.006132890522473506,0.17210922561855663,0.29395453712023933 +112,115,0.9125,0.27375,0.457001629346246,1.0,2.35,1,5.670124615880908e-12,1,106,6.7662815872449045e-06,1.3477073425279874e-06,3,5.9449353750005685,0.00615713314729473,0.17238317031317532,0.29478529786618346 +113,116,0.9166666666666666,0.27499999999999997,0.45766407217679417,1.0,2.35,1,5.639700883021509e-12,1,92,6.951997845061619e-06,3.0037695660916903e-06,3,5.331448499999169,0.00618685188638473,0.17269684535049395,0.2953839466916843 +114,117,0.9249999999999999,0.27749999999999997,0.4590314820155833,1.0,2.35,1,6.057789905326339e-12,9,140,9.134236319430222e-06,3.4868626400749595e-06,3,16.771128375001354,0.0062653554257931215,0.17350800071935685,0.2965800760631017 +115,118,0.9333333333333333,0.27999999999999997,0.46066894534128205,1.0,2.35,1,6.178032989315346e-12,4,52,8.618980236962948e-06,3.558459729473425e-06,3,3.8785589580002124,0.006319168133463519,0.17401363159405378,0.2976533019921203 +116,119,0.9416666666666667,0.2825,0.462097331189846,1.0,2.35,1,6.119166464425613e-12,1,43,8.401702971227998e-06,3.977951819153502e-06,3,2.805362958000842,0.006370891808264633,0.17452446162422625,0.2988767468135495 +117,120,0.95,0.285,0.4631178870197493,1.0,2.35,1,6.19654204564333e-12,1,456,9.996484258811833e-06,6.373831570690618e-07,3,24.52910574999987,0.006438741509670536,0.17522023555617858,0.30046821396652157 +118,121,0.9583333333333334,0.2875,0.46359155544651764,1.0,2.35,1,6.345943765334832e-12,1,401,7.518784463478312e-06,3.1542776319521543e-06,3,22.68330245800098,0.006517886842065015,0.1760780124030047,0.30239572900881423 +119,122,0.9666666666666667,0.29,0.45259563743016623,1.0,2.4000000000000004,1,6.290190547101872e-12,1,254,9.784349817687499e-06,3.5010960618305203e-07,3,16.581954584000414,0.006615381531131498,0.17758274262181992,0.3069215829661562 +120,123,0.975,0.2925,0.45393630352659226,1.0,2.4000000000000004,1,6.37644300603134e-12,1,82,5.63553762666924e-06,2.158073367995424e-07,3,5.041625167001257,0.006650750164782844,0.17799301774022191,0.3081153104686457 +121,124,0.9833333333333333,0.295,0.45546822926789493,1.0,2.4000000000000004,1,6.39166394238265e-12,1,265,9.859454952132474e-06,3.346264952120185e-07,3,14.498269457999413,0.0067049015685611045,0.17852033095460484,0.30943046628414955 +122,125,0.9916666666666667,0.2975,0.4569848941506086,1.0,2.4000000000000004,1,6.357456559210837e-12,1,190,9.764161269187888e-06,4.046606230558437e-07,3,10.461227166000754,0.006756527213425692,0.17902535159921953,0.3107605471402066 +123,126,1.0,0.3,0.4584674467512238,1.0,2.4000000000000004,1,6.41659922791458e-12,1,347,3.6113212391608585e-06,7.030074108882109e-07,3,18.75619129199913,0.0068173494470058806,0.1796263859263525,0.31238567792402255 diff --git a/examples/two_material_dcb_beta/results/visual_manifest.json b/examples/two_material_dcb_beta/results/visual_manifest.json new file mode 100644 index 000000000..27da8ff1c --- /dev/null +++ b/examples/two_material_dcb_beta/results/visual_manifest.json @@ -0,0 +1,71 @@ +[ + { + "path": "initial_conditions.png", + "size_bytes": 38653, + "artifact_type": "image", + "width_px": 1440, + "height_px": 630 + }, + { + "path": "material_fields.png", + "size_bytes": 39255, + "artifact_type": "image", + "width_px": 1800, + "height_px": 684 + }, + { + "path": "damage_final.png", + "size_bytes": 81916, + "artifact_type": "image", + "width_px": 1440, + "height_px": 630 + }, + { + "path": "displacement_final.png", + "size_bytes": 91897, + "artifact_type": "image", + "width_px": 1440, + "height_px": 630 + }, + { + "path": "strain_final.png", + "size_bytes": 29247, + "artifact_type": "image", + "width_px": 1440, + "height_px": 630 + }, + { + "path": "stress_final.png", + "size_bytes": 73039, + "artifact_type": "image", + "width_px": 1440, + "height_px": 630 + }, + { + "path": "load_displacement.png", + "size_bytes": 51739, + "artifact_type": "image", + "width_px": 1152, + "height_px": 720 + }, + { + "path": "convergence_and_crack_front.png", + "size_bytes": 106734, + "artifact_type": "image", + "width_px": 1800, + "height_px": 720 + }, + { + "path": "damage_evolution.gif", + "size_bytes": 1673734, + "artifact_type": "animation" + }, + { + "path": "matched_control_comparison.png", + "artifact_type": "image" + }, + { + "path": "matched_control_damage.png", + "artifact_type": "image" + } +] diff --git a/pyproject.toml b/pyproject.toml index 8bb4ff860..1b1ec709f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -97,8 +97,8 @@ dev = [ "sphinx-copybutton>=0.5", "sphinxcontrib-mermaid>=2.0", ] -# Zarr is part of the core install because new trajectory and dataset -# workflows are Zarr-first. This extra is kept as a stable install alias. +# HDF5 is the default trajectory format. Zarr remains installed for existing +# stores and explicit opt-in output; this extra is a stable install alias. dataset = [ "zarr>=2.18,<3", "numcodecs>=0.13", diff --git a/requirements.txt b/requirements.txt index a77b8c343..e1bb6cb05 100644 --- a/requirements.txt +++ b/requirements.txt @@ -23,11 +23,11 @@ Pillow>=9.0 # apt install ffmpeg (Ubuntu/Debian) # If ffmpeg is not installed, animations fall back to GIF automatically. -# HDF5 output (GNO training data) +# HDF5 output (default single-file trajectory storage) h5py>=3.7 -# Zarr trajectory stores. Keep pinned to the v2 API until the reader/writer -# stack is migrated to Zarr v3. +# Explicit Zarr output and existing-store compatibility. Keep pinned to the +# v2 API until the reader/writer stack is migrated to Zarr v3. zarr>=2.18,<3 numcodecs>=0.13 diff --git a/src/phast/__init__.py b/src/phast/__init__.py index ecb3cf4a6..0e20eaf02 100644 --- a/src/phast/__init__.py +++ b/src/phast/__init__.py @@ -31,7 +31,7 @@ mechanics_solver : Displacement solvers (explicit, static, quasi-static, L-BFGS) staggered_solver : Orchestrator coupling mechanics + damage device : Device management and profiling -io_utils : VTU / Zarr / legacy H5 / CSV output +io_utils : HDF5 / VTU / CSV output; explicit Zarr support problem : Fluent Problem builder API adaptive : Adaptive mesh refinement (newest vertex bisection) """ diff --git a/src/phast/config/config.py b/src/phast/config/config.py index fc725970d..2ae10210d 100644 --- a/src/phast/config/config.py +++ b/src/phast/config/config.py @@ -421,8 +421,9 @@ class OutputConfig: h5: bool = False # Public spelling for enabling trajectory snapshots. trajectory: bool = False - # Preferred trajectory backend is Zarr; H5 is legacy compatibility. - trajectory_format: str = 'zarr' + # HDF5 keeps each trajectory in one file, including on synced storage. + # Directory-based Zarr output requires an explicit format selection. + trajectory_format: str = 'h5' # Snapshot cadence for trajectory outputs. h5_every: int = 20 vtu: bool = False diff --git a/src/phast/config/explain_config.py b/src/phast/config/explain_config.py index 719415122..54868e27b 100644 --- a/src/phast/config/explain_config.py +++ b/src/phast/config/explain_config.py @@ -122,14 +122,84 @@ def _yaml_declared_node_sets(cfg: Any) -> set[str]: return names +def _build_workflow_explanation(config_path: str) -> tuple[str, int]: + """Describe a schema-2 input without resolving geometry or running a solve.""" + from ..workflow import problem_spec_from_yaml + + try: + spec = problem_spec_from_yaml(config_path) + except (OSError, ValueError, TypeError, KeyError) as exc: + return f"Error in {config_path}: {exc}", 2 + + lines = [f"Config: {config_path}", f"Schema version: {spec.schema_version}", + f"Problem: {spec.name}"] + if spec.reference: + lines.append(f"Reference: {spec.reference}") + lines.extend(["", "Geometry and mesh"]) + if spec.geometry is not None: + lines.append(f" type: {spec.geometry.kind}; units: {spec.geometry.units}") + for key, value in spec.geometry.parameters.items(): + lines.append(f" {key}: {value}") + if spec.mesh is not None: + lines.append(f" mesh: {spec.mesh.path or spec.mesh.kind}") + for key, value in spec.mesh.parameters.items(): + lines.append(f" {key}: {value}") + + lines.extend(["", "Regions (declared selections, not resolved node/element sets)"]) + for region in spec.regions: + lines.append(f" {region.name}: {region.kind}; {region.selector}") + lines.extend(["", "Materials and assignments"]) + for material in spec.materials: + lines.append(f" {material.name}: {material.model}; region={material.region or ''}") + for key, value in material.parameters.items(): + lines.append(f" {key}: {value}") + lines.extend(["", "Initial conditions"]) + for initial in spec.initial_conditions: + lines.append(f" {initial.field}: region={initial.region}; value={initial.value}") + lines.extend(["", "Boundary conditions"]) + for boundary in spec.boundary_conditions: + lines.append( + f" {boundary.name or boundary.kind}: {boundary.kind}; " + f"region={boundary.region}; component={boundary.component}; value={boundary.value}" + ) + lines.extend(["", "Analysis steps"]) + for step in spec.analysis_steps: + lines.append(f" {step.name}: {step.kind}; controls={step.controls}") + lines.append(f" active boundary conditions: {', '.join(step.active_boundary_conditions) or ''}") + lines.extend(["", "Solver (requested)", f" type: {spec.solver.kind}"]) + for key, value in spec.solver.parameters.items(): + lines.append(f" {key}: {value}") + lines.extend(["", "Outputs", f" output_dir: {spec.outputs.directory or ''}"]) + for field in spec.outputs.fields: + lines.append(f" field {field.name}: every={field.every}; {field.parameters}") + for history in spec.outputs.history: + lines.append( + f" history {history.name}: every={history.every}; " + f"region={history.region}; component={history.component}" + ) + for visual in spec.outputs.postprocess: + lines.append(f" visual {visual.kind}: {visual.parameters}") + lines.extend([ + "", "Scope", + " Declared settings only: no mesh, solver, or output directory was created.", + " This summary does not confirm execution support, convergence, or physical accuracy.", + f' Check the requested execution route with: python -m phast run "{config_path}" --validate-only', + " Multi-material validation resolves the geometric mesh to check selections and assignments.", + ]) + return "\n".join(lines), 0 + + def build_explanation(config_path: str) -> tuple[str, int]: """Return ``(report, exit_code)`` for a YAML config path. - The command intentionally stops at ``load_config``. It does not call + Legacy inputs stop at ``load_config``; schema-2 inputs stop at the + declarative ``ProblemSpec``. The command does not call ``resolve_config`` because that may generate/load meshes and allocate solver objects, which is too heavy for a dry-run explanation command. """ raw, errors = validate_config_file(config_path) + if isinstance(raw, dict) and raw.get("schema_version", 1) in (2, "2"): + return _build_workflow_explanation(config_path) if errors: return format_errors(errors, config_path), 2 diff --git a/src/phast/config/run_config.py b/src/phast/config/run_config.py index 6c8605561..13647d2dc 100644 --- a/src/phast/config/run_config.py +++ b/src/phast/config/run_config.py @@ -127,14 +127,14 @@ def main(): parser.add_argument('--device', type=str, default=None) parser.add_argument('--h5', action='store_true', default=None) parser.add_argument('--trajectory', action='store_true', default=None, - help='Enable trajectory snapshots (Zarr). Alias for the ' + help='Enable trajectory snapshots (HDF5 by default). Alias for the ' 'output.trajectory / legacy --h5.') parser.add_argument('--trajectory-format', choices=['zarr', 'h5', 'both'], default=None, help='Trajectory backend for snapshots. Default is ' 'output.trajectory_format from YAML, normally ' - 'zarr. H5 is legacy compatibility.') + 'h5. Zarr and both require explicit selection.') parser.add_argument('--plots', action='store_true', default=None) parser.add_argument('--gif', action='store_true', default=None) parser.add_argument('--fast', action='store_true', default=None) @@ -180,6 +180,9 @@ def main(): raw_for_workflow = yaml.safe_load(fh) or {} except OSError: raw_for_workflow = {} + except yaml.YAMLError as exc: + print(f"error: cannot parse YAML: {exc}", file=sys.stderr) + sys.exit(2) if isinstance(raw_for_workflow, dict) and raw_for_workflow.get("schema_version", 1) in (2, "2"): from ..workflow import ( execution_plan_from_spec, @@ -189,12 +192,24 @@ def main(): ) from ..workflow.execution import WorkflowExecutionError + # Do not silently discard legacy CLI overrides at the v2 boundary. + unsupported_overrides = [ + key for key, value in vars(args).items() + if key not in {"config", "output_dir", "validate_only"} and value is not None + ] + if unsupported_overrides: + print( + "error: schema-v2 supports only --output_dir as a runtime override; " + "put these settings in the YAML: " + ", ".join(unsupported_overrides), + file=sys.stderr, + ) + sys.exit(2) try: spec = problem_spec_from_yaml(args.config) + issues = validate_problem_spec(spec) except Exception as exc: print(f"error: cannot compile schema-v2 workflow contract: {exc}", file=sys.stderr) sys.exit(2) - issues = validate_problem_spec(spec) if issues: for issue in issues: print(f"error: {issue.category}: {issue.message}", file=sys.stderr) @@ -211,7 +226,7 @@ def main(): print( "error: schema_version 2 workflow decks are currently " "executable only for promoted solid_mechanics examples " - "and supported quasi_static fracture specs; " + "and supported explicit/single-material or quasi_static fracture specs; " "use --validate-only or run an equivalent v1 compatibility YAML.", file=sys.stderr, ) @@ -471,9 +486,8 @@ def main(): plot_initial_conditions(mesh, mat, bcs, solver_cfg, save_path=os.path.join(output_dir, 'initial_conditions.png')) - # Trajectory snapshots. Zarr is the public default; H5 remains available - # for legacy postprocessors and paper artifacts. - trajectory_format = getattr(cfg.output, 'trajectory_format', 'zarr') + # HDF5 is the default. Zarr stores are created only on explicit request. + trajectory_format = getattr(cfg.output, 'trajectory_format', 'h5') if trajectory_format not in ('zarr', 'h5', 'both'): raise ValueError( "output.trajectory_format must be one of: zarr, h5, both") @@ -487,7 +501,7 @@ def main(): if trajectory_format in ('h5', 'both'): h5_path = os.path.join(output_dir, 'training_data.h5') h5f = init_h5(h5_path, mesh, mat) - print(f"H5 snapshots: {h5_path} (legacy compatibility)") + print(f"HDF5 snapshots: {h5_path}") # Determine step count. ``num_steps`` (YAML or --num_steps CLI) takes # precedence; only fall back to the CFL-derived n_steps = t_total/dt diff --git a/src/phast/result.py b/src/phast/result.py index b8321e5b6..1d8a79e2d 100644 --- a/src/phast/result.py +++ b/src/phast/result.py @@ -183,7 +183,11 @@ def mesh(self) -> dict[str, Any]: if isinstance(value, dict) and value: return dict(value) - trajectory_mesh = self._zarr_mesh_metadata() or self._h5_mesh_metadata() + trajectory_mesh = ( + self._h5_mesh_metadata() + if (self.path / "training_data.h5").is_file() + else self._zarr_mesh_metadata() + ) if trajectory_mesh: return trajectory_mesh @@ -356,16 +360,18 @@ def _fields(self) -> dict[str, set[str]]: def _field_sources(self) -> dict[str, tuple[str, set[str]]]: if self._field_source_cache is None: sources: dict[str, tuple[str, set[str]]] = {} - for source_kind, names in ( - ("zarr", self._discover_zarr_fields()), - ("h5", self._discover_h5_fields()), - ): - for raw_name in names: - reference = _reference_field_name(raw_name) - if reference not in sources: - sources[reference] = (source_kind, {raw_name}) - elif sources[reference][0] == source_kind: - sources[reference][1].add(raw_name) + # Select one store, rather than mixing current HDF5 fields with + # potentially older Zarr fields or requiring both backends. + if (self.path / "training_data.h5").is_file(): + source_kind, names = "h5", self._discover_h5_fields() + else: + source_kind, names = "zarr", self._discover_zarr_fields() + for raw_name in names: + reference = _reference_field_name(raw_name) + if reference not in sources: + sources[reference] = (source_kind, {raw_name}) + else: + sources[reference][1].add(raw_name) self._field_source_cache = sources return self._field_source_cache diff --git a/src/phast/solid_mechanics_runners/_common.py b/src/phast/solid_mechanics_runners/_common.py index 8c3ce2184..34c08628a 100644 --- a/src/phast/solid_mechanics_runners/_common.py +++ b/src/phast/solid_mechanics_runners/_common.py @@ -136,13 +136,30 @@ def write_run_lockfile( *, config: dict[str, Any], command: str, + trajectory_paths: list[Path] | None = None, ) -> None: - """Write the resolved public example config used for this run.""" + """Record the config and trajectories actually written by this run. + + Pass paths returned by this run's writers. Existing stores in a reused + output directory are not evidence that this run wrote a trajectory. + """ + paths = [Path(path) for path in (trajectory_paths or [])] + formats = set() + for path in paths: + if path.name == "training_data.h5" and path.is_file(): + formats.add("h5") + elif path.name == "training_data.zarr" and path.is_dir(): + formats.add("zarr") + else: + raise ValueError(f"Trajectory output is missing or unsupported: {path}") + actual_format = "both" if len(formats) == 2 else next(iter(formats), None) lockfile = { "schema_version": 1, "command": os.environ.get("PHAST_SOLID_MECH_COMMAND", command), "resolved_config": config, - "trajectory_format": "zarr", + "trajectory_format": actual_format, + "requested_trajectory_format": config.get("output", {}).get("trajectory_format", "h5"), + "trajectory_files": [path.name for path in paths], } (out_dir / "run_lockfile.json").write_text(json.dumps(lockfile, indent=2)) @@ -156,6 +173,59 @@ def _zarr_array(group: Any, name: str, data: Any) -> None: group.create_dataset(name, data=arr, shape=arr.shape, dtype=arr.dtype) +def write_solid_trajectory( + out_dir: Path, + *, + mesh: Any, + steps: list[dict[str, Any]], + fields: dict[str, Any], + trajectory_format: str = "h5", +) -> Path: + """Write stored solid histories to HDF5, or explicitly requested Zarr. + + Fields are step-major arrays with one entry per row in ``steps``. HDF5 + uses the per-step layout understood by the public Result reader. + """ + if trajectory_format == "zarr": + return write_solid_zarr(out_dir, mesh=mesh, steps=steps, fields=fields) + if trajectory_format != "h5": + raise ValueError("trajectory_format must be h5 or zarr") + + import h5py + + arrays = {} + for name, value in fields.items(): + if hasattr(value, "detach"): + value = value.detach().cpu().numpy() + array = np.asarray(value) + if array.ndim == 0 or array.shape[0] != len(steps): + raise ValueError(f"Field {name!r} must contain one entry per trajectory step") + arrays[name] = array + + path = out_dir / "training_data.h5" + with h5py.File(path, "w") as root: + root.attrs["format"] = "phast.solid_mechanics.trajectory.h5" + root.attrs["schema_version"] = 1 + root.attrs["num_steps"] = len(steps) + sim = root.create_group("simulation_data") + mesh_group = sim.create_group("mesh") + mesh_group.create_dataset("node_coordinates", data=mesh.nodes.detach().cpu().numpy()) + mesh_group.create_dataset("element_connectivity", data=mesh.elements.detach().cpu().numpy()) + step_group = sim.create_group("steps") + for index, row in enumerate(steps): + group = step_group.create_group(f"step_{int(row.get('step', index)):04d}") + for key, value in row.items(): + group.attrs[key] = value + for name, array in arrays.items(): + data = array[index] + compression = ( + {"compression": "gzip", "compression_opts": 4} + if data.ndim > 0 else {} + ) + group.create_dataset(name, data=data, **compression) + return path + + def write_solid_zarr( out_dir: Path, *, @@ -163,7 +233,7 @@ def write_solid_zarr( steps: list[dict[str, Any]], fields: dict[str, Any], ) -> Path: - """Write a compact tutorial trajectory store for solid-mechanics examples.""" + """Write a compact solid trajectory when Zarr is explicitly requested.""" import zarr path = out_dir / "training_data.zarr" diff --git a/src/phast/utils/io_utils.py b/src/phast/utils/io_utils.py index 75c65c1ec..a9d4d88dd 100644 --- a/src/phast/utils/io_utils.py +++ b/src/phast/utils/io_utils.py @@ -1,6 +1,6 @@ """ -Output utilities: VTU (ParaView), Zarr trajectory stores, CSV (history), -and legacy H5 compatibility helpers. +Output utilities: HDF5 trajectories, VTU (ParaView), CSV (history), +and explicitly selected Zarr trajectory stores. Includes helpers for GNO (Graph Neural Operator) training data export: - ``compute_edge_index`` converts triangle connectivity to PyG edge_index. @@ -461,11 +461,10 @@ def _write_snapshot_attrs(group, mesh, d, reaction_force=None, energies=None, def init_zarr(zarr_path: str, mesh, material): - """Create and initialize a Zarr trajectory store. + """Create and initialize an explicitly requested Zarr trajectory store. - The group/dataset hierarchy mirrors legacy ``training_data.h5`` so - existing field contracts stay stable while new runs use a chunked, - directory-backed store. + The group/dataset hierarchy mirrors ``training_data.h5`` so existing + field contracts remain compatible across the two storage formats. """ import zarr @@ -788,6 +787,9 @@ def init_h5(h5_path: str, mesh, material): import h5py h5f = h5py.File(h5_path, 'w') try: + h5f.attrs['format'] = 'phast.trajectory.h5' + h5f.attrs['writer'] = 'phast.io_utils.init_h5' + h5f.attrs['layouts'] = 'legacy_step_groups' mesh_grp = h5f.create_group('simulation_data/mesh') mesh_grp.create_dataset('node_coordinates', data=mesh.nodes.cpu().numpy()) diff --git a/src/phast/utils/postprocess_paper.py b/src/phast/utils/postprocess_paper.py index 9b4b24e2f..e2565fa73 100644 --- a/src/phast/utils/postprocess_paper.py +++ b/src/phast/utils/postprocess_paper.py @@ -348,8 +348,7 @@ def __init__(self, run_dir: str, dpi: int = None, fmt: str = 'png', log(f"Material: E={self.E}, nu={self.nu}, Gc={self.Gc}, l0={self.l0}, " f"split={self.energy_split}") - # Load trajectory store. Zarr is the current default; H5 remains - # supported for historical runs. + # Prefer HDF5. Continue to read explicitly selected or existing Zarr stores. h5_path = os.path.join(run_dir, 'training_data.h5') zarr_path = os.path.join(run_dir, 'training_data.zarr') self._h5 = None diff --git a/src/phast/workflow/adapters.py b/src/phast/workflow/adapters.py index 8d932e376..ddcc817b3 100644 --- a/src/phast/workflow/adapters.py +++ b/src/phast/workflow/adapters.py @@ -91,6 +91,8 @@ def _component_from_entry(entry: dict[str, Any]) -> int | None: component = entry.get("dof") if component is None: return None + if isinstance(component, bool): + raise ValueError("dof/component must not be a boolean") if isinstance(component, int): return component key = str(component).lower().strip() @@ -178,6 +180,15 @@ def _analysis_step_spec(loading: LoadingConfig, solver: SolverSettings) -> Analy dict(getattr(loading, "_workflow_controls", None) or _plain(loading)) ) kind = solver.solver_type + if not getattr(loading, "_workflow_controls", None): + defaults = LoadingConfig() + controls = { + key: value for key, value in controls.items() + if key in {"protocol", "num_steps", "dt"} + or getattr(defaults, key, object()) != value + } + if kind == "explicit" and loading.num_steps == 0 and loading.t_total > 0: + controls.pop("dt", None) name = getattr(loading, "_workflow_step_name", None) or loading.protocol or kind return AnalysisStepSpec( name=name, @@ -204,7 +215,11 @@ def _output_spec(config: OutputConfig) -> OutputSpec: workflow_fields = list(getattr(config, "_workflow_fields", []) or []) workflow_history = list(getattr(config, "_workflow_history", []) or []) - if config.trajectory and not workflow_fields: + has_trajectory = any( + item == "trajectory" if isinstance(item, str) else item.get("name") == "trajectory" + for item in workflow_fields + ) + if (config.trajectory or config.h5) and not has_trajectory: fields.append( FieldOutputSpec( name="trajectory", @@ -222,7 +237,7 @@ def _output_spec(config: OutputConfig) -> OutputSpec: ) for field in workflow_fields: if isinstance(field, str): - fields.append(FieldOutputSpec(name=field)) + fields.append(FieldOutputSpec(name=field, every=1)) else: item = dict(field or {}) name = item.pop("name") @@ -415,7 +430,7 @@ def _schema_v2_geometry(raw: dict[str, Any]) -> tuple[GeometrySpec | None, MeshS parameters = { key: value for key, value in geometry.items() - if key not in {"mesh_path", "type", "kind"} + if key not in {"mesh_path", "mesh_type", "type", "kind"} } return None, MeshSpec( kind=geometry.get("mesh_type", "file"), @@ -423,6 +438,8 @@ def _schema_v2_geometry(raw: dict[str, Any]) -> tuple[GeometrySpec | None, MeshS parameters=_drop_empty(parameters), ) kind = geometry.get("type") or geometry.get("kind") + if kind is None and geometry.get("primitives"): + kind = "primitive_dsl" if not kind: raise ValueError("schema_version 2 geometry requires type, kind, or mesh_path") parameters = dict(geometry.get("parameters") or {}) @@ -439,7 +456,7 @@ def _schema_v2_geometry(raw: dict[str, Any]) -> tuple[GeometrySpec | None, MeshS parameters[key] = value return GeometrySpec( kind=kind, - parameters=_drop_empty(parameters), + parameters=parameters, units=geometry.get("units", "mm"), primitives=geometry.get("primitives"), domain=geometry.get("domain"), @@ -484,12 +501,13 @@ def _schema_v2_materials( for name, entry in raw_materials.items(): data = dict(entry or {}) model = data.pop("model", "phase_field") + region = data.pop("region", None) params = data.pop("parameters", data) spec = MaterialSpec( name=name, model=model, - parameters=_drop_empty(dict(params or {})), - region=data.get("region"), + parameters=dict(params or {}), + region=region, ) materials_by_name[name] = spec material_entries.append(spec) @@ -503,7 +521,7 @@ def _schema_v2_materials( spec = MaterialSpec( name=name, model=model, - parameters=_drop_empty(dict(params or {})), + parameters=dict(params or {}), region=region, ) materials_by_name.setdefault(name, spec) @@ -539,7 +557,7 @@ def _schema_v2_initial_conditions(raw: dict[str, Any]) -> list[InitialConditionS field=field_name, region=region, value=value, - parameters=_drop_empty(data), + parameters=data, ) ) return specs @@ -562,7 +580,7 @@ def _schema_v2_boundary_conditions(raw: dict[str, Any]) -> list[BoundaryConditio region=region, component=component, value=value, - parameters=_drop_empty(data), + parameters=data, name=name, ) ) @@ -577,12 +595,12 @@ def _schema_v2_analysis_steps(raw: dict[str, Any]) -> list[AnalysisStepSpec]: kind = data.pop("type", data.pop("kind", None)) controls = dict(data.pop("controls", {}) or {}) active_bcs = tuple(data.pop("active_boundary_conditions", ()) or ()) - controls.update(_drop_empty(data)) + controls.update(data) steps.append( AnalysisStepSpec( name=name, kind=kind, - controls=_drop_empty(controls), + controls=controls, active_boundary_conditions=active_bcs, ) ) @@ -594,7 +612,15 @@ def _schema_v2_solver(raw: dict[str, Any], steps: list[AnalysisStepSpec]) -> Sol kind = data.pop("type", data.pop("kind", None)) if kind is None and steps: kind = steps[0].kind - return SolverSpec(kind=kind or "explicit", parameters=_drop_empty(data)) + return SolverSpec(kind=kind or "explicit", parameters=data) + + +def _schema_v2_cadence(value: Any) -> int: + if isinstance(value, str) and value.isdecimal(): + value = int(value) + if isinstance(value, bool) or not isinstance(value, int) or value < 1: + raise ValueError("output every must be a positive integer") + return value def _schema_v2_outputs(raw: dict[str, Any]) -> OutputSpec: @@ -602,8 +628,8 @@ def _schema_v2_outputs(raw: dict[str, Any]) -> OutputSpec: fields = [ FieldOutputSpec( name=entry["name"], - every=int(entry.get("every", 1)), - parameters=_drop_empty( + every=_schema_v2_cadence(entry.get("every", 1)), + parameters=dict( {key: value for key, value in entry.items() if key not in {"name", "every"}} ), ) @@ -613,7 +639,7 @@ def _schema_v2_outputs(raw: dict[str, Any]) -> OutputSpec: for entry in data.get("history", []) or []: item = dict(entry or {}) name = item.pop("name") - every = int(item.pop("every", 1)) + every = _schema_v2_cadence(item.pop("every", 1)) region = item.pop("region", None) component = _component_from_entry(item) item.pop("component", None) @@ -624,7 +650,7 @@ def _schema_v2_outputs(raw: dict[str, Any]) -> OutputSpec: every=every, region=region, component=component, - parameters=_drop_empty(item), + parameters=item, ) ) postprocess: list[PostprocessSpec] = [] @@ -640,7 +666,7 @@ def _schema_v2_outputs(raw: dict[str, Any]) -> OutputSpec: kind = item.pop("kind", None) if kind is None: kind = item.pop("name") - postprocess.append(PostprocessSpec(kind=kind, parameters=_drop_empty(item))) + postprocess.append(PostprocessSpec(kind=kind, parameters=item)) params = { key: value for key, value in data.items() @@ -651,15 +677,92 @@ def _schema_v2_outputs(raw: dict[str, Any]) -> OutputSpec: fields=fields, history=history, postprocess=postprocess, - parameters=_drop_empty(params), + parameters=params, ) +def _validate_schema_v2_shape(raw: dict[str, Any]) -> None: + """Check containers and discarded envelope keys before normalisation.""" + allowed = { + "schema_version", "name", "reference", "geometry", "regions", + "materials", "assignments", "initial_conditions", "boundary_conditions", + "analysis_steps", "solver", "outputs", + } + unknown = set(raw) - allowed + if unknown: + raise ValueError(f"Unknown schema-v2 top-level keys: {sorted(unknown)}") + for key in ("geometry", "solver", "outputs"): + if key in raw and not isinstance(raw[key], dict): + raise ValueError(f"{key} must be a mapping") + for key in ("regions", "materials"): + if key in raw and not isinstance(raw[key], (dict, list)): + raise ValueError(f"{key} must be a mapping or list") + for key in ("assignments", "initial_conditions", "boundary_conditions", "analysis_steps"): + if key in raw and ( + not isinstance(raw[key], list) + or any(not isinstance(item, dict) for item in raw[key]) + ): + raise ValueError(f"{key} must be a list of mappings") + for section in ("geometry", "solver"): + data = raw.get(section, {}) + if "type" in data and "kind" in data: + raise ValueError(f"{section}: specify type or kind, not both") + geometry = raw.get("geometry", {}) + if "mesh_path" in geometry and any( + key in geometry for key in ("type", "kind", "primitives", "domain", "named_groups", "parameters") + ): + raise ValueError("geometry.mesh_path cannot be combined with a generator or primitive geometry") + if "parameters" in geometry and not isinstance(geometry["parameters"], dict): + raise ValueError("geometry.parameters must be a mapping") + materials = raw.get("materials", {}) + entries = list(materials.values()) if isinstance(materials, dict) else materials + for entry in entries: + if not isinstance(entry, dict): + raise ValueError("materials must contain mappings") + if "parameters" in entry: + extra = set(entry) - {"name", "model", "region", "parameters"} + if extra or not isinstance(entry["parameters"], dict): + raise ValueError("material parameters must be a mapping without sibling parameters") + for entry in raw.get("assignments", []): + if set(entry) != {"material", "region"} or not entry.get("region"): + raise ValueError("assignments require only material and a nonempty region") + if raw.get("assignments"): + names = set(materials) if isinstance(materials, dict) else {e.get("name") for e in entries} + assigned = {entry["material"] for entry in raw["assignments"]} + if names != assigned: + raise ValueError("assignments must reference every declared material and no unknown material") + for entry in raw.get("analysis_steps", []): + if "type" in entry and "kind" in entry: + raise ValueError("analysis step: specify type or kind, not both") + if "controls" in entry and not isinstance(entry["controls"], dict): + raise ValueError("analysis step controls must be a mapping") + active = entry.get("active_boundary_conditions", []) + if not isinstance(active, list) or any(not isinstance(name, str) for name in active): + raise ValueError("active_boundary_conditions must be a list of names") + if set(entry.get("controls", {})) & (set(entry) - {"controls"}): + raise ValueError("analysis step controls must not be repeated as flat keys") + for entry in raw.get("boundary_conditions", []): + for first, second in (("type", "kind"), ("region", "nodes"), ("component", "dof")): + if first in entry and second in entry: + raise ValueError(f"boundary condition: specify {first} or {second}, not both") + outputs = raw.get("outputs", {}) + for key in ("fields", "history"): + value = outputs.get(key, []) + if not isinstance(value, list) or any(not isinstance(item, dict) for item in value): + raise ValueError(f"outputs.{key} must be a list of mappings") + visuals = outputs.get("visuals", {}) + if not isinstance(visuals, (dict, list)): + raise ValueError("outputs.visuals must be a mapping or list") + if isinstance(visuals, dict) and any(not isinstance(v, (bool, dict)) for v in visuals.values()): + raise ValueError("visual requests must be booleans or parameter mappings") + + def _schema_v2_spec( raw: dict[str, Any], *, source_path: str | None = None, ) -> ProblemSpec: + _validate_schema_v2_shape(raw) assignments = [dict(entry or {}) for entry in raw.get("assignments") or []] geometry, mesh = _schema_v2_geometry(raw) regions = _schema_v2_regions(raw, assignments) @@ -803,6 +906,8 @@ def problem_spec_to_schema_v2_dict(spec: ProblemSpec) -> dict[str, Any]: geometry = {"type": spec.mesh.kind} else: geometry = {"mesh_path": spec.mesh.path, "mesh_type": spec.mesh.kind} + if spec.source == "python:Problem": + geometry["mesh_path"] = str(Path(spec.mesh.path).expanduser().resolve()) geometry.update(spec.mesh.parameters) payload["geometry"] = _drop_empty(geometry) elif spec.geometry is not None: @@ -924,6 +1029,22 @@ def problem_spec_to_schema_v2_dict(spec: ProblemSpec) -> dict[str, Any]: for item in spec.outputs.postprocess ] outputs.update(spec.outputs.parameters) + if spec.solver.kind in {"explicit", "quasi_static"} and spec.source != "yaml:v2": + # Fluent builders contain legacy dataclass defaults. Export the actual + # requests, not a second set of aliases that can contradict them. + defaults = SolverSettings(solver_type=spec.solver.kind) + payload["solver"] = { + key: value for key, value in payload["solver"].items() + if key == "type" or getattr(defaults, key, object()) != value + } + consumed = {"output_dir", "h5", "trajectory", "trajectory_format", "h5_every", + "vtu", "vtu_every", "viz_format", "reaction_node_set", "reaction_component", + "plots", "gif", "gif_frames", "gif_fields", "animation_format"} + defaults_output = OutputConfig() + outputs = { + key: value for key, value in outputs.items() + if key not in consumed and getattr(defaults_output, key, object()) != value + } if outputs: payload["outputs"] = outputs return payload @@ -932,6 +1053,8 @@ def problem_spec_to_schema_v2_dict(spec: ProblemSpec) -> dict[str, Any]: def problem_specs_from_yaml(path: str | Path) -> list[ProblemSpec]: yaml_path = Path(path) raw = yaml.safe_load(yaml_path.read_text()) or {} + if not isinstance(raw, dict): + raise ValueError("top-level YAML must be a mapping") source_path = str(yaml_path) if raw.get("manifest_type") == "reproducibility_contract": return _validation_contract_specs(raw, source_path=source_path) diff --git a/src/phast/workflow/execution.py b/src/phast/workflow/execution.py index 41251c113..d0e50ef42 100644 --- a/src/phast/workflow/execution.py +++ b/src/phast/workflow/execution.py @@ -6,18 +6,24 @@ """ from __future__ import annotations -from dataclasses import dataclass +from dataclasses import dataclass, fields +import inspect +import math import os from pathlib import Path import subprocess import sys import tempfile +from typing import Any import yaml from ..solid_mechanics_runner import solid_example_id, _validate_solid_mechanics_config from ..config.config import OutputConfig as LegacyOutputConfig from ..config.config import SolverSettings as LegacySolverSettings +from ..config.config import MaterialConfig, get_geometry_registry +from ..config.config_validation import validate_config +from ..utils.units import MATERIAL_OVERRIDE_KINDS, BOUNDARY_VALUE_QUANTITY_KINDS, parse_quantity from .capabilities import CapabilityIssue, validate_problem_spec_capabilities from .specs import ProblemSpec @@ -132,6 +138,21 @@ def execution_plan_from_spec(spec: ProblemSpec) -> WorkflowExecutionPlan: detail = "; ".join(issue.message for issue in issues) raise WorkflowExecutionError(f"ProblemSpec has unsupported capabilities: {detail}") + if spec.source == "yaml:v2" and spec.solver.kind in _RUN_CONFIG_SOLVERS: + bridge_issues = _fracture_bridge_issues(spec) + if bridge_issues: + raise WorkflowExecutionError("; ".join(bridge_issues)) + if len(spec.materials) > 1 and spec.solver.kind == "quasi_static": + from .multimaterial_fracture import ( + MultimaterialWorkflowError, + validate_multimaterial_fracture_spec, + ) + + try: + validate_multimaterial_fracture_spec(spec) + except MultimaterialWorkflowError as exc: + raise WorkflowExecutionError(str(exc)) from exc + step_kinds = tuple(step.kind for step in spec.analysis_steps) python_solid_issues = ( _python_solid_mechanics_bridge_issues(spec) @@ -146,7 +167,7 @@ def execution_plan_from_spec(spec: ProblemSpec) -> WorkflowExecutionPlan: spec.solver.kind == "solid_mechanics" and _solid_mechanics_example_id_from_spec(spec) is not None ) - or _schema_v2_quasistatic_fracture_supported(spec) + or _schema_v2_fracture_supported(spec) ) if spec.source == "python:Problem" and spec.source_path is None: direct_execution_supported = ( @@ -216,6 +237,12 @@ def run_problem_spec( This is a compatibility bridge, not a new solver adapter. Python-built solid-mechanics specs are lowered to the existing YAML runner. """ + if spec.source == "yaml:v2": + from .validation import validate_problem_spec + + issues = validate_problem_spec(spec) + if issues: + raise WorkflowExecutionError("; ".join(issue.message for issue in issues)) plan = execution_plan_from_spec(spec) if spec.source_path is None: if ( @@ -243,7 +270,7 @@ def run_problem_spec( if spec.source == "yaml:v2" and not validate_only: if plan.route == "solid_mechanics_runner" and plan.direct_execution_supported: return _run_schema_v2_solid_mechanics_spec(spec, output_dir=output_dir) - if plan.route == "run_config" and _schema_v2_quasistatic_fracture_supported(spec): + if plan.route == "run_config" and _schema_v2_fracture_supported(spec): return _run_schema_v2_fracture_spec(spec, output_dir=output_dir) else: raise WorkflowExecutionError( @@ -386,6 +413,335 @@ def _schema_v2_quasistatic_fracture_supported(spec: ProblemSpec) -> bool: ) +def _schema_v2_fracture_supported(spec: ProblemSpec) -> bool: + return _schema_v2_quasistatic_fracture_supported(spec) or ( + spec.source == "yaml:v2" + and spec.solver.kind == "explicit" + and len(spec.materials) == 1 + and spec.materials[0].model == "phase_field" + and len(spec.analysis_steps) == 1 + and spec.analysis_steps[0].kind == "explicit" + and bool(spec.boundary_conditions) + ) + + +def _finite_quantity(value: Any, quantity: str | None = None) -> float: + if isinstance(value, bool) or value is None: + raise ValueError("a finite numeric value is required") + number = parse_quantity(value, quantity) if quantity else float(value) + if not math.isfinite(number): + raise ValueError("a finite numeric value is required") + return number + + +def _material_domain_issue(spec: ProblemSpec) -> str | None: + """Accept a selected external domain only after checking full coverage.""" + material = spec.materials[0] + if not material.region: + return None + region = next((r for r in spec.regions if r.name == material.region), None) + message = "a single material assignment must cover the full domain" + if region is None or region.kind != "domain": + return message + if not region.selector: + return None + aliases = {"from_mesh", "mesh_group", "physical_group", "element_set"} + if spec.mesh is None or not spec.mesh.path or len(region.selector) != 1 or not set(region.selector) <= aliases: + return message + "; selected domains require an external mesh element group" + from ..mesh_inspection import inspect_mesh + + path = Path(spec.mesh.path).expanduser() + if not path.is_absolute(): + base = Path(spec.source_path).resolve().parent if spec.source_path else Path.cwd() + path = base / path + try: + summary = inspect_mesh(path) + total = sum(int(cell["count"]) for cell in summary["cells"] if cell["type"] == "triangle") + if not total or any(cell["type"] not in {"triangle", "line", "vertex"} for cell in summary["cells"]): + return message + "; the bounded adapter requires a 2D T3 mesh" + external = next(iter(region.selector.values())) + group = summary["named_groups"].get(external) + if group is not None: + counts = group["cell_counts"] if group["dimension"] == 2 else {} + else: + counts = summary["cell_sets"].get(external, {}) + if counts.get("triangle", 0) != total: + return message + f"; mesh group {external!r} does not contain all {total} elements" + except (OSError, ValueError, TypeError, KeyError) as exc: + return message + f"; cannot verify mesh group: {exc}" + return None + + +def _fracture_bridge_issues(spec: ProblemSpec) -> tuple[str, ...]: + """Reject choices that the single-material compatibility runner discards. + + Multimaterial quasi-static execution retains its separate existing contract. + Validation here does not create a mesh, solver, predictor, or checkpoint. + """ + if len(spec.materials) > 1 and spec.solver.kind == "quasi_static": + return () + issues: list[str] = [] + if spec.solver.kind not in {"explicit", "quasi_static"}: + issues.append("schema-v2 fracture requires explicit or quasi_static") + if len(spec.materials) != 1: + issues.append("schema-v2 explicit fracture requires exactly one material") + if len(spec.analysis_steps) != 1: + issues.append("single-material fracture requires exactly one analysis step") + if issues: + return tuple(issues) + step = spec.analysis_steps[0] + if step.kind != spec.solver.kind: + issues.append("analysis step type must match solver.type") + if not spec.boundary_conditions: + issues.append("fracture requires boundary_conditions") + material = spec.materials[0] + if material.model != "phase_field": + issues.append("fracture requires material model phase_field") + regions = {region.name: region for region in spec.regions} + domain_issue = _material_domain_issue(spec) + if domain_issue: + issues.append(domain_issue) + alias_keys = {"from_mesh", "mesh_group", "physical_group", "node_set", "element_set"} + for region in spec.regions: + if region.selector and ( + len(region.selector) != 1 + or not set(region.selector) <= alias_keys + or not all(isinstance(v, str) and v for v in region.selector.values()) + ): + issues.append(f"region {region.name!r}: single-material execution requires a mesh-group alias") + if spec.geometry is not None and spec.mesh is not None: + issues.append("specify geometry or mesh, not both") + if spec.geometry is not None: + geometry = spec.geometry + if geometry.primitives: + if geometry.kind != "primitive_dsl" or set(geometry.parameters) - {"mesh"}: + issues.append("primitive geometry accepts only its mesh refinement parameters") + else: + if geometry.units != "mm": + issues.append("built-in geometry requires units: mm") + if geometry.domain or geometry.named_groups: + issues.append("domain and named_groups require primitive geometry") + registry = get_geometry_registry() + generator = registry.get(geometry.kind) + if generator is None or geometry.kind == "rectangular_sent_q4_structured": + issues.append("single-material schema-v2 geometry requires a supported 2D T3 generator") + elif set(geometry.parameters) - set(inspect.signature(generator).parameters): + issues.append("unsupported geometry parameters for the selected generator") + if geometry.parameters.get("order", 1) != 1: + issues.append("only first-order 2D fracture elements are supported") + if geometry.kind == "rectangular_sent_liu_structured" and "h_coarse" in geometry.parameters: + issues.append("the structured SENT generator uses h_crack, not h_coarse") + if spec.mesh is not None and ( + not spec.mesh.path or spec.mesh.parameters or spec.mesh.kind not in {"file", "external"} + ): + issues.append("external mesh execution requires a path without extra mesh parameters") + + known_material = {item.name for item in fields(MaterialConfig)} - {"preset", "overrides"} + if set(material.parameters) - known_material: + issues.append("unsupported material parameters") + for key, value in material.parameters.items(): + if key in MATERIAL_OVERRIDE_KINDS and value is not None: + try: + number = parse_quantity(value, MATERIAL_OVERRIDE_KINDS[key]) + if not math.isfinite(number) or ( + key in {"E", "Gc", "l0", "rho"} and number <= 0 + ) or (key == "nu" and not -1 < number < 0.5): + issues.append(f"material.{key} must be finite and within its physical range") + except (TypeError, ValueError): + issues.append(f"material.{key} has an invalid value or unit") + if material.parameters.get("kinematics", "small_strain") not in {"small_strain", None}: + issues.append("only small_strain kinematics is supported by this fracture adapter") + if material.parameters.get("pf_model", "AT2") not in {"AT1", "AT2"}: + issues.append("this fracture adapter supports AT1 or AT2, not other material models") + if material.parameters.get("energy_split", "spectral") not in {"spectral", "amor", "isotropic"}: + issues.append("this fracture adapter supports spectral, amor, or isotropic energy_split") + + solver = spec.solver.parameters + defaults = LegacySolverSettings(solver_type=spec.solver.kind) + if solver.get("damage_update", "classical") != "classical" or any( + solver.get(key) for key in ("damage_predictor", "damage_checkpoint", "damage_predictor_options") + ): + issues.append("learned damage execution is not supported by this schema-v2 adapter") + if solver.get("adaptive_dt", False): + issues.append("adaptive_dt is unsupported by the fixed-time CLI loading/output schedule") + try: + if not 0 < _finite_quantity(solver.get("dt_safety", defaults.dt_safety)) <= 1: + issues.append("solver.dt_safety must be in (0, 1]") + except (TypeError, ValueError): + issues.append("solver.dt_safety must be positive and finite") + for key, value in _coerce_legacy_values(dict(solver)).items(): + if isinstance(value, float) and not math.isfinite(value): + issues.append(f"solver.{key} must be finite") + if spec.solver.kind == "explicit": + if solver.get("time_integrator", "central_difference") not in {"central_difference", "verlet", "newmark"}: + issues.append("explicit execution requires the central_difference (Velocity-Verlet) integrator") + unused = {"backend", "static_tol", "static_max_iter", "max_stagger", "stagger_tol", + "stagger_criterion", "stagger_norm", "anderson_depth", "adaptive_stagger_tol", "rho_inf"} + if any(key in solver and solver[key] != getattr(defaults, key) for key in unused): + issues.append("quasi-static/implicit solver settings are not used by explicit dynamics") + else: + unused = {"time_integrator", "rho_inf", "dt_safety", "damage_every", "fresh_d_in_corrector", + "damping_ratio_max", "adaptive_dt_d_threshold"} + if any(key in solver and solver[key] != getattr(defaults, key) for key in unused): + issues.append("dynamic solver settings are not used by quasi_static") + controls = _coerce_legacy_values(step.controls) + count = controls.get("num_steps", 0) + if isinstance(count, bool) or not isinstance(count, int) or count < 0: + issues.append("controls.num_steps must be a nonnegative integer") + if controls.get("protocol", "simple") != "simple": + issues.append("schema-v2 single-material execution currently requires protocol: simple") + allowed_controls = {"protocol", "num_steps", "dt"} + if spec.solver.kind == "explicit": + allowed_controls |= {"t_total", "ramp_type", "t_ramp", "v0"} + count = controls.get("num_steps", 0) + if not count and not controls.get("t_total", 0): + issues.append("explicit controls require num_steps with dt, or a positive t_total") + if count and "dt" not in controls: + issues.append("explicit num_steps requires dt; omit num_steps and set t_total for automatic CFL stepping") + if count and controls.get("t_total", 0): + issues.append("specify num_steps or t_total, not both") + if not count and "dt" in controls: + issues.append("t_total-based automatic CFL stepping does not use controls.dt") + if "dt" in controls and "dt_safety" in solver: + issues.append("choose controls.dt or solver.dt_safety for automatic CFL stepping, not both") + ramp = controls.get("ramp_type", "constant") + if ramp != "constant" and not controls.get("t_ramp", 0): + issues.append("nonconstant loading requires a positive t_ramp") + if ramp == "constant" and controls.get("t_ramp", 0): + issues.append("constant loading does not use t_ramp") + if ramp != "velocity_impact" and controls.get("v0", 0): + issues.append("v0 is only used by velocity_impact loading") + elif not controls.get("num_steps", 0) or "dt" not in controls: + issues.append("quasi_static controls require positive num_steps and load-factor increment dt") + if set(controls) - allowed_controls: + issues.append("unsupported analysis step controls") + for key in ("dt", "t_total", "t_ramp"): + if key in controls: + try: + value = parse_quantity(controls[key], "time") if isinstance(controls[key], str) else controls[key] + if isinstance(value, bool) or not math.isfinite(value) or value <= 0: + issues.append(f"controls.{key} must be positive and finite") + except (TypeError, ValueError): + issues.append(f"controls.{key} must be a valid numeric value") + + allowed_bc_parameters = { + "fix": set(), "prescribe": set(), "neumann": set(), "pf_dirichlet": set(), + "traction": {"ramp_type", "t_ramp", "t_hold"}, "symmetry": {"axis"}, + "rigid_connector": {"master", "dofs", "prescribe", "rotation_free"}, + } + for bc in spec.boundary_conditions: + if set(_legacy_bc_parameters(bc.parameters)) - allowed_bc_parameters.get(bc.kind, set()): + issues.append(f"boundary condition {bc.name!r} has parameters unused by {bc.kind}") + if bc.kind in {"fix", "prescribe", "traction", "neumann"} and bc.component not in {0, 1}: + issues.append(f"boundary condition {bc.name!r} requires dof x or y") + if bc.kind == "fix" and bc.value not in {None, 0, 0.0}: + issues.append("fix uses zero displacement; use prescribe for a nonzero value") + if bc.kind in {"symmetry", "rigid_connector", "pf_dirichlet"} and bc.component is not None: + issues.append(f"{bc.kind} does not use component/dof") + if bc.kind in {"symmetry", "rigid_connector"} and bc.value not in {None, 0, 0.0}: + issues.append(f"{bc.kind} does not use value") + if bc.kind in {"fix", "prescribe", "traction", "neumann", "pf_dirichlet"}: + try: + value = _finite_quantity(0.0 if bc.value is None else bc.value, BOUNDARY_VALUE_QUANTITY_KINDS.get(bc.kind)) + if bc.kind == "pf_dirichlet" and not 0 <= value <= 1: + issues.append("pf_dirichlet damage value must be within [0, 1]") + except (TypeError, ValueError): + issues.append(f"boundary condition {bc.name!r} requires a finite value with valid units") + if bc.kind == "symmetry" and bc.parameters.get("axis") not in {"x", "y"}: + issues.append("symmetry requires axis: x or y") + if bc.kind == "rigid_connector": + master = bc.parameters.get("master") + if not isinstance(master, str) or master not in regions: + issues.append("rigid_connector requires master to name a declared mesh region") + dofs = bc.parameters.get("dofs", ["x", "y"]) + allowed_dofs = {"x", "y", 0, 1} + if not isinstance(dofs, list) or not dofs or any( + isinstance(dof, bool) or not isinstance(dof, (str, int)) or dof not in allowed_dofs for dof in dofs + ): + issues.append("rigid_connector dofs must be a nonempty list of x/y components") + prescribed = bc.parameters.get("prescribe", {}) + if not isinstance(prescribed, dict): + issues.append("rigid_connector prescribe must be a component mapping") + else: + for component, value in prescribed.items(): + try: + if isinstance(component, bool) or component not in allowed_dofs: + raise ValueError("invalid component") + _finite_quantity(value, "length") + except (TypeError, ValueError): + issues.append("rigid_connector prescribe requires x/y components and finite displacements") + if bc.kind == "traction": + ramp = bc.parameters.get("ramp_type", "constant") + if ramp != "constant": + try: + if _finite_quantity(bc.parameters.get("t_ramp"), "time") <= 0: + raise ValueError("nonpositive ramp") + except (TypeError, ValueError): + issues.append("nonconstant traction requires a positive finite t_ramp") + if spec.solver.kind != "explicit" and bc.parameters.get("ramp_type", "constant") != "constant": + issues.append("quasi_static traction uses the global load schedule, not a per-BC time ramp") + for initial in spec.initial_conditions: + if initial.field != "damage" or initial.parameters or not initial.region: + issues.append("initial_conditions support only damage on a named mesh region") + if initial.value is not None and ( + not isinstance(initial.value, (int, float)) or isinstance(initial.value, bool) + or not 0 <= initial.value <= 1 + ): + issues.append("initial damage value must be within [0, 1]") + + trajectory = next((f for f in spec.outputs.fields if f.name == "trajectory"), None) + for field in spec.outputs.fields: + if field.name == "trajectory": + if set(field.parameters) - {"format"} or field.parameters.get("format", "h5") not in {"h5", "zarr", "both"}: + issues.append("trajectory accepts only format: h5, zarr, or both") + elif field.name == "vtu": + issues.append("vtu field writing is not implemented by the compatibility CLI loop") + elif trajectory is None or field.every != trajectory.every or field.parameters: + issues.append("stored fields require a trajectory with the same cadence and no extra parameters") + reactions = [h for h in spec.outputs.history if h.name in {"reaction", "reaction_force", "load_displacement"}] + if len(reactions) > 1: + issues.append("the compatibility runner supports one reaction history selection") + for history in spec.outputs.history: + if history.every != 1 or history.parameters: + issues.append("history outputs support every: 1 and no extra parameters") + if history in reactions: + if not history.region or history.component not in {0, 1}: + issues.append("reaction history requires a region and dof x or y") + elif history.region is not None or history.component is not None: + issues.append("only reaction histories accept a region/component") + for item in spec.outputs.postprocess: + if item.kind not in {"plots", "animation", "initial_conditions", "damage_final"}: + issues.append(f"unsupported postprocess request {item.kind!r}") + elif item.kind == "animation": + if trajectory is None: + issues.append("animation requires trajectory output") + if set(item.parameters) - {"format", "frames", "fields"}: + issues.append("animation supports only format, frames, and fields") + elif item.parameters: + issues.append(f"{item.kind} does not accept parameters") + output_defaults = LegacyOutputConfig() + supported_output_parameters = { + "directory", "output_dir", "print_every", "profile", "h5", "trajectory", + "trajectory_format", "h5_every", "reaction_node_set", "reaction_component", + "plots", "gif", "gif_frames", "gif_fields", "animation_format", + "animation_renderer", "animation_raster_width", + } + if any( + key not in supported_output_parameters and getattr(output_defaults, key, object()) != value + for key, value in spec.outputs.parameters.items() + ): + issues.append("unsupported output parameters for the single-material CLI runner") + + if not issues: + payload = _fracture_legacy_yaml(spec) + issues.extend(f"{error.path}: {error.message}" for error in validate_config(payload)) + # The legacy validator checks these enums/ranges in overrides only. + issues.extend(f"{error.path}: {error.message}" for error in validate_config( + {"material": {"overrides": material.parameters}} + )) + return tuple(issues) + + def _quasistatic_fracture_supported(spec: ProblemSpec) -> bool: return ( spec.solver.kind == "quasi_static" @@ -415,6 +771,10 @@ def _legacy_fracture_geometry(spec: ProblemSpec) -> dict: "domain": spec.geometry.domain, "named_groups": spec.geometry.named_groups, } + if spec.geometry.primitives: + payload.pop("type") + payload.pop("parameters") + payload["mesh"] = spec.geometry.parameters.get("mesh") return _coerce_legacy_values( {key: value for key, value in payload.items() if value not in (None, {}, [])} ) @@ -494,6 +854,8 @@ def _legacy_fracture_boundary_conditions(spec: ProblemSpec) -> list[dict]: "value": bc.value if bc.value is not None else 0.0, } entry.update(_legacy_bc_parameters(bc.parameters)) + if "master" in entry: + entry["master"] = _legacy_region_name(spec, entry["master"]) lowered.append( _coerce_legacy_values( {key: value for key, value in entry.items() if value is not None} @@ -529,6 +891,7 @@ def _legacy_fracture_output(spec: ProblemSpec) -> dict: } if spec.outputs.directory is not None: output["output_dir"] = spec.outputs.directory + output.pop("directory", None) for field in spec.outputs.fields: if field.name == "trajectory": output["trajectory"] = True @@ -542,7 +905,7 @@ def _legacy_fracture_output(spec: ProblemSpec) -> dict: if "format" in field.parameters: output["viz_format"] = field.parameters["format"] for history in spec.outputs.history: - if history.name in {"reaction", "reaction_force"}: + if history.name in {"reaction", "reaction_force", "load_displacement"}: output["reaction_node_set"] = _legacy_region_name(spec, history.region) output["reaction_component"] = history.component for postprocess in spec.outputs.postprocess: @@ -590,6 +953,11 @@ def _quasistatic_fracture_legacy_yaml(spec: ProblemSpec) -> dict: "fracture workflow execution currently supports only quasi_static " "phase-field specs that lower cleanly to v1 run_config." ) + return _fracture_legacy_yaml(spec) + + +def _fracture_legacy_yaml(spec: ProblemSpec) -> dict[str, Any]: + """Normalise a supported fracture spec without duplicating a solver loop.""" return { "schema_version": 1, "name": spec.name, @@ -610,7 +978,9 @@ def _schema_v2_fracture_legacy_yaml(spec: ProblemSpec) -> dict: raise WorkflowExecutionError( "schema-v2 fracture execution requires a schema-v2 YAML ProblemSpec." ) - return _quasistatic_fracture_legacy_yaml(spec) + if not _schema_v2_fracture_supported(spec): + raise WorkflowExecutionError("unsupported schema-v2 fracture execution route") + return _fracture_legacy_yaml(spec) def _absolutize_legacy_mesh_path(payload: dict, base_dir: Path) -> None: @@ -631,9 +1001,18 @@ def _run_schema_v2_fracture_spec( *, output_dir: str | os.PathLike | None = None, ) -> int: + if len(spec.materials) > 1: + from .multimaterial_fracture import run_multimaterial_fracture_spec + + return run_multimaterial_fracture_spec(spec, output_dir=output_dir) payload = _schema_v2_fracture_legacy_yaml(spec) base_dir = Path(spec.source_path).resolve().parent if spec.source_path else Path.cwd() _absolutize_legacy_mesh_path(payload, base_dir) + destination = Path(output_dir or spec.outputs.directory or "outputs").resolve() + payload["output"]["output_dir"] = str(destination) + geometry = payload["geometry"] + if "type" in geometry and not geometry.get("mesh_path"): + geometry.setdefault("parameters", {}).setdefault("output_path", str(destination / "mesh.msh")) with tempfile.TemporaryDirectory(prefix="phast-schema-v2-fracture-") as tmp: lowered = Path(tmp) / "config.yaml" lowered.write_text(yaml.safe_dump(payload, sort_keys=False), encoding="utf-8") diff --git a/src/phast/workflow/multimaterial_fracture.py b/src/phast/workflow/multimaterial_fracture.py new file mode 100644 index 000000000..097290fca --- /dev/null +++ b/src/phast/workflow/multimaterial_fracture.py @@ -0,0 +1,899 @@ +"""Reusable schema-v2 runner for heterogeneous quasi-static fracture.""" +from __future__ import annotations + +import csv +import hashlib +import json +import platform +import shutil +import time +from collections import deque +from pathlib import Path +from typing import Any + +import matplotlib +matplotlib.use("Agg") +import matplotlib.pyplot as plt +from matplotlib.collections import LineCollection +import h5py +import meshio +import numpy as np +from PIL import Image +import torch + +from ..damage_solver import PhaseFieldDamageSolver +from ..fem_operators import FEMOperators +from ..material import Material +from ..mechanics_solver import QuasiStaticSolver +from ..mesh import FEMMesh +from ..io_utils import init_h5, write_h5_snapshot +from .specs import ProblemSpec + + +class MultimaterialWorkflowError(RuntimeError): + """Raised when the heterogeneous workflow cannot continue safely.""" + + +def _finite_scalar(value: Any, name: str, *, positive: bool = False) -> float: + try: + number = float(value) + except (TypeError, ValueError, OverflowError) as exc: + raise MultimaterialWorkflowError(f"{name} must be a finite scalar") from exc + if isinstance(value, (bool, np.bool_)) or not np.isfinite(number): + raise MultimaterialWorkflowError(f"{name} must be a finite scalar") + if positive and number <= 0.0: + raise MultimaterialWorkflowError(f"{name} must be positive") + return number + + +def _integer(value: Any, name: str, minimum: int = 1) -> int: + if (isinstance(value, (bool, np.bool_)) + or not isinstance(value, (int, np.integer)) or value < minimum): + raise MultimaterialWorkflowError(f"{name} must be an integer >= {minimum}") + return int(value) + + +def _structured_t3(length: float, height: float, nx: int, ny: int, + origin: tuple[float, float]) -> tuple[np.ndarray, np.ndarray]: + length = _finite_scalar(length, "geometry.length", positive=True) + height = _finite_scalar(height, "geometry.height", positive=True) + nx, ny = _integer(nx, "geometry.nx", 2), _integer(ny, "geometry.ny", 2) + if np.asarray(origin).shape != (2,) or not np.isfinite(origin).all(): + raise MultimaterialWorkflowError("geometry.origin must contain two finite coordinates") + xs = np.linspace(origin[0], origin[0] + length, nx + 1) + ys = np.linspace(origin[1], origin[1] + height, ny + 1) + nodes = np.array([(x, y) for y in ys for x in xs], dtype=np.float64) + elements = [] + stride = nx + 1 + for j in range(ny): + for i in range(nx): + n00 = j * stride + i + n10, n01, n11 = n00 + 1, n00 + stride, n00 + stride + 1 + elements.extend(((n00, n10, n11), (n00, n11, n01))) + return nodes, np.asarray(elements, dtype=np.int64) + + +def _build_mesh(spec: ProblemSpec) -> tuple[np.ndarray, np.ndarray]: + if spec.mesh is not None and spec.mesh.path: + loaded = meshio.read(spec.mesh.path) + blocks = [block.data for block in loaded.cells if block.type == "triangle"] + if not blocks: + raise MultimaterialWorkflowError("external mesh contains no T3 cells") + return np.asarray(loaded.points[:, :2], dtype=np.float64), np.vstack(blocks) + if spec.geometry is None or spec.geometry.kind not in { + "structured_rectangle", "structured_grid", "rectangle" + }: + raise MultimaterialWorkflowError( + "use structured_rectangle, structured_grid, rectangle, or an external T3 mesh") + p = spec.geometry.parameters + length = float(p.get("length", p.get("width", 1.0))) + height = float(p.get("height", 1.0)) + origin = p.get("origin", [0.0, -0.5 * height]) + return _structured_t3(length, height, p.get("nx", 40), + p.get("ny", 20), + (float(origin[0]), float(origin[1]))) + + +def _segment_distance(points: np.ndarray, start: np.ndarray, + end: np.ndarray) -> np.ndarray: + tangent = end - start + norm_sq = float(np.dot(tangent, tangent)) + if norm_sq <= 1.0e-30: + return np.linalg.norm(points - start, axis=1) + t = np.clip(np.einsum("ij,j->i", points - start, tangent) / norm_sq, 0.0, 1.0) + return np.linalg.norm(points - (start + t[:, None] * tangent), axis=1) + + +def _selector_mask(points: np.ndarray, selector: dict[str, Any], *, + nodal_bounds: tuple[np.ndarray, np.ndarray] | None = None) -> np.ndarray: + kind = str(selector.get("type", "all")).lower() + tol = _finite_scalar(selector.get("tolerance", 1.0e-9), "selector.tolerance") + if tol < 0.0: + raise MultimaterialWorkflowError("selector.tolerance must be nonnegative") + if kind == "all": + return np.ones(points.shape[0], dtype=bool) + if kind in {"all_of", "any_of"}: + children = selector.get("selectors") + if not isinstance(children, list) or not children: + raise MultimaterialWorkflowError( + f"{kind} selector requires a non-empty 'selectors' list") + masks = [_selector_mask(points, child, nodal_bounds=nodal_bounds) for child in children] + if kind == "all_of": + return np.logical_and.reduce(masks) + return np.logical_or.reduce(masks) + if kind == "not": + child = selector.get("selector") + if not isinstance(child, dict): + raise MultimaterialWorkflowError("not selector requires a 'selector' mapping") + return ~_selector_mask(points, child, nodal_bounds=nodal_bounds) + if kind in {"circle", "outside_circle"}: + centre = np.asarray(selector["center"], dtype=np.float64) + inside = np.linalg.norm(points - centre, axis=1) <= float(selector["radius"]) + tol + return ~inside if kind == "outside_circle" else inside + if kind == "rectangle": + lo = np.asarray(selector["origin"], dtype=np.float64) + hi = lo + np.asarray(selector["size"], dtype=np.float64) + return np.all(points >= lo - tol, axis=1) & np.all(points <= hi + tol, axis=1) + if kind == "line_segment": + return _segment_distance( + points, np.asarray(selector["from"], dtype=np.float64), + np.asarray(selector["to"], dtype=np.float64)) <= float(selector.get("thickness", tol)) + if kind in {"boundary", "boundary_segment"}: + if "side" in selector: + sides = {"left": (0, 0), "right": (0, 1), "bottom": (1, 0), "top": (1, 1)} + side = str(selector["side"]).lower() + if side not in sides or "axis" in selector or "value" in selector: + raise MultimaterialWorkflowError( + "boundary side must be left/right/top/bottom, without axis or value") + if nodal_bounds is None: + raise MultimaterialWorkflowError( + "boundary side requires full nodal bounds from a structured rectangle") + axis, end = sides[side] + mask = np.isclose(points[:, axis], nodal_bounds[end][axis], atol=tol, rtol=0.0) + else: + axis_name = str(selector["axis"]).lower() + if axis_name not in {"x", "y"}: + raise MultimaterialWorkflowError("boundary selector axis must be x or y") + axis = 0 if axis_name == "x" else 1 + mask = np.isclose(points[:, axis], float(selector["value"]), atol=tol) + for name, limits in (selector.get("bounds") or {}).items(): + bound_axis = 0 if str(name).lower() == "x" else 1 + mask &= points[:, bound_axis] >= float(limits[0]) - tol + mask &= points[:, bound_axis] <= float(limits[1]) + tol + return mask + raise MultimaterialWorkflowError(f"unsupported region selector {kind!r}") + + +def _resolve_regions(spec: ProblemSpec, nodes: np.ndarray, + elements: np.ndarray) -> tuple[dict[str, np.ndarray], dict[str, np.ndarray]]: + centroids = nodes[elements].mean(axis=1) + bounds = None if spec.mesh is not None and spec.mesh.path else (nodes.min(axis=0), nodes.max(axis=0)) + return ( + {region.name: _selector_mask(nodes, region.selector, nodal_bounds=bounds) for region in spec.regions}, + {region.name: _selector_mask(centroids, region.selector, nodal_bounds=bounds) for region in spec.regions}, + ) + + +def _shared(spec: ProblemSpec, key: str, default: Any = None) -> Any: + values = [material.parameters.get(key, default) for material in spec.materials] + if any(value != values[0] for value in values[1:]): + raise MultimaterialWorkflowError( + f"all materials must share {key!r}; received {values}") + return values[0] + + +def _assign_materials(spec: ProblemSpec, regions: dict[str, np.ndarray], + n_elements: int) -> tuple[np.ndarray, np.ndarray, np.ndarray, list[str]]: + E = np.full(n_elements, np.nan) + Gc = np.full(n_elements, np.nan) + labels = np.full(n_elements, -1, dtype=np.int64) + names = [] + for index, material in enumerate(spec.materials): + if material.region not in regions: + raise MultimaterialWorkflowError( + f"material {material.name!r} references unknown region {material.region!r}") + mask = regions[material.region] + if not bool(mask.any()): + raise MultimaterialWorkflowError(f"region {material.region!r} selects no elements") + if bool((mask & (labels >= 0)).any()): + raise MultimaterialWorkflowError( + f"material region {material.region!r} overlaps another assignment") + E[mask] = _finite_scalar(material.parameters.get("E"), f"{material.name}.E", positive=True) + Gc[mask] = _finite_scalar(material.parameters.get("Gc"), f"{material.name}.Gc", positive=True) + labels[mask] = index + names.append(material.name) + if bool((labels < 0).any()): + raise MultimaterialWorkflowError( + f"material assignments leave {int((labels < 0).sum())} elements unassigned") + return E, Gc, labels, names + + +def _validate_materials(spec: ProblemSpec) -> None: + defaults = {"nu": 0.3, "rho": 1.0, "eta_residual": 1.0e-6, + "energy_split": "amor", "pf_model": "AT2", "plane_stress": True} + allowed = {"E", "Gc", "l0", *defaults} + if not spec.materials: + raise MultimaterialWorkflowError("at least one material is required") + for material in spec.materials: + p = material.parameters + if material.model != "phase_field" or set(p) - allowed: + raise MultimaterialWorkflowError( + f"unsupported material model or parameters for {material.name!r}: {sorted(set(p) - allowed)}") + for key in ("E", "Gc", "l0", "rho"): + _finite_scalar(p.get(key, defaults.get(key)), f"{material.name}.{key}", positive=True) + nu = _finite_scalar(p.get("nu", 0.3), f"{material.name}.nu") + eta = _finite_scalar(p.get("eta_residual", 1.0e-6), f"{material.name}.eta_residual") + if not -1.0 < nu < 0.5: + raise MultimaterialWorkflowError("nu must satisfy -1 < nu < 0.5 for the Amor split") + if not 0.0 <= eta < 1.0: + raise MultimaterialWorkflowError("eta_residual must satisfy 0 <= eta_residual < 1") + if not isinstance(p.get("plane_stress", True), bool): + raise MultimaterialWorkflowError("plane_stress must be a boolean") + for key, default in {"l0": None, **defaults}.items(): + _shared(spec, key, default) + if _shared(spec, "energy_split", "amor") != "amor" or _shared(spec, "pf_model", "AT2") != "AT2": + raise MultimaterialWorkflowError("current route requires energy_split: amor and pf_model: AT2") + + +def _resolve_reaction(spec: ProblemSpec, regions: dict[str, np.ndarray], + resolved_bcs: list) -> tuple[torch.Tensor | None, int]: + """Resolve the requested reaction; the 2D integral is per unit thickness.""" + requests = [h for h in spec.outputs.history if h.name in {"reaction", "reaction_force", "load_displacement"}] + if len(requests) > 1: + raise MultimaterialWorkflowError("only one reaction/load_displacement history is supported") + default = next((item for item in resolved_bcs if item[0].kind == "prescribe"), None) + request = requests[0] if requests else None + indices = default[1] if default else None + component = int(default[0].component or 0) if default else 0 + if request is not None: + if request.region is not None: + mask = regions.get(request.region) + if mask is None or not mask.any(): + raise MultimaterialWorkflowError(f"reaction region {request.region!r} selects no nodes") + indices = torch.as_tensor(np.flatnonzero(mask), dtype=torch.long) + if request.component is not None: + if isinstance(request.component, bool) or request.component not in (0, 1): + raise MultimaterialWorkflowError("reaction component must be 0 or 1") + component = int(request.component) + if indices is None: + raise MultimaterialWorkflowError("reaction output requires a region or a prescribed boundary") + return indices, component + + +def _validate_outputs(spec: ProblemSpec) -> None: + if set(spec.outputs.parameters) - {"directory"}: + raise MultimaterialWorkflowError("unsupported output parameters") + fields = {"trajectory", "displacement", "strain", "stress", "damage", "vtu"} + histories = {"reaction", "reaction_force", "load_displacement", "max_damage", "solver_telemetry", "timing_per_step"} + for items, names, label in ((spec.outputs.fields, fields, "field"), (spec.outputs.history, histories, "history")): + seen = set() + for item in items: + if item.name not in names or item.name in seen: + raise MultimaterialWorkflowError(f"unsupported or duplicate {label} output {item.name!r}") + seen.add(item.name) + _integer(item.every, f"{label} output every") + allowed = {"format"} if label == "field" and item.name == "trajectory" else set() + if set(item.parameters) - allowed: + raise MultimaterialWorkflowError(f"unsupported parameters for {label} output {item.name!r}") + if allowed: + if item.parameters.get("format", "h5") != "h5": + raise MultimaterialWorkflowError("the heterogeneous runner supports HDF5 trajectories only") + elif item.every != 1: + raise MultimaterialWorkflowError(f"{item.name!r} output does not support custom cadence") + if label == "history" and item.name not in {"reaction", "reaction_force", "load_displacement"}: + if item.region is not None or item.component is not None: + raise MultimaterialWorkflowError(f"{item.name!r} history does not support region/component selection") + for item in spec.outputs.postprocess: + if item.kind not in {"plots", "initial_conditions", "animation"}: + raise MultimaterialWorkflowError(f"unsupported visual request {item.kind!r}") + if item.kind == "animation": + if set(item.parameters) - {"field"} or item.parameters.get("field", "damage") != "damage": + raise MultimaterialWorkflowError("only the default damage animation is supported") + elif item.parameters: + raise MultimaterialWorkflowError(f"unsupported parameters for visual {item.kind!r}") + + +def _contains_boundary(selector: dict[str, Any]) -> bool: + kind = str(selector.get("type", "all")).lower() + return kind in {"boundary", "boundary_segment"} or ( + kind in {"all_of", "any_of"} + and any(_contains_boundary(child) for child in selector.get("selectors", []))) + + +def validate_multimaterial_fracture_spec(spec: ProblemSpec) -> None: + """Preflight material, request and mesh-region inputs without solver construction. + + This builds/reads the mesh and resolves selectors, but creates no output + directory, FEM operators or solvers. Schema-v2 planning/validate-only may + call it directly. Errors are reported as MultimaterialWorkflowError. + """ + if (spec.solver.kind != "quasi_static" or len(spec.analysis_steps) != 1 + or spec.analysis_steps[0].kind != "quasi_static"): + raise MultimaterialWorkflowError("this route requires one quasi_static analysis step") + _validate_materials(spec) + _validate_outputs(spec) + controls = spec.analysis_steps[0].controls + if set(controls) - {"number_of_steps", "num_steps"}: + raise MultimaterialWorkflowError("unsupported quasi-static analysis controls") + _integer(controls.get("number_of_steps", controls.get("num_steps", 41)), "number_of_steps", 2) + try: + nodes, elements = _build_mesh(spec) + if not np.isfinite(nodes).all(): + raise MultimaterialWorkflowError("mesh coordinates must be finite") + node_regions, element_regions = _resolve_regions(spec, nodes, elements) + except (KeyError, TypeError, ValueError, IndexError) as exc: + raise MultimaterialWorkflowError(f"invalid geometry or region selector: {exc}") from exc + _assign_materials(spec, element_regions, len(elements)) + positive_seed = False + fixed = np.zeros(len(nodes), dtype=bool) + values = np.zeros(len(nodes)) + for initial in spec.initial_conditions: + if initial.field != "damage" or not initial.region or initial.parameters: + raise MultimaterialWorkflowError("only scalar region-based damage initial conditions are supported") + mask = node_regions.get(initial.region) + if mask is None or not mask.any(): + raise MultimaterialWorkflowError(f"initial damage region {initial.region!r} selects no nodes") + value = _finite_scalar(1.0 if initial.value is None else initial.value, "initial damage") + if not 0.0 <= value <= 1.0: + raise MultimaterialWorkflowError("initial damage must lie in [0, 1]") + if np.any(fixed & mask & (values != value)): + raise MultimaterialWorkflowError("conflicting initial damage constraints") + fixed |= mask + values[mask] = value + positive_seed |= value > 0.0 + if not positive_seed: + raise MultimaterialWorkflowError("a nonempty positive seeded damage region is required") + active = set(spec.analysis_steps[0].active_boundary_conditions) + if active - {bc.name for bc in spec.boundary_conditions}: + raise MultimaterialWorkflowError("active boundary condition name is not declared") + resolved = _resolve_bcs(spec, node_regions) + selectors = {region.name: region.selector for region in spec.regions} + structured = not (spec.mesh is not None and spec.mesh.path) + exterior = np.any(np.isclose(nodes, nodes.min(axis=0), atol=1.0e-9, rtol=0.0) + | np.isclose(nodes, nodes.max(axis=0), atol=1.0e-9, rtol=0.0), axis=1) + occupied = np.zeros((len(nodes), 2), dtype=bool) + prescribed_values = np.zeros((len(nodes), 2)) + for bc, indices in resolved: + if bc.kind not in {"fix", "prescribe"} or bc.parameters: + raise MultimaterialWorkflowError("only parameter-free fix/prescribe boundaries are supported") + if bc.component is not None and (isinstance(bc.component, bool) or bc.component not in (0, 1)): + raise MultimaterialWorkflowError("boundary component must be 0 or 1") + ids = indices.numpy() + if structured and _contains_boundary(selectors[bc.region]) and not exterior[ids].all(): + raise MultimaterialWorkflowError(f"boundary region {bc.region!r} selects interior nodes; update geometry-dependent selectors") + value = 0.0 if bc.kind == "fix" else _finite_scalar(bc.value, "prescribed displacement") + for component in ((0, 1) if bc.component is None else (bc.component,)): + if np.any(occupied[ids, component] & (prescribed_values[ids, component] != value)): + raise MultimaterialWorkflowError("conflicting displacement boundary conditions") + occupied[ids, component] = True + prescribed_values[ids, component] = value + _resolve_reaction(spec, node_regions, resolved) + + +def _field_residual(solver: PhaseFieldDamageSolver, history: torch.Tensor, + damage: torch.Tensor, Gc_field: torch.Tensor) -> torch.Tensor: + attrs = ("_Gc_l0_e", "_Gc_over_l0_e", "_at1_source_e", "_cg_Gc_l0_e_diag_lap") + original = {name: getattr(solver, name, None) for name in attrs} + try: + Gc_e = Gc_field.to(dtype=solver._cg_dtype, device=solver._cg_device) + solver._Gc_l0_e = Gc_e * solver._l0 + solver._Gc_over_l0_e = Gc_e / solver._l0 + solver._at1_source_e = torch.zeros_like(Gc_e) + solver._cg_Gc_l0_e_diag_lap = solver._Gc_l0_e.unsqueeze(1) * solver._cg_diag_lap + return solver.compute_residual(history, damage) + finally: + for name, value in original.items(): + setattr(solver, name, value) + + +def _projected_norm(residual: torch.Tensor, damage: torch.Tensor, + lower: torch.Tensor, fixed: torch.Tensor) -> float: + projected = residual.clone() + at_lower = damage <= lower + 1.0e-9 + at_upper = damage >= 1.0 - 1.0e-9 + projected[at_lower] = torch.minimum(projected[at_lower], torch.zeros_like(projected[at_lower])) + projected[at_upper] = torch.maximum(projected[at_upper], torch.zeros_like(projected[at_upper])) + projected[fixed] = 0.0 + return float(torch.linalg.vector_norm(projected, ord=float("inf")).item()) + + +def _connected_front(nodes: np.ndarray, elements: np.ndarray, damage: np.ndarray, + seeds: np.ndarray, threshold: float) -> float: + active = damage >= threshold + starts = [int(node) for node in seeds if active[int(node)]] + if not starts: + return float(nodes[seeds, 0].max()) + adjacency = [set() for _ in range(nodes.shape[0])] + for element in elements: + for i, node in enumerate(element): + for neighbour in element[i + 1:]: + adjacency[int(node)].add(int(neighbour)) + adjacency[int(neighbour)].add(int(node)) + visited = set(starts) + queue = deque(starts) + while queue: + node = queue.popleft() + for neighbour in adjacency[node]: + if active[neighbour] and neighbour not in visited: + visited.add(neighbour) + queue.append(neighbour) + return float(nodes[np.asarray(sorted(visited)), 0].max()) + + +def _write_csv(path: Path, rows: list[dict[str, Any]]) -> None: + with path.open("w", newline="", encoding="utf-8") as stream: + writer = csv.DictWriter(stream, fieldnames=list(rows[0]), lineterminator="\n") + writer.writeheader() + writer.writerows(rows) + + +def _material_edges(nodes: np.ndarray, elements: np.ndarray, + material_ids: np.ndarray) -> np.ndarray: + """Return mesh edges separating different bulk material assignments.""" + owner: dict[tuple[int, int], int] = {} + edges = [] + for element, material_id in zip(elements, material_ids): + for i, j in ((0, 1), (1, 2), (2, 0)): + edge = tuple(sorted((int(element[i]), int(element[j])))) + if edge in owner and owner[edge] != int(material_id): + edges.append(nodes[list(edge)]) + else: + owner[edge] = int(material_id) + return np.asarray(edges, dtype=np.float64).reshape(-1, 2, 2) + + +def _overlay_materials(ax, interfaces: np.ndarray | None) -> None: + if interfaces is not None and interfaces.size: + ax.add_collection(LineCollection(interfaces, colors="0.35", linewidths=0.7)) + + +def _save_h5_state(path: Path, step: int, mesh: FEMMesh, fem: FEMOperators, + displacement: torch.Tensor, damage: torch.Tensor, + history: torch.Tensor, *, load_factor: float, + opening: float, reaction: float, + diagnostics: dict[str, Any] | None = None) -> None: + """Store an accepted state using the shared PhAST HDF5 field schema.""" + strain = fem.compute_strain(displacement) + stress = fem.compute_stress(displacement, damage, strain=strain) + psi_plus = fem.compute_psi_plus(displacement, strain=strain) + with h5py.File(path, "a") as store: + write_h5_snapshot( + store, step, mesh, displacement, damage, psi_plus, history, + eps_xx=strain[0], eps_yy=strain[1], gam_xy=strain[2], + sxx=stress[0], syy=stress[1], sxy=stress[2], + reaction_force=reaction, applied_disp=opening, precision="float64", + ) + group = store[f"simulation_data/steps/step_{step:04d}"] + group.attrs["load_factor"] = float(load_factor) + if diagnostics is not None: + for name in ("projected_damage_residual", "mechanics_residual", + "damage_increment", "connected_crack_front_x"): + group.attrs[name] = float(diagnostics[name]) + store.attrs["num_steps"] = int(step) + store.attrs["num_snapshots"] = len(store["simulation_data/steps"]) + + +def _plot_field(path: Path, nodes: np.ndarray, elements: np.ndarray, + values: np.ndarray, title: str, label: str, nodal: bool, + vmin: float | None = None, vmax: float | None = None, + *, cmap: str = "viridis", + interfaces: np.ndarray | None = None) -> None: + fig, ax = plt.subplots(figsize=(8.0, 3.5), constrained_layout=True) + if nodal: + image = ax.tripcolor(nodes[:, 0], nodes[:, 1], elements, values, + shading="gouraud", vmin=vmin, vmax=vmax, cmap=cmap) + else: + image = ax.tripcolor(nodes[:, 0], nodes[:, 1], elements, + facecolors=values, shading="flat", vmin=vmin, vmax=vmax, + cmap=cmap) + _overlay_materials(ax, interfaces) + ax.set(aspect="equal", xlabel="x", ylabel="y", title=title) + fig.colorbar(image, ax=ax, shrink=0.82, label=label) + fig.savefig(path, dpi=180) + plt.close(fig) + + +def _frame(nodes: np.ndarray, elements: np.ndarray, damage: np.ndarray, + factor: float, interfaces: np.ndarray | None = None) -> Image.Image: + fig, ax = plt.subplots(figsize=(8.0, 3.5), constrained_layout=True) + image = ax.tripcolor(nodes[:, 0], nodes[:, 1], elements, damage, + shading="gouraud", cmap="Reds", vmin=0.0, vmax=1.0) + _overlay_materials(ax, interfaces) + ax.set(aspect="equal", xlabel="x", ylabel="y", + title=f"Phase-field damage, load factor = {factor:.4f}") + fig.colorbar(image, ax=ax, shrink=0.82, label="damage d") + fig.canvas.draw() + result = Image.fromarray(np.asarray(fig.canvas.buffer_rgba()).copy()).convert("RGB") + plt.close(fig) + return result + + +def _resolve_bcs(spec: ProblemSpec, regions: dict[str, np.ndarray]): + active = set(spec.analysis_steps[0].active_boundary_conditions) + resolved = [] + for bc in spec.boundary_conditions: + if active and bc.name not in active: + continue + if bc.region not in regions: + raise MultimaterialWorkflowError(f"unknown boundary region {bc.region!r}") + indices = np.flatnonzero(regions[bc.region]) + if not indices.size: + raise MultimaterialWorkflowError(f"boundary region {bc.region!r} selects no nodes") + resolved.append((bc, torch.as_tensor(indices, dtype=torch.long))) + return resolved + + +def _bc_state(n_nodes: int, resolved, factor: float): + mask = torch.zeros((n_nodes, 2), dtype=torch.bool) + values = torch.zeros((n_nodes, 2), dtype=torch.float64) + for bc, indices in resolved: + components = (0, 1) if bc.component is None else (int(bc.component),) + for component in components: + if bc.kind == "fix": + mask[indices, component] = True + elif bc.kind == "prescribe": + mask[indices, component] = True + values[indices, component] = factor * float(bc.value) + else: + raise MultimaterialWorkflowError( + f"supported boundary conditions are fix and prescribe, got {bc.kind!r}") + return mask, values + + +def run_multimaterial_fracture_spec(spec: ProblemSpec, *, output_dir=None) -> int: + """Execute a reusable heterogeneous schema-v2 quasi-static problem.""" + started = time.perf_counter() + validate_multimaterial_fracture_spec(spec) + if spec.solver.kind != "quasi_static" or len(spec.analysis_steps) != 1: + raise MultimaterialWorkflowError("this route requires one quasi_static analysis step") + if any(material.model != "phase_field" for material in spec.materials): + raise MultimaterialWorkflowError("all materials must use model: phase_field") + output = Path(output_dir or spec.outputs.directory or "runs/multimaterial_fracture") + output.mkdir(parents=True, exist_ok=True) + nodes_np, elements_np = _build_mesh(spec) + node_regions, element_regions = _resolve_regions(spec, nodes_np, elements_np) + E_np, Gc_np, material_ids, material_names = _assign_materials( + spec, element_regions, elements_np.shape[0]) + interfaces = _material_edges(nodes_np, elements_np, material_ids) + edge_lengths = np.linalg.norm( + nodes_np[elements_np[:, [1, 2, 0]]] - nodes_np[elements_np[:, [0, 1, 2]]], + axis=2) + maximum_edge_length = float(edge_lengths.max()) + nu, l0 = float(_shared(spec, "nu", 0.3)), float(_shared(spec, "l0")) + energy_split = str(_shared(spec, "energy_split", "amor")) + plane_stress = bool(_shared(spec, "plane_stress", True)) + pf_model = str(_shared(spec, "pf_model", "AT2")) + if energy_split != "amor" or pf_model != "AT2": + raise MultimaterialWorkflowError("current route requires energy_split: amor and pf_model: AT2") + + nodes = torch.as_tensor(nodes_np, dtype=torch.float64) + elements = torch.as_tensor(elements_np, dtype=torch.long) + mesh = FEMMesh.from_tensors(nodes, elements, device="cpu", dtype=torch.float64) + reference = spec.materials[0].parameters + material = Material( + E=float(reference["E"]), nu=nu, Gc=float(reference["Gc"]), l0=l0, + rho=float(reference.get("rho", 1.0)), + eta_residual=float(reference.get("eta_residual", 1.0e-6)), + energy_split=energy_split, pf_model=pf_model, plane_stress=plane_stress) + fem = FEMOperators(mesh, material) + fem.diff_E_field = torch.as_tensor(E_np, dtype=torch.float64) + settings = spec.solver.parameters + mechanics = QuasiStaticSolver( + fem, backend=str(settings.get("mechanics_backend", "auto")), + tol=float(settings.get("mechanics_tolerance", 1.0e-9)), + tol_rel=float(settings.get("mechanics_relative_tolerance", 1.0e-8)), + max_iter=int(settings.get("mechanics_max_iterations", 30)), line_search=True) + damage_solver = PhaseFieldDamageSolver( + fem, tol=float(settings.get("damage_tolerance", 1.0e-8)), + max_iter=int(settings.get("damage_max_iterations", 500)), + bounds_method=str(settings.get("damage_bounds_method", "projected_cg")), + use_multigrid=False) + Gc_field = torch.as_tensor(Gc_np, dtype=torch.float64) + resolved_bcs = _resolve_bcs(spec, node_regions) + reaction_indices, reaction_component = _resolve_reaction(spec, node_regions, resolved_bcs) + + fixed = torch.zeros(mesh.n_nodes, dtype=torch.bool) + fixed_values = torch.zeros(mesh.n_nodes, dtype=torch.float64) + for initial in spec.initial_conditions: + if initial.field == "damage" and initial.region: + mask = torch.as_tensor(node_regions[initial.region], dtype=torch.bool) + fixed |= mask + fixed_values[mask] = float(1.0 if initial.value is None else initial.value) + seeds = np.flatnonzero(fixed.numpy()) + if not seeds.size: + raise MultimaterialWorkflowError("a seeded damage region is required") + damage, displacement = fixed_values.clone(), torch.zeros((mesh.n_nodes, 2), dtype=torch.float64) + history = torch.zeros(mesh.n_elems, dtype=torch.float64) + external_force = torch.zeros_like(displacement) + + trajectory_request = next( + (field for field in spec.outputs.fields if field.name == "trajectory"), None) + trajectory_path = None + if trajectory_request is not None: + trajectory_format = str(trajectory_request.parameters.get("format", "h5")) + if trajectory_format != "h5": + raise MultimaterialWorkflowError( + "the heterogeneous runner supports HDF5 trajectories; " + "set the trajectory field format to h5 or omit format") + trajectory_path = output / "training_data.h5" + if trajectory_path.exists(): + raise MultimaterialWorkflowError( + f"refusing to overwrite {trajectory_path}; use a new output directory") + with init_h5(str(trajectory_path), mesh, material) as store: + store.attrs["format"] = "phast.trajectory.h5" + store.attrs["analysis"] = "quasi_static" + store.attrs["material_names"] = json.dumps(material_names) + group = store["simulation_data"].create_group("material_fields") + for name, values in (("material_id", material_ids), ("E", E_np), ("Gc", Gc_np)): + group.create_dataset(name, data=values) + store["simulation_data/metadata"].attrs["material_fields_path"] = ( + "simulation_data/material_fields") + _save_h5_state( + trajectory_path, 0, mesh, fem, displacement, damage, history, + load_factor=0.0, opening=0.0, reaction=0.0) + + controls = spec.analysis_steps[0].controls + n_steps = int(controls.get("number_of_steps", controls.get("num_steps", 41))) + max_stagger = int(settings.get("maximum_staggered_iterations", 100)) + increment_tol = float(settings.get("staggered_damage_tolerance", 1.0e-5)) + residual_tol = float(settings.get("projected_residual_tolerance", 1.0e-5)) + relaxation = float(settings.get("damage_relaxation", 0.7)) + nominal = 1.0 / (n_steps - 1) + min_increment = float(settings.get("minimum_load_increment", nominal / 16.0)) + max_cutbacks = int(settings.get("maximum_cutbacks", 20)) + threshold = float(settings.get("crack_front_threshold", 0.8)) + targets = deque(float(value) for value in np.linspace(0.0, 1.0, n_steps)[1:]) + accepted_factor, cutbacks, attempt = 0.0, 0, 0 + rows, frames = [], [_frame(nodes_np, elements_np, damage.numpy(), 0.0, interfaces)] + + while targets: + attempt += 1 + target = targets.popleft() + base_u, base_d, base_H = displacement.clone(), damage.clone(), history.clone() + bc_mask, bc_values = _bc_state(mesh.n_nodes, resolved_bcs, target) + trial_u, trial_d, trial_H = base_u.clone(), base_d.clone(), base_H.clone() + converged, failure = False, "" + step_started = time.perf_counter() + projected_residual = damage_increment = float("inf") + mechanics_iterations = 0 + for stagger_iteration in range(1, max_stagger + 1): + trial_u, mechanics_ok, mechanics_iterations = mechanics.solve( + trial_d, external_force, bc_mask, bc_values, u_init=trial_u) + if not mechanics_ok: + failure = f"mechanics residual {mechanics.last_residual}" + break + strain = fem.compute_strain(trial_u) + trial_H = torch.maximum(base_H, fem.compute_psi_plus(trial_u, strain=strain)) + candidate = damage_solver.solve( + trial_H, base_d, Gc_field=Gc_field, + pf_dirichlet_mask=fixed, pf_dirichlet_values=fixed_values, + initial_guess=trial_d) + if getattr(damage_solver, "last_converged", True) is False: + failure = "damage subproblem did not converge" + break + candidate[fixed] = fixed_values[fixed] + next_damage = torch.clamp( + torch.maximum(trial_d + relaxation * (candidate - trial_d), base_d), 0.0, 1.0) + next_damage[fixed] = fixed_values[fixed] + damage_increment = float(torch.max(torch.abs(next_damage - trial_d)).item()) + trial_d = next_damage + projected_residual = _projected_norm( + _field_residual(damage_solver, trial_H, trial_d, Gc_field), + trial_d, base_d, fixed) + if damage_increment <= increment_tol and projected_residual <= residual_tol: + converged = True + break + if converged: + trial_u, mechanics_ok, mechanics_iterations = mechanics.solve( + trial_d, external_force, bc_mask, bc_values, u_init=trial_u) + if not mechanics_ok: + converged, failure = False, "final mechanics solve failed" + if not converged: + span = target - accepted_factor + if bool(settings.get("automatic_cutback", True)) and span > min_increment and cutbacks < max_cutbacks: + midpoint = accepted_factor + 0.5 * span + targets.appendleft(target) + targets.appendleft(midpoint) + cutbacks += 1 + print(f"cutback {cutbacks}: factor {target:.6f} failed; retrying {midpoint:.6f}", flush=True) + continue + raise MultimaterialWorkflowError( + f"staggered solve failed at factor {target:.6f}: " + f"{failure or f'increment={damage_increment:.3e}, residual={projected_residual:.3e}'}") + + displacement, damage, history, accepted_factor = trial_u, trial_d, trial_H, target + internal = fem.internal_force(displacement, damage) + reaction_bc = next((item for item in resolved_bcs if item[0].kind == "prescribe"), None) + reaction = (float(internal[reaction_indices, reaction_component].sum().item()) + if reaction_indices is not None else 0.0) + opening = 0.0 + if reaction_bc: + bc, indices = reaction_bc + component = int(bc.component or 0) + prescribed = [ + target * float(item.value) + for item, _ in resolved_bcs + if item.kind == "prescribe" and int(item.component or 0) == component + ] + if prescribed: + opening = max(prescribed) - min(prescribed) + if opening == 0.0: + opening = max(abs(value) for value in prescribed) + damage_np = damage.detach().cpu().numpy() + front = _connected_front(nodes_np, elements_np, damage_np, seeds, threshold) + row = { + "accepted_step": len(rows) + 1, "attempt": attempt, + "load_factor": target, "opening": opening, "reaction_force": reaction, + "maximum_damage": float(damage.max().item()), + "connected_crack_front_x": front, + "mechanics_iterations": int(mechanics_iterations), + "mechanics_residual": float(mechanics.last_residual), + "damage_iterations": int(getattr(damage_solver, "last_iter", 0) or 0), + "staggered_iterations": int(stagger_iteration), + "damage_increment": damage_increment, + "projected_damage_residual": projected_residual, + "cutbacks_so_far": cutbacks, + "wall_seconds": time.perf_counter() - step_started, + } + for index, name in enumerate(material_names): + mask = material_ids == index + row[f"mean_damage_{name}"] = float(damage[elements[mask]].mean().item()) + rows.append(row) + if trajectory_path is not None and ( + len(rows) % trajectory_request.every == 0 or not targets): + _save_h5_state( + trajectory_path, len(rows), mesh, fem, displacement, damage, history, + load_factor=target, opening=opening, reaction=reaction, diagnostics=row) + frames.append(_frame(nodes_np, elements_np, damage_np, target, interfaces)) + print(f"accepted {len(rows):03d}: factor={target:.6f} opening={opening:.6e} " + f"reaction={reaction:.6e} front_x={front:.6f} residual={projected_residual:.3e}", flush=True) + + strain = fem.compute_strain(displacement) + stress = fem.compute_stress(displacement, damage, strain=strain) + eps_xx, eps_yy, gamma_xy = [value.detach().cpu().numpy() for value in strain] + sxx, syy, sxy = [value.detach().cpu().numpy() for value in stress] + eq_strain = np.sqrt(eps_xx**2 + eps_yy**2 + 0.5 * gamma_xy**2) + von_mises = np.sqrt(np.maximum(sxx**2 - sxx * syy + syy**2 + 3.0 * sxy**2, 0.0)) + u_np, d_np = displacement.detach().cpu().numpy(), damage.detach().cpu().numpy() + u_mag = np.linalg.norm(u_np, axis=1) + for name in ("history.csv", "solver_telemetry.csv", "timing_per_step.csv"): + _write_csv(output / name, rows) + with (output / "nodal_fields.csv").open("w", newline="", encoding="utf-8") as stream: + writer = csv.writer(stream, lineterminator="\n") + writer.writerow(["node", "x", "y", "ux", "uy", "displacement_magnitude", "damage"]) + for i, (xy, u, um, d) in enumerate(zip(nodes_np, u_np, u_mag, d_np)): + writer.writerow([i, xy[0], xy[1], u[0], u[1], um, d]) + with (output / "element_fields.csv").open("w", newline="", encoding="utf-8") as stream: + writer = csv.writer(stream, lineterminator="\n") + writer.writerow(["element", "material", "E", "Gc", "eps_xx", "eps_yy", + "gamma_xy", "equivalent_strain", "sxx", "syy", "sxy", "von_mises"]) + for i in range(elements_np.shape[0]): + writer.writerow([i, material_names[int(material_ids[i])], E_np[i], Gc_np[i], + eps_xx[i], eps_yy[i], gamma_xy[i], eq_strain[i], + sxx[i], syy[i], sxy[i], von_mises[i]]) + + fig, axes = plt.subplots(1, 2, figsize=(10.0, 3.8), constrained_layout=True) + for ax, values, title, label in ((axes[0], E_np, "Young's modulus", "E"), + (axes[1], Gc_np, "Fracture toughness", "Gc")): + image = ax.tripcolor(nodes_np[:, 0], nodes_np[:, 1], elements_np, + facecolors=values, shading="flat") + ax.set(aspect="equal", xlabel="x", ylabel="y", title=title) + fig.colorbar(image, ax=ax, shrink=0.82, label=label) + fig.savefig(output / "material_fields.png", dpi=180) + plt.close(fig) + fig, ax = plt.subplots(figsize=(8.0, 3.5), constrained_layout=True) + ax.tripcolor(nodes_np[:, 0], nodes_np[:, 1], elements_np, + facecolors=material_ids, shading="flat", cmap="Pastel1") + ax.scatter(nodes_np[seeds, 0], nodes_np[seeds, 1], s=9, color="black", label="initial crack") + for bc, indices in resolved_bcs: + ax.scatter(nodes_np[indices.numpy(), 0], nodes_np[indices.numpy(), 1], + s=11, label=bc.name or bc.kind) + ax.set(aspect="equal", xlabel="x", ylabel="y", + title="Geometry, materials, initial crack, and boundary conditions") + ax.legend(fontsize=8, ncol=2) + fig.savefig(output / "initial_conditions.png", dpi=180) + plt.close(fig) + _plot_field(output / "damage_final.png", nodes_np, elements_np, d_np, + "Final phase-field damage", "damage d", True, 0.0, 1.0, + cmap="Reds", interfaces=interfaces) + _plot_field(output / "displacement_final.png", nodes_np, elements_np, u_mag, + "Final displacement magnitude", "|u|", True, interfaces=interfaces) + _plot_field(output / "strain_final.png", nodes_np, elements_np, eq_strain, + "Final strain tensor norm", "strain tensor norm", False, + interfaces=interfaces) + _plot_field(output / "stress_final.png", nodes_np, elements_np, von_mises, + "Final von Mises stress", "von Mises stress", False, + cmap="plasma", interfaces=interfaces) + fig, ax = plt.subplots(figsize=(6.4, 4.0), constrained_layout=True) + ax.plot([row["opening"] for row in rows], [abs(row["reaction_force"]) for row in rows], "o-") + ax.set(xlabel="opening displacement", ylabel="reaction force magnitude", + title="Load-displacement response") + fig.savefig(output / "load_displacement.png", dpi=180) + plt.close(fig) + fig, axes = plt.subplots(1, 2, figsize=(10.0, 4.0), constrained_layout=True) + axes[0].semilogy([row["load_factor"] for row in rows], + [max(row["projected_damage_residual"], 1e-16) for row in rows], "o-") + axes[0].set(xlabel="load factor", ylabel="projected damage residual", + title="Damage convergence") + axes[1].plot([row["opening"] for row in rows], + [row["connected_crack_front_x"] for row in rows], "o-") + axes[1].set(xlabel="opening displacement", ylabel="connected crack-front x", + title="Connected crack advance") + fig.savefig(output / "convergence_and_crack_front.png", dpi=180) + plt.close(fig) + frames[0].save(output / "damage_evolution.gif", save_all=True, + append_images=frames[1:], duration=180, loop=0) + + meshio.write_points_cells( + output / "final_fields.vtu", + np.column_stack([nodes_np, np.zeros(nodes_np.shape[0])]), + [("triangle", elements_np)], + point_data={"displacement": np.column_stack([u_np, np.zeros(nodes_np.shape[0])]), + "displacement_magnitude": u_mag, "damage": d_np}, + cell_data={"material_id": [material_ids], "E": [E_np], "Gc": [Gc_np], + "equivalent_strain": [eq_strain], "von_mises": [von_mises], + "eps_xx": [eps_xx], "eps_yy": [eps_yy], "gamma_xy": [gamma_xy], + "sxx": [sxx], "syy": [syy], "sxy": [sxy]}) + if spec.source_path: + shutil.copy2(spec.source_path, output / "config.yaml") + config_text = Path(spec.source_path).read_text(encoding="utf-8") + else: + config_text = f"schema_version: 2\nname: {spec.name}\n" + (output / "config.yaml").write_text(config_text, encoding="utf-8") + elapsed = time.perf_counter() - started + summary = { + "schema_version": 2, "problem": spec.name, + "solver_path": "schema-v2 heterogeneous staggered quasi-static AT2", + "materials": material_names, "n_nodes": int(mesh.n_nodes), + "n_elements": int(mesh.n_elems), "l0": l0, + "maximum_element_size": float(mesh.elem_h.max().item()), + "maximum_element_size_over_l0": float(mesh.elem_h.max().item()) / l0, + "maximum_element_edge_length": maximum_edge_length, + "maximum_element_edge_length_over_l0": maximum_edge_length / l0, + "trajectory_format": "h5" if trajectory_path is not None else None, + "accepted_steps": len(rows), "cutbacks": cutbacks, + "final_opening": rows[-1]["opening"], + "final_reaction_force": rows[-1]["reaction_force"], + "final_connected_crack_front_x": rows[-1]["connected_crack_front_x"], + "final_maximum_damage": rows[-1]["maximum_damage"], + "maximum_projected_damage_residual": max(row["projected_damage_residual"] for row in rows), + "all_steps_converged": True, "runtime_seconds": elapsed, + "scope": "heterogeneous E/Gc AT2 teaching calculation; not ASTM D5528 or a calibrated bimaterial benchmark", + } + (output / "summary.json").write_text(json.dumps(summary, indent=2) + "\n", encoding="utf-8") + (output / "run_metadata.json").write_text(json.dumps({ + "schema_version": 1, "python": platform.python_version(), + "pytorch": torch.__version__, "device": "cpu", "dtype": "float64", + "runtime_seconds": elapsed}, indent=2) + "\n", encoding="utf-8") + (output / "run_lockfile.json").write_text(json.dumps({ + "schema_version": 2, + "config_sha256": hashlib.sha256(config_text.encode()).hexdigest(), + "source_config": spec.source_path, + "solver_parameters": dict(spec.solver.parameters)}, indent=2) + "\n", encoding="utf-8") + visuals = ["initial_conditions.png", "material_fields.png", "damage_final.png", + "displacement_final.png", "strain_final.png", "stress_final.png", + "load_displacement.png", "convergence_and_crack_front.png", + "damage_evolution.gif"] + visual_rows = [] + for name in visuals: + path = output / name + entry = {"path": name, "size_bytes": path.stat().st_size, + "artifact_type": "animation" if path.suffix == ".gif" else "image"} + if entry["artifact_type"] == "image": + with Image.open(path) as image: + entry["width_px"], entry["height_px"] = image.size + visual_rows.append(entry) + (output / "visual_manifest.json").write_text( + json.dumps(visual_rows, indent=2) + "\n", encoding="utf-8") + files = ["config.yaml", "history.csv", "solver_telemetry.csv", "timing_per_step.csv", + "nodal_fields.csv", "element_fields.csv", "final_fields.vtu", *visuals, + "summary.json", "run_metadata.json", "run_lockfile.json", + "visual_manifest.json", "run_manifest.json"] + if trajectory_path is not None: + files.append(trajectory_path.name) + (output / "run_manifest.json").write_text(json.dumps({ + "schema_version": 1, "problem": spec.name, + "command": f"python -m phast run {spec.source_path or ''} --output_dir {output}", + "files": files, "summary": summary}, indent=2) + "\n", encoding="utf-8") + print(json.dumps(summary, indent=2), flush=True) + return 0 diff --git a/tests/test_explain_standard_workflow.py b/tests/test_explain_standard_workflow.py new file mode 100644 index 000000000..f440591f4 --- /dev/null +++ b/tests/test_explain_standard_workflow.py @@ -0,0 +1,52 @@ +"""The common explanation command inspects inputs without starting a simulation.""" +from pathlib import Path +import os +import subprocess +import sys + +import pytest + +from phast.config.explain_config import build_explanation + + +ROOT = Path(__file__).resolve().parents[1] + + +@pytest.mark.parametrize("relative_path", [ + "standard_workflow/quasistatic_sent/config.yaml", + "standard_workflow/dynamic_sent/config.yaml", + "two_material_dcb_beta/config.yaml", + "two_material_dcb_beta/comparisons/tough_region.yaml", + "two_material_dcb_beta/comparisons/uniform_layer.yaml", +]) +def test_schema_v2_explanation_cli(relative_path, tmp_path): + config = ROOT / "examples" / relative_path + env = dict(os.environ, PYTHONPATH=os.pathsep.join((str(ROOT / "src"), str(ROOT)))) + result = subprocess.run( + [sys.executable, "-m", "phast", "explain-config", str(config)], + cwd=tmp_path, env=env, capture_output=True, text=True, timeout=60, check=False, + ) + assert result.returncode == 0, result.stdout + result.stderr + for heading in ("Schema version: 2", "Materials and assignments", "Boundary conditions", + "Analysis steps", "Solver (requested)", "Outputs", "--validate-only"): + assert heading in result.stdout + assert "no mesh, solver, or output directory was created" in result.stdout + assert not (tmp_path / "runs").exists() + + +def test_explanation_does_not_resolve_multimaterial_mesh(monkeypatch): + def must_not_build(*args, **kwargs): + pytest.fail("explanation attempted to build the geometric mesh") + + monkeypatch.setattr("phast.workflow.multimaterial_fracture._build_mesh", must_not_build) + report, code = build_explanation(str(ROOT / "examples/two_material_dcb_beta/config.yaml")) + assert code == 0, report + assert "Declared settings only" in report + + +def test_invalid_schema_v2_reports_an_input_error(tmp_path): + config = tmp_path / "invalid.yaml" + config.write_text("schema_version: 2\nname: incomplete\n", encoding="utf-8") + report, code = build_explanation(str(config)) + assert code == 2 + assert "Error in" in report diff --git a/tests/test_hdf5_defaults.py b/tests/test_hdf5_defaults.py new file mode 100644 index 000000000..c2035296d --- /dev/null +++ b/tests/test_hdf5_defaults.py @@ -0,0 +1,254 @@ +"""Focused storage-default, provenance, and legacy-reader contracts.""" +from __future__ import annotations + +import json +import sys +from pathlib import Path +from types import SimpleNamespace + +import h5py +import numpy as np +import pytest +import torch + +from examples.plasticity_interface_beta import _promoted_result_utils as promoted +from examples.quasistatic import _run_utils as quasistatic +from phast.config.config import OutputConfig +from phast.result import Result, ResultLoadError +from phast.solid_mechanics_runners import _common as solid +from phast.utils.io_utils import load_state_from_h5, load_state_from_zarr + + +@pytest.fixture +def model() -> tuple[SimpleNamespace, SimpleNamespace]: + mesh = SimpleNamespace( + nodes=torch.tensor([[0., 0.], [1., 0.], [0., 1.]], dtype=torch.float64), + elements=torch.tensor([[0, 1, 2]], dtype=torch.int64), + node_sets={}, + ) + material = SimpleNamespace( + E=210000., nu=0.3, Gc=2.7, l0=0.1, rho=1., + energy_split="amor", pf_model="AT2", plane_stress=False, + ) + return mesh, material + + +def write_history( + out_dir: Path, + family: str, + model: tuple[SimpleNamespace, SimpleNamespace], + fmt: str | None = None, +) -> list[Path]: + mesh, material = model + fields = { + "damage_nodal": np.array([[0., 0.1, 0.2], [0., 0.25, 1.]]), + "displacement": np.zeros((2, 3, 2)), + "H_elem": np.ones((2, 1)), + } + steps = [7, 21] + if family == "quasistatic": + options = {} if fmt is None else {"fmt": fmt} + writers = quasistatic.open_trajectory_writers( + out_dir, mesh, material, enabled=True, **options, + ) + try: + for index, step in enumerate(steps): + for writer in writers: + writer.write( + step, mesh, + u=torch.from_numpy(fields["displacement"][index]), + d=torch.from_numpy(fields["damage_nodal"][index]), + psi_plus_e=torch.ones(1), + H_e=torch.from_numpy(fields["H_elem"][index]), + time_s=float(step), + ) + finally: + for writer in writers: + writer.close(len(steps)) + return [Path(writer.path) for writer in writers] + options = {} if fmt is None else {"trajectory_format": fmt} + if family == "promoted": + path = promoted.write_trajectory( + out_dir, nodes=mesh.nodes.numpy(), elements=mesh.elements.numpy(), + snapshots=[ + (step, {name: array[index] for name, array in fields.items()}) + for index, step in enumerate(steps) + ], + metadata={"example": "storage_contract"}, **options, + ) + else: + path = solid.write_solid_trajectory( + out_dir, mesh=mesh, steps=[{"step": step} for step in steps], + fields=fields, **options, + ) + return [path] + + +def result_at(path: Path) -> Result: + (path / "run_metadata.json").write_text("{}", encoding="utf-8") + return Result(path) + + +def test_config_defaults_keep_trajectory_saving_opt_in() -> None: + output = OutputConfig() + assert output.trajectory_format == "h5" + assert not output.trajectory + assert not output.h5 + + +def test_disabled_quasistatic_output_creates_no_store(tmp_path, model, monkeypatch) -> None: + monkeypatch.setitem(sys.modules, "h5py", None) + monkeypatch.setitem(sys.modules, "zarr", None) + assert quasistatic.open_trajectory_writers(tmp_path, *model, enabled=False) == [] + assert not list(tmp_path.iterdir()) + + +@pytest.mark.parametrize("family", ["quasistatic", "promoted", "solid"]) +def test_default_writers_use_h5_without_zarr(tmp_path, model, monkeypatch, family) -> None: + monkeypatch.setitem(sys.modules, "zarr", None) + paths = write_history(tmp_path, family, model) + assert paths == [tmp_path / "training_data.h5"] + assert not (tmp_path / "training_data.zarr").exists() + with h5py.File(paths[0], "r") as root: + assert root.attrs["format"].endswith(".h5") + assert sorted(root["simulation_data/steps"]) == ["step_0007", "step_0021"] + result = result_at(tmp_path) + np.testing.assert_allclose(result.field("damage"), [0., 0.25, 1.]) + np.testing.assert_allclose(result.field("damage", step=7), [0., 0.1, 0.2]) + assert result.mesh()["source"] == "training_data.h5" + assert result.mesh()["n_nodes"] == 3 + + +@pytest.mark.parametrize("family", ["quasistatic", "promoted", "solid"]) +def test_explicit_zarr_remains_readable(tmp_path, model, family) -> None: + pytest.importorskip("zarr") + paths = write_history(tmp_path, family, model, "zarr") + assert paths == [tmp_path / "training_data.zarr"] + assert not (tmp_path / "training_data.h5").exists() + result = result_at(tmp_path) + np.testing.assert_allclose(result.field("damage"), [0., 0.25, 1.]) + np.testing.assert_allclose(result.field("damage", step=7), [0., 0.1, 0.2]) + assert result.mesh()["source"] == "training_data.zarr" + + +@pytest.mark.parametrize("family", ["quasistatic", "promoted", "solid"]) +def test_missing_h5_backend_never_falls_back(tmp_path, model, monkeypatch, family) -> None: + monkeypatch.setitem(sys.modules, "h5py", None) + with pytest.raises(ImportError): + write_history(tmp_path, family, model) + assert not (tmp_path / "training_data.zarr").exists() + assert not (tmp_path / "training_data.h5").exists() + + +@pytest.mark.parametrize("family", ["quasistatic", "promoted", "solid"]) +def test_invalid_format_creates_no_store(tmp_path, model, family) -> None: + with pytest.raises(ValueError, match="format"): + write_history(tmp_path, family, model, "invalid") + assert not list(tmp_path.iterdir()) + + +def test_both_is_explicit_and_restart_readers_keep_working(tmp_path, model) -> None: + pytest.importorskip("zarr") + paths = write_history(tmp_path, "quasistatic", model, "both") + assert {path.name for path in paths} == {"training_data.h5", "training_data.zarr"} + for loader, name in ( + (load_state_from_h5, "training_data.h5"), + (load_state_from_zarr, "training_data.zarr"), + ): + state = loader(str(tmp_path / name)) + assert state["step"] == 21 + assert state["time_s"] == 21. + np.testing.assert_allclose(state["d"].numpy(), [0., 0.25, 1.]) + + +def test_h5_preference_preserves_and_does_not_open_old_zarr(tmp_path, model, monkeypatch) -> None: + old_store = tmp_path / "training_data.zarr" + old_store.mkdir() + sentinel = old_store / "historical.txt" + sentinel.write_bytes(b"historical data, not an HDF5 run") + write_history(tmp_path, "promoted", model) + monkeypatch.setitem(sys.modules, "zarr", None) + result = result_at(tmp_path) + np.testing.assert_allclose(result.field("damage"), [0., 0.25, 1.]) + assert result.mesh()["source"] == "training_data.h5" + assert sentinel.read_bytes() == b"historical data, not an HDF5 run" + + +def test_result_does_not_mix_fields_from_two_stores(tmp_path, model, monkeypatch) -> None: + write_history(tmp_path, "promoted", model) + result = result_at(tmp_path) + monkeypatch.setattr(result, "_discover_zarr_fields", lambda: {"stress"}) + assert "stress" not in result.field_names() + with pytest.raises(ResultLoadError, match="Unknown field"): + result.field("stress") + + +def test_missing_h5_mesh_does_not_select_an_old_zarr_mesh(tmp_path, monkeypatch) -> None: + with h5py.File(tmp_path / "training_data.h5", "w"): + pass + result = result_at(tmp_path) + monkeypatch.setattr(result, "_zarr_mesh_metadata", lambda: {"n_nodes": 999}) + with pytest.raises(ResultLoadError, match="No mesh metadata"): + result.mesh() + + +def test_corrupt_h5_is_not_hidden_by_zarr(tmp_path, monkeypatch) -> None: + (tmp_path / "training_data.h5").write_bytes(b"not HDF5") + result = result_at(tmp_path) + monkeypatch.setattr(result, "_discover_zarr_fields", lambda: {"damage_nodal"}) + with pytest.raises(OSError): + result.field_names() + + +def test_promoted_zarr_compatibility_entry_point(tmp_path, model) -> None: + pytest.importorskip("zarr") + mesh, _ = model + path = promoted.write_zarr_trajectory( + tmp_path, nodes=mesh.nodes.numpy(), elements=mesh.elements.numpy(), + snapshots=[(3, {"damage_nodal": np.zeros(3)})], metadata={}, + ) + assert path.name == "training_data.zarr" + np.testing.assert_array_equal(result_at(tmp_path).field("damage", step=3), np.zeros(3)) + + +@pytest.mark.parametrize("fmt", [None, "h5", "zarr", "both"]) +def test_lockfile_records_actual_outputs_not_requested_default(tmp_path, model, fmt) -> None: + paths = [] + if fmt is not None: + if fmt in {"zarr", "both"}: + pytest.importorskip("zarr") + paths = write_history(tmp_path, "quasistatic", model, fmt) + solid.write_run_lockfile( + tmp_path, config={"output": {"trajectory_format": "h5"}}, + command="storage-contract", trajectory_paths=paths, + ) + lockfile = json.loads((tmp_path / "run_lockfile.json").read_text()) + assert lockfile["trajectory_format"] == fmt + assert lockfile["requested_trajectory_format"] == "h5" + assert lockfile["trajectory_files"] == [path.name for path in paths] + + +def test_lockfile_does_not_relabel_a_previous_run(tmp_path, model) -> None: + write_history(tmp_path, "solid", model) + solid.write_run_lockfile(tmp_path, config={}, command="no-trajectory-run") + lockfile = json.loads((tmp_path / "run_lockfile.json").read_text()) + assert lockfile["trajectory_format"] is None + assert lockfile["trajectory_files"] == [] + + +def test_lockfile_rejects_missing_trajectory_output(tmp_path) -> None: + with pytest.raises(ValueError, match="missing or unsupported"): + solid.write_run_lockfile( + tmp_path, config={}, command="missing-output", + trajectory_paths=[tmp_path / "training_data.h5"], + ) + assert not (tmp_path / "run_lockfile.json").exists() + + +def test_solid_h5_rejects_misaligned_history_before_writing(tmp_path, model) -> None: + with pytest.raises(ValueError, match="one entry per trajectory step"): + solid.write_solid_trajectory( + tmp_path, mesh=model[0], steps=[{"step": 1}], + fields={"damage_nodal": np.zeros((2, 3))}, + ) + assert not (tmp_path / "training_data.h5").exists() diff --git a/tests/test_multimaterial_workflow.py b/tests/test_multimaterial_workflow.py new file mode 100644 index 000000000..bb2b18867 --- /dev/null +++ b/tests/test_multimaterial_workflow.py @@ -0,0 +1,197 @@ +from pathlib import Path +from dataclasses import replace + +import numpy as np +import pytest + +from phast.workflow import execution_plan_from_spec, problem_spec_from_yaml +from phast.workflow import multimaterial_fracture as backend +from phast.workflow.multimaterial_fracture import ( + MultimaterialWorkflowError, _selector_mask, validate_multimaterial_fracture_spec, +) +from phast.workflow.specs import FieldOutputSpec, HistoryOutputSpec, InitialConditionSpec, PostprocessSpec + + +ROOT = Path(__file__).resolve().parents[1] +CONFIG = ROOT / "examples" / "two_material_dcb_beta" / "config.yaml" +SENT_CONFIG = ROOT / "examples" / "heterogeneous_sent_beta" / "config.yaml" + + +def test_dcb_config_uses_standard_executable_workflow(): + spec = problem_spec_from_yaml(CONFIG) + plan = execution_plan_from_spec(spec) + assert spec.schema_version == 2 + assert len(spec.materials) == 3 + assert plan.route == "run_config" + assert plan.direct_execution_supported + + +def test_heterogeneous_sent_uses_standard_executable_workflow(): + spec = problem_spec_from_yaml(SENT_CONFIG) + plan = execution_plan_from_spec(spec) + assert spec.schema_version == 2 + assert len(spec.materials) == 2 + assert plan.route == "run_config" + assert plan.direct_execution_supported + + +def test_circle_regions_partition_points(): + points = np.array([[0.0, 0.0], [1.0, 0.0], [2.0, 0.0]]) + circle = {"type": "circle", "center": [1.0, 0.0], "radius": 0.25} + outside = {"type": "outside_circle", "center": [1.0, 0.0], "radius": 0.25} + inside_mask = _selector_mask(points, circle) + outside_mask = _selector_mask(points, outside) + assert np.array_equal(inside_mask, np.array([False, True, False])) + assert np.array_equal(outside_mask, ~inside_mask) + + +def test_composable_region_selectors_partition_weak_layer(): + points = np.array([[0.0, 0.0], [0.0, 0.2], [1.0, 0.0]]) + circle = {"type": "circle", "center": [1.0, 0.0], "radius": 0.25} + weak = { + "type": "all_of", + "selectors": [ + {"type": "rectangle", "origin": [0.0, -0.1], "size": [2.0, 0.2]}, + {"type": "not", "selector": circle}, + ], + } + assert np.array_equal( + _selector_mask(points, weak), np.array([True, False, False])) + + +@pytest.fixture +def dcb_spec(): + return problem_spec_from_yaml(CONFIG) + + +def _material_change(spec, **parameters): + materials = list(spec.materials) + materials[-1] = replace(materials[-1], parameters={**materials[-1].parameters, **parameters}) + return replace(spec, materials=materials) + + +def _region_change(spec, name, selector): + return replace(spec, regions=[replace(r, selector=selector) if r.name == name else r for r in spec.regions]) + + +def _geometry_change(spec, **parameters): + return replace(spec, geometry=replace(spec.geometry, parameters={**spec.geometry.parameters, **parameters})) + + +@pytest.mark.parametrize("config", [CONFIG, SENT_CONFIG]) +def test_valid_preflight_never_constructs_a_kernel_or_creates_output(config, monkeypatch): + def forbidden(*args, **kwargs): + pytest.fail("preflight must not construct kernels or create output") + monkeypatch.setattr(backend.FEMMesh, "from_tensors", forbidden) + monkeypatch.setattr(backend, "FEMOperators", forbidden) + monkeypatch.setattr(backend, "QuasiStaticSolver", forbidden) + monkeypatch.setattr(backend, "PhaseFieldDamageSolver", forbidden) + monkeypatch.setattr(Path, "mkdir", forbidden) + assert validate_multimaterial_fracture_spec(problem_spec_from_yaml(config)) is None + + +@pytest.mark.parametrize("key", ["E", "Gc", "l0", "rho"]) +@pytest.mark.parametrize("value", [0.0, -1.0, float("nan"), float("inf")]) +def test_nonpositive_or_nonfinite_material_is_rejected(dcb_spec, key, value): + with pytest.raises(MultimaterialWorkflowError, match=key): + validate_multimaterial_fracture_spec(_material_change(dcb_spec, **{key: value})) + + +@pytest.mark.parametrize("nu", [-1.0, 0.5, float("nan"), float("inf")]) +def test_invalid_poisson_ratio(dcb_spec, nu): + with pytest.raises(MultimaterialWorkflowError, match="nu"): + validate_multimaterial_fracture_spec(_material_change(dcb_spec, nu=nu)) + + +@pytest.mark.parametrize("key,value", [("eta_residual", .01), ("rho", 2.), ("l0", .2), ("nu", .25), ("plane_stress", False)]) +def test_unsupported_material_differences_are_not_ignored(dcb_spec, key, value): + with pytest.raises(MultimaterialWorkflowError, match=key): + validate_multimaterial_fracture_spec(_material_change(dcb_spec, **{key: value})) + + +def test_unknown_material_parameter(dcb_spec): + with pytest.raises(MultimaterialWorkflowError, match="unsupported material"): + validate_multimaterial_fracture_spec(_material_change(dcb_spec, viscosity=1.)) + + +@pytest.mark.parametrize("length,message", [(5., "selects no nodes"), (8., "interior nodes")]) +def test_stale_coordinate_clamp_rejected(dcb_spec, length, message): + spec = _region_change(dcb_spec, "right_clamp", {"type": "boundary", "axis": "x", "value": 6.}) + with pytest.raises(MultimaterialWorkflowError, match=message): + validate_multimaterial_fracture_spec(_geometry_change(spec, length=length)) + + +def test_empty_seed_rejected_before_solver_and_output(dcb_spec, monkeypatch): + def forbidden(*args, **kwargs): + pytest.fail("invalid input reached kernel construction or output creation") + monkeypatch.setattr(backend.FEMMesh, "from_tensors", forbidden) + monkeypatch.setattr(Path, "mkdir", forbidden) + with pytest.raises(MultimaterialWorkflowError, match="initial damage region.*selects no nodes"): + backend.run_multimaterial_fracture_spec(_geometry_change(dcb_spec, ny=47)) + + +def test_empty_material2_region(dcb_spec): + spec = _region_change(dcb_spec, "material_2_region", {"type": "circle", "center": [20., 0.], "radius": .2}) + with pytest.raises(MultimaterialWorkflowError, match="material_2_region.*selects no elements"): + validate_multimaterial_fracture_spec(spec) + + +@pytest.mark.parametrize("side,axis,end", [("left", 0, 0), ("right", 0, 1), ("bottom", 1, 0), ("top", 1, 1)]) +def test_side_selector_uses_full_nodal_bounds(dcb_spec, side, axis, end): + nodes, elements = backend._build_mesh(dcb_spec) + bounds = (nodes.min(axis=0), nodes.max(axis=0)) + selector = {"type": "boundary", "side": side} + mask = _selector_mask(nodes, selector, nodal_bounds=bounds) + assert np.array_equal(mask, np.isclose(nodes[:, axis], bounds[end][axis])) + assert not _selector_mask(nodes[elements].mean(axis=1), selector, nodal_bounds=bounds).any() + with pytest.raises(MultimaterialWorkflowError, match="structured rectangle"): + _selector_mask(nodes, selector) + + +def test_right_side_preserves_reference_nodes_and_tracks_length(dcb_spec): + nodes, elements = backend._build_mesh(dcb_spec) + old, _ = backend._resolve_regions(dcb_spec, nodes, elements) + spec = _region_change(dcb_spec, "right_clamp", {"type": "boundary", "side": "right", "tolerance": 1.e-8}) + new, _ = backend._resolve_regions(spec, nodes, elements) + assert np.array_equal(old["right_clamp"], new["right_clamp"]) + validate_multimaterial_fracture_spec(_geometry_change(spec, length=8.)) + + +@pytest.mark.parametrize("condition", [InitialConditionSpec(field="displacement", region="initial_crack", value=0.), InitialConditionSpec(field="damage", region="initial_crack", value=2.), InitialConditionSpec(field="damage", region="initial_crack", value=float("nan"))]) +def test_invalid_initial_condition(dcb_spec, condition): + with pytest.raises(MultimaterialWorkflowError): + validate_multimaterial_fracture_spec(replace(dcb_spec, initial_conditions=[condition])) + + +@pytest.mark.parametrize("field", ["history_field_nodal", "psi_plus", "velocity", "unknown"]) +def test_unimplemented_field_requests(dcb_spec, field): + outputs = replace(dcb_spec.outputs, fields=[FieldOutputSpec(name=field)]) + with pytest.raises(MultimaterialWorkflowError, match="field output"): + validate_multimaterial_fracture_spec(replace(dcb_spec, outputs=outputs)) + + +def test_energy_history_rejected(dcb_spec): + outputs = replace(dcb_spec.outputs, history=[HistoryOutputSpec(name="energy")]) + with pytest.raises(MultimaterialWorkflowError, match="history output"): + validate_multimaterial_fracture_spec(replace(dcb_spec, outputs=outputs)) + + +def test_unimplemented_animation_and_trajectory_format(dcb_spec): + for outputs in [replace(dcb_spec.outputs, postprocess=[PostprocessSpec(kind="animation", parameters={"field": "stress"})]), replace(dcb_spec.outputs, fields=[FieldOutputSpec(name="trajectory", parameters={"format": "zarr"})])]: + with pytest.raises(MultimaterialWorkflowError): + validate_multimaterial_fracture_spec(replace(dcb_spec, outputs=outputs)) + + +def test_reaction_request_honours_region_and_component(dcb_spec): + nodes, elements = backend._build_mesh(dcb_spec) + regions, _ = backend._resolve_regions(dcb_spec, nodes, elements) + bcs = backend._resolve_bcs(dcb_spec, regions) + reference_indices, reference_component = backend._resolve_reaction(dcb_spec, regions, bcs) + assert np.array_equal(reference_indices.numpy(), np.flatnonzero(regions["upper_load"])) + assert reference_component == 1 + output = replace(dcb_spec.outputs, history=[HistoryOutputSpec(name="reaction_force", region="right_clamp", component=0)]) + spec = replace(dcb_spec, outputs=output) + validate_multimaterial_fracture_spec(spec) + indices, component = backend._resolve_reaction(spec, regions, bcs) + assert np.array_equal(indices.numpy(), np.flatnonzero(regions["right_clamp"])) + assert component == 0 diff --git a/tests/test_standard_workflow.py b/tests/test_standard_workflow.py new file mode 100644 index 000000000..3f35711be --- /dev/null +++ b/tests/test_standard_workflow.py @@ -0,0 +1,398 @@ +"""Bounded schema-v2 fracture execution through the existing public CLI.""" +from __future__ import annotations + +import copy +import csv +import json +import os +from pathlib import Path +import subprocess +import sys +from typing import Any + +import h5py +import meshio +import numpy as np +import pytest +import yaml + +from phast import Problem +from phast.config.config import load_config +from phast.workflow import ( + execution_plan_from_spec, problem_spec_from_yaml, problem_spec_to_schema_v2_dict, + run_problem_spec, validate_problem_spec, +) +from phast.workflow.execution import WorkflowExecutionError, _schema_v2_fracture_legacy_yaml + +ROOT = Path(__file__).resolve().parents[1] +EXAMPLES = ROOT / "examples" / "standard_workflow" +TOP_LEVEL = [ + "schema_version", "name", "reference", "geometry", "regions", "materials", + "assignments", "initial_conditions", "boundary_conditions", "analysis_steps", + "solver", "outputs", +] + + +def _example(kind: str = "dynamic_sent") -> dict[str, Any]: + return yaml.safe_load((EXAMPLES / kind / "config.yaml").read_text()) + + +def _write(tmp_path: Path, raw: Any, name: str = "config.yaml") -> Path: + path = tmp_path / name + path.write_text(yaml.safe_dump(raw, sort_keys=False)) + return path + + +def _cli(path: Path, *args: str) -> subprocess.CompletedProcess[str]: + env = dict(os.environ, PYTHONPATH=os.pathsep.join((str(ROOT / "src"), str(ROOT))), + MPLBACKEND="Agg", OMP_NUM_THREADS="1", OPENBLAS_NUM_THREADS="1") + return subprocess.run( + [sys.executable, "-m", "phast", "run", str(path), *args], cwd=path.parent, + env=env, text=True, capture_output=True, timeout=60, check=False, + ) + + +@pytest.mark.parametrize("relative_path", [ + "config.yaml", "comparisons/tough_region.yaml", "comparisons/uniform_layer.yaml", +]) +def test_dcb_cli_validation_does_not_solve(relative_path: str, tmp_path: Path) -> None: + raw = yaml.safe_load((ROOT / "examples" / "two_material_dcb_beta" / relative_path).read_text()) + target = tmp_path / "must_not_exist" + raw["outputs"]["directory"] = str(target) + result = _cli(_write(tmp_path, raw), "--validate-only") + assert result.returncode == 0, result.stdout + result.stderr + assert not target.exists() + + +@pytest.mark.parametrize("case", ["negative_Gc", "empty_seed", "interior_boundary"]) +def test_dcb_invalid_edits_fail_during_cli_validation(case: str, tmp_path: Path) -> None: + raw = yaml.safe_load((ROOT / "examples" / "two_material_dcb_beta" / "config.yaml").read_text()) + target = tmp_path / "must_not_exist" + raw["outputs"]["directory"] = str(target) + if case == "negative_Gc": + raw["materials"]["material_2"]["parameters"]["Gc"] = -0.12 + elif case == "empty_seed": + raw["regions"]["initial_crack"].update({"from": [10.0, 0.0], "to": [11.0, 0.0]}) + else: + raw["geometry"]["parameters"]["length"] = 12.0 + raw["regions"]["right_clamp"] = { + "kind": "node_region", "type": "boundary", "axis": "x", "value": 6.0, + } + path = _write(tmp_path, raw) + assert validate_problem_spec(problem_spec_from_yaml(path)), case + result = _cli(path, "--validate-only") + assert result.returncode == 2, result.stdout + result.stderr + assert not target.exists() + + +@pytest.mark.parametrize("kind", ["dynamic_sent", "quasistatic_sent"]) +def test_canonical_load_and_round_trip(kind: str, tmp_path: Path) -> None: + raw = _example(kind) + assert list(raw) == TOP_LEVEL + spec = problem_spec_from_yaml(_write(tmp_path, raw)) + assert not validate_problem_spec(spec) + assert execution_plan_from_spec(spec).direct_execution_supported + assert spec.outputs.fields[0].parameters["format"] == "h5" + restored = problem_spec_from_yaml(_write(tmp_path, problem_spec_to_schema_v2_dict(spec), "roundtrip.yaml")) + assert _schema_v2_fracture_legacy_yaml(restored) == _schema_v2_fracture_legacy_yaml(spec) + lowered = _schema_v2_fracture_legacy_yaml(spec) + assert lowered["output"]["output_dir"] == raw["outputs"]["directory"] + assert "directory" not in lowered["output"] + assert lowered["boundary_conditions"][2]["nodes"] == "top" + assert lowered["initial_conditions"]["preseed_damage"][0]["nodes"] == "crack" + + +@pytest.mark.parametrize("kind", ["dynamic_sent", "quasistatic_sent"]) +def test_cli_validate_run_output_override_and_v1_parity(kind: str, tmp_path: Path) -> None: + raw = _example(kind) + ignored = tmp_path / "configured_but_overridden" + raw["outputs"]["directory"] = str(ignored) + path = _write(tmp_path, raw) + target = tmp_path / "v2" + validation = _cli(path, "--validate-only", "--output_dir", str(target)) + assert validation.returncode == 0, validation.stdout + validation.stderr + assert "passes schema-v2 workflow contract validation" in validation.stdout + assert not target.exists() + run = _cli(path, "--output_dir", str(target)) + assert run.returncode == 0, run.stdout + run.stderr + assert not ignored.exists() + assert not (target / "training_data.zarr").exists() + for name in ("training_data.h5", "config.yaml", "run_lockfile.json", "run_metadata.json", + "energy.csv", "results.csv", "solver_telemetry.csv", "timing_per_step.csv"): + assert (target / name).is_file(), name + metadata = json.loads((target / "run_metadata.json").read_text()) + assert "num_steps" in json.dumps(metadata) + with (target / "energy.csv").open() as stream: + assert len(list(csv.DictReader(stream))) == 4 + with h5py.File(target / "training_data.h5") as store: + assert store.attrs["num_steps"] == 4 + + # The same normalised inputs still use the v1 loader and original loop. + spec = problem_spec_from_yaml(path) + legacy = _schema_v2_fracture_legacy_yaml(spec) + legacy["geometry"]["parameters"]["output_path"] = str(tmp_path / "v1" / "mesh.msh") + v1_path = _write(tmp_path, legacy, "legacy.yaml") + v1_spec = problem_spec_from_yaml(v1_path) + assert v1_spec.source == "yaml:v1" + assert execution_plan_from_spec(v1_spec).direct_execution_supported + v1_run = _cli(v1_path, "--output_dir", str(tmp_path / "v1")) + assert v1_run.returncode == 0, v1_run.stdout + v1_run.stderr + np.testing.assert_allclose( + np.genfromtxt(target / "energy.csv", delimiter=",", skip_header=1), + np.genfromtxt(tmp_path / "v1" / "energy.csv", delimiter=",", skip_header=1), + rtol=1.0e-12, atol=1.0e-14, + ) + + +def test_automatic_cfl_loading_and_hdf5_default(tmp_path: Path) -> None: + raw = _example() + raw["analysis_steps"][0]["controls"] = {"t_total": 1.0e-7} + raw["solver"]["dt_safety"] = 0.5 + raw["outputs"]["fields"][0].pop("format") + spec = problem_spec_from_yaml(_write(tmp_path, raw)) + assert not validate_problem_spec(spec) + path = _write(tmp_path, _schema_v2_fracture_legacy_yaml(spec), "legacy.yaml") + config = load_config(str(path)) + assert config.loading.num_steps == 0 + assert config.solver.dt_safety == 0.5 + assert config.output.trajectory_format == "h5" + + +@pytest.mark.parametrize("case", [ + "multiple_steps", "step_mismatch", "multimaterial_dynamic", "partial_material", + "geometric_region", "initial_velocity", "initial_damage_range", "unknown_solver", + "learned", "implicit_integrator", "adaptive_dt", "unused_backend", "unknown_control", + "missing_dt", "both_time_limits", "fixed_dt_and_cfl", "unknown_geometry", "3d", + "higher_order", "material_typo", "negative_density", "nonfinite_material", + "unknown_output", "vtu", "field_without_trajectory", "field_cadence", + "history_cadence", "two_reactions", "unknown_visual", "unknown_bc_parameter", + "nonzero_fix", "bad_trajectory_format", +]) +def test_unsupported_choices_fail_before_execution(case: str, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None: + raw = _example() + if case == "multiple_steps": + raw["analysis_steps"].append({**copy.deepcopy(raw["analysis_steps"][0]), "name": "second"}) + elif case == "step_mismatch": + raw["analysis_steps"][0]["type"] = "quasi_static" + elif case == "multimaterial_dynamic": + raw["materials"]["second"] = copy.deepcopy(raw["materials"]["glass"]) + raw["assignments"].append({"material": "second", "region": "body"}) + elif case == "partial_material": + raw["assignments"][0]["region"] = "left_edge" + elif case == "geometric_region": + raw["regions"]["left_edge"] = {"type": "boundary", "axis": "x", "value": 0} + elif case == "initial_velocity": + raw["initial_conditions"][0]["field"] = "velocity" + elif case == "initial_damage_range": + raw["initial_conditions"][0]["value"] = 2.0 + elif case in {"unknown_solver", "learned", "implicit_integrator", "adaptive_dt", "unused_backend"}: + key, value = { + "unknown_solver": ("damage_toll", 1.0e-6), "learned": ("damage_update", "learned_proposal"), + "implicit_integrator": ("time_integrator", "generalized_alpha"), + "adaptive_dt": ("adaptive_dt", True), "unused_backend": ("backend", "scipy"), + }[case] + raw["solver"][key] = value + elif case == "unknown_control": + raw["analysis_steps"][0]["controls"]["number_of_stepz"] = 2 + elif case == "missing_dt": + raw["analysis_steps"][0]["controls"].pop("dt") + elif case == "both_time_limits": + raw["analysis_steps"][0]["controls"]["t_total"] = 1.0e-6 + elif case == "fixed_dt_and_cfl": + raw["solver"]["dt_safety"] = 0.5 + elif case in {"unknown_geometry", "3d", "higher_order"}: + raw["geometry"]["parameters"][{"unknown_geometry": "width_typo", "3d": "nz", "higher_order": "order"}[case]] = 2 + elif case in {"material_typo", "negative_density", "nonfinite_material"}: + key, value = {"material_typo": ("Gc_typo", 1.0), "negative_density": ("rho", -1.0), "nonfinite_material": ("E", float("nan"))}[case] + raw["materials"]["glass"]["parameters"][key] = value + elif case == "unknown_output": + raw["outputs"]["trajectory_formatt"] = "h5" + elif case == "vtu": + raw["outputs"]["fields"].append({"name": "vtu"}) + elif case == "field_without_trajectory": + raw["outputs"]["fields"].pop(0) + elif case == "field_cadence": + raw["outputs"]["fields"][1]["every"] = 2 + elif case == "history_cadence": + raw["outputs"]["history"][0]["every"] = 2 + elif case == "two_reactions": + raw["outputs"]["history"].append({"name": "reaction", "region": "lower_edge", "dof": "y"}) + elif case == "unknown_visual": + raw["outputs"]["visuals"]["thumbnail"] = True + elif case == "unknown_bc_parameter": + raw["boundary_conditions"][2]["ramp_type"] = "linear" + elif case == "nonzero_fix": + raw["boundary_conditions"][0]["value"] = 1.0 + elif case == "bad_trajectory_format": + raw["outputs"]["fields"][0]["format"] = "hdf_typo" + spec = problem_spec_from_yaml(_write(tmp_path, raw)) + assert validate_problem_spec(spec), case + monkeypatch.setattr("phast.workflow.execution.subprocess.run", lambda *a, **kw: pytest.fail("invalid spec started a subprocess")) + with pytest.raises(WorkflowExecutionError): + run_problem_spec(spec, output_dir=tmp_path / "must_not_exist") + assert not (tmp_path / "must_not_exist").exists() + + +@pytest.mark.parametrize("case", ["unknown_top", "materials_scalar", "steps_scalar", "controls_scalar", "active_scalar", "fractional_cadence", "boolean_cadence", "material_sibling", "dof_aliases"]) +def test_malformed_v2_input(case: str, tmp_path: Path) -> None: + raw = _example() + if case == "unknown_top": + raw["output"] = {} + elif case == "materials_scalar": + raw["materials"] = "glass" + elif case == "steps_scalar": + raw["analysis_steps"] = "explicit" + elif case == "controls_scalar": + raw["analysis_steps"][0]["controls"] = 1 + elif case == "active_scalar": + raw["analysis_steps"][0]["active_boundary_conditions"] = "open_upper" + elif case in {"fractional_cadence", "boolean_cadence"}: + raw["outputs"]["fields"][0]["every"] = 1.5 if case == "fractional_cadence" else True + elif case == "material_sibling": + raw["materials"]["glass"]["Gc"] = 3.0 + elif case == "dof_aliases": + raw["boundary_conditions"][0]["component"] = 1 + with pytest.raises((ValueError, TypeError)): + problem_spec_from_yaml(_write(tmp_path, raw)) + + +def test_cli_rejects_unsupported_override_and_malformed_input(tmp_path: Path) -> None: + path = _write(tmp_path, _example()) + result = _cli(path, "--validate-only", "--num_steps", "2") + assert result.returncode == 2 + assert "only --output_dir" in result.stderr + malformed = _write(tmp_path, {**_example(), "ignored_setting": 1}, "malformed.yaml") + result = _cli(malformed, "--validate-only") + assert result.returncode == 2 + assert "Unknown schema-v2 top-level keys" in result.stderr + assert "Traceback" not in result.stderr + + +def test_primitive_geometry_preserves_mesh_refinement(tmp_path: Path) -> None: + raw = _example() + raw["geometry"] = { + "units": "mm", "primitives": {"plate": {"type": "rectangle", "origin": [0, 0], "size": [4, 4]}}, + "domain": {"base": "plate"}, "mesh": {"element_size": {"default": 0.5}}, + } + spec = problem_spec_from_yaml(_write(tmp_path, raw)) + assert not validate_problem_spec(spec) + geometry = _schema_v2_fracture_legacy_yaml(spec)["geometry"] + assert "type" not in geometry + assert "parameters" not in geometry + assert geometry["mesh"] == raw["geometry"]["mesh"] + + +def test_original_v1_public_dynamic_input_is_preserved() -> None: + path = ROOT / "examples/dynamic/B3_dynamic_sent/config.yaml" + spec = problem_spec_from_yaml(path) + config = load_config(str(path)) + assert spec.source == "yaml:v1" + assert config.loading.num_steps == 0 + assert config.loading.t_total == pytest.approx(1.0e-4) + assert config.solver.dt_safety == 0.8 + assert config.material.energy_split == "spectral" + assert config.output.trajectory_format == "h5" + assert execution_plan_from_spec(spec).direct_execution_supported + + +def _fluent_external_problem(tmp_path: Path, *, partial: bool = False) -> Problem: + mesh_path = tmp_path / "plate.msh" + mesh = meshio.Mesh( + points=np.array([[0., 0., 0.], [1., 0., 0.], [1., 1., 0.], [0., 1., 0.]]), + cells=[("line", np.array([[0, 1], [1, 2], [2, 3], [3, 0]])), + ("triangle", np.array([[0, 1, 2], [0, 2, 3]]))], + field_data={"bottom": [1, 1], "right": [2, 1], "top": [3, 1], "left": [4, 1], "body": [5, 2], "other": [6, 2]}, + cell_data={"gmsh:physical": [np.array([1, 2, 3, 4]), np.array([5, 6 if partial else 5])], + "gmsh:geometrical": [np.array([1, 2, 3, 4]), np.array([5, 6 if partial else 5])]}, + ) + meshio.write(mesh_path, mesh, file_format="gmsh22", binary=False) + return (Problem("Saved two-step quasi-static setup") + .mesh(mesh_path) + .region("body", kind="domain", from_mesh="body") + .region("lower", from_mesh="bottom").region("upper", from_mesh="top") + .material("miehe_tension", region="body", E=1000.0, l0=0.5, energy_split="isotropic") + .boundary_condition("fix", region="lower", dof="xy", name="clamp") + .boundary_condition("prescribe", region="upper", dof="y", value=1.0e-6, name="opening") + .analysis_step("opening", kind="quasi_static", controls={"num_steps": 2, "dt": 0.5}, + active_boundary_conditions=["clamp", "opening"]) + .solver("quasi_static", backend="scipy", preconditioner="jacobi") + .outputs(fields=[{"name": "trajectory", "every": 1, "format": "h5"}], + histories=[{"name": "reaction_force", "region": "upper", "dof": "y"}], + h5_every=1, plots=False, profile=True, gif=False, + output_dir=str(tmp_path / "configured"))) + + +def test_actual_problem_save_validate_and_run(tmp_path: Path) -> None: + problem = _fluent_external_problem(tmp_path) + path = tmp_path / "saved.yaml" + problem.save(path) + spec = problem_spec_from_yaml(path) + assert spec.source == "yaml:v2" + assert spec.mesh is not None and not spec.mesh.parameters + assert not validate_problem_spec(spec) + assert spec.outputs.parameters["profile"] is True + assert "h5" not in spec.outputs.parameters + validation = _cli(path, "--validate-only") + assert validation.returncode == 0, validation.stdout + validation.stderr + run = _cli(path, "--output_dir", str(tmp_path / "saved_run")) + assert run.returncode == 0, run.stdout + run.stderr + with h5py.File(tmp_path / "saved_run" / "training_data.h5") as store: + assert store.attrs["num_steps"] == 2 + assert (tmp_path / "saved_run" / "results.csv").is_file() + + +def test_saved_material_subdomain_is_not_silently_made_global(tmp_path: Path) -> None: + problem = _fluent_external_problem(tmp_path, partial=True) + path = tmp_path / "partial.yaml" + problem.save(path) + issues = validate_problem_spec(problem_spec_from_yaml(path)) + assert any("does not contain all 2 elements" in issue.message for issue in issues) + result = _cli(path, "--validate-only") + assert result.returncode == 2 + assert "does not contain all 2 elements" in result.stderr + + +@pytest.mark.parametrize("case", [ + "damage_bc_range", "damage_bc_nan", "displacement_units", "symmetry_axis", "connector_master", + "connector_dofs", "connector_prescribe", "null_steps", "zero_cfl", "damage_component", + "symmetry_value", "connector_component", "step_aliases", +]) +def test_reviewed_input_failures_are_rejected(case: str, tmp_path: Path) -> None: + raw = _example() + if case == "damage_bc_range": + raw["boundary_conditions"][-1]["value"] = 2.0 + elif case == "damage_bc_nan": + raw["boundary_conditions"][-1]["value"] = float("nan") + elif case == "displacement_units": + raw["boundary_conditions"][2]["value"] = "2 bananas" + elif case in {"symmetry_axis", "symmetry_value"}: + raw["boundary_conditions"][0] = {"name": "restrain_left", "type": "symmetry", "region": "left_edge"} + if case == "symmetry_value": + raw["boundary_conditions"][0].update(axis="x", value=2.0) + elif case.startswith("connector"): + bc = {"name": "restrain_left", "type": "rigid_connector", "region": "left_edge", "master": "right_edge"} + if case == "connector_master": + bc.pop("master") + elif case == "connector_dofs": + bc["dofs"] = ["z"] + elif case == "connector_prescribe": + bc["prescribe"] = {"z": 1.0} + else: + bc["component"] = 0 + raw["boundary_conditions"][0] = bc + elif case in {"null_steps", "zero_cfl"}: + raw["analysis_steps"][0]["controls"] = {"t_total": 1.0e-7} + if case == "null_steps": + raw["analysis_steps"][0]["controls"]["num_steps"] = None + else: + raw["solver"]["dt_safety"] = 0.0 + elif case == "damage_component": + raw["boundary_conditions"][-1]["component"] = 0 + elif case == "step_aliases": + raw["analysis_steps"][0]["kind"] = "quasi_static" + path = _write(tmp_path, raw) + if case == "step_aliases": + with pytest.raises(ValueError, match="type or kind"): + problem_spec_from_yaml(path) + else: + assert validate_problem_spec(problem_spec_from_yaml(path)), case diff --git a/tests/test_teaching_notebook_contract.py b/tests/test_teaching_notebook_contract.py new file mode 100644 index 000000000..acab12d61 --- /dev/null +++ b/tests/test_teaching_notebook_contract.py @@ -0,0 +1,102 @@ +"""Bounded contracts for the three executable teaching notebooks.""" +from __future__ import annotations + +import ast +import json +from pathlib import Path + +import numpy as np +import pytest + + +ROOT = Path(__file__).resolve().parents[1] +NAMES = ( + "notebook_setup.ipynb", + "problem_setup_walkthrough.ipynb", + "notebook_square_plate_fracture.ipynb", +) + + +@pytest.fixture(scope="module") +def notebooks(): + return { + name: json.loads((ROOT / "docs" / "tutorial" / name).read_text(encoding="utf-8")) + for name in NAMES + } + + +def sources(notebook, kind=None): + return [ + "".join(cell["source"]) + for cell in notebook["cells"] + if kind is None or cell["cell_type"] == kind + ] + + +@pytest.mark.parametrize("name", NAMES) +def test_notebooks_have_clean_compilable_cells(notebooks, name): + for index, cell in enumerate(notebooks[name]["cells"]): + if cell["cell_type"] == "code": + assert cell["execution_count"] is None + assert cell["outputs"] == [] + compile("".join(cell["source"]), f"{name}:cell-{index}", "exec") + + +@pytest.mark.parametrize("name", NAMES) +def test_installation_and_finite_output_contract(notebooks, name): + all_source = "\n".join(sources(notebooks[name])) + code = "\n".join(sources(notebooks[name], "code")) + assert "Python >=3.10" in all_source + assert "jupyterlab" in all_source + assert "mutable" in all_source + assert "nan_to_num" not in code + assert "v0.16.2-arxiv.2606.23458" not in all_source + assert "PHAST_NOTEBOOK_OUTPUT_ROOT" in code + assert "require_finite" in code + assert '"Reds"' in code + + +def test_setup_notebooks_share_single_configuration(notebooks): + first, second = (notebooks[name] for name in NAMES[:2]) + assert sources(first, "code") == sources(second, "code") + code = "\n".join(sources(first, "code")) + assert "problem.save(config_path)" in code + assert "execution_config" not in code + assert "authored_problem_spec.yaml" not in code + assert "fail_on_mechanics_nonconvergence=True" in code + assert "fail_on_stagger_nonconvergence=True" in code + assert "range(history_len)" not in code + assert "stored_steps" in code + assert "its plot is omitted" in code + + +@pytest.mark.parametrize("name", NAMES) +@pytest.mark.parametrize("bad", ([np.nan], [np.inf], [-np.inf], [])) +def test_nonfinite_and_empty_fields_are_rejected(notebooks, name, bad): + definitions = [] + for source in sources(notebooks[name], "code"): + definitions.extend( + node for node in ast.parse(source).body + if isinstance(node, ast.FunctionDef) and node.name == "require_finite" + ) + assert len(definitions) == 1 + namespace = {"np": np} + module = ast.Module(body=definitions, type_ignores=[]) + exec(compile(module, "", "exec"), namespace) + guard = namespace["require_finite"] + with pytest.raises(ValueError, match="non-finite"): + guard(bad, "test field") + np.testing.assert_array_equal(guard([0.0, 1.0], "valid field"), [0.0, 1.0]) + + +def test_square_plate_preserves_compatibility_and_stress_meaning(notebooks): + notebook = notebooks[NAMES[2]] + text = "\n".join(sources(notebook)) + code = "\n".join(sources(notebook, "code")) + assert "schema-v1 compatibility" in text + assert "notebook_setup.ipynb" in text + assert "not the full three-dimensional von Mises stress for plane strain" in text + assert '"In-plane equivalent stress [MPa]"' in code + assert '"Von Mises stress [MPa]"' not in code + assert "damage_frames" in code + assert 'cmap="magma"' not in code