Getting Started¶

This guide takes a new user from a source checkout to a validated configuration, a small completed simulation, and programmatic result inspection. No optional HPC or sparse-direct backend is required for the basic workflow.

1. Prerequisites¶

PhAST requires Python 3.10 or later and Git. The base installation obtains PyTorch, NumPy, SciPy, Gmsh, meshio, Matplotlib, YAML support, and the standard result-storage dependencies from pyproject.toml.

PhAST itself does not require a separate CMake build. PETSc/MUMPS, AmgX, cuDSS, PyAMG, and other optional backends should be installed only for workflows that explicitly require them.

2. Create An Environment And Install¶

On Linux or macOS:

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 .

On Windows PowerShell:

git clone https://github.com/CEMS-Lab/PhAST.git
cd PhAST
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

An editable installation is appropriate for a source repository: changes made under src/phast/ are immediately available in the active environment.

3. Verify The Environment¶

Run the environment report:

python -m phast doctor

The report identifies Python and PyTorch versions, CPU/GPU visibility, required packages, optional sparse backends, and the backend selected by backend: auto. An unavailable optional backend is not an installation failure.

Next, validate a fracture configuration without generating a mesh or allocating the full solver:

python -m phast run examples/dynamic/B2_kalthoff_winkler/config.yaml --validate-only

Expected output:

OK: examples/dynamic/B2_kalthoff_winkler/config.yaml passes schema validation.

For a readable summary of the model before execution:

python -m phast explain-config examples/dynamic/B2_kalthoff_winkler/config.yaml

The installation verification page explains common doctor outcomes.

4. Know Which YAML Files Are Runnable¶

PhAST contains several kinds of YAML file:

If a file is not named config.yaml and is described as a contract, manifest, schema, or reference template, consult its README before passing it to python -m phast run.

5. Run A Small End-To-End Example¶

Use the linear-elastic plate to verify mesh construction, solver execution, artifact writing, and result loading:

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

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.

Inspect the completed result without rerunning the solver:

import phast

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

phast.load_result reports only artifacts present in the result directory. It does not synthesize fields that were not written.

6. Run A Phase-Field Fracture Example¶

Begin by validating and explaining the selected example:

python -m phast run examples/quasistatic/miehe_tension/config.yaml --validate-only
python -m phast explain-config examples/quasistatic/miehe_tension/config.yaml

Then execute it into a separate result directory:

python -m phast run examples/quasistatic/miehe_tension/config.yaml \
  --output_dir runs/miehe_tension

Fracture examples may require substantially more time and memory than the linear-elastic installation check. Review the example README, mesh resolution, device, and output settings before starting a complete benchmark rerun.

7. Understand The Solver Sequence¶

For a fracture simulation, PhAST:

1. parses and validates the YAML or phast.Problem definition;

2. constructs or imports a two-dimensional finite-element mesh;

3. evaluates element-level mechanical quantities with PyTorch tensor operators;

4. advances explicit dynamics or solves quasi-static mechanical equilibrium;

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.

Read User Guide Overview for the software pathway and Physics, Units, and Formulation for the governing equations and staggered algorithm.

8. Create A New Setup¶

To generate a starter YAML:

python -m phast new my_benchmark --type quasi_static --material pmma_bleyer

Validate and inspect it before execution:

python -m phast run my_benchmark.yaml --validate-only
python -m phast explain-config my_benchmark.yaml

Alternatively, use the fluent phast.Problem interface while constructing a model programmatically. The problem setup guide maps common finite-element concepts to both YAML and the Python API.

9. Platform And Optional Backend Notes¶

Backend availability is machine-dependent. Do not infer PETSc/MUMPS, cuDSS, or AmgX support from package installation alone; confirm it with python -m phast doctor on the target machine.

10. If You Become Stuck¶

Consult Troubleshooting, then open a GitHub issue if the problem remains or the instructions are unclear. Include:

• the exact command;

• the YAML path;

• operating system and Python/PyTorch versions;

• relevant python -m phast doctor output; and

• the 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.

11. Build The Documentation¶

python -m pip install -r requirements-docs.txt
sphinx-build -W -b html docs docs/_build/html

The hosted documentation is available at https://cems-lab.github.io/PhAST/.