Quick Start

This page provides instructions for running WSIM using an example configuration stored in the source repository.


The instructions assume that WSIM will be run through Docker, and that Docker is already installed.

The configuration operates globally at half-degree resolution and is based on use of the following datasets:

Preparing to run WSIM

To begin, two directories should be created to store WSIM data:

  • a source directory, in which WSIM will store raw and processed input data files; and

  • a runs directory, in which WSIM will create a data workspace for the model configuration.

In this example, the source directory is ~/wsim/source and the runs directory is ~/wsim/runs.

Once these directories have been created, a Makefile can be generated with instructions to fetch and preprocess source data, spin-up the land surface model, and produce composite indices of water surplus and deficit. The Makefile encapsulates a complex process, requiring about 25,000 steps to spin up a model and produce composite indices. (About 75% of these steps occur as part of the model spinup process, and only need to be executed the first time WSIM is run.)

The command below requests a Makefile based on the workflow/config/config_cfs.py config file for the 201801 (January 2018) model iteration. (The ~ shortcut for the home directory is not used because it does not function as expected with some Docker commands.)

docker run \
  -it \
  --rm \
  -v `echo $HOME`/wsim:/opt/wsim_data:rw \
  isciences/wsim:latest \
  workflow/makemake.py \
    --config workflow/config/config_cfs.py \
    --source /opt/wsim_data/source \
    --workspace /opt/wsim_data/runs/quickstart \
    --start 201801


The steps for model iterations up to January 2017 are automatically included in the file as part of the spinup process. If we try to run 201802 or a later step, WSIM will fail unless we have run 201801 first.

Running the model

Once the Makefile is generated, the following command can be run to generate composite indices. Note the use of the -j8 flag, instructing Make to run up to 8 processes in parallel.

docker run \
  -it \
  --rm \
  -v /home/dbaston/wsim:/opt/wsim_data:rw \
  --workdir /opt/wsim_data/runs/quickstart \
  isciences/wsim:latest \
  make \
    -j8 \


Running the spin-up process will cause several gigabytes of data to be downloaded and will occupy a multi-core processor for several hours.

After running, a series of netCDF files with composite indices will be present in wsim/runs/quickstart/composite. Some examples are below:

  • composite_1mo_201801.nc contains composite indices calculated from observed data for January 2018.

  • composite_12mo_201801.nc contains composite indices calculated from observed data for the 12-month period ending in January 2018.

  • composite_12mo_201801_trgt201810.nc contains forecast composite indices for the 12-month period ending in October 2018, calculated using observed data from November 2017 to January 2018, and predictions of a 28-member forecast ensemble from February 2018 to October 2018.

Each netCDF file contains variables with the composite surplus/deficit values, and variables indicating which input indicator (runoff, soil moisture, etc.) was primarily responsible for the surplus/deficit.

Data in these files can be viewed with a netCDF viewer such as Panoply or a general-purpose GIS such as QGIS. Another option is to use GeoServer which can read a directory of netCDF files and publish it as a Web Map Service. This method is described in greater detail below.

Serving WSIM results via Web Map Service

The isciences/wsim_geoserver Docker container contains a GeoServer installation and script that can be used to serve data output from WSIM. The following command can be used to start the GeoServer container:

docker run \
  -d \
  --name wsim_geoserver \
  --publish 8080:8080 \
  --log-driver json-file \
  --log-opt max-size=100m \
  -v /mnt/fig_rw/WSIM_DEV/runs:/opt/wsim_data:ro \

Once the GeoServer container is up and running, we can run a script from within the container to configure layers from the quickstart workspace:

docker exec \
  -it \
  wsim_geoserver \
  configure_geoserver.py \
    quickstart init

Once the configuration script has run, you can open a web browser and request a hotspot map for a given model iteration, forecast target date, and time integration window. An example URL is shown below.


The following URL parameters can be used to control the map output:




image format to produce


width of generated image


height of generated image


list of layers to include in map


spatial reference system for rendered map


bounding box of the map, in units of srs


model iteration date


time-integration window (used to select data values)


parameters used to scale color ramps


forecast target date

Viewing results in a web application

The wsim_viewer Docker container provides a simple web application that can be used to interactively view WSIM outputs as rendered by GeoServer. It can be run with the following command:

docker run \
  -d \
  --name wsim_viewer \
  --publish 80:80 \
  -e GEOSERVER=http://localhost:8080/geoserver \
  -e START_DATE=201801 \
  -e END_DATE=201801 \
  -e WORKSPACES=quickstart \

where the GEOSERVER parameter is used to point the viewer to the running version of GeoServer, and the START_DATE and END_DATE parameters are used to specify the model iterations available in the viewer.