Publish layered DCB student notebook and colour-coded setup

docs/index.md

@@ -143,6 +143,7 @@ tutorial/index
 tutorial/01_phase_field_primer
 tutorial/02_visual_glossary
 tutorial/notebook_square_plate_fracture
+tutorial/notebook_layered_dcb
 tutorial/notebook_dynamic_sent
 tutorial/notebook_setup
 tutorial/notebook_mesh_resolution

docs/tutorial/index.md

@@ -33,6 +33,10 @@ silently migrate them or add 3D fracture support.
 5. [Retained Miehe SENT results](notebook_retained_results.ipynb)
    examines checked-in load-displacement and damage evidence and states the
    current post-processing boundary.
+6. [Layered DCB: understand, edit, and interpret a fracture model](notebook_layered_dcb.ipynb)
+   explains material regions, the initial crack, boundary conditions, the
+   implicit staggered solution, and result interpretation. It displays retained
+   evidence by default and makes a new simulation an explicit choice.
 
 Asymmetric three-point bending and L-shaped panel notebooks are not presented
 as public benchmarks because the current repository does not retain the
@@ -55,6 +59,7 @@ 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. |
+| [Layered DCB student notebook](notebook_layered_dcb.ipynb) | Self-paced; full solve optional | Connect the physical model and equations to editable YAML, view a geometry schematic, inspect retained fields and animation, and design a material-contrast comparison. |
 | [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. |

examples/two_material_dcb_beta/README.md

@@ -108,8 +108,51 @@ 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.
 
+## Material Regions And Input Conditions
+
+![Input diagram showing blue outer material, grey weak layer, ochre circular Material 2, the starter crack, right clamp, and prescribed opening displacements.](results/material_regions_and_loading.png)
+
+The example contains **three bulk material regions**, despite its historical
+folder name. Blue denotes the outer Material 1, grey denotes the weak layer,
+and ochre denotes the circular Material 2. All three have the same Young's
+modulus, $E = 5{,}000$ MPa. Their fracture toughnesses are respectively
+$G_c = 1.00$, $0.04$, and $0.12$ N/mm. Material 2 is therefore tougher than
+the weak layer, not stiffer. The colours describe the input assignments;
+they are not the red damage scale used in the result figures.
+
+The plate measures $6.0 \times 1.2$ mm. The weak layer is $0.6$ mm high,
+the circular region has radius $0.20$ mm, and the initial crack is $1.5$ mm
+long. The right edge is fixed in both directions. The upper and lower
+left-edge loading segments receive vertical displacements of $+0.15$ mm
+and $-0.15$ mm at the final load factor, giving a relative opening of
+$0.30$ mm. Horizontal displacement is not prescribed on these loading
+segments. Other tractions are zero. The material boundaries do not have
+an independent cohesive or interface law.
+
+After installing PhAST, run this command from the repository root to draw
+the setup before solving:
+
+```bash
+# Read the YAML, build its mesh and selections, and draw the inputs only.
+python examples/two_material_dcb_beta/plot_setup.py \
+  --config examples/two_material_dcb_beta/config.yaml \
+  --output-dir runs/dcb_setup
+```
+
+The output is `runs/dcb_setup/material_regions_and_loading.png`. Use
+`--config` with your edited YAML to inspect a modified setup. This command
+uses the same PhAST mesh, material assignments, and node selections as the
+solver; it neither solves the fracture problem nor establishes convergence.
+New full calculations also write `material_regions_and_loading.png`.
+
 ## Standard Results
 
+For a step-by-step explanation, use the
+[layered DCB student notebook](../../docs/tutorial/notebook_layered_dcb.ipynb).
+It connects the equations to editable geometry, materials, loads, solver
+settings, and result interpretation. Retained images and animation are the
+default; running a new simulation is an explicit choice.
+
 Retained lightweight evidence is in [results/README.md](results/README.md).
 It is not a new run of the documentation commands:
 

examples/two_material_dcb_beta/plot_setup.py

@@ -0,0 +1,36 @@
+"""Draw the DCB input configuration without running a fracture calculation."""
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from phast.workflow import problem_spec_from_yaml
+from phast.workflow.multimaterial_fracture import (
+    _assign_materials,
+    _build_mesh,
+    _resolve_bcs,
+    _resolve_regions,
+)
+from phast.workflow.setup_plot import save_material_setup
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--config", type=Path, default=Path(__file__).with_name("config.yaml"))
+    parser.add_argument("--output-dir", type=Path, default=Path("runs/dcb_setup"))
+    args = parser.parse_args()
+    spec = problem_spec_from_yaml(args.config)
+    # Reuse the solver's mesh and selections, rather than a second model setup.
+    nodes, elements = _build_mesh(spec)
+    node_regions, element_regions = _resolve_regions(spec, nodes, elements)
+    _, _, material_ids, material_names = _assign_materials(spec, element_regions, len(elements))
+    path = save_material_setup(
+        spec, nodes, elements, material_ids, material_names, node_regions,
+        _resolve_bcs(spec, node_regions),
+        args.output_dir / "material_regions_and_loading.png",
+    )
+    print(f"Input diagram saved to {path}; no fracture simulation was run.")
+
+
+if __name__ == "__main__":
+    main()

examples/two_material_dcb_beta/results/README.md

@@ -12,6 +12,27 @@ 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.
 
+## Material Regions And Input Conditions
+
+![Reference input diagram with three coloured bulk regions, a black starter crack, a fixed right edge, and opposite vertical displacements at the left edge.](material_regions_and_loading.png)
+
+This new diagram represents the reference YAML inputs, not a new fracture
+calculation. Blue is the outer Material 1, grey is the weak bulk layer, and
+ochre is the circular Material 2. All regions have $E = 5{,}000$ MPa; their
+fracture toughnesses are $1.00$, $0.04$, and $0.12$ N/mm, respectively.
+Material 2 is tougher than the weak layer but has the same elastic modulus.
+
+The right edge has $u_x = u_y = 0$. The upper and lower loading segments
+on the left edge reach $u_y = +0.15$ mm and $u_y = -0.15$ mm, respectively.
+Their horizontal displacement remains free. The final relative opening is
+$0.30$ mm. Black marks on the centreline identify the prescribed initial
+crack, not newly propagated damage. Other tractions are zero.
+
+Colours show bulk assignments, not a cohesive interface or a computed damage
+field. The [example instructions](../README.md#material-regions-and-input-conditions)
+explain how to regenerate the diagram after editing the geometry, materials,
+or boundary conditions. Retained simulation figures below remain unchanged.
+
 ## What The Calculation Demonstrates
 
 At a total opening of 0.30 mm, the seeded crack bifurcates within the weak

examples/two_material_dcb_beta/results/visual_manifest.json

@@ -67,5 +67,14 @@
   {
     "path": "matched_control_damage.png",
     "artifact_type": "image"
+  },
+  {
+    "path": "material_regions_and_loading.png",
+    "artifact_type": "image",
+    "source": "../config.yaml",
+    "width_px": 1800,
+    "height_px": 1200,
+    "generation_command": "python examples/two_material_dcb_beta/plot_setup.py --config examples/two_material_dcb_beta/config.yaml --output-dir examples/two_material_dcb_beta/results",
+    "claim_role": "Input representation only; no new fracture calculation."
   }
 ]

src/phast/workflow/multimaterial_fracture.py

@@ -28,6 +28,7 @@
 from ..mesh import FEMMesh
 from ..io_utils import init_h5, write_h5_snapshot
 from .specs import ProblemSpec
+from .setup_plot import save_material_setup
 
 
 class MultimaterialWorkflowError(RuntimeError):
@@ -870,7 +871,11 @@ def run_multimaterial_fracture_spec(spec: ProblemSpec, *, output_dir=None) -> in
         "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",
+    save_material_setup(
+        spec, nodes_np, elements_np, material_ids, material_names, node_regions,
+        resolved_bcs, output / "material_regions_and_loading.png",
+    )
+    visuals = ["initial_conditions.png", "material_regions_and_loading.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"]