SpineOpt input data structure update

[nhniina]

SpineOpt input data structure will see major changes in the forthcoming versions. The plan for the changes is desribed here.

The following classes will be updated:

old class	new class
unit__from_node	node__to_unit
unit__from_node__investment_group	unit_flow__investment_group
unit__from_node__user_constraint	unit_flow__user_constraint
unit__node__node	unit_flow__unit_flow
unit__to_node__investment_group	unit_flow__investment_group
unit__to_node__user_constraint	unit_flow__user_constraint

In addition, the following new class will be created:

new class	additional info
unit_flow	superclass for node__to_unit and unit__to_node subclasses

Several parameters will be renamed. They are listed here:

old class	old parameter name	new class	new_parameter
connection	connection_availability_factor	connection	availability_factor
connection	connection_investment_econ_lifetime	connection	econ_lifetime
connection	connection_investment_tech_lifetime	connection	tech_lifetime
connection	connection_investment_variable_type	connection	investment_variable_type
connection	connection_reactance	connection	reactance
connection	connection_resistance	connection	resistance
model	db_lp_solver	model	lp_solver
model	db_lp_solver_options	model	lp_solver_options
model	db_mip_solver	model	mip_solver
model	db_mip_solver_options unit__to_node	model	mip_solver_options
node	frac_state_loss	node	storage_self_discharge
node	state_coeff	node	storage_state_coeff
node	storage_investment_econ_lifetime	node	storage_econ_lifetime
node	storage_investment_tech_lifetime	node	storage_tech_lifetime
temporal_block	representative_periods_mapping	temporal_block	periods_represented?
unit	number_of_units	unit	existing_units
unit	unit_availability_factor	unit	availability_factor
unit	unit_investment_econ_lifetime	unit	econ_lifetime
unit	unit_investment_tech_lifetime	unit	tech_lifetime
unit	unit_investment_variable_type	unit	investment_variable_type
unit__from_node	fuel_cost	node__to_unit	flow_cost
unit__from_node	unit_capacity	node__to_unit	capacity_per_unit
unit__from_node	vom_cost	node__to_unit	flow_cost
unit__to_node	fuel_cost	unit__to_node	flow_cost
unit__to_node	unit_capacity	unit__to_node	capacity_per_unit
unit__to_node	vom_cost	unit__to_node	flow_cost
unit__node__node	fix_ratio_in_in_unit_flow	unit_flow__unit_flow	equality_constraint
unit__node__node	fix_ratio_in_out_unit_flow	unit_flow__unit_flow	equality_constraint
unit__node__node	fix_ratio_out_in_unit_flow	unit_flow__unit_flow	equality_constraint
unit__node__node	fix_ratio_out_out_unit_flow	unit_flow__unit_flow	equality_constraint
unit__node__node	fix_units_on_coefficient_in_in	unit_flow__unit_flow	equality_constant
unit__node__node	fix_units_on_coefficient_in_out	unit_flow__unit_flow	equality_constant
unit__node__node	fix_units_on_coefficient_out_in	unit_flow__unit_flow	equality_constant
unit__node__node	fix_units_on_coefficient_out_out	unit_flow__unit_flow	equality_constant
unit__node__node	max_ratio_in_in_unit_flow	unit_flow__unit_flow	greater_than_constraint
unit__node__node	max_ratio_in_out_unit_flow	unit_flow__unit_flow	greater_than_constraint
unit__node__node	max_ratio_out_in_unit_flow	unit_flow__unit_flow	greater_than_constraint
unit__node__node	max_ratio_out_out_unit_flow	unit_flow__unit_flow	greater_than_constraint
unit__node__node	max_units_on_coefficient_in_in	unit_flow__unit_flow	greater_than_constant
unit__node__node	max_units_on_coefficient_in_out	unit_flow__unit_flow	greater_than_constant
unit__node__node	max_units_on_coefficient_out_in	unit_flow__unit_flow	greater_than_constant
unit__node__node	max_units_on_coefficient_out_out	unit_flow__unit_flow	greater_than_constant
unit__node__node	min_ratio_in_in_unit_flow	unit_flow__unit_flow	less_than_constraint
unit__node__node	min_ratio_in_out_unit_flow	unit_flow__unit_flow	less_than_constraint
unit__node__node	min_ratio_out_in_unit_flow	unit_flow__unit_flow	less_than_constraint
unit__node__node	min_ratio_out_out_unit_flow	unit_flow__unit_flow	less_than_constraint
unit__node__node	min_units_on_coefficient_in_in	unit_flow__unit_flow	less_than_constant
unit__node__node	min_units_on_coefficient_in_out	unit_flow__unit_flow	less_than_constant
unit__node__node	min_units_on_coefficient_out_in	unit_flow__unit_flow	less_than_constant
unit__node__node	min_units_on_coefficient_out_out	unit_flow__unit_flow	less_than_constant

