kub-dataset: Simulator Datasets

1. Purpose

This page documents simulator dataset commands under:

cemdb/simulators/vX.Y.Z

Simulator datasets store FMU model bundles organized by LOD directories and support models under others/.

New datasets should be generated through kub-dataset generate simulator and should use manifest.json as the source of truth for the dataset inventory.

For exhaustive command options and API notes, see kub-dataset: Full Reference.

2. Simulator Layout

cemdb/simulators/
└── v0.3.0/
    ├── manifest.json
    ├── lod0/
    │   ├── App4Walls1Floor1Roof.fmu
    │   └── ...
    ├── lod1/
    │   ├── App4Walls1Floor1Roof.fmu
    │   └── ...
    ├── others/
    │   └── Sun.fmu
    └── _build/              # optional, only with --keep-workdir

lod*.metadata.json and others.metadata.json are legacy artifacts. They may still appear in older datasets or compatibility workflows, but new generated datasets should not rely on them.

3. Simulator Command Synopsis

kub-dataset generate simulator --version <version> [options]

kub-dataset pack-simulator --version <version> [--lod <lod>] [--single]
kub-dataset unpack-simulator <archive> [--force]

kub-dataset push-simulator --version <version> [--lod <lod>] --api-key <key>
kub-dataset pull-simulator --version <version> [--lod <lod>] [--dvc] [--force]

kub-dataset list-simulators [--local] [--remote] [--version <version>] [--format {table,json}]
kub-dataset list-simulator-versions [--version <version>]

kub-dataset delete-simulator --version <version> [--lod <lod>] --api-key <key>

4. Core Workflows

4.1. Generation

For a focused step-by-step guide, see kub-dataset: generate simulator.

# Generate the built-in production lod0 + lod1 FMU matrix
kub-dataset generate simulator --version 0.3.0

# Restrict generation to selected LODs
kub-dataset generate simulator --version 0.3.0 --lod 0 --lod 1

# Use a custom JSON generation specification
kub-dataset generate simulator --version 0.3.0 --spec simulators.json

# Plan only, without generating FMUs
kub-dataset generate simulator --version 0.3.0 --dry-run

# Keep the intermediate generated Modelica work tree
kub-dataset generate simulator --version 0.3.0 --keep-workdir

The built-in production preset generates:

  • lod0: 60 building FMUs

  • lod1: 294 building FMUs

  • others/Sun.fmu

The command writes the final dataset under:

cemdb/simulators/vX.Y.Z/

For generate simulator, --cemdb-root should point to cemdb/simulators.

4.2. Packaging and Restoration

# Pack all directories as independent archives
kub-dataset pack-simulator --version 0.1.0

# Pack one LOD only
kub-dataset pack-simulator --version 0.1.0 --lod 0

# Create one unified archive with manifest
kub-dataset pack-simulator --version 0.1.0 --single

# Restore from archive
kub-dataset unpack-simulator simulators-v0.1.0.zip --force

4.3. Remote Publication and Download

# Push complete simulator version to Girder
kub-dataset push-simulator --version 0.1.0 --api-key $GIRDER_API_KEY

# Pull all directories for a version
kub-dataset pull-simulator --version 0.1.0 --force

# Pull one LOD and create DVC tracking
kub-dataset pull-simulator --version 0.1.0 --lod 0 --dvc --force

4.4. Discovery and Cleanup

# Compare local/remote availability
kub-dataset list-simulators
kub-dataset list-simulators --remote --format json

# Delete one item or an entire version on Girder
kub-dataset delete-simulator --version 0.1.0 --lod others --api-key $GIRDER_API_KEY --yes
kub-dataset delete-simulator --version 0.1.0 --api-key $GIRDER_API_KEY --yes

5. Notes

  • --lod accepts numeric LOD (for example 0, 1, 2) or named directory such as others.

  • With unpack-simulator, unified archives include manifest.json; single-directory archives do not.

  • generate simulator currently targets lod0, lod1, and others/Sun.fmu through mo2fmu.

  • New simulator datasets should be read from manifest.json; legacy metadata sidecars are compatibility-only.

6. Related Pages