Using GridPACK with Docker

GridPACK is available as a Docker image with all dependencies pre-installed and ready to use.

Quick Start

Pull the Image

docker pull pnnl/gridpack:latest

Run with Your Files

The container starts in /app/workspace by default. Mount your current directory to work with your files:

docker run -it --rm -v $(pwd):/app/workspace pnnl/gridpack:latest

Usage Examples

Interactive Shell

# Mount your working directory and start an interactive session
docker run -it --rm -v $(pwd):/app/workspace pnnl/gridpack:latest bash

Run a Specific Command

# Run a GridPACK application directly
docker run --rm -v $(pwd):/app/workspace pnnl/gridpack:latest \
  powerflow.x input.xml

Python Scripts

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

Run Tests

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

Working Directory

The container is configured with:

Working directory: /app/workspace
GridPACK installation: /app/src/install
Build directory: /app/src/build

Mount your data/scripts to /app/workspace to access them from within the container.

Environment Variables

The following environment variables are pre-configured:

GRIDPACK_DIR=/app/src/install
PATH=/app/src/install/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

Multi-Architecture Support

The Docker image supports both AMD64 and ARM64 architectures. Docker automatically pulls the correct image for your platform.

To explicitly specify an architecture:

# For AMD64 (Intel/AMD processors)
docker pull --platform linux/amd64 pnnl/gridpack:latest

# For ARM64 (Apple Silicon, AWS Graviton)
docker pull --platform linux/arm64 pnnl/gridpack:latest

Available Tags

latest - Latest stable release
dev - Development builds
vX.Y.Z - Specific version releases

Tips

Add -it for interactive terminal access
Add --rm to automatically remove the container after exit
Use -v to mount local directories into the container
Increase memory limits for large simulations: --memory=8g
Use multiple cores: Set OMPI_NUM_PROCS or pass to MPI commands

Example Workflow

# 1. Create a project directory
mkdir my-gridpack-project
cd my-gridpack-project

# 2. Create your input files
cat > input.xml << EOF
<?xml version="1.0" encoding="utf-8"?>
<Configuration>
  <!-- Your GridPACK configuration -->
</Configuration>
EOF

# 3. Run GridPACK in the container
docker run -it --rm -v $(pwd):/app/workspace pnnl/gridpack:latest bash

# Inside container:
# powerflow.x input.xml
# exit

Troubleshooting

Permission Issues

If you encounter permission issues with mounted volumes:

# Run with your user ID
docker run -it --rm -u $(id -u):$(id -g) -v $(pwd):/app/workspace pnnl/gridpack:latest

MPI Warnings

The container sets OMPI_ALLOW_RUN_AS_ROOT=1 to allow running MPI as root. This is safe for containerized environments.

Running Applications with MPI

GridPACK applications can be run with MPI inside the Docker container. For example:

# Run with 4 MPI processes
docker run --rm -v $(pwd):/app/workspace pnnl/gridpack:latest \
  mpirun -n 4 powerflow.x input.xml

For detailed information on MPI execution, application arguments, and input file conventions, see Configuring and Building GridPACK (Running GridPACK Applications section).

Building from Source

If you need to build GridPACK from source instead of using Docker, see Configuring and Building GridPACK for detailed instructions on using build scripts or manual compilation.