Installation

Table of Contents

• 1. Prerequisites
• 2. Clone PICurv
• 3. Automated Install (Recommended)
• 4. Install Base Toolchain (Manual Path)
• 5. Install PETSc
• 6. Configure Environment Variables
• 7. Build with picurv
• 8. Verify Installation
• 9. Common Installation Failures
• 10. Next Steps

Type How-toFor New usersStatus Local and HPC

Installation

Build the solver.
Prove the toolchain.

Set up PICurv, connect it to PETSc and MPI, and leave the installation with three verified command-line tools.

Use the bootstrap installer Follow the manual path →

A complete install

C compiler+MPI+PETSc

simulator postprocessor picurv

Compile. Launch. Validate.

The route

From dependencies to a verified build.

01PrepareCheck the toolchain 02CloneGet the source 03InstallBootstrap PICurv 04VerifyExercise the build

Choose your path

Match the install to your machine.

RecommendedLocal workstation Use bootstrap to create the managed Python environment and build the tools.→ Existing modulesHPC cluster Keep the site toolchain and ask bootstrap to skip operating-system packages.→ Full controlManual setup Install the base tools and PETSc yourself, then build through the PICurv CLI.→

1. Prerequisites

PICurv sits on a compact scientific-computing toolchain. Have these components available before starting the build:

CompilerC compilergcc or clang

Parallel runtimeMPImpich or openmpi

BuildGNU Makemake

CLI runtimePython 3.10+with pip

Source controlGitgit

NumericsPETSc 3.20.3+with DMSwarm

If PETSc is the only missing component, bootstrap can build it during the automated path.

2. Clone PICurv

git clone https://github.com/VishalKandala/PICurv.git
cd PICurv

The remaining commands run from this repository root.

3. Automated Install (Recommended)

The bootstrap path is the shortest route to a repeatable local installation. It checks the native toolchain, isolates the Python CLI, and builds the three PICurv launch targets.

From the PICurv repo root:

export PETSC_DIR=/path/to/petsc
# Set PETSC_ARCH only for old-style in-tree PETSc builds:
# export PETSC_ARCH=arch-linux-c-debug
./bootstrap_install.sh --install-shell-hook

If PETSc is not installed yet, let the script build it:

./bootstrap_install.sh --install-petsc

The script installs system and Python dependencies, verifies PETSc/DMSwarm visibility, then builds:

• bin/simulator (compiled C solver)
• bin/postprocessor (compiled C post-processor)
• bin/picurv (launcher for picurv_cli/picurv, the Python conductor entrypoint)

By default, bootstrap creates .picurv-venv/ under the repo and installs the Python-side CLI dependencies there. PETSc, MPI, compilers, and scheduler tools remain provided by your loaded system or cluster modules. Bootstrap also writes .picurv-python-env, which records the seed Python runtime library path needed to launch the managed venv after you switch to a different module stack.

On an existing HPC cluster where modules already provide compilers, MPI, and PETSc, skip OS package installation:

module load <compiler-mpi-petsc-stack>
./bootstrap_install.sh --skip-system-deps --install-shell-hook
source ~/.bashrc
picurv --help

Useful variants:

./bootstrap_install.sh --venv-dir /path/to/picurv-venv
./bootstrap_install.sh --python-bin /path/to/python3.11
./bootstrap_install.sh --upgrade-pip
./bootstrap_install.sh --install-shell-hook
./bootstrap_install.sh --no-venv

Use --no-venv when your site requires Python packages to come from modules or a centrally managed environment. If the only visible interpreter is Python 3.6, load a newer Python module before the default bootstrap path; otherwise use --no-venv and site-approved package versions.

Bootstrap does not upgrade pip during a normal install. This keeps routine updates smaller and avoids unnecessary package churn on quota-constrained cluster home directories. Pass --upgrade-pip when an explicit upgrade is needed.

Bootstrap writes .picurv-python and .picurv-python-env atomically, then checks that picurv, simulator, and postprocessor all report the release in the root VERSION file. A partial interpreter record or mixed-version native build therefore fails installation instead of becoming a latent cluster-launch error.

4. Install Base Toolchain (Manual Path)

Manual path

Use the remaining setup sections when system packages, cluster policy, or a custom PETSc build make bootstrap unsuitable.

Back to the recommended path ↑

Debian/Ubuntu:

sudo apt-get update
sudo apt-get install -y build-essential gfortran mpich git make pkg-config libx11-dev python3 python3-pip python3-venv
python3 -m venv .picurv-venv
.picurv-venv/bin/python -m pip install --upgrade pip
.picurv-venv/bin/python -m pip install pyyaml numpy packaging matplotlib

RHEL/CentOS/Fedora:

sudo yum groupinstall -y "Development Tools"
sudo yum install -y mpich-devel python3 python3-pip git
python3 -m venv .picurv-venv
.picurv-venv/bin/python -m pip install --upgrade pip
.picurv-venv/bin/python -m pip install pyyaml numpy packaging matplotlib

matplotlib is part of the standard Python dependency set because it powers summarize --plot and study plot generation.

Bootstrap verifies yaml, numpy, packaging, and matplotlib imports with PYTHONPATH and user-site packages disabled. This matches the isolated Python environment used by the picurv launcher and catches dependencies that are visible only through a loaded cluster module.

