Simstack Onboarding

Repo for the onboarding and introduction to Simstack II

Access

1. Register access to the jupyterhub: https://material-digital.de/
2. Go to: https://pyiron.material-digital.de/

Some jupyter instance should pop up

Web UI:

This is the web UI for Simstack II, where you can submit and monitor workflows, manage resources, and inspect results. Go to https://pmd-simstack-demo.ydns.eu/ and login with the provided credentials.

Installation

1. Open https://pmd-simstack-demo.ydns.eu/login, sign in, go to Profile, and create a new resource:

local/display name: pyiron
hostname: any value (for example pyiron.material-digital.de)
default: true

2. Save the resource, then generate/rotate and download the token for that local resource.
3. Download your simstack.toml from Profile and make sure the filename is exactly simstack.toml (lowercase, exact name).
4. Open https://pyiron.material-digital.de, sign in with SSO, launch the Simstack Onboarding template
5. In Jupyter file browser, open the simstack-onboarding subfolder and upload simstack.toml into that folder.
6. Open a terminal in Jupyter and run step by step:

uv run create_model_table --dir models --dir private --dir public
uv run create_node_table --dir models --dir private --dir public
uv run simstack_runner --resource pyiron --no-pull --detach False

Running the first workflow

1. in the UI go to submit
2. under public / first_steps / simple_operations / add click "favorite"
3. select "favorite"
4. fill in some numbers for a and b
5. click submit workflow
6. in the task tabs you should see an entry "add", first yellow, then hopefully green
7. click on the green entry and you should see the inputs / outputs / logs of the workflow
8. in the jupyter instance lots of log entries should have been printed to the terminal
9. go to the jupyter instance and create a new terminal, go to the simstack directory
10. you should see a new folder called "add" with an empty directory with the job_id

Writing your first workflow

1. inspect the code in the first_steps/simple_operations.py
2. copy this file to first_steps/complex_operations.py
3. write a function complex_operation which takes three args, adds the first two using the sum node and multiplies the result with the third arg
4. test the function in the jupyter instance by adding the following code

import asyncio 
from simstack.core.context import context 

async def main():
    await context.initialize()
    arg1 = FloatData(field_name="arg1",value=1)
    arg2 = FloatData(field_name="arg2",value=2)
    arg3 = FloatData(field_name="arg3",value=3)
    result = await complex_operation(arg1,arg2,arg3)
    print(result.value)

if __name__ == "__main__":
    asyncio.run(main())

5. open a terminal and set export PYTHONPATH=pwd run this code in a terminal as: uv run python public/first_steps/complex_operation.py. You should get an error like this:

2026-02-26 11:33:50 - Context         - INFO       - context.py          : 157 - Database connection to None mongodb://wolfgang-onboarding@simstack.int.kit.edu:27017//None
2026-02-26 11:33:50 - config-reader   - INFO       - config_reader.py    :  75 - toml-file read, use_db_for_init: True
2026-02-26 11:33:50 - init_resource   - INFO       - init_data_source.py :  18 - Initializing ConfigReader from database, allowed resources: ['local', 'self']
2026-02-26 11:33:50 - init_resource   - INFO       - init_data_source.py :  32 - ConfigReader resources: ['local', 'self']
2026-02-26 11:33:50 - init_resource   - WARNING    - init_data_source.py :  44 - Initializing paths from database is not yet implemented
2026-02-26 11:33:50 - config-reader   - INFO       - config_reader.py    : 103 - ConfigReader initialized with workdir: /home/jovyan/simstack
2026-02-26 11:33:50 - config-reader   - INFO       - config_reader.py    : 105 - resource_definition.resource_str: self
2026-02-26 11:33:50 - config-reader   - INFO       - config_reader.py    : 105 - resource_definition.workdir: /home/jovyan/simstack
2026-02-26 11:33:50 - config-reader   - INFO       - config_reader.py    : 105 - resource_definition.hostname: localhost
2026-02-26 11:33:50 - config-reader   - INFO       - config_reader.py    : 105 - resource_definition.python_paths: []
2026-02-26 11:33:50 - config-reader   - INFO       - config_reader.py    : 105 - resource_definition.environment_start: None
2026-02-26 11:33:50 - config-reader   - INFO       - config_reader.py    : 105 - resource_definition.ssh_key: None
2026-02-26 11:33:50 - config-reader   - INFO       - config_reader.py    : 105 - resource_definition.routes: []
2026-02-26 11:33:50 - config-reader   - INFO       - config_reader.py    : 105 - resource_definition.is_default: False
2026-02-26 11:33:50 - config-reader   - INFO       - config_reader.py    : 105 - resource_definition.git_branch: main
2026-02-26 11:33:50 - config-reader   - INFO       - config_reader.py    : 105 - resource_definition.id: 69a02f9edf0b43d7cbef6ef3
2026-02-26 11:33:50 - Node            - ERROR      - node.py             : 183 - Could not find function mapping for name: complex_operation
Traceback (most recent call last):
  File "/home/jovyan/simstack-onboarding/public/first_steps/complex_workflow.py", line 21, in <module>
    asyncio.run(main())
  File "/home/jovyan/simstack-onboarding/.venv/lib/python3.12/site-packages/nest_asyncio.py", line 30, in run
    return loop.run_until_complete(task)
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/jovyan/simstack-onboarding/.venv/lib/python3.12/site-packages/nest_asyncio.py", line 98, in run_until_complete
    return f.result()
           ^^^^^^^^^^
  File "/home/jovyan/.local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/lib/python3.12/asyncio/futures.py", line 202, in result
    raise self._exception.with_traceback(self._exception_tb)
  File "/home/jovyan/.local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/lib/python3.12/asyncio/tasks.py", line 314, in __step_run_and_handle_result
    result = coro.send(None)
             ^^^^^^^^^^^^^^^
  File "/home/jovyan/simstack-onboarding/public/first_steps/complex_workflow.py", line 17, in main
    result = await complex_operation(arg1,arg2,arg3)
                   ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/jovyan/simstack-onboarding/.venv/lib/python3.12/site-packages/simstack/core/node.py", line 889, in sync_wrapper
    status = loop.run_until_complete(execution_node.get_node_registry())
             ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/jovyan/simstack-onboarding/.venv/lib/python3.12/site-packages/nest_asyncio.py", line 98, in run_until_complete
    return f.result()
           ^^^^^^^^^^
  File "/home/jovyan/.local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/lib/python3.12/asyncio/futures.py", line 202, in result
    raise self._exception.with_traceback(self._exception_tb)
  File "/home/jovyan/.local/share/uv/python/cpython-3.12.12-linux-x86_64-gnu/lib/python3.12/asyncio/tasks.py", line 314, in __step_run_and_handle_result
    result = coro.send(None)
             ^^^^^^^^^^^^^^^
  File "/home/jovyan/simstack-onboarding/.venv/lib/python3.12/site-packages/simstack/core/node.py", line 267, in get_node_registry
    await self.make_registry_entry(function_hash, arg_hash)
  File "/home/jovyan/simstack-onboarding/.venv/lib/python3.12/site-packages/simstack/core/node.py", line 184, in make_registry_entry
    raise ValueError(f"Could not find function mapping for name: {self.name}")
ValueError: Could not find function mapping for name: complex_operation

the first part tells you that the process started OK, but the second part tells you that the function complex_operation is not registered.

6. rerun: uv run create_node_table --dir private --dir public and the program again (should work now)
7. go to the UI
8. inspect the task tab, click on the little arrow next to the complex_operation task and should see the subtasks
9. go to submit: click on the complex_operation task, fill in some values and click submit
10. go to the task tab and inspect the results