User guide¶

Introduction¶

Siteopt can represent detailed interactions between buildings, local energy production, storage, and the wider grid, allowing planners to explore how different technologies and operating strategies perform over time. By capturing temporal variability such as hourly demand, weather‑driven renewable output, and dynamic electricity prices, Siteopt helps identify cost‑efficient, low‑carbon solutions for heating, cooling, and electricity supply. Its modular structure also makes it easy to test future scenarios, compare investment options for sustainable district‑level energy planning.

Standard workflow¶

The standard workflow for Siteopt usage can be outlined as follows:

• Visualizing the model topology and needed entities in one's own mind or paper
• Preparing the input data in form of excel files and CSV files
• Moving the input files to the current_input folder of a Siteopt installation
• Starting Spine Toolbox and building the model database
• Optionally selecting representative time periods
• Running optimization
• Compiling result summary
• Analyzing results

Visualizing the model topology and needed entities¶

It is important to understand the way energy systems are abstracted in Siteopt. Abstraction can be a bit daunting at first but it allows the Siteopt to model a wider variety of systems instead of limiting to a very restricted set of components. The key idea in the abstraction is that Siteopt uses only a few simple basic components but parameters are used to modify them so that they can resemble various real life components. Let us now see what these basic components are and what they can be used for. Let us use the following simple example system for this.

In the example you can see different Siteopt components. They have been described in the table below.

Table 1: Siteopt components.

Component	Example icon	Description
Node		Node is a place where energy flows meet and demand can take place. This can for example be a consumer point, point of exchange with another subsystem. Often used interchangeably with "block". Indeed, nodes define locations in the model.
Renewable unit		Renewable units produce either electricity or heat. The production is sent to a specified node.
Power-to-heat unit		Power-to-heat units produce either heat or cooling using electricity.
Connection		Connections allow energy transmission. They can be e.g. transmission lines or pipelines.
Storage		Storages allow energy storage. They can be storages for heat, electricity or cold.
Diverting unit		unit which produces side streams such as emissions.

Note that in the example system the power grid and loads are also nodes. This is precisely what we mean by using a restricted set of components to model many different real-world items. With these components it is possible to model quite a few different systems. The user should rely on these components when visualizing the model topology. In practise, the recommended steps are:

• Decide the energy vectors which are taken into account: electricity, heat or cooling
• Decide the spatial resolution of demand modelling. For example, does the model "block" refer to a single building, city block or wider area?
• Think about where the whole system is connected to external energy supply, if there is one.
• Think about the grid connections and their detail: is every block connected directly to the external energy supply, is the grid more complex?

Important concepts¶

Siteopt allows scenario analysis. However, scenarios are inputted in a smart way so that you only need to enter the parameters which change between scenarios. There's no need to repeat every parameter value for every scenario. The following picture shows how alternatives are used to help scenario analysis.

In the picture the scenario "My scenario" contains two alternatives in addition to the Base alternative. Alternative 2 has the highest priority, which makes it override all other values. However, it has only been defined for Parameter 1. Alternative 1 overrides the Base value of Parameter 2.

Preparing the input data¶

The input is mostly given as Microsoft Excel files. Timeseries files are given in comma separated value (CSV) format. The following input files are expected to lie in the current_input folder:

In addition there are two JSON files in the root folder : repr_settings_elexia.json and representative_periods_template.json. The user is normally not expected to touch these.

Not all of the files are expected to containt data. In that case just leave the header row (first row) in the file. In addition to the above mentioned files, the user can also add additional timeseries as CSV files. They can be referenced from the Excel files as explained below.

In the following we will go through each of the files and show how to fill them.

The nodes table¶

In nodes.xlsx each row represents one node. However, you can give several alternative parameter values for a node, and in this case each alternative makes one row. Also, you have to define the different grids for each node. For example if cooling demand exists in a node, you have to add a row where grid is "cool".

Node names should be unique. However, you can use the same name in different grids. Normally the incoming flows to node must match the outgoing flows and possible demand. However, if one declares balance_type_none then no such condition is enforced.

If you wish to define values (e.g. demand) for different alternatives, add a separate row for each node and alternative. Notice that demand time series can also be inputted as shown in the next section.

Demand data¶

Demand data for three grids (electricity, heating and cooling) can be given in cross-tabulated CSV files. These are:

• tscr_cooldemand.csv for cooling demand timeseries
• tscr_elecdemand.csv for electricity demand timeseries
• tscr_heatdemand.csv for heat demand timeseries

The format of these files is the following:

It is probably obvious to the user that these files are not meant to be populated manually but using spreadsheet software or other software for processing time series data. Note that you don't need to input demand data via these files. You can also specify timeseries in the nodes input table. In that case you need a separate file for each node and grid.

Production units table¶

In pv_units.xlsx the user defines renewable generation units such as PV units and wind turbines or solar collectors.

There are also data related to the supply chain carbon dioxide emissions of the production units:

If you wish to define parameter values for different alternatives, add a separate row for each unit and alternative.

Heat pumps and chiller units table¶

In hp_units.xlsx the user defines heat pumps and chillers. Unlike renewable generation units (defined in pv_units.xlsx) these technologies require electricity to operate.

Group potentials table¶

Normally, investments into different VRE units are independent. However, if for example they share the same area, potentials for certain groups of units can be defined. In group_potential.xlsx the user defines aggregated renewable unit investment potentials for PV units and wind turbines or solar collectors.

