Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/GridOPTICS/GridPACK/llms.txt

Use this file to discover all available pages before exploring further.

The fastest way to run GridPACK is with the official Docker image. It includes a complete installation of GridPACK and all its dependencies — OpenMPI, Boost, Global Arrays, and PETSc — compiled and ready to use. The image supports both AMD64 (Intel/AMD) and ARM64 (Apple Silicon, AWS Graviton) architectures; Docker automatically pulls the correct variant for your platform.
The container’s default working directory is /app/workspace. When you mount a local directory with -v, its contents appear at that path inside the container. All GridPACK application binaries are on the PATH.

​
Pull and run the image

1

Pull the image

Pull the latest stable image from Docker Hub:
docker pull pnnl/gridpack:latest
To pin to a specific release, use a versioned tag instead:
docker pull pnnl/gridpack:v3.6
Available tags: latest (latest stable), dev (development builds), and vX.Y.Z for specific semantic version releases such as v3.6.
2

Start an interactive session

Mount your current directory into the container and open an interactive shell:
docker run -it --rm -v $(pwd):/app/workspace pnnl/gridpack:latest bash
The flags used here:
FlagPurpose
-itAllocate a TTY and keep stdin open for interactive use
--rmRemove the container automatically when you exit
-v $(pwd):/app/workspaceMount your current host directory into the container
You will land at /app/workspace inside the container.
3

Run the dynamics simulation example

The container ships with pre-built GridPACK application binaries and test input files. Run the full-Y dynamics simulation on the 145-bus test case:
cd /app/src/build/applications/dynamic_simulation_full_y
cp input_145.xml input.xml
./dsf.x
On a successful run, timing statistics are printed to the terminal after the simulation completes. You can also run the 9-bus test case:
cp input_9bus.xml input.xml
./dsf.x
4

Run with MPI for parallel execution

GridPACK applications are MPI-parallel. Use mpirun inside the container to run on multiple processes:
mpirun -n 4 ./dsf.x input.xml
The container sets OMPI_ALLOW_RUN_AS_ROOT=1 so MPI runs without privilege warnings in the containerized environment.
For large simulations, increase the container’s memory limit by adding --memory=8g (or more) to your docker run command.

​
Run a single command without an interactive shell

You do not need an interactive session for scripted workflows. Pass the command directly to docker run: 
# Run power flow directly
docker run --rm -v $(pwd):/app/workspace pnnl/gridpack:latest \
  powerflow.x input.xml

# Run a Python script using the GridPACK Python bindings
docker run --rm -v $(pwd):/app/workspace pnnl/gridpack:latest \
  python3 my_gridpack_script.py

# Run the full test suite
docker run --rm pnnl/gridpack:latest bash -c "cd /app/src/build && ctest"

​
Specify architecture explicitly

Docker selects the correct image variant automatically, but you can request a specific architecture: 
# Intel/AMD processors
docker pull --platform linux/amd64 pnnl/gridpack:latest

# Apple Silicon or AWS Graviton
docker pull --platform linux/arm64 pnnl/gridpack:latest

​
Container directory layout

PathContents
/app/workspaceDefault working directory; mount your files here
/app/src/installGridPACK installation (binaries, headers, libraries)
/app/src/buildBuild directory with application executables and test inputs
/depsPre-built Boost, Global Arrays, and PETSc installations

​
Pre-configured environment variables

The following environment variables are set inside the container: 
GRIDPACK_DIR=/app/src/install
PATH=/app/src/install/bin:/app/src/install/local/bin:$PATH
LD_LIBRARY_PATH=/deps/boost-1.81.0/install_for_gridpack/lib:\
                /deps/ga-5.9.1/install_for_gridpack/lib:\
                /deps/petsc/install_for_gridpack/lib

​
Troubleshooting

Permission errors on mounted files If you encounter file permission errors when writing output to the mounted volume, run the container with your host user ID: 
docker run -it --rm -u $(id -u):$(id -g) -v $(pwd):/app/workspace pnnl/gridpack:latest bash
MPI warnings about running as root The container sets OMPI_ALLOW_RUN_AS_ROOT=1 and OMPI_ALLOW_RUN_AS_ROOT_CONFIRM=1. These suppress the OpenMPI root-user warning and are safe in containerized environments.

​
Next steps

Build from source

Compile GridPACK outside of Docker with full control over dependencies and build flags.

Power flow application

Learn how to configure and run the AC power flow application on your own network files.

Build docs developers (and LLMs) love

Get started for freeTalk to us