Running the WRIMS Engine in Headless Mode

Overview

The WRIMS engine can be run headless (without the graphical interface) by invoking the wrims-core JAR directly alongside its dependency JARs and native libraries. This is useful for batch processing, automated testing, or running studies from a CI/CD pipeline or scheduled task.

Note

These instructions assume you are working from the root directory of the wrims-engine repository and that you have a Java 21 JDK installed.

Prerequisites

  • Clone the wrims-engine repository.

  • Have Java 21 JDK available (e.g., Eclipse Temurin)

  • A WRIMS model directory containing a study.config file. (These study.config files are similar to the .launch files that WRIMS GUI uses. To create your own, refer to the configuration page.

Steps

1. Build the wrims-core Module

Run the Gradle build task for wrims-core from the wrims-engine project root directory.

./gradlew :wrims-core:build

Note

Gradle is a muti-use tool for Java projects. Don’t worry too much about learning how to use it if all you want to do is run WRIMS. All you need to know is that it is helpful in downloading all of the dependencies WRIMS needs, and putting those in the appropriate location on your machine. If you use Python, Gradle is similar to Conda.

The Gradle build task compiles the wrims-eninge JAR file and produces two directories:

  • wrims-core/build/libs/

    • Contains the wrims-core JAR file, which holds all of the classes that run WRIMS models.

  • wrims-core/build/tmp/libs/

    • Contains all dependency JARs, like the JARs needed to use the MILP solvers.

2. Download Native Libraries

Run the Gradle getNatives task to download the required Windows DLL files. These are placed in wrims-core/build/tmp/x64/ and must be on the system PATH at runtime.

./gradlew :wrims-core:getNatives

Note

Why does this not happen with the build task: these DLL files don’t change very often, so it speeds up our build times to separate these steps. If you aren’t planning on developing new versions of WRIMS Engine, you don’t need to worry about the details here.

3. Configure the Batch Script

A template batch file, run_wrims_study_example.bat, is provided in the root of the repository. Copy it and rename it for your project (e.g., run_project.bat), then edit the two project-specific variables at the top:

Variable

Description

PROJECT_DIR

Absolute path to your WRIMS project directory (e.g., J:\wrims\projects\dcr2023)

CONFIG_FILE

Name of the study configuration file within that directory (e.g., study.config)

Warning

You must also set the JAVA_HOME environment variable to point to your Java 21 JDK installation. This is something that is set on your machine, not in the batch file.

The remaining variables control Java classpath and entry-point settings. Do not change these unless you have moved the script out of the repository root.

Below is the full annotated batch file for reference:

@echo off

set PROJECT_DIR=J:\wrims\projects\dcr2023
set CONFIG_FILE=study.config

REM Path to your Java 21 JDK installation
set JAVA_HOME="J:\java\jdk\jdk_21.0.8_temurin"

set temp_wrims2=".\foo"

REM Add native DLLs to PATH (relative to wrims-engine root — do not change)
set PATH=%PATH%;wrims-core\build\tmp\x64

REM Add project-specific external libraries to PATH (do not change)
set PATH=%PATH%;%PROJECT_DIR%\Run\External

REM Entry point for headless execution (do not change)
set MAIN_CLASS=gov.ca.water.wrims.engine.core.components.ControllerBatch

REM Classpath entries (do not change when running from wrims-engine root)
set WRIMS_CORE_JAR="wrims-core\build\libs\*"
set WRIMS_CORE_DEPENDENCIES="wrims-core\build\tmp\libs\*"

REM Launch the engine with 4 GB heap and an extended thread stack size
%JAVA_HOME%\bin\java -Xmx4096m -Xss1024K ^
    -cp "%WRIMS_CORE_JAR%;%WRIMS_CORE_DEPENDENCIES%" ^
    %MAIN_CLASS% ^
    -config=%PROJECT_DIR%\%CONFIG_FILE%

pause

4. Run the Batch File

Execute the batch file from the wrims-engine root directory. You can either double-click it in Windows Explorer or run it from a terminal:

run_project.bat

The engine will start, load the study configuration, and run to completion. The pause at the end of the script keeps the terminal window open so you can review any output or error messages before it closes.

Troubleshooting

java not found

Verify that JAVA_HOME points to a valid Java 21 JDK directory and that %JAVA_HOME%\bin\java.exe exists.

Missing DLL errors on startup

Confirm that Step 2 completed successfully and that wrims-core\build\tmp\x64 is populated.

ClassNotFoundException for ControllerBatch

Confirm that Step 1 completed successfully and that wrims-core\build\libs\ and wrims-core\build\tmp\libs\ are populated.

Study config not found

Double-check that PROJECT_DIR and CONFIG_FILE together form the correct absolute path to your study.config file.

Script must be run from the repository root

The classpath and DLL path entries are relative. Always launch the script from the wrims-engine root directory, not from a subdirectory.