CEMDB Data Layout

cemdb/
|-- simulators/              # Shared FMU datasets (read-only across all simulations)
|   |-- ideal/               # Ideal heating system FMUs
|   |-- boiler/              # Boiler heating system FMUs
|   `-- heatPump/            # Heat pump system FMUs
`-- locations/               # Location-specific data
    `-- <location>/          # e.g., "kernante", "strasbourg", "paris"
        |-- gis/             # GIS input data
        |-- weather/         # Weather data files
        |-- scenarios/       # Scenario definitions
        |-- preprocessing/   # Cached preprocessing data
        `-- simulations/     # Simulation outputs
            |-- single/
            |   `-- run_<timestamp>/
            |       |-- manifest.json
            |       |-- setup.json
            |       `-- database/
            `-- ensemble/
                `-- run_<timestamp>/
                    |-- manifest.json
                    |-- setup.json
                    |-- ensemble/      # Aggregated ensemble statistics
                    |-- sample_000/
                    |   `-- database/
                    |-- sample_001/
                    |   `-- database/
                    `-- database/      # Run-level logs/config

namespace Feel::Ktirio::Ub {

enum class RunType {
    Single,     // Standalone simulation
    Ensemble    // Coordinated ensemble simulation
};

} // namespace Feel::Ktirio::Ub

from feelpp.ktirio.ub import RunType

# Available values:
RunType.Single    # Single simulation
RunType.Ensemble  # Ensemble simulation

// Basic run ID (no type prefix)
std::string runId = PathManager::generateRunId();
// -> "run_2025-01-15_14-30-45"

// Type-prefixed run IDs
std::string singleRunId = PathManager::generateRunId(RunType::Single, true);
// -> "single_run_2025-01-15_14-30-45"

std::string ensembleRunId = PathManager::generateRunId(RunType::Ensemble, true);
// -> "ensemble_run_2025-01-15_14-30-45"

from feelpp.ktirio.ub import core as ktirio_core

# Basic run ID (no type prefix)
run_id = ktirio_core.PathManager.generateRunId()
# -> "run_2025-01-15_14-30-45"

# Type-prefixed run IDs
single_run_id = ktirio_core.PathManager.generateRunId(
    ktirio_core.RunType.Single,
    includeTypePrefix=True
)
# -> "single_run_2025-01-15_14-30-45"

ensemble_run_id = ktirio_core.PathManager.generateRunId(
    ktirio_core.RunType.Ensemble,
    includeTypePrefix=True
)
# -> "ensemble_run_2025-01-15_14-30-45"

#include <ktirio/ub/pathmanager.hpp>

using namespace Feel::Ktirio::Ub;

// Single simulation
PathManager::instance().initialize(
    customRoot,
    locationName,
    runId,
    std::nullopt,
    RunType::Single
);

// Ensemble simulation (coordinator)
PathManager::instance().initialize(
    customRoot,
    locationName,
    PathManager::generateRunId(RunType::Ensemble),
    std::nullopt,
    RunType::Ensemble
);

// Ensemble simulation (member)
PathManager::instance().initialize(
    customRoot,
    locationName,
    runId,
    "000",
    RunType::Ensemble
);

from feelpp.ktirio.ub import core as ktirio_core

pm = ktirio_core.PathManager.instance()

pm.initialize(
    customRoot="/path/to/cemdb",
    locationName="kernante",
    runId=ktirio_core.PathManager.generateRunId(ktirio_core.RunType.Single),
    ensembleMemberId=None,
    runType=ktirio_core.RunType.Single
)

ensemble_run_id = ktirio_core.PathManager.generateRunId(
    ktirio_core.RunType.Ensemble,
    includeTypePrefix=True
)

pm.initialize(
    customRoot="/path/to/cemdb",
    locationName="kernante",
    runId=ensemble_run_id,
    ensembleMemberId=None,
    runType=ktirio_core.RunType.Ensemble
)

pm.initialize(
    customRoot="/path/to/cemdb",
    locationName="kernante",
    runId=ensemble_run_id,
    ensembleMemberId="000",
    runType=ktirio_core.RunType.Ensemble
)

// Root paths
std::filesystem::path cemdbRoot() const;
std::filesystem::path simulatorsDir() const;
std::filesystem::path locationRoot() const;

// Input data paths
std::filesystem::path locationGisDir() const;
std::filesystem::path locationWeatherDir() const;
std::filesystem::path locationScenariosDir() const;
std::filesystem::path locationPreprocessingDir() const;

// Simulation paths (type-aware)
std::filesystem::path locationSimulationsDir() const;
std::filesystem::path currentRunDir() const;
std::filesystem::path databaseDir() const;

// Ensemble-specific paths
std::filesystem::path ensembleDir() const;
std::filesystem::path ensembleMemberDir(const std::string& memberId) const;

// Run type
RunType runType() const;
bool isEnsembleMode() const;

{
  "buildingId": "building_001",
  "outputs": {
    "FinalEnergy": { "val": 125.4, "unit": "MJ" },
    "UsefullEnergy": { "val": 112.8, "unit": "MJ" },
    "IndoorTemperature": { "mean": 20.5, "std": 1.2, "unit": "degC" }
  }
}

{
  "run_id": "run_2025-01-15_14-30-00",
  "location": "kernante",
  "run_type": "Single",
  "world_size": 1,
  "start_time": 0.0,
  "stop_time": 86400.0,
  "step_time": 3600.0,
  "backend": "json",
  "artifact_base": "cemdb/locations/kernante/simulations/single/run_2025-01-15_14-30-00",
  "artifacts": [
    { "dataset": "global_kpi_summary", "path": "database/stats/global_kpi_summary.parquet" },
    { "dataset": "report", "path": "database/report/report.json" }
  ],
  "setup_summary": {
    "buildings_total": 125,
    "buildings_simulated": 120,
    "buildings_skipped": 5,
    "solar_shading_enabled": true,
    "solar_shading_components": ["building", "terrain"],
    "ideal_flows_enabled": false,
    "outputs": {
      "hdf5": true,
      "csv": false,
      "visualization": true,
      "report": true,
      "building_reports": false
    }
  }
}

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "KUB Manifest v4",
  "type": "object",
  "required": ["schema_version", "run_id", "run_type", "artifact_base", "artifacts"],
  "properties": {
    "schema_version": {
      "type": "integer",
      "const": 4,
      "description": "Schema version identifier"
    },
    "run_id": {
      "type": "string",
      "description": "Unique run identifier (e.g., run_2025-01-15_14-30-00)"
    },
    "run_type": {
      "type": "string",
      "enum": ["Single", "Ensemble"],
      "description": "Simulation run type"
    },
    "location": {
      "type": "string",
      "description": "Geographic location identifier"
    },
    "world_size": {
      "type": "integer",
      "minimum": 1,
      "description": "Number of MPI processes used"
    },
    "start_time": {
      "type": "number",
      "description": "Simulation start time (seconds)"
    },
    "stop_time": {
      "type": "number",
      "description": "Simulation stop time (seconds)"
    },
    "step_time": {
      "type": "number",
      "description": "Simulation time step (seconds)"
    },
    "backend": {
      "type": "string",
      "enum": ["json", "parquet"],
      "description": "Output backend type"
    },
    "artifact_base": {
      "type": "string",
      "description": "Base path for resolving relative artifact paths"
    },
    "repository_root": {
      "type": "string",
      "description": "Repository root path (for run-root manifests)"
    },
    "artifacts": {
      "type": "array",
      "items": { "$ref": "#/$defs/artifact" },
      "description": "List of output artifacts"
    },
    "setup_summary": {
      "$ref": "#/$defs/setup_summary",
      "description": "Simulation configuration summary"
    },
    "provenance": {
      "$ref": "#/$defs/provenance",
      "description": "Software version and build info"
    },
    "samples": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Ensemble sample identifiers (ensemble runs only)"
    }
  },
  "$defs": {
    "artifact": {
      "type": "object",
      "required": ["dataset", "path"],
      "properties": {
        "dataset": {
          "type": "string",
          "description": "Dataset identifier"
        },
        "path": {
          "type": "string",
          "description": "Relative path from artifact_base"
        },
        "type": {
          "type": "string",
          "enum": ["shared", "partitioned", "resource", "composite"],
          "description": "Artifact type for MPI-parallel outputs"
        },
        "schema_id": {
          "type": "string",
          "description": "Schema identifier (e.g., kub.global_kpi_summary)"
        },
        "schema_version": {
          "type": "string",
          "description": "Schema version (e.g., 1.0)"
        },
        "sha256": {
          "type": "string",
          "description": "SHA-256 hash of file content"
        },
        "files": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "path": { "type": "string" },
              "rank": { "type": "integer" },
              "sha256": { "type": "string" }
            }
          },
          "description": "Individual files for composite artifacts"
        }
      }
    },
    "setup_summary": {
      "type": "object",
      "properties": {
        "buildings_total": { "type": "integer" },
        "buildings_simulated": { "type": "integer" },
        "buildings_skipped": { "type": "integer" },
        "solar_shading_enabled": { "type": "boolean" },
        "solar_shading_components": {
          "type": "array",
          "items": { "type": "string" }
        },
        "ideal_flows_enabled": { "type": "boolean" },
        "outputs": {
          "type": "object",
          "properties": {
            "hdf5": { "type": "boolean" },
            "csv": { "type": "boolean" },
            "visualization": { "type": "boolean" },
            "report": { "type": "boolean" },
            "building_reports": { "type": "boolean" }
          }
        }
      }
    },
    "provenance": {
      "type": "object",
      "properties": {
        "schema_version": { "type": "integer" },
        "run_id": { "type": "string" },
        "run_type": { "type": "string" },
        "software": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "cem_version": { "type": "string" },
            "feelpp_version": { "type": "string" }
          }
        },
        "git": {
          "type": "object",
          "properties": {
            "commit": { "type": "string" },
            "branch": { "type": "string" },
            "dirty": { "type": "boolean" }
          }
        },
        "timestamp_utc": { "type": "string" },
        "hostname": { "type": "string" }
      }
    }
  }
}

{
  "window": {
    "mode": "full",
    "start_time": 0.0,
    "end_time": 86400.0
  },
  "levels": ["city", "district"],
  "kpis": ["FinalEnergy", "IndoorTemperature", "HeatingPower"],
  "building_level": true,
  "unit_validation_mode": "warn"
}

window:
  mode: full
  start_time: 0.0
  end_time: 86400.0
levels:
  - city
  - district
kpis:
  - FinalEnergy
  - IndoorTemperature
  - HeatingPower
building_level: true
unit_validation_mode: warn

{
  "kpis": [
    {
      "id": "FinalEnergy",
      "unit": "kWh",
      "reducer": "sum",
      "aggregations": ["mean", "sum", "min", "max"]
    },
    {
      "id": "IndoorTemperature",
      "unit": "degC",
      "reducer": "weighted_mean",
      "aggregations": ["mean", "std", "min", "max"]
    },
    {
      "id": "HeatingPower",
      "unit": "W",
      "reducer": "weighted_mean",
      "parameters": {
        "integration_method": "trapezoidal"
      },
      "aggregations": ["mean", "peak", "integrated"]
    }
  ]
}

simulations/
`-- run_<timestamp>/
    |-- database/
    `-- ensemble/

simulations/
|-- single/
|   `-- run_<timestamp>/
|       `-- database/
`-- ensemble/
    `-- run_<timestamp>/
        |-- member_<N>/database/
        `-- ensemble/

