Defining a basic simulation

The first step before running a simulation is defining it. For annular, this is done as a collection of configuration and data files. Here, we will introduce everything necessary for a basic simulation that you can expand or change to suit your needs. You can download this sample project as a zip file, which contains the following folders and files:

energy-system-simulation/
├── simulation-configuration.ymmsl  (1)
├── generators/                     (2)
│   └── G01.yaml
├── satellite-configurations/       (3)
│   ├── battery-flexible.yaml
│   └── cronian-configurations/     (4)
│       └── P01.yaml
└── csv_files/
    ├── availability_factors.csv
    ├── battery-flexible-demand.csv
    └── ...

For each of the numbered files/folders, the corresponding section below will give some explanation and an example of the relevant files. This folder structure might seem excessive for a small example, but if you stick to it for your own simulations, it will help keep your files organized. The most important aspect of this structure is that the complete collection of files in the top-level folder can be a self-contained configuration. The simulation run will work no matter where on your filesystem you move the folder to, as long as the relative references between files stay intact.

Paths must be relative

For the sake of consistency and ease of referring to configurations from anywhere, whenever a path is defined in a configuration file, it is treated as relative to the configuration file it’s defined in. This means that as long as all files related to a simulation are located together in a single folder, the referred files will always be found regardless of where the simulation is started from. This also means you can easily move all files related to a simulation around, without having to adjust any path references to other files.

1. Annular configuration file

The base configuration of an annular simulation is given in the simulation_configuration.ymmsl file. This file serves two main functions:

  1. defining a few fixed parameters for the coupled simulation

  2. defining any number of global settings that will be accessible to all satellite models unless specifically overwritten.

simulation-configuration.ymmsl
ymmsl_version: v0.1

settings:
  # Simulation configuration settings
  config_name: test_configuration
  generator_configs: generators
  timeseries_data_path: csv-files/availability-factors.csv
  satellite_configs: satellite-configurations

  # Global settings
  ceiling_price: 4000
  start_hour: 0
  num_hours: 72
  rolling_horizon_step: 24

The following configuration settings are expected:

  • generator_configs: Folder containing cronian configurations for the generators to be included in the central market model. Note: only ‘Generators’ get loaded from this folder.

  • timeseries_data_path: Path to a CSV file containing the hourly availability timeseries for the generators.

  • satellite_configs: Folder containing configuration files defining the bidding strategies for the satellite models.

These keys are needed to set up the coupled simulation, and will not be made available to satellite models. All remaining keys will be passed through to all satellite models in the simulation. Of these keys, the following four are required:

  • ceiling_price: The market-wide ceiling price for bids. Bids at this price are guaranteed to be satisfied.

  • start_hour: Integer offset of where to start in the previously specified timeseries_data.

  • num_hours: Length of the simulation in number of hours.

  • rolling_horizon_step: Length of the rolling horizon step, i.e., number of hours for which bids are exchanged at every simulation iteration. Currently, only 24 is supported.

The start_hour and num_hours keys can be used to run smaller simulations from a larger data file. For example, if the timeseries_data_path contains data on years 2009-2015, a simulation can be run only for the year 2011 by specifying:

start_hour: 17520  # skip 2 * 8760 hours
num_hours: 8760

2. Cronian generator configuration files

This folder should contain any number of cronian configuration files that specify the known supply side of the energy market. Generators defined here are modelled directly into the market clearing optimization problem.

The example contains a single generator of offshore wind power with a linear cost:

G01.yaml
Generators:
  name: Offshore Wind
  id: G01
  marginal_cost_linear: 5
  marginal_cost_quadratic: 0
  installed_capacity: 40000
  availability_factor: offshore

3. Satellite definitions & resources

This folder contains the files defining the satellite models. Each satellite model will in turn be run in an independent process during the coupled simulation, that behaves according to the bidding strategy defined in it.

These configuration files have only one mandatory key from annular’s point of view: strategy. This has to be a name that matches one of the available bidding strategies. The remaining values in the file will be processed by the selected strategy, so see its documentation for more information.

In this example we use a Multi-Profile Bidding Strategy, that models some demand that can be flexibly satisfied through the use of a battery:

battery-flexible.yaml
strategy: multi_profile
floor_price: 0
cronian_config_path: ../cronian-configurations/P01.yaml
demands_path: ../csv-files/demand-timeseries.csv
forecasts_path: ../csv-files/forecast-prices.csv
carrier_prices_path: ../csv-files/other-carriers-prices.csv

Note that for the CSV files, we are referring to ../csv-files/. This is because that folder is a ‘sibling’ folder of the satellite-configurations/ folder in which this battery-flexible.yml file is located.

You can find further information on how to configure the Multi-Profile Bidding Strategy on its dedicated documentation page.

4. Nested files for satellite models

A bidding strategy such as the Multi-Profile Bidding Strategy example above commonly depends on some further data or configuration. To keep those neatly organized, we recommend storing that information in a dedicated folder inside your satellite-configurations/ folder. In this case, we store the cronian configuration in a cronian-configurations/ subfolder for it and any potential other cronian configuration files for other satellites.

P01.yaml
Prosumers:
  name: battery flexibility
  id: P01
  demand:
    electric:
      carrier: electricity
      base:
        peak: 1
        n_profile: flexible demand
  assets:
    Battery:
      behavior_type: storage
      input: electricity
      output: electricity
      energy_capacity: 100
      initial_energy: 0
      charge_capacity: 100
      discharge_capacity: 100
      charge_efficiency: 0.9
      discharge_efficiency: 0.9