5. Install PETSc

Recommended source install:

git clone -b v3.20.3 https://gitlab.com/petsc/petsc.git
cd petsc

Debug build example:

./configure --with-cc=mpicc --with-cxx=mpicxx --with-fc=mpif90 \
            --download-fblaslapack --download-metis --download-parmetis \
            --with-dmswarm=1 --with-debugging=1
make all
make check

Optimized build example:

./configure --with-cc=mpicc --with-cxx=mpicxx --with-fc=mpif90 \
            --download-fblaslapack --download-metis --download-parmetis \
            --with-dmswarm=1 --with-debugging=0 \
            --COPTFLAGS='-O3' --CXXOPTFLAGS='-O3' --FOPTFLAGS='-O3'
make all
make check

Official references:

• https://petsc.org/release/install/
• https://petsc.org/release/docs/manual/

6. Configure Environment Variables

Add to your shell profile (~/.bashrc or equivalent):

export PETSC_DIR=/path/to/petsc
# PETSC_ARCH is optional for prefix installs from EasyBuild/Spack/system packages.
# export PETSC_ARCH=arch-linux-c-debug
source /path/to/PICurv/etc/picurv.sh

The etc/picurv.sh script sets PICURV_DIR, exports PICURV_PYTHON when a managed venv or bootstrap-selected Python is available, adds bin/ to your PATH for compiled executables, and also exposes picurv_cli/ as a fallback so picurv still resolves if bin/picurv is temporarily absent before a rebuild. It is idempotent and safe to source multiple times.

If you want bootstrap to add this setup to ~/.bashrc, pass --install-shell-hook. The hook is written as a managed block, so rerunning the installer updates it instead of appending duplicate source lines. Use --shell-rc <path> to target another shell startup file.

Reload and verify:

source ~/.bashrc
echo "$PETSC_DIR"
echo "$PETSC_ARCH"
picurv --help

Verify PETSc has DMSwarm headers:

test -f "$PETSC_DIR/include/petscdmswarm.h" && echo "DMSwarm header found"
test -f "$PETSC_DIR/$PETSC_ARCH/include/petscconf.h" || test -f "$PETSC_DIR/include/petscconf.h"

7. Build with picurv

./picurv_cli/picurv build

Expected binaries:

• bin/simulator (compiled C solver)
• bin/postprocessor (compiled C post-processor)
• bin/picurv (launcher → picurv_cli/picurv)

Useful variants:

./picurv_cli/picurv build clean-project
./picurv_cli/picurv build SYSTEM=cluster
make audit-build

After source etc/picurv.sh, use picurv directly from any directory. ./picurv_cli/picurv build writes <repo>/logs/build.log in the source repo. If you are auditing compiler warnings from a direct Make invocation, use make audit-build to generate both <repo>/logs/build.log and <repo>/logs/build.warnings.log.

8. Verify Installation

Verification progresses from the installed PETSc toolchain to the complete MPI validation sweep. Start small, then choose the depth appropriate for your machine.

make doctor

Recommended sequence after a successful build:

picurv version
simulator --version
postprocessor --version

All three must report the same release. Each executable's second line names the PETSc it was built against; under it picurv version shows the libpetsc this shell would load, marked when it is not that PETSc. picurv version --format json also reports the Git commit, dirty-tree state, active workspace, and optional workspace requirement.

picurv version status checks that agreement for you and exits non-zero if it does not hold, which is the form to use in a job script or a CI step:

picurv version status || echo "rebuild before running"

1. 01make doctor

   Builds and runs a minimal PETSc-backed binary.

2. 02make smoke

   Confirms that the compiled PICurv executables launch.

3. 03make check

   Runs Python regressions and PETSc-backed validation.

4. 04make check-full

   Adds MPI units, fixed-size multi-rank smoke, and rank-matrix smoke.

What make doctor does not prove:

• it does not prove a full solver case is numerically correct
• it does not replace case-specific validation or convergence testing

9. Common Installation Failures

• PETSC_DIR is unset or points at the wrong PETSc installation; PETSC_ARCH is only required for old-style in-tree PETSc builds.
• MPI compiler wrappers are unavailable in PATH.
• The Python interpreter is too old for default bootstrap; load Python 3.10+, pass --python-bin, or use --no-venv.
• Visualization modules leak incompatible Python packages into PYTHONPATH; prefer the managed venv launcher for normal CLI use.
• The managed venv cannot find libpython; rerun bootstrap so .picurv-python-env records the seed runtime library path.
• An old checkout still uses a bin/picurv symlink; rerun make -B conductor after pulling current source.
• PETSc was configured without the required downloaded dependencies.
• The X11 development library is missing at link time; install libx11-dev when Linux reports cannot find -lX11.
• Object files are stale after a toolchain change; use clean-project.

For runtime-level failures after successful build, see Common Fatal Errors and Fixes.

For the full testing model after installation, see Testing and Validation Guide.

10. Next Steps

Run your first case Create, validate, solve, and inspect the Quick Start simulation. Resolve a failure Trace installation, configuration, MPI, and runtime symptoms. Understand the checks See what each test layer verifies and where its evidence comes from.

Next Quick Start →