Remove the experimental learned-damage route

DOCUMENTATION_STYLE.md

@@ -340,8 +340,6 @@ Prefer a more specific term whenever one exists.
 | 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 |
@@ -384,7 +382,7 @@ When comparing performance, report:
 
 Do not describe one backend as universally fastest.
 
-## 10. Differentiability and learned models
+## 10. Differentiability
 
 Avoid unqualified statements that PhAST differentiates every fracture
 calculation. Prefer:
@@ -393,18 +391,6 @@ calculation. Prefer:
 > 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.

README.md

@@ -223,7 +223,6 @@ Browse the full [example gallery](docs/example-gallery.md) for the complete list
 | Post-process simulation data | `phast.load_result(path)` | [Public API Reference](docs/user_guide/public_api_reference.md) |
 | Review supported physics | Capability matrix | [Capability Matrix](docs/user_guide/capability_matrix.md) |
 | Learn step-by-step setup | Tutorial notebook | [Problem Setup Walkthrough](docs/tutorial/problem_setup_walkthrough.ipynb) |
-| Add an audited learned damage model | Predictor plug-in protocol | [Modular FEM and Learned Damage](docs/tutorial/03_modular_fem_and_learned_damage.md) |
 | Learn elementwise `E(x)` and `Gc(x)` fields | Script-contract teaching example | [Heterogeneous Material Fields](docs/tutorial/05_heterogeneous_material_fields.md) |
 | Diagnose failed runs | Troubleshooting guide | [Troubleshooting](docs/troubleshooting.md) |
 

configs/REFERENCE.yaml

@@ -386,14 +386,6 @@ solver:
   # softmax_H_beta: null  # float or null
   # H_update_method: hard_max  # str, enum: hard_max|softmax|smooth_max|log_smooth|custom_subgrad
   # enable_damage: true  # bool
-  # damage_update: classical  # str, enum: classical|learned_proposal|learned_replacement
-  # damage_predictor: null  # str or null, module:factory used by learned routes
-  # damage_checkpoint: null  # str or null, interpreted by the predictor factory
-  # damage_predictor_options: {}  # mapping, architecture-specific adapter options
-  # damage_residual_rtol: 0.001  # float, range: [0.0, +inf]
-  # damage_residual_atol: 1e-08  # float, range: [0.0, +inf]
-  # damage_bound_tolerance: 1e-08  # float, range: [0.0, +inf]
-  # damage_fallback: true  # bool, use classical damage solve after rejection
   # fail_on_mechanics_nonconvergence: true  # bool
   # adaptive_dt: false  # bool
   # adaptive_dt_d_threshold: 0.01  # float

configs/phast.schema.json

@@ -152,7 +152,14 @@
               "enum": [
                 "standard",
                 "cubic",
-                "rational"
+                "rational",
+                "rational_at2"
+              ]
+            },
+            "stress_degradation": {
+              "enum": [
+                "split",
+                "full"
               ]
             },
             "driving_force": {
@@ -308,7 +315,19 @@
           "enum": [
             "standard",
             "cubic",
-            "rational"
+            "rational",
+            "rational_at2"
+          ]
+        },
+        "stress_degradation": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "enum": [
+            "split",
+            "full"
           ]
         },
         "kinematics": {
@@ -622,53 +641,6 @@
           "type": "boolean",
           "default": true
         },
