THERMOS Job Server

Input schema

buildings

Each row is a building, or demand that can be connected to a heat network. Buildings which are forbidden (by 'constraint') are not validated, because they cannot be in a solution.

Field	Type	Description
`geometry`	anything but null	A point or polygon for the building
`building_id`	nullable string	Used to identify this building in other outputs.
`annual_demand_kwh`	double greater than or equal to 0.0	The annual heat demand for the building; drives revenues from tariffs.
`peak_demand_kw`	double greater than or equal to 0.0	The peak heat demand for the building; drives connection costs. Assumed to already incorporate any load diversity within the building.
`connections`	integer greater than or equal to 1	The number of end users in the building; for example a block of flats might have multiple connections in it.
`constraint`	keyword, and enum of :required, :optional, :forbidden	How the solution is constrained for this element. If required, it must be in the network. If optional, it may or may not. Otherwise it may not be used
`demand_group`	anything	Any buildings which have the same demand group will either all be connected at once or not at all.
`connection_cost_id`	integer	Refers to the connection costs table
`tariff_id`	integer	Refers to the tariffs table
`extra_pv`	nullable double	An additional PV for connecting this building (or if negative, cost)

paths

Each row is a path where a heat network pipe can be laid.

Field	Type	Description
`geometry`	anything but null	The line-string geometry for this path
`path_id`	nullable string	Used to identify this path in other outputs. Paths may be split into parts, in which case a new ID will be generated.
`constraint`	keyword, and enum of :required, :optional, :forbidden	How the solution is constrained for this element. If required, it must be in the network. If optional, it may or may not. Otherwise it may not be used
`existing_diameter`	nullable double greater than or equal to 10.0	If a pipe is already here, the diameter of that pipe (in mm). When there is an existing pipe, the network will pay only REPEX for it unless a larger pipe is needed. If a larger pipe is needed, the cost is as for a new pipe.
`civil_cost_id`	nullable integer	Refers to the civil costs table. Determines the cost of putting a pipe here
`extra_pv`	nullable double	An additional PV for using this path (or if negative, cost)

supply_costs

Additional complex supply costs table. Each supply may have a number of additional cost components added through this table. They are added together, and are applied additionally to the simple costs present in the supply table.

Field	Type	Description
`supply_cost_type`	string	An identifier to group related supply cost rows. Can be referred to from supply table.
`type`	string	A user-defined name for the cost (e.g. plant, energy_centre, ...)
`cost`	keyword, and enum of :capex_per_kw, :capex_fixed, :opex_per_kw, :opex_fixed, :repex_per_kw, :repex_fixed, :heat_per_kwh	What kind of cost this is
`value`	A ¤/kW curve. Each entry is a point on the curve, as (kW capacity, ¤ cost). If the curve is too short, it continues flat. Can be used for any _per_kw type, or A timeseries; entry N is the cost in year N. Can be used for heat_per_kwh type., or A constant value. Can be used for any type; for _per_kw or _per_kwh implies a series of enough length.	The cost itself; can be a curve expressed as json, or a constant value.

tariffs

Tariffs produce income for the network; they determine the value of connecting a building.

Field	Type	Description
`tariff_id`	integer	Used to refer to the tariff in other tables
`name`	string	A friendly name for the tariff
`annual_charge_fixed`	double greater than or equal to 0.0	Customers on this tariff pay this fixed cost every year from year 1
`annual_charge_per_kwh`	double greater than or equal to 0.0	Customers on this tarriff pay this per unit heat delivered from year 1
`annual_charge_per_kw`	double greater than or equal to 0.0	Customers on this tariff pay this per kW peak demand from year 1
`connection_charge_fixed`	double greater than or equal to 0.0	Customers on this tariff pay this fixed cost up-front in year 0
`connection_charge_per_kw`	double greater than or equal to 0.0	Customers on this tariff pay this fixed cost per kW peak demand up-front in year 0

connection_costs

Connection costs are costs to the network (distinct from connection charges, seen in the tariff structure). They represent works in the building to connect it to a network, e.g. HIU installation.

