Configurations¶

System Configurations¶

The system.json defines the structure of the energy system. The following table summarizes the available system settings and their default values.

Table 2 System Settings¶
Key	Type	Default Value	Description
`set_conversion_technologies`	`list[str]`	`[]`	list of conversion technologies included in the optimization
`set_storage_technologies`	`list[str]`	`[]`	list of storage technologies included in the optimization
`set_retrofitting_technologies`	`list[str]`	`[]`	list of retrofitting technologies included in the optimization
`set_transport_technologies`	`list[str]`	`[]`	list of transport technologies included in the optimization
`set_transport_technologies_loss_exponential`	`list[str]`	`[]`	list of transport technologies included in the optimization for which to use an exponential loss factor
`use_capacities_existing`	`bool`	`True`	per default a brownfield optimization is conducted, by setting this parameter to `False` existing technology capacities are ignored and a greenfield optimization is conducted
`allow_investment`	`bool`	`True`	per default, investment in new technology capacity is allowed, by setting this parameter to `False` only existing technology capacities are used and only the operation is optimized
`double_capex_transport`	`bool`	`False`	per default the capex for transport is not separated into the capacity- and the distance-dependent term, as this introduces binary variables
`set_nodes`	`list[str]`	`[]`	per default all nodes are selected, however, by overwriting the empty list value you can conduct the optimization for a subset of subset of nodes
`coords`	dict[str, dict[str, float]]	`{}`	dictionary with the coordinates of the nodes, is filled by ZEN-garden
`unaggregated_time_steps_per_year`	`int`	`8760`	per default the total hours per year are set to 8760, overwrite this parameter if you want to investigate a shorter period
`conduct_time_series_aggregation`	`bool`	`False`	per default the time-series-aggregation is not conducted, set to `True` to enable the timeseries aggregation
`total_hours_per_year`	`int`	`8760`	defines the definition of a year. Do not change this value unless you know what you are doing
`aggregated_time_steps_per_year`	`int`	`10`	per default the timeseries aggregation aggregates the number of time-steps to 10, overwrite this value to increase or decrease the intra-yearly temporal resolution
`reference_year`	`int`	`2024`	per default the reference year is set to 2024
`optimized_years`	`int`	`1`	per default, the optimization is conducted for 1 year, change this value to investigate longer time horizons
`interval_between_years`	`int`	`1`	per default, the optimization is conducted for each year, change this value to only investigate every second (2) year or every third (3) year, etc.
`use_rolling_horizon`	`bool`	`False`	per default the optimization is conducted assuming perfect foresight, set this parameter to `True` if you want to use a rolling horizon approach with myopic foresight instead
`years_in_rolling_horizon`	`int`	`1`	per default the foresight is limited of the rolling horizon approach is limited to one year, flexibly increase or decrease this value to investigate longer or shorter foresight horizons
`years_in_decision_horizon`	`int`	`1`	per default, the rolling horizon decision horizon is one year, increase this value to only allow decision every second (2) or third (3) planning period, etc.
`conduct_scenario_analysis`	`bool`	`False`	per default, the optimization is only conducted for the default scenario. Set this value to true to `True` to conduct a scenario analysis
`run_default_scenario`	`bool`	`True`	per default the optimization is conducted for the default scenario as well as all scenarios specified in `scenarios.json` , if `False` the optimization is only conducted for the scenarios specified in `scenarios.json`
`clean_sub_scenarios`	`bool`	`False`	per default sub-scenarios are not removed, set to `True` to delete sub-scenarios between runs
`set_transport_technologies_loss_exponential`	`list[str]`	`[]`	list of transport technologies for which exponential transport loss function is used
`double_capex_transport`	`bool`	`False`	per default only distance dependent capital expenditures are applied to transport tech, if true, apply both fix capital expenditures (capex) and distance dependent capex to installation of transport technologies
`storage_periodicity`	`bool`	`True`	enable storage periodicity
`multiyear_periodicity`	`bool`	`False`	enable storage periodicity over multiple years
`exclude_parameters_from_TSA`	`bool`	`True`	exclude selected parameters from the timeseries aggregation
`knowledge_depreciation_rate`	`float`	`0.1`	knowledge deprecation rate to be used in the technology expansion constraint
`storage_charge_discharge_binary`	`bool`	`False`	add binary variable to avoid simultaneous charging and discharging of all storage technologies