-        "damage_update": {
-          "type": "string",
-          "default": "classical",
-          "enum": [
-            "classical",
-            "learned_proposal",
-            "learned_replacement"
-          ]
-        },
-        "damage_predictor": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "default": null
-        },
-        "damage_checkpoint": {
-          "type": [
-            "string",
-            "null"
-          ],
-          "default": null
-        },
-        "damage_predictor_options": {
-          "type": "object",
-          "additionalProperties": true,
-          "default": {}
-        },
-        "damage_residual_rtol": {
-          "type": "number",
-          "default": 0.001,
-          "minimum": 0.0
-        },
-        "damage_residual_atol": {
-          "type": "number",
-          "default": 1e-08,
-          "minimum": 0.0
-        },
-        "damage_bound_tolerance": {
-          "type": "number",
-          "default": 1e-08,
-          "minimum": 0.0
-        },
-        "damage_fallback": {
-          "type": "boolean",
-          "default": true
-        },
         "fail_on_mechanics_nonconvergence": {
           "type": "boolean",
           "default": true

docs/index.md

@@ -148,7 +148,7 @@ tutorial/notebook_dynamic_sent
 tutorial/notebook_setup
 tutorial/notebook_mesh_resolution
 tutorial/notebook_retained_results
-tutorial/03_modular_fem_and_learned_damage
+tutorial/03_modular_fem
 tutorial/04_exploration_experiments
 tutorial/05_heterogeneous_material_fields
 tutorial/06_first_research_study
@@ -176,7 +176,6 @@ user_guide/setup_problems
 user_guide/python_api
 user_guide/yaml_workflow
 user_guide/results_visualization
-user_guide/learned_damage
 performance-reproducibility
 paper-reproduction
 ```

docs/tutorial/03_modular_fem.md

@@ -0,0 +1,94 @@
+# Modular fracture problems
+
+This tutorial describes how the main components of a phase-field fracture
+problem fit together in PhAST without assuming prior knowledge of the
+codebase.
+
+| Lesson item | Scope |
+|---|---|
+| Prerequisites | Complete the installation checks and read the phase-field primer. |
+| Route | Quasi-static staggered phase-field fracture through a checked-in YAML configuration. |
+| Hardware | CPU is sufficient for configuration inspection and the bounded example route. |
+| Verification | Inspect the selected route, result manifest, and convergence history. |
+
+## 1. The finite-element problem
+
+A runnable problem combines:
+
+1. A mesh defining geometry, nodes, elements, and physical boundary groups.
+2. A material defining elasticity, fracture resistance, regularization length,
+   density, crack-density model, degradation law, and energy split.
+3. Initial conditions defining displacement, velocity, damage, and any initial
+   crack.
+4. Boundary conditions constraining mechanical or phase-field degrees of
+   freedom.
+5. Loading prescribing the time-dependent displacement or force history.
+6. Solver settings choosing integration, linear algebra, and the damage
+   subproblem.
+7. Output settings selecting fields and sampling frequency.
+
+Keep reusable configurations under `configs/`. Schema, manifest, contract, and
+template files are machine-readable specifications rather than simulations.
+
+## 2. Distinguish the fracture-model choices
+
+- `pf_model: AT1` or `AT2` selects the crack-density functional.
+- `energy_split` selects the elastic-energy decomposition. Implementations
+  include `spectral`, `spectral_stress`,
+  `spectral_plane_stress_condensed`, `isotropic`, `amor`, and `star_convex`.
+- `degradation_type` selects the stiffness-degradation family.
+
+The supported coupled AT1/AT2 route uses `degradation_type: standard`.
+PF-CZM is experimental and constructs its rational law from its own
+parameters. Although the material layer contains additional degradation
+functions, PhAST does not present cubic or rational degradation as supported
+coupled AT1/AT2 damage solves.
+
+## 3. Begin from a complete problem
+
+Mesh groups, loading controls, and output requests are geometry-specific. Use
+the checked-in Miehe tension configuration rather than a fragment containing
+placeholder paths:
+
+```bash
+python -m phast explain-config examples/quasistatic/miehe_tension/config.yaml
+python -m phast run examples/quasistatic/miehe_tension/config.yaml --validate-only
+python -m phast run examples/quasistatic/miehe_tension/config.yaml \
+  --num_steps 5 --output_dir runs/miehe_tension_five_step
+```
+
+The five-step calculation is a bounded workflow exercise, not a crack-growth
+validation result. Read the example README before undertaking the full
+calculation; it records the retained runtime and evidence boundary.
+
+## 4. How automatic route selection works
+
+Automatic device and sparse-backend settings select a deterministic route from
+the backends available in the current environment. This is a portability
+policy, not a universal fastest-solver guarantee. Performance depends on
+problem size, sparsity, hardware, installed libraries, and transfer costs.
+
+At startup and completion, PhAST reports the device, precision, element type,
+mechanics solver, configured and resolved sparse backend, fracture model,
+energy split, history update, damage-bound treatment, and preconditioner.
+Preserve this report with benchmark results.
+
+```bash
+python -m phast doctor
+```
+
+## 5. A defensible student workflow
+
+1. Run an existing example without changing its formulation.
+2. Modify one component at a time: mesh, material, loading, or energy split.
+3. Examine the route report and retained displacement, damage, and history.
+4. Compare each modified run with the unmodified reference calculation.
+
+Students and developers are invited to propose tutorials and examples. If an
+installation step, configuration field, or solver message is unclear, open a
+GitHub issue with the configuration, environment report, and minimal
+reproduction.
+
+Continue with [Heterogeneous material fields](05_heterogeneous_material_fields.md)
+for an element-ordered material-field teaching problem, or return to the
+[example gallery](../example-gallery.md) for complete workflows.