Base math¶
Complete base mathematical formulation for a Calliope model. This math is always applied but can be overridden with pre-defined additional math or your own math.
A guide to math documentation¶
If a math component's initial conditions are met (the first if statement), it will be applied to a model.
For each objective, constraint and global expression, a number of sub-conditions then apply (the subsequent, indented if statements) to decide on the specific expression to apply at a given iteration of the component dimensions.
In the expressions, terms in bold font are decision variables and terms in italic font are parameters.
The decision variables and parameters are listed at the end of the page; they also refer back to the global expressions / constraints in which they are used.
Those parameters which are defined over time (timesteps) in the expressions can be defined by a user as a single, time invariant value, or as a timeseries that is loaded from file or dataframe.
Note
For every math component in the documentation, we include the YAML snippet that was used to generate the math in a separate tab.
Download the base math formulation as a YAML file
Objective¶
min_cost_optimisation (active)¶
Minimise the total cost of installing and operating all technologies in the system. If multiple cost classes are present (e.g., monetary and co2 emissions), the weighted sum of total costs is minimised. Cost class weights can be defined in the indexed parameter objective_cost_weights.
description: Minimise the total cost of installing and operating all
technologies in the system. If multiple cost classes are present (e.g.,
monetary and co2 emissions), the weighted sum of total costs is minimised.
Cost class weights can be defined in the indexed parameter
`objective_cost_weights`.
equations:
- expression: "sum(\n sum(cost, over=[nodes, techs])\n * objective_cost_weights,\n\
\ over=costs\n) + $unmet_demand"
sub_expressions:
unmet_demand:
- expression: "sum(\n sum(unmet_demand - unused_supply, over=[carriers, nodes])\n\
\ * timestep_weights,\n over=timesteps\n) * bigM"
sense: minimise
Subject to¶
area_use_capacity_per_loc¶
Set an upper bound on the total area that all technologies with area_use can occupy at a given node.
Uses
area_use_per_flow_capacity¶
Set a fixed relationship between a technology's flow capacity and its area use.
balance_conversion¶
Fix the relationship between a conversion technology's outflow and consumption.
Uses
balance_demand¶
Set the upper bound on, or a fixed total of, that a demand technology must dump to its sink in each timestep.
description: Set the upper bound on, or a fixed total of, that a demand
technology must dump to its sink in each timestep.
equations:
- where: sink_use_equals
expression: flow_in_inc_eff == sink_use_equals * $sink_scaler
- where: NOT sink_use_equals AND sink_use_max
expression: flow_in_inc_eff <= sink_use_max * $sink_scaler
sub_expressions:
sink_scaler:
- where: sink_unit==per_area
expression: area_use
- where: sink_unit==per_cap
expression: sum(flow_cap, over=carriers)
- where: sink_unit==absolute
expression: '1'
foreach:
- nodes
- techs
- carriers
- timesteps
where: base_tech==demand
balance_demand_min_use¶
Set the lower bound on the quantity of flow a demand technology must dump to its sink in each timestep.
description: Set the lower bound on the quantity of flow a `demand` technology
must dump to its sink in each timestep.
equations:
- expression: flow_in_inc_eff >= sink_use_min * $sink_scaler
sub_expressions:
sink_scaler:
- where: sink_unit==per_area
expression: area_use
- where: sink_unit==per_cap
expression: sum(flow_cap, over=carriers)
- where: sink_unit==absolute
expression: '1'
foreach:
- nodes
- techs
- carriers
- timesteps
where: sink_use_min AND NOT sink_use_equals AND base_tech==demand
balance_storage¶
Fix the quantity of carrier stored in a storage technology at the end of each timestep based on the net flow of carrier charged and discharged and the quantity of carrier stored at the start of the timestep.
Uses
description: Fix the quantity of carrier stored in a `storage` technology at the
end of each timestep based on the net flow of carrier charged and discharged
and the quantity of carrier stored at the start of the timestep.
equations:
- expression: "storage == $storage_previous_step -\n sum(flow_out_inc_eff, over=carriers)
+ sum(flow_in_inc_eff, over=carriers)"
sub_expressions:
storage_previous_step:
- where: timesteps==get_val_at_index(timesteps=0) AND NOT cyclic_storage==True
expression: storage_initial * storage_cap
- where: "(\n (timesteps==get_val_at_index(timesteps=0) AND cyclic_storage==True)\n\
\ OR NOT timesteps==get_val_at_index(timesteps=0)\n) AND NOT cluster_first_timestep==True"
expression: (1 - storage_loss) ** roll(timestep_resolution, timesteps=1) *
roll(storage, timesteps=1)
- where: cluster_first_timestep==True AND NOT
(timesteps==get_val_at_index(timesteps=0) AND NOT cyclic_storage==True)
expression: (1 - storage_loss) **
select_from_lookup_arrays(timestep_resolution,
timesteps=lookup_cluster_last_timestep) *
select_from_lookup_arrays(storage, timesteps=lookup_cluster_last_timestep)
foreach:
- nodes
- techs
- timesteps
where: (include_storage==true or base_tech==storage) AND NOT (base_tech==supply
OR base_tech==demand)
balance_supply_min_use¶
Set the lower bound on the quantity of its source a supply technology must use in each timestep.
description: Set the lower bound on the quantity of its source a `supply`
technology must use in each timestep.
equations:
- expression: source_use >= source_use_min * $source_scaler
sub_expressions:
source_scaler:
- where: source_unit==per_area
expression: area_use
- where: source_unit==per_cap
expression: sum(flow_cap, over=carriers)
- where: source_unit==absolute
expression: '1'
foreach:
- nodes
- techs
- timesteps
where: source_use_min AND NOT source_use_equals AND base_tech==supply
balance_supply_no_storage¶
Fix the outflow of a supply technology to its consumption of the available source.
Uses
balance_supply_with_storage¶
Fix the outflow of a supply technology to its consumption of the available source, with a storage buffer to temporally offset the outflow from source consumption.
Uses
description: Fix the outflow of a `supply` technology to its consumption of the
available source, with a storage buffer to temporally offset the outflow from
source consumption.
equations:
- expression: storage == $storage_previous_step + source_use * source_eff -
flow_out_inc_eff
sub_expressions:
storage_previous_step:
- where: timesteps==get_val_at_index(timesteps=0) AND NOT cyclic_storage==True
expression: storage_initial * storage_cap
- where: "(\n (timesteps==get_val_at_index(timesteps=0) AND cyclic_storage==True)\n\
\ OR NOT timesteps==get_val_at_index(timesteps=0)\n) AND NOT cluster_first_timestep==True"
expression: (1 - storage_loss) ** roll(timestep_resolution, timesteps=1) *
roll(storage, timesteps=1)
- where: cluster_first_timestep==True AND NOT
(timesteps==get_val_at_index(timesteps=0) AND NOT cyclic_storage==True)
expression: (1 - storage_loss) **
select_from_lookup_arrays(timestep_resolution,
timesteps=lookup_cluster_last_timestep) *
select_from_lookup_arrays(storage, timesteps=lookup_cluster_last_timestep)
foreach:
- nodes
- techs
- carriers
- timesteps
where: storage AND base_tech==supply
balance_transmission¶
Fix the relationship between between carrier flowing into and out of a transmission link in each timestep.
description: Fix the relationship between between carrier flowing into and out
of a `transmission` link in each timestep.
equations:
- expression: sum(flow_out_inc_eff, over=[nodes, carriers]) ==
sum(flow_in_inc_eff, over=[nodes, carriers])
foreach:
- techs
- timesteps
where: base_tech==transmission
export_balance¶
Set the lower bound of a technology's outflow to a technology's carrier export, for any technologies that can export carriers out of the system.
Uses
flow_capacity_per_storage_capacity_max¶
Set the upper bound of storage flow capacity relative to its storage capacity.
flow_capacity_per_storage_capacity_min¶
Set the lower bound of storage flow capacity relative to its storage capacity.
flow_capacity_systemwide_max¶
Set an upper bound on flow capacity of a technology across all nodes in which the technology exists.
flow_capacity_systemwide_min¶
Set a lower bound on flow capacity of a technology across all nodes in which the technology exists.
flow_in_max¶
Set the upper bound of a technology's inflow.
flow_out_max¶
Set the upper bound of a technology's outflow.
flow_out_min¶
Set the lower bound of a technology's outflow.
force_zero_area_use¶
Set a technology's area use to zero if its flow capacity upper bound is zero.
Uses
ramping_down¶
Set the upper bound on a technology's ability to ramp outflow down beyond a certain percentage compared to the previous timestep.
description: Set the upper bound on a technology's ability to ramp outflow down
beyond a certain percentage compared to the previous timestep.
equations:
- expression: -1 * flow_ramping * flow_cap <= $flow - roll($flow, timesteps=1)
sub_expressions:
flow:
- where: carrier_out AND NOT carrier_in
expression: flow_out / timestep_resolution
- where: carrier_in AND NOT carrier_out
expression: flow_in / timestep_resolution
- where: carrier_in AND carrier_out
expression: (flow_out - flow_in) / timestep_resolution
foreach:
- nodes
- techs
- carriers
- timesteps
where: flow_ramping AND NOT timesteps==get_val_at_index(timesteps=0)
ramping_up¶
Set the upper bound on a technology's ability to ramp outflow up beyond a certain percentage compared to the previous timestep.
description: Set the upper bound on a technology's ability to ramp outflow up
beyond a certain percentage compared to the previous timestep.
equations:
- expression: $flow - roll($flow, timesteps=1) <= flow_ramping * flow_cap
sub_expressions:
flow:
- where: carrier_out AND NOT carrier_in
expression: flow_out / timestep_resolution
- where: carrier_in AND NOT carrier_out
expression: flow_in / timestep_resolution
- where: carrier_in AND carrier_out
expression: (flow_out - flow_in) / timestep_resolution
foreach:
- nodes
- techs
- carriers
- timesteps
where: flow_ramping AND NOT timesteps==get_val_at_index(timesteps=0)
set_storage_initial¶
Fix the relationship between carrier stored in a storage technology at the start and end of the whole model period.
description: Fix the relationship between carrier stored in a `storage`
technology at the start and end of the whole model period.
equations:
- expression: "storage[timesteps=$final_step] * (\n (1 - storage_loss) ** timestep_resolution[timesteps=$final_step]\n\
) == storage_initial * storage_cap"
slices:
final_step:
- expression: get_val_at_index(timesteps=-1)
foreach:
- nodes
- techs
where: storage AND storage_initial AND cyclic_storage==True
source_availability_supply¶
Set the upper bound on, or a fixed total of, a supply technology's ability to consume its available resource.
description: Set the upper bound on, or a fixed total of, a `supply`
technology's ability to consume its available resource.
equations:
- where: source_use_equals
expression: source_use == source_use_equals * $source_scaler
- where: NOT source_use_equals AND source_use_max
expression: source_use <= source_use_max * $source_scaler
sub_expressions:
source_scaler:
- where: source_unit==per_area
expression: area_use
- where: source_unit==per_cap
expression: sum(flow_cap, over=carriers)
- where: source_unit==absolute
expression: '1'
foreach:
- nodes
- techs
- timesteps
where: source_use AND (source_use_equals OR source_use_max)
source_capacity_equals_flow_capacity¶
Set a supply technology's flow capacity to equal its source capacity.
source_max¶
Set the upper bound of a supply technology's source consumption.
storage_discharge_depth_limit¶
Set the lower bound of the stored carrier a technology must keep in reserve at all times.
storage_max¶
Set the upper bound of the amount of carrier a technology can store.
Uses
symmetric_transmission¶
Fix the flow capacity of two transmission technologies representing the same link in the system.
system_balance¶
Set the global carrier balance of the optimisation problem by fixing the total production of a given carrier to equal the total consumption of that carrier at every node in every timestep.
description: Set the global carrier balance of the optimisation problem by
fixing the total production of a given carrier to equal the total consumption
of that carrier at every node in every timestep.
equations:
- expression: sum(flow_out, over=techs) - sum(flow_in, over=techs) -
sum(flow_export, over=techs) + (unmet_demand + unused_supply) == 0
foreach:
- nodes
- carriers
- timesteps
Where¶
cost¶
The total annualised costs of a technology, including installation and operation costs.
Unit: cost
Default: 0
title: Total costs
description: The total annualised costs of a technology, including installation
and operation costs.
equations:
- expression: cost_investment_annualised + sum(cost_operation_variable,
over=timesteps) + cost_operation_fixed
foreach:
- nodes
- techs
- costs
where: cost_investment_annualised OR cost_operation_variable OR
cost_operation_fixed
unit: cost
default: 0
cost_investment¶
The installation costs of a technology, including those linked to the nameplate capacity, land use, and storage size.
Uses
Unit: cost
Default: 0
title: Total investment costs
description: The installation costs of a technology, including those linked to
the nameplate capacity, land use, and storage size.
equations:
- expression: sum(cost_investment_flow_cap, over=carriers) +
cost_investment_storage_cap + cost_investment_source_cap +
cost_investment_area_use
foreach:
- nodes
- techs
- costs
where: cost_investment_flow_cap OR cost_investment_storage_cap OR
cost_investment_source_cap OR cost_investment_area_use
unit: cost
default: 0
cost_investment_annualised¶
An annuity factor has been applied to scale lifetime investment costs to annual values that can be directly compared to operation costs. If the modeling period is not equal to one full year, this will be scaled accordingly.
Used in
Uses
Unit: cost
Default: 0
title: Equivalent annual investment costs
description: An annuity factor has been applied to scale lifetime investment
costs to annual values that can be directly compared to operation costs. If
the modeling period is not equal to one full year, this will be scaled
accordingly.
equations:
- expression: $annualisation_weight * $depreciation_rate * cost_investment
sub_expressions:
annualisation_weight:
- expression: sum(timestep_resolution * timestep_weights, over=timesteps) /
8760
depreciation_rate:
- where: cost_depreciation_rate
expression: cost_depreciation_rate
- where: NOT cost_depreciation_rate AND (NOT cost_interest_rate OR
cost_interest_rate==0)
expression: 1 / lifetime
- where: NOT cost_depreciation_rate AND cost_interest_rate>0
expression: (cost_interest_rate * ((1 + cost_interest_rate) ** lifetime)) /
(((1 + cost_interest_rate) ** lifetime) - 1)
foreach:
- nodes
- techs
- costs
where: cost_investment
unit: cost
default: 0
cost_investment_area_use¶
The investment costs associated with the area used by a technology.
Used in
Uses
Unit: cost
Default: 0
cost_investment_flow_cap¶
The investment costs associated with the nominal/rated capacity of a technology.
Used in
Unit: cost
Default: 0
title: Flow capacity investment costs
description: The investment costs associated with the nominal/rated capacity of
a technology.
equations:
- expression: $cost_sum * flow_cap
sub_expressions:
cost_sum:
- where: base_tech==transmission
expression: (cost_flow_cap + cost_flow_cap_per_distance * distance) * 0.5
- where: NOT base_tech==transmission
expression: cost_flow_cap
foreach:
- nodes
- techs
- carriers
- costs
where: flow_cap AND (cost_flow_cap OR cost_flow_cap_per_distance)
unit: cost
default: 0
cost_investment_source_cap¶
The investment costs associated with the source consumption capacity of a technology.
Used in
Unit: cost
Default: 0
cost_investment_storage_cap¶
The investment costs associated with the storage capacity of a technology.
Used in
Unit: cost
Default: 0
cost_operation_fixed¶
The fixed, annual operation costs of a technology, which are calculated relative to investment costs. If the modeling period is not equal to one full year, this will be scaled accordingly.
Used in
Uses
Unit: cost
Default: 0
title: Total fixed operation costs
description: The fixed, annual operation costs of a technology, which are
calculated relative to investment costs. If the modeling period is not equal
to one full year, this will be scaled accordingly.
equations:
- expression: "$annualisation_weight * (\n sum(cost_om_annual * flow_cap, over=carriers)
+\n cost_investment * cost_om_annual_investment_fraction\n)"
sub_expressions:
annualisation_weight:
- expression: sum(timestep_resolution * timestep_weights, over=timesteps) /
8760
foreach:
- nodes
- techs
- costs
where: (cost_om_annual AND flow_cap) OR (cost_investment AND
cost_om_annual_investment_fraction)
unit: cost
default: 0
cost_operation_variable¶
The operating costs per timestep of a technology.
Used in
Uses
Unit: \(\frac{\text{cost}}{\text{hour}}\)
Default: 0
title: Variable operating costs
description: The operating costs per timestep of a technology.
equations:
- expression: timestep_weights * ($cost_export + $cost_flow_out + $cost_flow_in)
sub_expressions:
cost_export:
- expression: sum(cost_export * flow_export, over=carriers)
cost_flow_in:
- where: base_tech==supply
expression: cost_source_use * source_use
- where: NOT base_tech==supply
expression: sum(cost_flow_in * flow_in, over=carriers)
cost_flow_out:
- expression: sum(cost_flow_out * flow_out, over=carriers)
foreach:
- nodes
- techs
- costs
- timesteps
where: cost_export OR cost_flow_in OR cost_flow_out OR cost_source_use
unit: $\frac{\text{cost}}{\text{hour}}$
default: 0
flow_in_inc_eff¶
Inflows after taking efficiency losses into account.
Unit: energy
Default: 0
title: Carrier inflow including losses
description: Inflows after taking efficiency losses into account.
equations:
- where: base_tech==transmission
expression: flow_in * flow_in_eff * flow_in_eff_per_distance ** distance
- where: NOT base_tech==transmission
expression: flow_in * flow_in_eff
foreach:
- nodes
- techs
- carriers
- timesteps
where: flow_in
unit: energy
default: 0
flow_out_inc_eff¶
Outflows after taking efficiency losses into account.
Unit: energy
Default: 0
title: Carrier outflow including losses
description: Outflows after taking efficiency losses into account.
equations:
- where: base_tech==transmission
expression: "flow_out / (\n flow_out_eff * flow_out_parasitic_eff *\n flow_out_eff_per_distance
** distance\n)"
- where: NOT base_tech==transmission
expression: flow_out / (flow_out_eff * flow_out_parasitic_eff)
foreach:
- nodes
- techs
- carriers
- timesteps
where: flow_out
unit: energy
default: 0
Decision Variables¶
area_use¶
The area in space utilised directly (e.g., solar PV panels) or indirectly (e.g., biofuel crops) by a technology.
Used in
Unit: area
Default: 0
title: Area utilisation
description: The area in space utilised directly (e.g., solar PV panels) or
indirectly (e.g., biofuel crops) by a technology.
foreach:
- nodes
- techs
where: (area_use_min OR area_use_max OR area_use_per_flow_cap OR
sink_unit==per_area OR source_unit==per_area)
unit: area
default: 0
bounds:
max: area_use_max
min: area_use_min
flow_cap¶
A technology's flow capacity, also known as its nominal or nameplate capacity.
Used in
- area_use_per_flow_capacity
- balance_demand
- balance_demand_min_use
- balance_supply_min_use
- capacity_factor
- cost_investment_flow_cap
- cost_operation_fixed
- curtailment
- flow_capacity_per_storage_capacity_max
- flow_capacity_per_storage_capacity_min
- flow_capacity_systemwide_max
- flow_capacity_systemwide_min
- flow_in_max
- flow_out_max
- flow_out_min
- ramping_down
- ramping_up
- source_availability_supply
- source_capacity_equals_flow_capacity
- symmetric_transmission
- systemwide_capacity_factor
- total_curtailment
Uses
Unit: power
Default: 0
flow_export¶
The flow of a carrier exported outside the system boundaries by a technology per timestep.
Unit: energy
Default: 0
flow_in¶
The inflow to a technology per timestep, also known as the flow consumed (by storage technologies) or the flow sent (by transmission technologies) on a link.
Uses
Unit: energy
Default: 0
title: Carrier inflow
description: The inflow to a technology per timestep, also known as the flow
consumed (by `storage` technologies) or the flow sent (by `transmission`
technologies) on a link.
foreach:
- nodes
- techs
- carriers
- timesteps
where: carrier_in
unit: energy
default: 0
bounds:
min: 0
flow_out¶
The outflow of a technology per timestep, also known as the flow discharged (from storage technologies) or the flow received (by transmission technologies) on a link.
Used in
Uses
Unit: energy
Default: 0
title: Carrier outflow
description: The outflow of a technology per timestep, also known as the flow
discharged (from `storage` technologies) or the flow received (by
`transmission` technologies) on a link.
foreach:
- nodes
- techs
- carriers
- timesteps
where: carrier_out
unit: energy
default: 0
bounds:
min: 0
link_flow_cap¶
A transmission technology's flow capacity, also known as its nominal or nameplate capacity.
Used in
Uses
Unit: power
Default: 0
source_cap¶
The upper limit on a flow that can be consumed from outside the system boundaries by a supply technology in each timestep.
Used in
Unit: power
Default: 0
source_use¶
The carrier flow consumed from outside the system boundaries by a supply technology.
Used in
Uses
Unit: energy
Default: 0
storage¶
The carrier stored by a storage technology in each timestep.
Used in
Uses
Unit: energy
Default: 0
storage_cap¶
The upper limit on a carrier that can be stored by a technology in any timestep.
Used in
Unit: energy
Default: 0
unmet_demand¶
Virtual source of carrier flow to ensure model feasibility. This should only be considered a debugging rather than a modelling tool as it may distort the model in other ways due to the large impact it has on the objective function value. When present in a model in which it has been requested, it indicates an inability for technologies in the model to reach a sufficient combined supply capacity to meet demand.
Unit: energy
Default: 0
title: Unmet demand (load shedding)
description: Virtual source of carrier flow to ensure model feasibility. This
should only be considered a debugging rather than a modelling tool as it may
distort the model in other ways due to the large impact it has on the
objective function value. When present in a model in which it has been
requested, it indicates an inability for technologies in the model to reach a
sufficient combined supply capacity to meet demand.
foreach:
- nodes
- carriers
- timesteps
where: config.ensure_feasibility==True
unit: energy
default: 0
bounds:
min: 0
unused_supply¶
Virtual sink of carrier flow to ensure model feasibility. This should only be considered a debugging rather than a modelling tool as it may distort the model in other ways due to the large impact it has on the objective function value. In model results, the negation of this variable is combined with unmet_demand and presented as only one variable: unmet_demand. When present in a model in which it has been requested, it indicates an inability for technologies in the model to reach a sufficient combined consumption capacity to meet required outflow (e.g. from renewables without the possibility of curtailment).
Unit: energy
Default: 0
title: Unused supply (curtailment)
description: 'Virtual sink of carrier flow to ensure model feasibility. This should
only be considered a debugging rather than a modelling tool as it may distort the
model in other ways due to the large impact it has on the objective function value.
In model results, the negation of this variable is combined with `unmet_demand`
and presented as only one variable: `unmet_demand`. When present in a model in which
it has been requested, it indicates an inability for technologies in the model to
reach a sufficient combined consumption capacity to meet required outflow (e.g.
from renewables without the possibility of curtailment).'
foreach:
- nodes
- carriers
- timesteps
where: config.ensure_feasibility==True
unit: energy
default: 0
bounds:
max: 0
Postprocessed Statistics¶
capacity_factor¶
The fraction of a technology's capacity that is utilised for carrier outflow in each time period.
Unit: unitless
Default: 0
title: Capacity factor
description: The fraction of a technology's capacity that is utilised for
carrier outflow in each time period.
equations:
- expression: flow_out / (flow_cap * timestep_resolution)
foreach:
- nodes
- techs
- carriers
- timesteps
where: flow_out AND flow_cap>0
unit: unitless
default: 0
curtailment¶
Fraction of outflow curtailed compared to that could have been generated if utilising all available resource. This is useful for renewable energy technologies, for which unused resource in any hour is effectively lost revenue.
Unit: unitless
Default: 0
title: Curtailment
description: Fraction of outflow curtailed compared to that could have been
generated if utilising all available resource. This is useful for renewable
energy technologies, for which unused resource in any hour is effectively lost
revenue.
equations:
- expression: 1 - (source_use / (source_use_max * $source_scaler))
sub_expressions:
source_scaler:
- where: source_unit==per_area
expression: area_use
- where: source_unit==per_cap
expression: sum(flow_cap, over=carriers)
- where: source_unit==absolute
expression: '1'
foreach:
- nodes
- techs
- timesteps
where: base_tech==supply AND source_use_max>0 AND NOT source_use_max==inf AND
source_cap>0
unit: unitless
default: 0
systemwide_capacity_factor¶
The fraction of a technology's capacity that is utilised for carrier outflow, averaged over the full time horizon and all nodes.
Unit: unitless
Default: 0
title: Systemwide capacity factor
description: The fraction of a technology's capacity that is utilised for
carrier outflow, averaged over the full time horizon and all nodes.
equations:
- expression: sum(flow_out * timestep_weights, over=[nodes, timesteps]) /
(sum(flow_cap, over=nodes) * sum(timestep_resolution * timestep_weights,
over=timesteps))
foreach:
- techs
- carriers
where: flow_out AND flow_cap>0
unit: unitless
default: 0
systemwide_levelised_cost¶
Levelised cost of each technology's generated carrier, averaged over all nodes and time periods.
Uses
Unit: \(\frac{\text{cost}}{\text{energy}}\)
Default: 0
title: Systemwide levelised cost of energy (LCOE)
description: Levelised cost of each technology's generated carrier, averaged
over all nodes and time periods.
equations:
- expression: sum(cost, over=nodes) / total_generation
foreach:
- techs
- carriers
- costs
where: total_generation>0 AND any(cost, over=nodes)
unit: $\frac{\text{cost}}{\text{energy}}$
default: 0
total_curtailment¶
Fraction of outflow curtailed compared to that could have been generated if utilising all available resource, averaged over the full time horizon. This is useful for renewable energy technologies, for which unused resource in any hour is effectively lost revenue.
Unit: unitless
Default: 0
title: Total curtailment
description: Fraction of outflow curtailed compared to that could have been
generated if utilising all available resource, averaged over the full time
horizon. This is useful for renewable energy technologies, for which unused
resource in any hour is effectively lost revenue.
equations:
- expression: 1 - (sum(source_use, over=timesteps) / sum(source_use_max *
$source_scaler, over=timesteps))
sub_expressions:
source_scaler:
- where: source_unit==per_area
expression: area_use
- where: source_unit==per_cap
expression: sum(flow_cap, over=carriers)
- where: source_unit==absolute
expression: '1'
foreach:
- nodes
- techs
where: base_tech==supply AND source_use_max AND source_cap>0
unit: unitless
default: 0
total_generation¶
Sum of technology carrier outflow across all nodes and time periods.
Unit: energy
Default: 0
total_levelised_cost¶
Levelised cost of each carrier in the system, averaged over all technologies, nodes, and time periods.
Uses
Unit: \(\frac{\text{cost}}{\text{energy}}\)
Default: 0
title: Total levelised cost of energy (LCOE)
description: Levelised cost of each carrier in the system, averaged over all
technologies, nodes, and time periods.
equations:
- expression: sum(cost, over=[nodes, techs]) / sum(total_generation, over=techs)
foreach:
- carriers
- costs
where: sum(total_generation, over=techs)>0
unit: $\frac{\text{cost}}{\text{energy}}$
default: 0
unmet_sum¶
Net unmet demand for each time period, node, and carrier. This accounts for the net effect of the two dummy variables: unmet demand (load shedding) and unused supply (forced curtailment). Note: this should only be used for debugging.
Unit: energy
Default: 0
title: Net unmet demand
description: 'Net unmet demand for each time period, node, and carrier. This accounts
for the net effect of the two dummy variables: unmet demand (load shedding) and
unused supply (forced curtailment). Note: this should only be used for debugging.'
equations:
- expression: unmet_demand + unused_supply
foreach:
- nodes
- carriers
- timesteps
where: config.ensure_feasibility == True
unit: energy
default: 0
Parameters¶
area_use_max¶
If set to a finite value, limits the upper bound of the area_use decision variable to this value.
Used in
Unit: \(\text{area}\)
Default: inf
area_use_min¶
Limits the lower bound of the area_use decision variable to this value.
Used in
Unit: \(\text{area}\)
Default: 0
area_use_per_flow_cap¶
If set, forces area_use to follow flow_cap with the given numerical ratio (e.g. setting to 1.5 means that area_use == 1.5 * flow_cap).
Used in
Unit: \(\frac{\text{area}}{\text{power}}\)
Default: nan
available_area¶
Available area for resource area use by all technologies at a node.
Used in
Unit: area.
Default: inf
bigM¶
BigM is a large value used to define certain optimisation problems. See https://en.wikipedia.org/wiki/Big_M_method for more information. This value should be larger than the largest values that any decision variables can take, but should not be too large (i.e., do not set it greater than 3 orders of magnitude above the numeric range of the model). If too large, numerical problems may arise in the optimisation.
Used in
Unit: unitless
Default: 1000000.0
cost_area_use¶
Cost per unit area_use.
Used in
Unit: \(\text{area}\)
Default: 0
cost_depreciation_rate¶
Applied to "annualise" investment costs so they are comparable to variable costs. If not provided, this will be calculated using technology lifetime and cost_interest_rate.
Used in
Unit: unitless.
Default: 1
cost_export¶
Cost per unit of flow_export in each timestep. Usually used in the negative sense, as a subsidy.
Used in
Unit: \(\frac{\text{cost}}{\text{energy}}\)
Default: 0
cost_flow_cap¶
Cost per unit of the decision variable flow_cap.
Used in
Unit: \(\frac{\text{cost}}{\text{power}}\)
Default: 0
cost_flow_cap_per_distance¶
Cost per unit of the decision variable flow_cap and per unit distance of a transmission link. Applied to transmission links only.
Used in
Unit: \(\frac{\text{cost}}{\text{power}\times\text{distance}}\)
Default: 0
cost_flow_in¶
Cost per unit of flow_in in each timestep.
Used in
Unit: \(\frac{\text{cost}}{\text{energy}}\)
Default: 0
cost_flow_out¶
Cost per unit of flow_out in each timestep.
Used in
Unit: \(\frac{\text{cost}}{\text{energy}}\)
Default: 0
cost_interest_rate¶
Used when computing levelized costs and technology depreciation_rate (relative to lifetime).
Used in
Unit: unitless
Default: 0
cost_om_annual¶
Annual costs applied per unit flow_cap. These costs are not subject to being recalculated relative to technology lifetime, only scaled to reflect the fraction of one year that the model represents (e.g., 7 days ~= 0.02 of a year).
Used in
Unit: \(\frac{\text{cost}}{\text{power}}\)
Default: 0
cost_om_annual_investment_fraction¶
Add an additional cost to total investment costs (except cost_om_annual) that is a fraction of that total.
Used in
Unit: unitless.
Default: 0
cost_source_cap¶
Cost per unit source_cap.
Used in
Unit: \(\frac{\text{cost}}{\text{power}}\)
Default: 0
cost_source_use¶
Cost per unit of source_use in supply technologies.
Used in
Unit: \(\frac{\text{cost}}{\text{energy}}\)
Default: 0
cost_storage_cap¶
Cost per unit storage_cap, i.e., the maximum available capacity of the storage technology's "reservoir".
Used in
Unit: \(\frac{\text{cost}}{\text{energy}}\)
Default: 0
distance¶
Used for ..._per_distance constraints. If not defined, it will be automatically derived from latitude/longitude of nodes in a link.
Unit: distance.
Default: 1.0
export_max¶
If carrier_export is defined, limit the allowed export of produced carrier for a technology.
Used in
Unit: power.
Default: inf
export_min¶
If carrier_export is defined, set a lower bound on the amount of produced carrier that must be exported for a technology.
Used in
Unit: power.
Default: 0
flow_cap_max¶
Limits flow_cap to a maximum.
Used in
Unit: power.
Default: inf
flow_cap_max_systemwide¶
Limits the sum of flow_cap over all nodes in the model to a maximum.
Used in
Unit: power or \(\frac{\text{power}}{\text{unit}}\)
Default: inf
flow_cap_min¶
Limits flow_cap to a minimum.
Used in
Unit: power or \(\frac{\text{power}}{\text{unit}}\)
Default: 0
flow_cap_min_systemwide¶
Limits the sum of flow_cap over all nodes in the model to a minimum.
Used in
Unit: power.
Default: 0
flow_cap_per_storage_cap_max¶
ratio of maximum charge/discharge (kW) for a given storage capacity (kWh).
Unit: \(\text{hour}^{-1}\)
Default: inf
flow_cap_per_storage_cap_min¶
ratio of minimum charge/discharge (kW) for a given storage capacity (kWh).
Unit: \(\text{hour}^{-1}\)
Default: 0
flow_in_eff¶
Conversion efficiency from source/flow_in (tech dependent) into the technology. Set as value between 1 (no loss) and 0 (all lost).
Used in
Unit: unitless.
Default: 1.0
flow_in_eff_per_distance¶
Total link efficiency will be calculated as \(\text{flow\_in\_eff}\times{}\text{flow\_in\_eff\_per\_distance}^\text{distance}\). Set as value between 1 (no loss) and 0 (all lost).
Used in
Unit: \(\frac{\text{1}}{\text{distance}}\)
Default: 1.0
flow_out_eff¶
Conversion efficiency from the technology to sink/flow_out (tech dependent). Set as value between 1 (no loss) and 0 (all lost).
Used in
Unit: unitless.
Default: 1.0
flow_out_eff_per_distance¶
Total link efficiency will be calculated as \(\text{flow\_out\_eff}\times{}\text{flow\_out\_eff\_per\_distance}^\text{distance}\). Set as value between 1 (no loss) and 0 (all lost).
Used in
Unit: \(\frac{\text{1}}{\text{distance}}\)
Default: 1.0
flow_out_min_relative¶
Set to a value between 0 and 1 to force minimum flow_out as a fraction of the technology rated capacity.
Used in
Unit: unitless.
Default: 0
flow_out_parasitic_eff¶
Additional losses as flow gets transferred from the plant to the carrier, e.g. due to plant parasitic consumption. Set as value between 1 (no loss) and 0 (all lost).
Used in
Unit: unitless.
Default: 1.0
flow_ramping¶
limit maximum outflow / inflow / outflow - inflow (technology base class dependent) to a fraction of maximum capacity, which increases by that fraction at each timestep.
Used in
Unit: \(\frac{1}{\text{hour}}\)
Default: 1.0
lifetime¶
Must be defined if fixed capital costs are defined. A reasonable value for many technologies is around 20-25 years.
Used in
Unit: years.
Default: inf
objective_cost_weights¶
Weightings for cost classes to apply in the objective function.
Used in
Unit: unitless
Default: 1
sink_use_equals¶
Required amount of carrier removal from the system (e.g., electricity demand, transport distance). Unit dictated by source_unit.
Used in
Unit: energy | \(\frac{\text{energy}}{\text{power}}\) | \(\frac{\text{energy}}{\text{area}}\)
Default: nan
sink_use_max¶
Maximum sink use to remove a carrier from the system (e.g., electricity demand, transport distance). Unit dictated by source_unit.
Used in
Unit: energy | \(\frac{\text{energy}}{\text{power}}\) | \(\frac{\text{energy}}{\text{area}}\)
Default: inf
sink_use_min¶
Minimum sink use to remove a carrier from the system (e.g., electricity demand, transport distance). Unit dictated by source_unit.
Used in
Unit: energy | \(\frac{\text{energy}}{\text{power}}\) | \(\frac{\text{energy}}{\text{area}}\)
Default: 0
source_cap_max¶
Upper limit on source_cap decision variable.
Used in
Unit: power.
Default: inf
source_cap_min¶
Lower limit on source_cap decision variable.
Used in
Unit: power.
Default: 0
source_eff¶
Conversion efficiency from the technology from source. Set as value between 1 (no loss) and 0 (all lost).
Used in
Unit: unitless.
Default: 1.0
source_use_equals¶
Required amount of carrier removal from the system (e.g., biofuel, coal, rainfall, wind flow). Unit dictated by source_unit.
Unit: energy | \(\frac{\text{energy}}{\text{power}}\) | \(\frac{\text{energy}}{\text{area}}\)
Default: nan
source_use_max¶
Maximum source use to add a carrier to the system (e.g., biofuel, coal, rainfall, wind flow). Unit dictated by source_unit.
Unit: energy | \(\frac{\text{energy}}{\text{power}}\) | \(\frac{\text{energy}}{\text{area}}\)
Default: inf
source_use_min¶
Minimum source use to add a carrier from the system (e.g., biofuel, coal, rainfall, wind flow). Unit dictated by source_unit.
Used in
Unit: energy | \(\frac{\text{energy}}{\text{power}}\) | \(\frac{\text{energy}}{\text{area}}\)
Default: 0
storage_cap_max¶
Limit upper bound of storage_cap decision variable.
Used in
Unit: energy.
Default: inf
storage_cap_min¶
Limit lower bound of storage_cap decision variable.
Used in
Unit: energy.
Default: 0
storage_discharge_depth¶
Defines the minimum level of storage state of charge, as a fraction of total storage capacity.
Used in
Unit: unitless.
Default: 0
storage_initial¶
Set stored flow in device at the first timestep, as a fraction of total storage capacity.
Unit: unitless.
Default: 0
storage_loss¶
Rate of storage loss per hour, used to calculate lost stored flow as (1 - storage_loss)^hours_per_timestep.
Unit: \(\frac{\text{1}}{\text{hour}}\)
Default: 0
timestep_resolution¶
Used in
Unit: hours.
Default: 1
timestep_weights¶
Used in
Unit: unitless.
Default: 1
Lookup Arrays¶
base_tech¶
Should be the name of one of the abstract base classes, from which some initial parameter defaults will be derived and with which certain base math will be triggered.
Used in
- balance_conversion
- balance_demand
- balance_demand_min_use
- balance_storage
- balance_supply_min_use
- balance_supply_no_storage
- balance_supply_with_storage
- balance_transmission
- cost_investment_flow_cap
- cost_operation_variable
- curtailment
- flow_in_inc_eff
- flow_out_inc_eff
- link_flow_cap
- source_cap
- source_use
- storage
- storage_cap
- symmetric_transmission
- total_curtailment
- total_generation
Default: nan
Type: string
carrier_export¶
Carrier(s) produced by this technology that can be exported out of the system boundaries without having to go to a pre-defined sink (i.e., via a demand technology). Must be a subset of carrier_out.
Used in
Default: False
Type: bool
carrier_in¶
Carrier(s) consumed by this technology. Only transmission, conversion, storage, and demand technologies can define this parameter
Used in
Default: False
Type: bool
carrier_out¶
Carrier(s) produced by this technology. Only transmission, conversion, storage, and supply technologies can define this parameter
Used in
Default: False
Type: bool
cluster_first_timestep¶
If true, the timestep is the first in the given clustered day.
Default: False
Type: bool
cyclic_storage¶
If true, link storage levels in the last model timestep with the first model timestep. inter_cluster_storage custom math must be included if using time clustering and setting this to true.
Default: True
Type: bool
include_storage¶
When true, math will be triggered to allow discontinuous carrier inflow and outflows across timesteps.
Default: False
Type: bool
lookup_cluster_last_timestep¶
The last timestep of each cluster.
Default: nan
Type: datetime
sink_unit¶
Sets the unit of Sink to either absolute (unit: energy), per_area (unit: energy/area), or per_cap (unit: energy/power). per_area uses the area_use decision variable to scale the sink while per_cap uses the flow_cap decision variable.
Default: absolute
Type: string
source_cap_equals_flow_cap¶
If true, the decision variables source_cap and flow_cap are forced to equal one another.
Default: False
Type: bool
source_unit¶
Sets the unit of Source to either absolute (unit: energy), per_area (unit: energy/area), or per_cap (unit: energy/power). per_area uses the area_use decision variable to scale the source while per_cap uses the flow_cap decision variable.
Default: absolute
Type: string