kub-dataset: generate simulator

1. Purpose

This page documents the kub-dataset generate simulator workflow used to build versioned FMU datasets under:

cemdb/simulators/vX.Y.Z

It covers:

  • full production lod0 and lod1 generation

  • restricted lod0 generation

  • custom generation specifications with --spec

  • progress monitoring through generation.log

  • Dymola and mo2fmu prerequisites

For broader simulator-dataset workflows such as packing, pushing, and pulling, see kub-dataset: Simulator Datasets.

2. Command Synopsis

kub-dataset generate simulator \
  --version <version> \
  [--cemdb-root <path>] \
  [--spec <spec.json>] \
  [--lod <lod>] ... \
  [--description <text>] \
  [--dry-run] \
  [--keep-workdir] \
  [--force] \
  [--dymola-root <path>] \
  [--dymola-path <path>] \
  [--dymola-wheel <relative-wheel-path>] \
  [-v]

The CLI parser for these options is defined in src/python/feelpp/ktirio/ub/dataset/cli.py and implemented by generate_simulator_dataset() in src/python/feelpp/ktirio/ub/dataset/simulator_generation.py.

3. Prerequisites

3.1. Python Environment

The command can be run either through an installed kub-dataset entry point or directly from the repository root:

PYTHONPATH=src/python .venv/bin/python -m feelpp.ktirio.ub.dataset.cli generate simulator ...

3.2. Dymola and mo2fmu

Simulator generation currently relies on Dymola through mo2fmu.

Default toolchain paths are:

  • Dymola root: /opt/dymola-2025xRefresh1-x86_64/

  • Dymola executable: /usr/local/bin/dymola

  • Dymola Python wheel: Modelica/Library/python_interface/dymola-2025.1-py3-none-any.whl

These defaults come from src/python/feelpp/ktirio/ub/dataset/simulator_generation.py.

Override them when needed:

kub-dataset generate simulator \
  --version 0.3.0 \
  --dymola-root /opt/dymola-2025xRefresh1-x86_64/ \
  --dymola-path /usr/local/bin/dymola \
  --dymola-wheel Modelica/Library/python_interface/dymola-2025.1-py3-none-any.whl

mo2fmu must be importable from the active Python environment.

4. Output Layout

A successful generation creates:

cemdb/simulators/
└── v0.3.0/
    ├── generation.log
    ├── manifest.json
    ├── lod0/
    │   ├── App4Walls1Floor1Roof.fmu
    │   └── ...
    ├── lod1/
    │   ├── App4Walls1Floor1Roof.fmu
    │   └── ...
    ├── others/
    │   └── Sun.fmu
    └── _build/              # only when --keep-workdir is used

generation.log is written inside the version directory from the start of the run and is the recommended progress monitor.

5. Built-In Production Matrix

Without --spec, the generator uses the built-in production matrix defined in src/python/feelpp/ktirio/ub/dataset/simulator_generation.py.

Current built-in matrix:

  • lod0

    • floors 1..10

    • 4 walls

    • 1 roof panel

    • 0 roof walls

    • glazing false and true

    • heating systems: ideal, boiler, heatPump

  • lod1

    • floors 1..7

    • walls 4..10

    • 1 roof panel

    • 0 roof walls

    • glazing false and true

    • heating systems: ideal, boiler, heatPump

  • support models

    • others/Sun.fmu

This corresponds to:

  • lod0: 60 building FMUs

  • lod1: 294 building FMUs

  • others: 1 support FMU

6. Common Workflows

6.1. Generate a New Full Production Dataset

kub-dataset generate simulator \
  --version 0.3.0 \
  --cemdb-root cemdb/simulators \
  --force \
  -v

This generates the built-in lod0 + lod1 matrix plus others/Sun.fmu.

6.2. Generate Only lod0

kub-dataset generate simulator \
  --version 0.3.0 \
  --cemdb-root cemdb/simulators \
  --lod 0 \
  --force \
  -v

This is the usual command to regenerate only the lod0 FMU dataset.

6.3. Generate a Custom lod0 Subset

For a reduced Kernante-oriented lod0 subset, save the following specification as kernante-lod0-glazed.json:

Unresolved include directive in modules/ROOT/pages/tools/kub-dataset-generate-simulator.adoc - include::example$kub-dataset-generate-simulator-kernante-lod0-glazed.json[]

This generates only:

  • lod0

  • floors 1..4

  • glazed variants only

  • heating systems ideal, boiler, and heatPump

  • others/Sun.fmu

Run it with:

kub-dataset generate simulator \
  --version 0.3.0-test \
  --cemdb-root cemdb/simulators \
  --spec kernante-lod0-glazed.json \
  --force \
  -v

6.4. Plan Without Generating FMUs

kub-dataset generate simulator \
  --version 0.3.0 \
  --cemdb-root cemdb/simulators \
  --lod 0 \
  --dry-run

6.5. Keep the Intermediate Build Tree

kub-dataset generate simulator \
  --version 0.3.0 \
  --cemdb-root cemdb/simulators \
  --lod 0 \
  --keep-workdir \
  --force \
  -v

With --keep-workdir, the generated Modelica tree is preserved under:

cemdb/simulators/v0.3.0/_build

7. Progress Monitoring

The generator writes a persistent log file:

cemdb/simulators/vX.Y.Z/generation.log

Typical monitoring commands:

tail -f cemdb/simulators/v0.3.0/generation.log
find cemdb/simulators/v0.3.0/lod0 -name '*.fmu' | wc -l

The log distinguishes:

  • total FMU jobs, including support models such as Sun.fmu

  • finalized building FMUs in each lod* directory

  • finalized support FMUs under others/

8. Important Notes

  • --cemdb-root for this command should point to cemdb/simulators.

  • --lod is repeatable and accepts numeric LOD values such as 0 and 1.

  • --force overwrites an existing version directory.

  • New generated datasets use manifest.json as the source of truth.

  • _build appears only when --keep-workdir is enabled.

9. Related Pages