Running a Simulation

The model requires configuration files (Model Input - Configuration Files) and data files (Model Input - Data Files) to run. In a dedicated project directory (e.g., project_dir), create the following folder structure:

project_dir/
├── config/
│   └── config_files/
│       └── ...
└── data/
    └── ...

Place the configuration files in the config/config_files directory. A set of configuration files is provided on GitHub, from where they can be downloaded.

Place the data files in the data directory. Data files for Switzerland are provided on Zenodo. The data package already has the correct directory structure and can be placed in the data directory (unzipping required). Make sure that the version of the Zenodo data package matches the DEM version you are using. For regions other than Switzerland, data must be created according to the format described in Model Input - Data Files.

DEM can be run three different ways:

  • Using the command-line interface: for running simulations without writing any Python code.

  • Interactively in a Python environment: by importing the district_energy_model package in a script or notebook.

  • Directly from the source code: by executing the provided Python modules within the project repository.

Run from command-line tool

Step 1: Activate the Conda Environment

Open the command-line tool and activate the DEM Conda environment (exact name depends on installed version):

conda activate dem_0_1_0_rc0

Step 2: Configure the Simulation

If not already done, adapt the configuration files as described in Model Input - Configuration Files and place them in the config/config_files directory.

Step 3: Run the Simulation

Run DEM from the command line with the following command:

district_energy_model --project_dir=/path/to/project

Specifying a project directory using --project_dir is optional. If not provided, DEM uses the current working directory. The project_dir should contain both data/ and config/config_files directories. Simulation results will be stored inside the selected project directory. DEM will automatically create a directory named dem_output containing output files.

Run programmatically in Python

DEM can also be launched directly from a Python script, which allows the model to be integrated into larger Python workflows or other projects. A minimal example looks as follows:

import district_energy_model as dem

my_model = dem.model.launch()

In this example, the district_energy_model module is first imported. The second line creates and runs a model instance using the default configuration. By default, the data and config directories are expected to reside in the same root directory as the Python script. If they are stored elsewhere, the directory can be specified via the root_dir=... argument in the launch() method. The model configuration is read from the YAML configuration files unless otherwise specified.

Once launched, results can be retrieved from the model instance (my_model):

res_hourly = my_model.hourly_results()
res_annual = my_model.annual_results()
res_cost = my_model.total_cost()

The content of the output is described under Model Output.

  • hourly_results() returns a DataFrame with hourly time series of energy and resource flows.

  • annual_results() returns a dict containing annual aggregated values.

  • total_cost() returns a dict containing cost information (currently only available for optimisation runs), including monetary costs and emissions.

Instead of using YAML configuration files, input can also be supplied directly to the launch() method via a Python dictionary. This is useful when configuration values depend on preceding computations or when parameter studies are generated programmatically.

The following example shows how to run DEM with configuration input passed directly in Python:

import district_energy_model as dem

# Adjust input configuration:
config_dict = {
    'simulation':{
            'number_of_days':365,
            'district_number':2762,
            },
    'scenarios':{
            'demand_side':True,
            'pv_integration':True,
            },
    'heat_pump':{
            'deployment':True,
            },
    'district_heating':{
            'deployment':True,
            },
    'solar_pv':{
            'potential_integration_factor':0.7,
            },
    }

# Create and run model:
my_model = dem.model.launch(
    root_dir = './',
    config_files = False,
    config_dict = config_dict
    )

# Retrieve results:
res_hourly = my_model.hourly_results()
res_annual = my_model.annual_results()
res_cost = my_model.total_cost()

Here, configuration input is passed directly to launch() via config_dict. All values provided in config_dict override the corresponding default configuration. With the exception of technology parameters, the structure of config_dict matches the structure of the YAML configuration files (see Model Input - Configuration Files). The name of the respective configuration file serves as the top-level dictionary key. For technologies, the technology names themselves are used as top-level keys.

When configuration is supplied programmatically, the argument config_files must be set to False (the default is True). The root_dir argument specifies the directory containing the data folder with all required input files (see Model Input - Data Files).

Run from source code

You can run the District Energy Model directly from the Python source code available on GitHub. Python and the required packages must be installed beforehand.

Step 1: Clone the Repository

Clone the GitHub repository to a local directory:

git clone https://github.com/HSLUDEM/District_Energy_Model.git

Keep the directory structure exactly as cloned. See Directory Structure for details.

Step 2: Create and Activate the Conda Environment

(See Step 1 in Installation)

Step 3: Prepare Data Files

Place the required input data in the directories described above and in Model Input - Data Files.

Step 3: Configuation Files

Create configuration files as described in Model Input - Configuration Files and place them in the config/config_files directory.

Step 4: Run the Simulation

Execute the Python script src/run_dem_local.py either:

  • from an IDE (e.g., Spyder, Visual Studio Code), or

  • from a terminal window.

Step 5: Retrieve Results

Simulation results are saved automatically to the root directory. DEM will automatically create a directory named dem_output containing output files. See Model Output for details on output files and structure.