Simstack II Setup

UI Setup

  1. Register at simstack.int.kit.edu (inside the KIT network). This will create an inactive user.

  2. Email the maintainer so your account can be activated and you can receive:

    • a database name

    • a database password

    (This is not automated yet.)

  3. Go to your profile and upload your resources configuration.

Example resources configuration

[
  {
    "id": "<object-id>",
    "resource_str": "local-home",
    "hostname": "localhost",
    "workdir": "$HOME/simstack",
    "python_paths": [],
    "environment_start": "",
    "ssh_key": "$HOME/.ssh/id_rsa",
    "routes": [
      "int-nano"
    ],
    "queue": "default"
  },
  {
    "id": "<object-id>",
    "resource_str": "int-nano",
    "hostname": "int-nano.int.kit.edu",
    "workdir": "$HOME/simstack",
    "python_paths": [],
    "environment_start": "",
    "ssh_key": "$HOME/.ssh/id_rsa",
    "routes": [],
    "queue": "default"
  },
  {
    "id": "<object-id>",
    "resource_str": "justus",
    "hostname": "justus2.uni-ulm.de",
    "workdir": "$HOME/simstack",
    "python_paths": [],
    "environment_start": "",
    "ssh_key": "$HOME/.ssh/id_rsa",
    "routes": [
      "int-nano",
      "local-home"
    ],
    "queue": "slurm-queue"
  }
]

Installation of Runners

Prerequisites

Clone the repository

In $HOME/projects clone the repository:

  • SSH (if your SSH key is added to GitLab):

    git clone git@gitlab.kit.edu:kit/ag_wenzel/simstack-model.git

  • HTTPS (if you have a token):

    git clone https://gitlab.kit.edu/kit/ag_wenzel/simstack-model.git

Then:

cd simstack-model

Host-specific environment notes

On int-nano you may need to override the C/C++ toolchain because the default compiler is too old. Add the following to your ~/.bashrc:

export PATH=/path/to/gcc-12.3/bin:$PATH
export LD_LIBRARY_PATH=/path/to/gcc-12.3/lib64:$LD_LIBRARY_PATH
export CC=/path/to/gcc-12.3/bin/gcc
export CXX=/path/to/gcc-12.3/bin/g++

Set the paths to the location where gcc-12.3 is installed (e.g. /shared/user/ww or /home/ws/<user>). It is unclear what you need on other systems.

On justus you may need:

export LD_LIBRARY_PATH=$HOME/local/lib:$MKLROOT/lib/intel64:$LD_LIBRARY_PATH

Sync dependencies

source ~/.bashrc
uv sync --locked

Note: This will install all required dependencies, including mongomock and mongomock-motor, which are used for in-memory database support during testing.

Create simstack.toml

Create a simstack.toml file (placeholders shown below):

[parameters]
[parameters.general]
use_db = true
workdir_self = "<PATH_TO_SIMSTACK_DATA_DIR>"
# these are parameters for one user for all hosts

[parameters.db]
database = "<NAME>_data"
test_database = "<NAME>_test"
connection_string = "mongodb://<USER>:<PASSWORD>@<HOST>:27017/"
mongodump_path = "<PATH_TO_MONGODUMP_EXE>"

Where:

  • <PATH_TO_SIMSTACK_DATA_DIR> is the path to the data directory created above (e.g. $HOME/simstack)

  • <NAME> is your database name (often your first name in lower case)

  • <PASSWORD> is the database password

  • <PATH_TO_MONGODUMP_EXE> is the path to the mongodump executable (required for database backups)

Initialize the system

This will happen automatically when the default runner starts.

uv run create_model_table --dir examples --dir applications
uv run create_node_table --dir examples --dir applications

Note: this may crash if your database is very old.

Configure Git identity (required)

Because the runner performs Git operations, ensure you have:

git config --global user.email "<YOUR_EMAIL_ADDRESS>"
git config --global user.name "<YOUR_NAME>"

Start the runner

From $HOME/projects/simstack-model:

nohup uv run simstack_runner --resource <RESOURCE_NAME> &

Where <RESOURCE_NAME> is one of the resources you defined in the UI.

Ignore after this line

Notes / scratch commands:

git submodule add -b new-init https://git@github.com/simstack/simstack.git simstack

uv lock --upgrade-package <package-name>