Building GridPACK from source

Building GridPACK from source gives you full control over compiler flags, dependency versions, and optional features such as the Python interface and progress-ranks runtime for Global Arrays. GridPACK has been built and tested on Linux (Ubuntu, RHEL, CentOS, Debian), macOS, and HPC clusters. The process involves installing three external libraries — Boost, Global Arrays, and PETSc — and then configuring and compiling GridPACK itself with CMake.

Two convenience scripts in the top-level GridPACK directory automate most of this process: install_gridpack_deps.sh builds all external libraries and install_gridpack.sh builds and installs GridPACK. Try them first — they work on most Linux platforms and can be adapted for others with minor edits.

Prerequisites

Before you begin, make sure the following tools are available on your system:

Requirement	Minimum version	Notes
CMake	3.22	Required by `src/CMakeLists.txt`
GCC (GNU compiler)	Any recent version	C++ support required; Fortran optional
MPI	Any	OpenMPI or MPICH; provides `mpicc`, `mpicxx`, `mpiexec`

Most HPC clusters have MPI pre-installed. On Ubuntu, install it with apt-get install openmpi-bin openmpi-common libopenmpi-dev. On macOS, use brew install open-mpi.

Using the convenience scripts

Clone the repository

git clone https://github.com/GridOPTICS/GridPACK.git
cd GridPACK

Install external dependencies

Run the dependency script from the top-level GridPACK directory. It downloads and builds Boost 1.81.0, Global Arrays 5.9, and PETSc (3.20.6), placing everything under external-dependencies/:

./install_gridpack_deps.sh

This script can take around an hour depending on your system. It requires internet access to download the source archives.

After the script completes, source the generated environment file to configure library paths:

source gridpack_env.sh   # bash/zsh
# or
source gridpack_env.csh  # csh/tcsh

Build GridPACK

Run the GridPACK build script. By default it builds GridPACK with shared libraries and the Python interface:

./install_gridpack.sh

To build without the Python interface, edit the top of install_gridpack.sh and set:

install_gridpack_python=false

After a successful run, two directories are created under src/:

src/build/ — application executables and test inputs
src/install/ — installed libraries, headers, and Python packages

Manual build

If the scripts do not work on your platform, build each dependency by hand and then configure GridPACK with CMake.

Clone the repository and initialize submodules

git clone https://github.com/GridOPTICS/GridPACK.git
cd GridPACK
git submodule update --init

The git submodule update --init command is required when building from a Git clone. If you are building from a release tarball, the submodules are already included.

Install Boost 1.78.0

GridPACK requires Boost built with the mpi, serialization, random, filesystem, and system libraries.

# Download and extract
wget https://boostorg.jfrog.io/artifactory/main/release/1.78.0/source/boost_1_78_0.tar.gz
tar -xvf boost_1_78_0.tar.gz
cd boost_1_78_0

# Configure
./bootstrap.sh --prefix=install_for_gridpack \
  --with-libraries=mpi,serialization,random,filesystem,system

Edit the generated project-config.jam and add this line to enable MPI support:

using mpi ;

Then build and install:

./b2 -a -d+2 link=static stage
./b2 -a -d+2 link=static install

To build Boost as shared libraries (required if you plan to build GridPACK with shared libraries or the Python interface), use link=shared instead of link=static.

A successful install creates include/ and lib/ subdirectories inside install_for_gridpack/.

Install Global Arrays 5.8

Global Arrays (GA) provides the one-sided communication layer used by GridPACK.

# Download and extract
wget https://github.com/GlobalArrays/ga/releases/download/v5.8/ga-5.8.tar.gz
tar -xvf ga-5.8.tar.gz
cd ga-5.8

# Configure
./configure --with-mpi-ts --disable-f77 \
            --without-blas --enable-cxx --enable-i4 \
            --prefix=${PWD}/install_for_gridpack

# Build and install
make -j 10 install

--with-mpi-ts selects the MPI two-sided runtime, which is the simplest and most portable option. For large-scale runs (more than ~12 processes), consider switching to the progress-ranks runtime (--with-mpi-pr). See the Section3-ConfigureBuild docs for details.

To build GA as shared libraries, add --enable-shared to the configure command.

Install PETSc 3.16.4

PETSc provides the parallel linear algebra and solver infrastructure used throughout GridPACK.

# Clone and check out the target version
git clone https://gitlab.com/petsc/petsc.git
cd petsc
git checkout v3.16.4

# Set required environment variables
export PETSC_DIR=${PWD}
export PETSC_ARCH=build-dir