Per default, the technology selection is empty. You must define the set of technologies you want to investigate in your system. Only technologies selected in system.json are added to the optimization problem. You can flexibly select any subset of the technologies available in your set_technologies folder. Selecting a technology that is not defined in your input data will raise an error.

Per default, all nodes defined in energy_system/set_nodes.csv are added. You can reduce the number of nodes by selecting a subset of nodes in your system.json. In addition, you can specify the starting year (reference_year), the time horizon (optimized_years), and the interyearly resolution (interval_between_years) in the system.json.

Per default, each year is represented by 8760 timesteps of length 1h. You can change the interyearly resolution by modifying the unaggregated_time_steps_per_year. To reduce the complexity, timeseries aggregation can be used (conduct_time_series_aggregation) to reduce the number of time steps. Per default, the number of timesteps is reduced to 10 (aggregated_time_steps_per_year). Tutorial 5: Time Series Aggregation and The time parameters in ZEN-garden provide a detailed description of the time representation and the time parameters.

Config Configurations¶

This section describes all configurations which can be set in the config.json file. The config.json file generally contains a list of two dictionaries: analysis and solver. Each of these dictionaries contains configurations which the user can specify. The lists below contain a complete list of configurations for each dictionary.

Analysis¶

The dataset, the objective function and the solver are selected in the analysis dictionary of config.json. The following table summarizes the available analysis settings and their default values:

Table 3 Analysis Settings¶
Key	Type	Default Value	Description
`dataset`	`str`	`str()`	folder name of the dataset to be used
`objective`	`str`	`total_cost`	select the objective function. Options are: `total_cost`, i.e. net-present cost, and `total_carbon_emissions`
`sense`	`str`	`min`	sense of the optimization. Options are: `min` and `max`
`folder_output`	`str`	`./outputs/`	folder where the output files will be saved
`overwrite_output`	`bool`	`True`	if true, overwrite existing files in the output folder
`output_format`	`str`	`h5`	output format of the optimization results. Currently only `h5` is supported
`time_series_aggregation`	`TimeSeriesAggregation`	`TimeSeriesAggregation()`	additional settings for the time series aggregation algorithm
`earliest_year_of_data`	`int`	`1900`	earliest possible year of input data
`zen_garden_version`	`str`	`None`	version of ZEN-garden, will be filled out automatically

The settings of the timeseries aggregation algorithm are also specified in the analysis section. The following table summarizes the available timeseries aggregation settings and their default values. For further information on how to use the timeseries aggregation, see Using time series aggregation. In addition, Tutorial 5: Time Series Aggregation and The time parameters in ZEN-garden provide helpful information on the time representation and the time parameters in ZEN-garden.

Table 4 Timeseries Aggregation Settings¶
Key	Type	Default Value	Description
`slv`	`Solver`	`Solver()`	specify the solver settings. Per default the solver settings are used
`clusterMethod`	`str`	`hierarchical`	select the clustering method. Per default the hierarchical clustering is used. Other options are
`solver`	`str`	`slv.name`	select a solver. Per default the solver specified in the solver settings is used.
`hoursPerPeriod`	`int`	`1`	specify the length of a period in hours. ZEN-garden clusters representative time steps, so do not change the value unless you know what you are doing
`extremePeriodMethod`	`Optional[str]`	`None`	select the extreme period method
`rescaleClusterPeriods`	`bool`	`False`	rescale cluster periods
`representationMethod`	`str`	`meanRepresentation`	select the representation method
`resolution`	`int`	`1`	select the resolution. Do not change this value unless you know what you are doing

Solver¶

Solver settings are also specified in the config.json. The following table summarizes the available solver settings and their default values.

