Installation Guide

Table of Contents

• 1. Prerequisites
• 2. Install Base Toolchain
• 3. Install PETSc
• 4. Configure Environment Variables
• 5. Clone PICurv
• 6. Build with pic.flow
• 7. Verify Installation
• 8. Common Installation Failures
• 9. Next Steps

This guide covers dependency setup, PETSc configuration, and binary build verification for PICurv.

1. Prerequisites

Install these first:

• C compiler (gcc or clang)
• MPI implementation (mpich or openmpi)
• GNU Make
• Python 3 + pip
• Git
• PETSc 3.20.3+ with DMSwarm support

2. Install Base Toolchain

Debian/Ubuntu:

sudo apt-get update
sudo apt-get install -y build-essential gfortran mpich python3 python3-pip git
python3 -m pip install --user pyyaml numpy

RHEL/CentOS/Fedora:

sudo yum groupinstall -y "Development Tools"
sudo yum install -y mpich-devel python3 python3-pip git
python3 -m pip install --user pyyaml numpy

Optional (study plot generation):

python3 -m pip install --user matplotlib

3. 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/

4. Configure Environment Variables

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

export PETSC_DIR=/path/to/petsc
export PETSC_ARCH=arch-linux-c-debug

Reload and verify:

source ~/.bashrc
echo "$PETSC_DIR"
echo "$PETSC_ARCH"

5. Clone PICurv

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

6. Build with pic.flow

./scripts/pic.flow build

Expected binaries:

• bin/picsolver
• bin/postprocessor

Useful variants:

./scripts/pic.flow build clean-project
./scripts/pic.flow build SYSTEM=cluster

7. Verify Installation

./scripts/pic.flow --help
./scripts/pic.flow run --help
./scripts/pic.flow sweep --help
./scripts/pic.flow validate --help

If these commands work and binaries exist, your installation is ready.

8. Common Installation Failures

• PETSC_DIR/PETSC_ARCH unset or mismatched with built arch.
• MPI compiler wrappers unavailable in PATH.
• PETSc configured without required downloaded dependencies.
• stale object files after toolchain changes (use clean-project).

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

9. Next Steps

• First simulation walkthrough: Tutorial: Your First Simulation (Flat Channel)