import shutil
from pathlib import Path

cemdb_root = Path("/path/to/cemdb")
location = "kernante"
simulations = cemdb_root / "locations" / location / "simulations"

(simulations / "single").mkdir(exist_ok=True)
(simulations / "ensemble").mkdir(exist_ok=True)

for run_dir in simulations.glob("run_*"):
    if (run_dir / "database").exists():
        has_ensemble = (run_dir / "ensemble").exists()
        has_members = any(run_dir.glob("member_*") )

        if has_ensemble or has_members:
            target = simulations / "ensemble" / run_dir.name
            shutil.move(str(run_dir), str(target))
        else:
            target = simulations / "single" / run_dir.name
            shutil.move(str(run_dir), str(target))

PathManager::instance().initialize(
    "/data/cemdb",
    "kernante",
    "run_2025-01-15_14-30-00",
    std::nullopt,
    RunType::Single
);

auto model = cityEnergyModel();
auto instance = model->newInstance(startTime, stopTime, stepTime);
instance->execute();

// Results saved to:
// /data/cemdb/locations/kernante/simulations/single/run_2025-01-15_14-30-00/database/

PathManager::instance().initialize(
    "/data/cemdb",
    "kernante",
    "run_2025-01-15_15-00-00",
    std::nullopt,
    RunType::Ensemble
);

auto model = cityEnergyModel();
EnsemblePlan plan = loadEnsemblePlan("uncertainty.json");
auto stats = model->executeEnsemble(plan, startTime, stopTime, stepTime);

// Results saved to:
// /data/cemdb/locations/kernante/simulations/ensemble/run_2025-01-15_15-00-00/
//    |-- member_000/database/
//    |-- member_001/database/
//    `-- ensemble/

from feelpp.ktirio.ub import core as ktirio_core
from pathlib import Path
import json

pm = ktirio_core.PathManager.instance()
pm.initialize(
    customRoot="/data/cemdb",
    locationName="kernante",
    runId="run_2025-01-15_15-00-00",
    runType=ktirio_core.RunType.Ensemble
)

ensemble_dir = Path(pm.ensembleDir())
statistics_file = ensemble_dir / "statistics.json"

with open(statistics_file) as f:
    stats = json.load(f)

print(f"Mean FinalEnergy: {stats['outputs']['FinalEnergy']['mean']} MJ")
print(f"95% CI: [{stats['outputs']['FinalEnergy']['ci_lower']}, "
      f"{stats['outputs']['FinalEnergy']['ci_upper']}]")