For example, if you wish to create an aggregated investment constraint which pertains to two different units, add two lines to this file. Input the unit blocks, grids and names as in pv_input.xslx. Think of a descriptive and unique name for this constraint and put it into the groupcolumn on both lines. On one (not both) of the lines in candidate_units columns, write the maximum number of subunits which can be invested.

Connections table¶

In Siteopt and SpineOpt connections are entities which can transfer energy and material from one node to another. These include power lines and pipelines. However, as Siteopt works in an abstract level, it does not require that you specify what type of real infrastructure the connection represents. Instead you enter parameters which determine how these connection behave.

In connections_input.xlsx each row represents one connection entity. The header row shows what is expected on each column. The columns are as follows:

Storages table¶

In storages-input.xlsx the user defines electricity, heat and cold storages.

The storage table is more complex than the other tables because the power conversion section (charger and discharger) is defined separately from the actual storage. Thus an investment cost is given both from the storage capacity and charger power. These are given for one subunit on an annual basis as usual. The maximum number of subunits is be given both for the storage section and charger section. Normally it is convenient to define one subunit as kW or MW for charger and kWh or MWh for the storage section but they may also be defined e.g. according to certain battery model if it is convenient for the user.

Diverting units table¶

At the time diverting units are mostly used for internal accounting purposes of the optimization model because the underlying SpineOpt model does not account for emissions. Nothing prevents their use by the user. The user should, however, tolerate the bit more complex notation used for these units.

Modelspec table¶

The modelspec.xlsx file contains five sheets but only two of them are normally needed by the user. params_1d_datetime contain the following data about the model time horizon:

In other words, here you adjust which parts of the given time series are used for optimization. params_1d_durations sheet contain data about the time resolution used by optimization. Normally it contains two rows. One of the rows determines the time resolution used in the day-to-day optimization of the system. The other defines how often investments can be made. Presently Siteopt supports only a single investment for each entity, so the time resolution for investments should be longer than the model horizon.

It is suggested that you keep the values as 1 hfor myblock but you may increase the value to several hours to speed up computation. For myinvestmentblock you can use e.g. 1 Y.

Scenarios table¶

The scenarios.xlsx file contains three sheets. The scenario sheet just lists the different scenario names in the first column (first row just is header row). Likewise the alternative sheet lists different alternatives in the first column, where the first row is header row. scenario_alternative sheet is more complex and has two kind of entries. On this sheet, the first column (A) is reserved for scenario names and two next columns (B-C) for alternative names. When two columns (A and B) are filled, this has the meaning that an alternative belongs to a scenario. When three columns (A, B and C) are filled, this has the meaning of defining the order of alternatives. In this case the alternative written in column C has higher precedence and alternative written in column B. If There are more than 2 alternatives in any scenario, more rows should be used to define the order of the alternatives.

The following picture shows an example.

Entering data¶

You will need different types of data for different parameter indices and values. The following datatypes can be entered in the input tables.

For datetimes such as time stamps the recommended format is ISO8601 (e.g. 2020-03-01T01:00). In case of timeseries, the actual timeseries data should be placed in a CSV file in the input data folder (same folder as the referencing Excel file). The file should have two columns which have column titles "time" and "value". File name should have the format ts_ + time series name + .csv. For example if you write ts:elec7 in the input data table, file name ts_elec7.csv is expected. Note that Siteopt does not make daylight saving time adjustments.

For durations the data should be entered in format xU where x is an integer and U is either Y (for year), M (for month), D (for day), h (for hour), m (for minute), or s (for second). For example "60m".

Using Siteopt via Spine Toolbox¶

You can use Siteopt in two ways: via Spine Toolbox or via web browser. Here the first method is explained.

Starting Siteopt¶

When using Siteopt via Spine Toolbox first start the toolbox. Run the commands

conda activate spinetb
spinetoolbox

Then inside Spine Toolbox:

• Open the project folder where you have downloaded Siteopt_toolbox: File -> Open project…
• Navigate to the folder where you have downloaded Siteopt_toolbox
• Press Ok
• If you get a notification to upgrade databases, just upgrade them

Building the database for optimization¶

The Siteopt inputs need to be translated to a format which is understood by the optimization model. This should be done each time you change the inputs (i.e. the Excel files described above or the time series CSV files).

• Close the input Excel files
• Observe the Design view window in the toolbox
• Using left mouse button held, select everything to the left of the pink ”Input data” box (see figure)
• In the top toolbox press Execute Selection
• Wait until all the hammer tools have a green check mark
• Red cross in tool icon means an error

Building the database can take several minutes.

Running representative periods selection¶

Representative periods are a way to simplify long‑term energy system studies without losing the big picture. Instead of simulating every hour of an entire year — which would be extremely heavy to compute — the year is broken into a small number of “typical” days that capture the main patterns in demand and renewable generation. Think of it like choosing a few key scenes from a movie that still let you understand the whole story. In Siteopt, you can either use representative periods or not. If you decide to use them,

Running optimization¶

Optimization of the model can be started by selecting the "Optimize" tool in Toolbox and clicking "Execute selection" in the toolbar.

Running the optimization can take anything from a few minutes to tens of minutes. Reducing the number of nodes and optimized units as well as increasing time resolution can reduce the running time.