Field	Type	Description
`connection_cost_id`	anything	Used to refer to the connection cost in other tables
`name`	string	A friendly name for the connection cost
`capex_fixed`	double greater than or equal to 0.0	The fixed up-front part of this connection cost
`capex_per_connection`	double greater than or equal to 0.0	An up-front cost paid per connection within the building (see the buildings table column 'connections')
`capex_per_kw`	double greater than or equal to 0.0	An up-front cost paid per unit capacity
`repex_fixed`	double greater than or equal to 0.0	The fixed repex for this connection cost; lifetime is set by the parameters
`repex_per_connection`	double greater than or equal to 0.0	The repex per connection within the building (see buildings -> connections).
`repex_per_kw`	double greater than or equal to 0.0	The repex per unit capacity
`opex_fixed`	double greater than or equal to 0.0	The annual fixed opex paid for this connection cost
`opex_per_connection`	double greater than or equal to 0.0	The annual opex per connection within the building (see buildings -> connections)
`opex_per_kw`	double greater than or equal to 0.0	The annual opex per kW capacity needed

supplies

Each row is a point where the heat network can be supplied with heat.

Field	Type	Description
`geometry`	anything but null	A point or polygon where the supply is
`supply_id`	nullable string	Used to identify this supply in other outputs
`constraint`	keyword, and enum of :required, :optional, :forbidden	How the solution is constrained for this element. If required, it must be in the network. If optional, it may or may not. Otherwise it may not be used
`annual_capacity_kwh`	double greater than or equal to 0.0	The maximum kWh our this supply can yield
`peak_capacity_kw`	double greater than or equal to 0.0	The maximum output this supply can yield
`capex_fixed`	double greater than or equal to 0.0	The fixed upfront cost
`capex_per_kw`	double greater than or equal to 0.0	The upfront cost per unit capacity
`opex_fixed`	double greater than or equal to 0.0	The annual fixed opex
`opex_per_kw`	double greater than or equal to 0.0	The annual opex per unit capacity
`repex_fixed`	double greater than or equal to 0.0	The fixed repex - lifetime is set by parameters
`repex_per_kw`	double greater than or equal to 0.0	The capacity related repex - lifetime is set by parameters
`cost_per_kwh`	double greater than or equal to 0.0	The cost per unit heat produced
`emissions_per_kwh`	nullable double greater than or equal to 0.0	The emissions factor for kgCO2 equivalent per kWh heat output.
`supply_cost_type`	nullable string	Optionally a reference to supply_cost_type in supply_costs

parameters

Parameters are global settings that control the optimiser. See parameter specific help for more info.

Field	Type	Description
`parameter`	keyword, and enum of :finance/npv-rate, :finance/npv-term, :finance/plant-lifetime, :finance/distribution-lifetime, :finance/building-hx-lifetime, :optimiser/runtime-limit, :optimiser/mip-gap, :optimiser/param-gap, :optimiser/iteration-limit, :optimiser/flow-temperature, :optimiser/return-temperature, :optimiser/ground-temperature, :network/diversity-limit, :network/diversity-rate, :optimiser/objective, :optimiser/prevent-loops, :constraint/min-linear-density, :constraint/max-linear-density, :constraint/min-kwh, :constraint/max-kwh, :constraint/min-network-length, :constraint/max-network-length, :constraint/min-npv, :constraint/max-npv, :constraint/max-emissions-factor, :constraint/min-buildings, :constraint/max-buildings, :constraint/min-connections, :constraint/max-connections, :constraint/max-supplies, :objective/use-connection-capex, :objective/use-connection-repex, :objective/use-connection-opex, :objective/use-supply-capex, :objective/use-supply-repex, :objective/use-supply-opex, :objective/use-pipe-capex, :objective/use-pipe-repex, :objective/use-tariffs	The name of a parameter
`value`	nullable string	The value of the parameter. A blank string is equivalent to a NULL. Some parameters are allowed to be NULL; see the parameter specific help for more info.

civil_costs

Describes the cost per meter of flow and return pipe and trenching according to different dig conditions.

Field	Type	Description
`diameter_mm`	double greater than or equal to 10.0	The diameter of flow / return pipe in mm
`civil_cost_id`	integer	The civil cost ID; this says what kind of surface is being dug up (see civil_cost_names)
`cost_m`	double greater than or equal to 0.0	The capex (and repex) of 1m of flow and return pipe of this diameter installed

civil_cost_names

Gives friendly names to the civil cost IDs used in civil_costs

Field	Type	Description
`civil_cost_id`	integer	The identifier used in civil_costs and in paths tables to refer to a civil cost
`name`	string	A friendly name (e.g. soft dig / hard dig)
`is_default`	nullable boolean	Whether this is the default civil cost. It will be used for paths with no civil cost set, and for connectors introduced by the model. Should be true for exactly one row.

