Quickstart

1. Case Kernante

This section provides a step-by-step guide to running a basic simulation using the Ktirio Urban Building (KUB) application with the kernante dataset.

1.1. Prerequisites

  • Apptainer (or Singularity) installed and in your PATH.

  • MPI (e.g. mpich or openmpi) available, although you can run the process in parallel inside the container if you do not have MPI installed.

  • The KUB container name (e.g. kub.sif) will be pulled automatically.

  • Internet access (or local mirror) for CKAN/Girder downloads.

openmpi is recommended for parallel execution, but you can run the process in parallel inside the container if you do not have MPI installed.

1.2. Fetch Input Data

Download the required kernante input data from CKAN:

$ wget https://ckan.hidalgo2.eu/dataset/a7f354a6-620f-42dc-bda4-7fc945746e57/resource/d0978965-f708-4ee3-bfac-e1c7c99e232c/download/kernante_input.zip

Unzip the archive into your working directory:

$ unzip kernante_input.zip

1.3. Create Output Directory

Create a directory on the root of your current directory called kub_outputs:

$ mkdir ./kub_outputs

1.4. Download the KUB Container

Pull the latest KUB Apptainer image (tagged master-sif) from GitHub Container Registry:

$ apptainer pull -F kub.sif oras://ghcr.io/feelpp/ktirio-urban-building:master-sif

1.5. Configure the Simulation

Edit the configuration file kernante_input/kernante.cfg to adjust simulation parameters such as the simulation time frame or output folder. Ensure all file paths are correct and accessible from inside the container.

1.6. Run the Simulation

Set the Apptainer home directory to the output folder:

$ export APPTAINER_HOME=$PWD/kub_outputs/

Execute the simulation using 4 MPI processes, mounting the kernante_input folder into the container:

$ mpiexec -n 4 --bind-to core \
    apptainer exec -B ./kernante_input/:/kernante_input/ \
    --env OMP_NUM_THREADS=1 \
    kub.sif \
    feelpp_kub_cem \
    --config-files /kernante_input/IdealHeaters.cfg /kernante_input/kernante.cfg

If running on the Gaya cluster, also mount the /opt/ directory:

--bind /opt/:/opt/

1.7. Visualize the Results

After the simulation completes, the results are stored under:

./kub_outputs/feelppdb/kernante_output/instances/np_4/lod0/exports/

Use ParaView to open the Ensight Gold cases file

$ paraview kub_outputs/feelppdb/kernante_output/instances/np_4/lod0/exports/City_Energy_Modeling.case