# Object Classes

`commodity`

A good or product that can be consumed, produced, traded. E.g., electricity, oil, gas, water...

Related Parameters:commodity_lodf_tolerance, commodity_physics, commodity_ptdf_threshold and is_active

Related Relationship Classes:node__commodity and unit__commodity

Commodities correspond to the type of energy traded. When associated with a node through the node__commodity relationship, a specific form of energy, i.e. commodity, can be associated with a specific location. Furthermore, by linking commodities with units, it is possible to track the flows of a certain commodity and impose limitations on the use of a certain commodity (See also max_cum_in_unit_flow_bound). For the representation of specific commodity physics, related to e.g. the representation of the electric network, designated parameters can be defined to enforce commodity specific behaviour. (See also commodity_physics)

`connection`

A transfer of commodities between nodes. E.g. electricity line, gas pipeline...

Related Parameters:candidate_connections, connection_availability_factor, connection_contingency, connection_flow_cost, connection_investment_cost, connection_investment_lifetime, connection_investment_variable_type, connection_monitored, connection_reactance_base, connection_reactance, connection_resistance, connection_type, fix_connections_invested_available, fix_connections_invested, graph_view_position, has_binary_gas_flow and is_active

Related Relationship Classes:connection__from_node__unit_constraint, connection__from_node, connection__investment_stochastic_structure, connection__investment_temporal_block, connection__node__node, connection__to_node__unit_constraint and connection__to_node

A connection represents a transfer of one commodity over space. For example, an electricity transmission line, a gas pipe, a river branch, can be modelled using a connection.

A connection always takes commodities from one or more nodes, and releases them to one or more (possibly the same) nodes. The former are specificed through the connection__from_node relationship, and the latter through connection__to_node. Every connection inherits the temporal and stochastic structures from the associated nodes. The model will generate `connection_flow`

variables for every combination of connection, node, *direction* (from node or to node), *time slice*, and *stochastic scenario*, according to the above relationships.

The operation of the connection is specified through a number of parameter values. For example, the capacity of the connection, as the maximum amount of energy that can enter or leave it, is given by connection_capacity. The conversion ratio of input to output can be specified using any of fix_ratio_out_in_connection_flow, max_ratio_out_in_connection_flow, and min_ratio_out_in_connection_flow parameters in the connection__node__node relationship. The delay on a connection, as the time it takes for the energy to go from one end to the other, is given by connection_flow_delay.

`model`

An instance of SpineOpt, that specifies general parameters such as the temporal horizon.

Related Parameters:big_m, duration_unit, is_active, max_gap, max_iterations, model_end, model_start, model_type, roll_forward, write_lodf_file, write_mps_file and write_ptdf_file

Related Relationship Classes:model__default_investment_stochastic_structure, model__default_investment_temporal_block, model__default_stochastic_structure, model__default_temporal_block, model__report, model__stochastic_structure and model__temporal_block

The model object holds general information about the optimization problem at hand. Firstly, the modelling horizon is specified on the model object, i.e. the scope of the optimization model, and if applicable the duration of the rolling window (see also model_start, model_end and roll_forward). Secondly, the model works as an overarching assembler - only through linking temporal_blocks and stochastic_structures to a model object via relationships, they become part of the optimization problem, and respectively linked nodes, connections and units. If desired the user can also specify defaults for temporals and stochastic via the designated default relationships (see e.g., model__default_temporal_block). In this case, the default temporal is populated for missing node__temporal_block relationships. Lastly, the model object contains information about the algorithm used for solving the problem (see model_type).

`node`

A universal aggregator of commodify flows over units and connections, with storage capabilities.

Related Parameters:balance_type, candidate_storages, demand, downward_reserve, fix_node_pressure, fix_node_state, fix_node_voltage_angle, fix_storages_invested_available, fix_storages_invested, frac_state_loss, fractional_demand, graph_view_position, has_pressure, has_state, has_voltage_angle, is_active, is_reserve_node, max_node_pressure, max_voltage_angle, min_node_pressure, min_voltage_angle, minimum_reserve_activation_time, nodal_balance_sense, node_opf_type, node_slack_penalty, node_state_cap, node_state_min, state_coeff, storage_investment_cost, storage_investment_lifetime, storage_investment_variable_type, tax_in_unit_flow, tax_net_unit_flow, tax_out_unit_flow and upward_reserve