In addition to simple renaming, some parameters will be changed from a flat structure to Map parameters, allowing for easier grouping of parameters that belong to certain features. These are listed here:

old class	old parameter name	new class	new parameter name	map index
connection	candidate_connections	connection	investment_limits	[max_new]
connection	connections_invested_big_m_mga	connection	mga	[investment_big_m]
connection	connections_invested_mga	connection	mga	[investment]
connection	connections_invested_mga_weight	connection	mga	[investment_weight]
connection	fix_connections_invested	connection	investment_limits	[fix_new]
connection	fix_connections_invested_available	connection	investment_limits	[fix_cumulative]
connection	initial_connections_invested	connection	investment_limits	[min_new]?
connection	initial_connections_invested_available	connection	investment_limits	[min_cumulative]?
model	max_gap	model	decomposition	[max_gap]
model	max_iterations	model	decomposition	[max_iterations]
model	max_mga_iterations	model	mga	[max_iterations]
model	max_mga_slack	model	mga	[max_slack]
model	min_iterations	model	decomposition	[min_iterations]
node	candidate_storages	node	storage_investment_limits	[max_new]
node	fix_node_pressure	node	pressure_limits	[fix]
node	fix_node_state	node	storage_state_limits	[fix]
node	fix_node_voltage_angle	node	voltage_angle_limits	[fix]
node	fix_storages_invested	node	storage_investment_limits	[fix_new]
node	fix_storages_invested_available	node	storage_investment_limits	[fix_cumulative]
node	initial_node_pressure	node	pressure_limits	[initial]
node	initial_node_state	node	storage_state_limits	[initial]
node	initial_node_voltage_angle	node	voltage_angle_limits	[initial]
node	initial_storages_invested	node	storage_investment_limits	[min_new]?
node	initial_storages_invested_available	node	storage_investment_limits	[min_cumulative]?
node	max_node_pressure	node	pressure_limits	[max]
node	max_voltage_angle	node	voltage_angle_limits	[max]
node	min_node_pressure	node	pressure_limits	[min]
node	min_voltage_angle	node	voltage_angle_limits	[min]
node	node_state_cap	node	storage_state_limits	[max]
node	node_state_min	node	storage_state_limits	[min]
node	storages_invested_big_m_mga	node	storage_mga	[investment_big_m]
node	storages_invested_mga	node	storage_mga	[investment]
node	storages_invested_mga_weight	node	storage_mga	[investment_weight]
unit	candidate_units	unit	investment_limits	[max_new]
unit	fix_units_invested	unit	investment_limits	[fix_new]
unit	fix_units_invested_available	unit	investment_limits	[fix_cumulative]
unit	fix_units_on	unit	units_online	[min, max]
unit	initial_units_invested	unit	investment_limits	[min_new]?
unit	initial_units_invested_available	unit	investment_limits	[min_cumulative]?
unit	initial_units_on	unit	units_online	[initial]
unit	units_invested_big_m_mga	unit	mga	[investment_big_m]
unit	units_invested_mga	unit	mga	[investment]
unit	units_invested_mga_weight	unit	mga	[investment_weight]
unit__from_node	fix_unit_flow	node__to_unit	flow_limits	[fix]
unit__from_node	initial_unit_flow	node__to_unit	flow_limits	[initial]
unit__from_node	max_total_cumulated_unit_flow_from_node	node__to_unit	flow_limits	[max_cumulative]
unit__from_node	min_total_cumulated_unit_flow_from_node	node__to_unit	flow_limits	[min_cumulative]
unit__from_node	min_unit_flow	node__to_unit	flow_limits	[min]
unit__from_node	ramp_down_limit	node__to_unit	ramp_limits	[ramp_down]
unit__from_node	ramp_up_limit	node__to_unit	ramp_limits	[ramp_up]
unit__from_node	shut_down_limit	node__to_unit	ramp_limits	[shutdown]
unit__from_node	start_up_limit	node__to_unit	ramp_limits	[startup]
unit__to_node	fix_unit_flow	unit__to_node	flow_limits	[fix]
unit__to_node	initial_unit_flow	unit__to_node	flow_limits	[initial]
unit__to_node	max_total_cumulated_unit_flow_to_node	unit__to_node	flow_limits	[max_cumulative]
unit__to_node	min_total_cumulated_unit_flow_to_node	unit__to_node	flow_limits	[min_cumulative]
unit__to_node	min_unit_flow	unit__to_node	flow_limits	[min]
unit__to_node	ramp_down_limit	unit__to_node	ramp_limits	[ramp_down]
unit__to_node	ramp_up_limit	unit__to_node	ramp_limits	[ramp_up]
unit__to_node	shut_down_limit	unit__to_node	ramp_limits	[shutdown]
unit__to_node	start_up_limit	unit__to_node	ramp_limits	[startup]