Table 5 Solver Settings¶
Key	Type	Default Value	Description
`name`	`str`	`highs`	select solver
`solver_options`	`SolverOptions`	`SolverOptions()`	pass solver options to the selected solver
`save_duals`	`bool`	`False`	if true, dual variables are computed, otherwise, computation of dual variables is skipped
`save_reduced_costs`	`bool`	`False`	if true, reduced costs are computed, otherwise, computation of reduced costs is skipped
`save_parameters`	`bool`	`True`	if true, parameters are saved, otherwise, parameters are not saved
`selected_saved_parameters`	`list[str]`	[]	list of parameters to save. If empty, all parameters are saved.
`selected_saved_variables`	`list[str]`	[]	list of variables to save. If empty, all variables are saved.
`selected_saved_duals`	`list[str]`	[]	list of duals to save. If empty, all duals are saved. (only if `save_duals` is `True`).
`selected_saved_reduced_costs`	`list[str]`	[]	list variables for which reduced costs are saved. If empty, all reduced costs are saved. (only if `save_reduced_costs` is `True`).
`solver_dir`	`str`	`.//outputs//solver_files`	folder path where solver log files are (temporarily) saved
`keep_files`	`bool`	`False`	if true, solver log files are saved, otherwise solver log files are deleted after each run
`io_api`	`str`	`lp`	api that is used to pass the optimization problem to the solver, must be `lp`, `mps`, or `direct`
`check_unit_consistency`	`bool`	`True`	check for unit consistency in the input data. IMPORTANT: Only disable, if you know exactly what you are doing
`analyze_numerics`	`bool`	`True`	print numerics of the optimization problem
`run_diagnostics`	`bool`	`False`	If true, additional data such as solving time, number of iterations etc. will be saved and model creation data will be printed
`use_scaling`	`bool`	`True`	if true, scaling algorithm is applied to improve the numerics of the optimization problem
`scaling_include_rhs`	`bool`	`True`	if true, the right-hand-side (rhs) is included in the scaling algorithm
`scaling_algorithm`	`Union[list[str],str]`	`['geom','geom','geom']`	specify which scaling algorithms should be used. The length of the list defines the number of iterations. Per default three iterations of `geom` are conducted
`round_parameters`	`bool`	`False`	specify whether to round parameters
`rounding_decimal_points_capacity`	`int`	`4`	specify the rounding decimal points for capacities value if `round_parameters` is `True`
`rounding_decimal_points_tsa`	`int`	`4`	specify the rounding decimal points used in the timeseries aggregation if `round_parameters` is `True`
`rounding_decimal_points_units`	`int`	`6`	specify the rounding decimal points for the unit conversions
`linear_regression_check`	`dict[str, float]`	`{'eps_intercept': 0.1, 'epsRvalue': 1 - (1e-5)}`	settings of the linear regression checking if a piecewise affine linearization is needed

Per default the open-source solver HiGHS is used. You can change the solver by modifying the solver key. Solver-specific settings are passed via the solver_settings. Please refer to the solver documentation for the available solver settings for the solver that you are using.

For linear optimization problems, the dual variables can be computed and saved by selecting save_duals=True. Saving the duals helps understand the optimality of the solution, but it also strongly increases the file size of the output files. Reduced costs can be saved by setting save_reduced_costs=True. This can increase significantly the file size of output files. The parameters of the optimization problem can be saved by selecting save_parameters=True. If you only want to save specific parameters, you can specify them in the selected_saved_parameters list. The same applies to the variables, duals and reduced costs, which can be specified in the selected_saved_variables, selected_saved_duals, and selected_saved_reduced_costs lists, respectively. The name of the duals corresponds to the name of the constraints.

Note

Non-selected parameters, variables, reduced costs and duals are not saved. We recommend to only use the option if you are sure that you do not need them. The visualization platform may not work properly if you do not save the parameters and variables.

You can analyze the numerics of your optimization problem via analyze_numerics. In addition, a scaling algorithm is available. Per default, four iterations of the scaling algorithm are conducted without including the values of the right-hand-side. Tutorial 7: Scaling provides a detailed description of the scaling algorithm.

Plugins¶

Activating plugins and passing configurations to plugins is done by modifying the plugins key in the config.json. The key name corresponds to the plugin name to be activated. the dictonary under this key defines the configuration for the plugin.