Output schema

buildings

The buildings table will be updated with new columns.

Field	Type	Description
`building_id`	string	The input building_id, or a new building ID will be generated
`in_network`	boolean	True if the building got connected to a heat network.
`unreachable`	boolean	True if the building cannot be on a network because there is no path from any supply to it.
`connection_cost_pv`	double	The PV contribution of the connection cost for the building
`tariff_pv`	double	The PV contribution of tariff revenues for the building

supplies

Supply rows are updated with additional columns.

Field	Type	Description
`supply_id`	string	The supply ID from the input, or a newly generated ID if no ID in the input
`in_network`	boolean	True if the supply is used in the network
`diversity`	nullable double	The diversity factor applied to the total demand this supply is meeting
`load_kw`	nullable double	The peak output from the supply (after diversity, kW)
`load_kwh`	nullable double	The annual output from the supply (including losses, kWh/yr)
`plant_pv`	nullable double	The total PV contribution from the supply

paths

The paths table will be updated with new rows and new columns. New rows are created for connectors or when an input path is split into pieces.

Field	Type	Description
`geometry`	anything	The geometry of the path
`path_id`	string	The ID for the path. If it is the entirety of an input path, this will be the path_id of the input path (which will be generated if absent). If the input has been split into parts, they will have their original ID with a suffix -1 -2 etc. If the path is a connector an ID like C-1, C-2 will be generated.
`in_network`	boolean	True if the path is used in the heat network.
`connector`	boolean	True if the path was a connector generated by the model.
`diameter_mm`	nullable double	The diameter of installed pipe.
`diversity`	nullable double	The diversity applied to the loads down the pipe.
`load_kw`	nullable double	The peak power the pipe carries (kW)
`capacity_kw`	nullable double	The maximum power the pipe could carry (kW)
`losses_kwh`	nullable double	The annual heat loss from the pipe (kWh/yr)
`cost_pv`	nullable double	The PV contribution of the pipe
`peripheral`	boolean	If true, the path doesn't go to any demands, so would never be in a network.
`unreachable`	boolean	If true, the path is not connected to any supply, and so cannot be in a network.

cashflow

The cashflow table is added to the output and contains details of the cost model.

Field	Type	Description
`year`	integer	The year in which the cost happens, starting from 0. Costs in year 0 are not discounted, costs in year 1 are discounted once, and so on.
`value`	double	The nominal value in that year (without discounting)
`cost`	nullable string	What kind of cost is this (capex, opex, etc)
`type`	nullable string	What part of the system is this cost for (a pipe, a building etc)
`connection_cost_id`	nullable integer	Refers to connection_cost_id in the connection_costs table
`tariff_id`	nullable integer	Refers to tariff_id in the tariffs table
`civil_cost_id`	nullable integer	Refers to civil_cost_id in the civil_costs table
`building_id`	nullable string	Refers to building_id in the buildings table
`supply_id`	nullable string	Refers to supply_id in the supplies table
`path_id`	nullable string	Refers to path_id in the paths table

solution_summary

A single-row giving some high-level information about the optimisation and the solution

Field	Type	Description
`state`	string	Whether the solution is optimal, non-optimal, proven infeasible, etc.
`objective`	double	The objective value.
`mip_gap`	double	The MIP gap of the solution.
`runtime`	double	The runtime of the optimisation in seconds.
`iterations`	integer	The number of iterations of the optimisation loop
`lower_bound`	double	The lower bound on the objective
`upper_bound`	double	The upper bound on the objective
`network_building_count`	integer	How many buildings were connected to a network.
`network_connection_count`	integer	How many customers were connected to a network (some buildings may have multiple connections).
`network_length`	double	The length of the network, in meters
`network_linear_density`	double	The useful heat delivered by the network divided by its length, in kWh/m
`network_kwh`	double	The useful heat delivered by the network, in kWh/yr
`network_losses_kwh`	double	The heat losses from the network, in kWh/yr
`network_npv`	double	The total NPV of all the network components; this does not reflect the parameters controlling which types of cost are included in the objective.
`git_rev`	string	The model version used to generate this result
`user`	string	The user who ran the model
`run`	string	The name for the run
`start_date`	string	When the run started

infeasible_reasons

If present, possible explanations for why the problem is infeasible

Field	Type	Description
`reason_type`	string	A short string categorising the explanation
`message`	string	An explanatory message that may be the cause of infeasibility