A few parameters will be moved from one class to another class. Some of these also renamed at the same time. The parameters that will be moved are:

old class	old parameter name	new class	new parameter name
unit	curtailment_cost	unit__to_node, node__to_unit	curtailment_cost
unit	fom_cost	unit__to_node, node__to_unit	fixed_annual_cost
unit	shut_down_cost	unit__to_node, node__to_unit	shutdown_cost
unit	start_up_cost	unit__to_node, node__to_unit	startup_cost

Finally, some parameters will be moved to another class, the parameter may be renamed, and some calculation may be performed on the parameter. These parameters are the following:

old class	old parameter name	new class	new parameter name	additional info
unit	unit_investment_cost	unit__to_node, node__to_unit	investment_cost	divided by unit capacity
unit	units_on_cost	unit__to_node, node__to_unit	online_cost	divided by unit capacity

Additional changes

• node: balance_type will be renamed to node_type and updated to include options storage_node and storage_group (based on has_state, which will be removed)

[manuelma]

Great stuff @nhniina - this level of exhaustivity is really great to assess these changes.

I have some comments:

• node_type instead of balance_type? I might prefer to keep the latter, it is way more explicit.
• periods_represented instead of representative_periods_mapping? I don't like any of them too much but I feel we could do a little bit better than periods_represented, maybe representative_temporal_blocks? In any case we should name mapping parameters after the values and not after the keys if we want to follow the computer science standard. Another option is the 'value_by_key' approach, so in this case something like representative_block_by_period might work? And yet another option is the 'key_to_value' convention (period_to_representative_block).
• investment_method instead of investment_variable_type? I again prefer to keep the latter, it's more explicit. The other one throws me off as something completely different than the type of variable used to represent investments.
• The map_index for initial_storages_invested shouldn't be [min_new] but rather [initial] I believe. This might also be the case for other initial_* parameters so could be useful to double check.

But again, thank you so much for going through all this.