Skip to content



License Travis CI GitHub Action CI status Conda

Note: if looking for content of geoclaw-landspill-cases, please checkout tag v0.1. This repository has been converted to a fully working solver package.

geoclaw-landspill is a package for running oil overland flow simulations for applications in pipeline risk management. It includes a numerical solver and some pre-/post-processing utilities.

The numerical solver is a modified version of GeoClaw. GeoClaw solves full shallow-water equations. We added several new features and utilities to it and make it usable to simulate the overland flow from pipeline ruptures. These features include:

  • adding point sources to mimic the rupture points
  • adding evaporation models
  • adding Darcy-Weisbach bottom friction models with land roughness
  • adding temperature-dependent viscosity
  • recording detail locations and time of oil flowing into in-land waterbodies
  • downloading topography and hydrology data automatically (the US only)
  • generating CF-1.7 compliant NetCDF files


  1. Dependencies, installation, and tests
  2. Usage
  3. Configuration file:
  4. Example cases
  5. Containers: Docker and Singularity

Quick start

We only maintain compatibility with Linux. Though using pip or building from source may still work in Mac OS or Windows (e.g., through WSL), we are not able to help with the installation issues on these two systems.

Beyond this quick start, to see more details, please refer to the documentation section.

1. Installation

The fast way to install geoclaw-landspill is through Anaconda's conda command. The following command creates a conda environment (called landspill) and installs the package and dependencies:

$ conda create \
    -n landspill -c barbagroup -c conda-forge \
    python=3.8 geoclaw-landspill

Then use conda activate landspill or source <conda installation prefix>/bin/activate landspill to activate the environment. Type geoclaw-landspill --help in the terminal to see if geoclaw-landspill is correctly installed.

2. Running an example case

To run an example case under the folder cases, users have to clone this repository. We currently don't maintain another repository for cases. After cloning this repository, run

$ geoclaw-landspill run <path to an example case folder>

For example, to run utal-flat-maya:

$ geoclaw-landspill run ./cases/utah-flat-maya

Users can use environment variable OMP_NUM_THREADS to control how many CPU threads the simulation should use for OpenMP parallelization.

3. Creating a CF-compliant NetCDF raster file

After a simulation is done, users can convert flow depth in raw simulation data into a CF-compliant NetCDF raster file. For example,

$ geoclaw-landspill createnc ./case/utah-flat-maya

Replace ./cases/utah-flat-maya with the path to another desired case.

QGIS and ArcGIS should be able to read the resulting NetCDF raster file.

Third-party codes and licenses




Pi-Yueh Chuang: