Skip to content
SimPaths
Environment Setup

Environment Setup

This page covers the local software requirements, repository setup, and the first-time build and database steps needed before SimPaths is ready to run.

Local requirements

Component Version Sources
Java Development Kit (JDK) 25 Adoptium
Apache Maven 3.8 or later Apache Maven
Git Not pinned Git

It is worth checking the toolchain before going further:

java -version
mvn -version
git --version

Clone the repository

Clone SimPaths and move into the repository root:

git clone https://github.com/simpaths/SimPaths.git
cd SimPaths

Build the executables

Build them from the repository root:

mvn clean package

After a successful package step, both jars are written to the repository root.

SimPaths uses the Maven Shade plugin to build two runnable jars:

  • singlerun.jar for single simulations via simpaths.experiment.SimPathsStart
  • multirun.jar for repeated runs via simpaths.experiment.SimPathsMultiRun

Input layout

Before a real run, SimPaths expects the input/ directory to contain:

  • InitialPopulations/ for starting population CSV files
  • EUROMODoutput/ for donor tax-benefit input files
  • Excel workbooks such as EUROMODpolicySchedule.xlsx, DatabaseCountryYear.xlsx, and the align_*.xlsx, reg_*.xlsx, scenario_*.xlsx, and projections_*.xlsx parameter files

The key point here is that SimPaths does not run directly from the raw CSV and EUROMOD files. During setup, the code rebuilds the local H2 database input/input.mv.db from those sources by calling Parameters.databaseSetup().

First-time setup

The first-time setup step is what turns the repository from "compiled" into "runnable".

For a clean first headless setup, the most explicit route is:

java -jar singlerun.jar -Setup -c UK -s 2019 -g false --rewrite-policy-schedule

Once that succeeds, a run-only check is straightforward:

java -jar singlerun.jar -Run -c UK -s 2019 -g false

If you prefer the repeated-run path, the equivalent setup command is:

java -jar multirun.jar -DBSetup -config config/default.yml

Common setup problems

The usual setup failures are:

Problem What happens
wrong Java version the build or runtime fails before the model even starts
missing initial population files setup falls back to training data, or database creation fails
missing donor files the tax-benefit database cannot be rebuilt
stale policy schedule the EUROMOD output files and EUROMODpolicySchedule.xlsx do not line up
database needs rebuilding donor files or schedule changed, but the old input/input.mv.db is still being reused

If donor inputs, donor years, or the policy schedule change, rebuild the database before trying to interpret any results.

Next step

Once the project is built and the input data are in place, continue to Running Your First Simulation.