Install PhAST¶

PhAST requires Python 3.10 or newer. Python 3.11 is the recommended baseline, and continuous integration currently verifies Python 3.10-3.12. Later Python versions are permitted but are not yet part of the regular test matrix. The base installation includes the dependencies needed by the public solver; PETSc/MUMPS, GPU direct solvers, and other HPC backends remain optional.

Tested platform matrix¶

“Tested” describes the public GitHub Actions matrix. It does not imply that every optional accelerator, compiler, MPI stack, or sparse backend is tested on that platform.

Virtual environment with pip¶

From a clone of the repository:

python3 -m venv .venv
source .venv/bin/activate                 # Windows: .venv\\Scripts\\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

For an isolated conda environment, the existing route is:

conda env create --file environment.yml
conda activate phast

Install documentation tooling separately when building the site:

python -m pip install -r requirements-docs.txt

Platform activation¶

On Linux and macOS:

source .venv/bin/activate

On Windows PowerShell:

.venv\Scripts\Activate.ps1

If PowerShell blocks activation, use a process-scoped policy rather than a machine-wide change:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.venv\Scripts\Activate.ps1

Docker¶

The repository image is a portable CPU route for the bounded installation check. It does not start a fracture simulation:

git clone https://github.com/CEMS-Lab/PhAST.git
cd PhAST
docker build --tag phast:local .
docker run --rm phast:local

Run the first completed example and retain its output on the host:

mkdir -p runs
docker run --rm \
  --cpus 2 --memory 4g \
  --volume "$PWD/runs:/opt/phast/runs" \
  phast:local \
  python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml \
  --output_dir runs/linear_plate

The equivalent Windows PowerShell command is:

New-Item -ItemType Directory -Force runs | Out-Null
docker run --rm `
  --cpus 2 --memory 4g `
  --mount "type=bind,source=$((Resolve-Path .\runs).Path),target=/opt/phast/runs" `
  phast:local `
  python -m phast run examples/solid_mechanics_beta/linear_plate/config.yaml `
  --output_dir runs/linear_plate

The two-CPU, 4 GB limits are a conservative starting point for the compact linear-plate check, not a resource prescription for fracture benchmarks. Increase them only after inspecting the requirements of the selected example.

Open an interactive shell when inspecting the container environment:

docker run --rm -it --cpus 2 --memory 4g --entrypoint /bin/sh phast:local

Verify before running a simulation¶

Use the verification ladder: 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.

If installation fails, retain the first traceback and consult Troubleshooting. Optional backend installation should be deferred until the doctor shows that the intended workflow needs it.

First-error recovery¶

Preserve the first traceback. Opening a question issue is appropriate whenever the documented recovery step does not resolve it.