Tutorials¶

This page is the onboarding map for new PhAST users. Start with the shortest validation path, then move to Python authoring, YAML reproduction, and result inspection.

Start Here¶

Launch the step-by-step problem setup notebook in Colab:

Tutorial	Time	What you learn
Getting started	5 min	Install PhAST, run `doctor`, validate a shipped example, and inspect a result.
Problem setup notebook	30-45 min	Create geometry, mesh and inspect named regions, apply initial conditions, supports, loads, solver settings, run a short solve, and post-process artifacts.
Python API	10-15 min	Author a model with `phast.Problem` and understand the fluent method map.
Visual glossary	10 min	Read the picture-first guide to AT1/AT2, energy splits, and `l0`.
YAML workflow	10 min	Run a public declarative configuration and understand the standard result directory.
Example gallery	5 min	Choose a runnable dynamic, quasi-static, or solid-mechanics example.
Public API reference	5 min	Read metadata, histories, visuals, and stored trajectory fields.

Recommended Learning Path¶

Install the package and run python -m phast doctor.
Validate a public YAML configuration with --validate-only.
Run one small public example into runs/<case>.
Inspect the completed run with phast.load_result(...).
Build a small model with phast.Problem.
Read the visual glossary if the terminology feels abstract.
Move durable studies into a YAML configuration when you need reproducibility or HPC submission.

Users coming from Abaqus, COMSOL, FEniCS, or deal.II should read Setting up new problems first. It maps familiar FEM concepts such as parts, mesh sets, materials, loads, steps, jobs, and result databases to the PhAST fluent API and YAML configuration structure.

Runnable Examples¶

Workflow	Entry point	Typical output
Dynamic fracture	`python -m phast run examples/dynamic/B2_kalthoff_winkler/config.yaml --validate-only`	Dynamic damage fields, histories, metadata, and curated animation assets.
Dynamic crack branching	`python -m phast run examples/dynamic/B7_dynamic_crack_branching_comsol/config.yaml --validate-only`	Crack-branching comparison package and visual summaries.
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.
Solid mechanics	`python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml --output_dir runs/linear_plate`	Displacement/stress plots, response history, and metadata.

The example gallery lists the current public examples and their expected artifacts. Longer or beta validation workflows are summarized in the capability matrix rather than treated as first-run tutorials.

Python Authoring vs YAML Reproduction¶

Use Python when you are designing a model:

import phast

result = (
    phast.Problem("linear plate")
    .geometry("structured_grid", nx=40, ny=12, length=1.0, height=0.2)
    .region("body", kind="domain")
    .material("steel", model="solid_mechanics", region="body", E=2.1e11, nu=0.3)
    .analysis_step("load", kind="solid_mechanics", controls={"tip_force_y": -1.0e3})
    .solver("solid_mechanics", example="solid_mechanics.linear_plate")
    .outputs(fields=["displacement", "von_mises"], histories=["response"], plots=True)
    .run(output_dir="runs/linear_plate", return_result=True)
)

Use YAML when you want an exact configuration file:

python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml \
  --output_dir runs/linear_plate

Both paths are inspected the same way:

import phast

result = phast.load_result("runs/linear_plate")
print(result.metadata())
print(result.history_names())
print(result.visuals())

Tutorial Contract¶

Each public tutorial should state:

the command to run from the repository root,
expected runtime and device,
what physics and solver path are active,
which output files should appear,
how to inspect the result with phast.load_result(...),
which capability-matrix row supports the claim.

If an example depends on unavailable raw trajectory output, unreleased paper assets, or a custom diagnostic script to make sense, it should stay out of the public tutorial path until it is promoted.