# Configure — downloads additional solver packages automatically
./configure \
    --download-superlu_dist \
    --download-metis \
    --download-parmetis \
    --download-suitesparse \
    --download-f2cblaslapack \
    --prefix=${PWD}/install_for_gridpack

# Build, install, and verify
make
make install
make check

--download-f2cblaslapack is not needed if your system has a compatible BLAS/LAPACK. --download-cmake is not needed if CMake 3.18.1 or newer is available. To build PETSc as shared libraries, add --with-shared-libraries=1.

Configure GridPACK with CMake

Create a build directory under GridPACK/src/ and run CMake with paths to the installed dependencies. It is best practice to put the CMake invocation in a shell script so it can be re-run and edited easily.

cd GridPACK/src
mkdir build && cd build

Create a file named build.sh with the following content, adjusting the paths to match your installation directories:

rm -rf CMake*

cmake \
  -D GA_DIR:STRING="/path/to/ga-5.8/install_for_gridpack" \
  -D BOOST_ROOT:STRING="/path/to/boost_1_78_0/install_for_gridpack" \
  -D Boost_DIR:STRING="/path/to/boost_1_78_0/install_for_gridpack/lib/cmake/Boost-1.78.0" \
  -D BOOST_LIBRARYDIR:STRING="/path/to/boost_1_78_0/install_for_gridpack/lib" \
  -D PETSC_DIR:PATH="/path/to/petsc/install_for_gridpack" \
  -D MPI_CXX_COMPILER:STRING='mpicxx' \
  -D MPI_C_COMPILER:STRING='mpicc' \
  -D MPIEXEC:STRING='mpiexec' \
  -D MPIEXEC_MAX_NUMPROCS:STRING=2 \
  -D GRIDPACK_TEST_TIMEOUT:STRING=30 \
  -D CMAKE_INSTALL_PREFIX:PATH="/path/to/GridPACK/src/install" \
  -D CMAKE_BUILD_TYPE:STRING=Debug \
  ..

Key CMake variables:

Variable	Description
`GA_DIR`	Path to the Global Arrays install prefix
`BOOST_ROOT`	Path to the Boost install prefix
`PETSC_DIR`	Path to the PETSc install prefix
`MPI_CXX_COMPILER`	MPI C++ wrapper (typically `mpicxx`)
`MPI_C_COMPILER`	MPI C wrapper (typically `mpicc`)
`MPIEXEC`	MPI launch command (typically `mpiexec` or `mpirun`)
`CMAKE_INSTALL_PREFIX`	Directory where GridPACK will be installed
`CMAKE_BUILD_TYPE`	`Debug`, `Release`, or `RelWithDebInfo`
`BUILD_SHARED_LIBS`	Set to `YES` to build shared libraries instead of static

If you installed PETSc without --prefix, it writes files to $PETSC_DIR/$PETSC_ARCH. In that case, add -D PETSC_ARCH=<your-arch-name> to the CMake command.

Make the script executable and run it:

chmod +x build.sh
./build.sh

Compile and install

make -j 10 install

Build warnings are expected and can be safely ignored. After installation, src/install/ contains the GridPACK libraries and headers, and src/build/ contains the application executables.

Test the installation

Run the CTest suite:

make test

Some tests may fail depending on your platform configuration. To verify the core simulation is working, run the dynamics application directly:

cd applications/dynamic_simulation_full_y
cp input_145.xml input.xml
./dsf.x

If the run completes and prints timing statistics, the installation is working correctly.

Shared vs. static libraries

By default, GridPACK builds static libraries. To build shared libraries — required for the Python interface — add -D BUILD_SHARED_LIBS=YES to the CMake command and ensure that Boost, GA, and PETSc were also built as shared libraries. Building with shared libraries is what the convenience scripts and Docker image use.

Next steps

What is GridPACK

Learn about GridPACK’s capabilities, supported formats, and framework architecture.

Power flow application

Run your first power flow simulation using a PSS/E RAW file as input.

Get Started

Core Concepts

Framework Reference

Applications

Developer Guide

Building GridPACK from source

Prerequisites

Using the convenience scripts

Manual build

Shared vs. static libraries

Next steps

What is GridPACK

Power flow application

Build docs developers (and LLMs) love

Get Started

Core Concepts

Framework Reference

Applications

Developer Guide

Documentation Index

​Prerequisites

​Using the convenience scripts

​Manual build

​Shared vs. static libraries

​Next steps

What is GridPACK

Power flow application

Build docs developers (and LLMs) love

Prerequisites

Using the convenience scripts

Manual build

Shared vs. static libraries

Next steps