Related Relationship Classes:connection__from_node__unit_constraint, connection__from_node, connection__node__node, connection__to_node__unit_constraint, connection__to_node, node__commodity, node__investment_stochastic_structure, node__investment_temporal_block, node__node, node__stochastic_structure, node__temporal_block, node__unit_constraint, unit__from_node__unit_constraint, unit__from_node, unit__node__node, unit__to_node__unit_constraint and unit__to_node

The node is perhaps the most important `object class`

out of the Systemic object classes, as it is what connects the rest together via the Systemic relationship classes. Essentially, nodes act as points in the modelled commodity network where commodity balance is enforced via the node balance and node injection constraints, tying together the inputs and outputs from units and connections, as well as any external demand. Furthermore, nodes play a crucial role for defining the temporal and stochastic structures of the model via the node__temporal_block and node__stochastic_structure relationships. For more details about the Temporal Framework and the Stochastic Framework, please refer to the dedicated sections.

Since nodes act as the points where commodity balance is enforced, this also makes them a natural fit for implementing *storage*. The has_state parameter controls whether a node has a `node_state`

variable, which essentially represents the commodity content of the node. The state_coeff parameter tells how the `node_state`

variable relates to all the commodity flows. Storage losses are handled via the frac_state_loss parameter, and potential diffusion of commodity content to other nodes via the diff_coeff parameter for the node__node relationship.

`output`

A variable name from SpineOpt that can be included in a report.

Related Parameters:is_active

Related Relationship Classes:report__output

An output is essentially a handle for a *SpineOpt* variable and Objective function to be included in a report and written into an output database. Typically, e.g. the unit_flow variables are desired as output from most models, so creating an output object called `unit_flow`

allows one to designate it as something to be written in the desired report. Note that unless appropriate model__report and report__output relationships are defined, *SpineOpt* doesn't write any output!

`report`

A results report from a particular SpineOpt run, including the value of specific variables.

Related Parameters:is_active and output_db_url

Related Relationship Classes:model__report and report__output

A report is essentially a group of outputs from a model, that gets written into the output database as a result of running *SpineOpt*. Note that unless appropriate model__report and report__output relationships are defined, *SpineOpt* doesn't write any output!

`stochastic_scenario`

A scenario for stochastic optimisation in SpineOpt.

Related Parameters:is_active

Related Relationship Classes:parent_stochastic_scenario__child_stochastic_scenario and stochastic_structure__stochastic_scenario

Essentially, a stochastic_scenario is a label for an alternative period of time, describing one possibility of what might come to pass. They are the basic building blocks of the scenario-based Stochastic Framework in *SpineOpt.jl*, but aren't really meaningful on their own. Only when combined into a stochastic_structure using the stochastic_structure__stochastic_scenario and parent_stochastic_scenario__child_stochastic_scenario relationships, along with Parameters like the weight_relative_to_parents and stochastic_scenario_end, they become meaningful.

`stochastic_structure`

A group of stochastic scenarios that represent a structure.

Related Parameters:is_active

Related Relationship Classes:connection__investment_stochastic_structure, model__default_investment_stochastic_structure, model__default_stochastic_structure, model__stochastic_structure, node__investment_stochastic_structure, node__stochastic_structure, stochastic_structure__stochastic_scenario, unit__investment_stochastic_structure and units_on__stochastic_structure

The stochastic_structure is the key component of the scenario-based Stochastic Framework in *SpineOpt.jl*, and essentially represents a group of stochastic_scenarios with set Parameters. The stochastic_structure__stochastic_scenario relationship defines which stochastic_scenarios are included in which stochastic_structures, and the weight_relative_to_parents and stochastic_scenario_end Parameters define the exact shape and impact of the stochastic_structure, along with the parent_stochastic_scenario__child_stochastic_scenario relationship.

The main reason as to why stochastic_structures are so important is, that they act as handles connecting the Stochastic Framework to the modelled system. This is handled using the Structural relationship classes e.g. node__stochastic_structure, which define the stochastic_structure applied to each `object`

describing the modelled system. Connecting each system `object`

to the appropriate stochastic_structure individually can be a bit bothersome at times, so there are also a number of convenience Meta relationship classes like the model__default_stochastic_structure, which allow setting model-wide defaults to be used whenever specific definitions are missing.

`temporal_block`

A length of time with a particular resolution.

Related Parameters:block_end, block_start, is_active, representative_periods_mapping, resolution and weight

Related Relationship Classes:connection__investment_temporal_block, model__default_investment_temporal_block, model__default_temporal_block, model__temporal_block, node__investment_temporal_block, node__temporal_block, unit__investment_temporal_block and units_on__temporal_block

A temporal block defines the temporal properties of the optimization that is to be solved in the current window. It is the key building block of the Temporal Framework. Most importantly, it holds the necessary information about the resolution and horizon of the optimization. A single model can have multiple temporal blocks, which is one of the main sources of temporal flexibility in Spine: by linking different parts of the model to different temporal blocks, a single model can contain aspects that are solved with different temporal resolutions or time horizons.

`unit`

A conversion of one/many comodities between nodes.

Related Parameters:candidate_units, curtailment_cost, fix_units_invested_available, fix_units_invested, fix_units_on, fom_cost, graph_view_position, is_active, min_down_time, min_up_time, number_of_units, online_variable_type, shut_down_cost, start_up_cost, unit_availability_factor, unit_investment_cost, unit_investment_lifetime and unit_investment_variable_type

Related Relationship Classes:unit__commodity, unit__from_node__unit_constraint, unit__from_node, unit__investment_stochastic_structure, unit__investment_temporal_block, unit__node__node, unit__to_node__unit_constraint, unit__to_node, unit__unit_constraint, units_on__stochastic_structure and units_on__temporal_block

A unit represents an energy conversion process, where energy of one commodity can be converted into energy of another commodity. For example, a gas turbine, a power plant, or even a load, can be modelled using a unit.

A unit always takes energy from one or more nodes, and releases energy to one or more (possibly the same) nodes. The former are specificed through the unit__from_node relationship, and the latter through unit__to_node. Every unit has a temporal and stochastic structures given by the units_on__temporal_block and [units_on__stochastic_structure] relationships. The model will generate `unit_flow`

variables for every combination of unit, node, *direction* (from node or to node), *time slice*, and *stochastic scenario*, according to the above relationships.

The operation of the unit is specified through a number of parameter values. For example, the capacity of the unit, as the maximum amount of energy that can enter or leave it, is given by unit_capacity. The conversion ratio of input to output can be specified using any of fix_ratio_out_in_unit_flow, max_ratio_out_in_unit_flow, and min_ratio_out_in_unit_flow. The variable operating cost is given by vom_cost.

`unit_constraint`

A generic data-driven custom constraint.

Related Parameters:constraint_sense, is_active and right_hand_side

Related Relationship Classes:connection__from_node__unit_constraint, connection__to_node__unit_constraint, node__unit_constraint, unit__from_node__unit_constraint, unit__to_node__unit_constraint and unit__unit_constraint

The unit_constraint is a generic data-driven custom constraint, which allows for defining constraints involving multiple units, nodes, or connections. The constraint_sense parameter changes the sense of the unit_constraint, while the right_hand_side parameter allows for defining the constant terms of the constraint.

Coefficients for the different variables appearing in the unit_constraint are defined using relationships, like e.g. unit__from_node__unit_constraint and connection__to_node__unit_constraint for unit_flow and connection_flow variables, or unit__unit_constraint and node__unit_constraint for units_on, units_started_up, and node_state variables.

For more information, see the dedicated article on Unit Constraints