zen_garden.utils

Class is defining to read in the results of an Optimization problem.

Functions

align_like(da, other[, fillna, astype])

Aligns a data array like another data array.

download_example_dataset(dataset)

Downloads a dataset example to the current working directory.

get_inheritors(klass)

Get all child classes of a given class.

get_label_position(obj, label)

Get dict of index and coordinate for variable or constraint labels.

linexpr_from_tuple_np(tuples, coords, model)

Transforms tuples of (coeff, var) into a linopy linear expression.

lp_sum(exprs[, dim])

Sum of linear expressions with lp.expressions.merge, returns 0 if list is emtpy.

reformat_slicing_index(index, component)

Reformats the slicing index to a tuple of strings that is readable by pytables :param index: slicing index of the resulting dataframe :param component: component for which the index is reformatted :return: reformatted index.

setup_logger([level])

Set up logger.

slice_df_by_index(df, index_tuple)

Recreate the slicing index from a tuple of strings and slice the dataframe.

xr_like(fill_value, dtype, other, dims)

Create an xarray with fill value and dtype like the other object.

Classes

IISConstraintParser(iis_file, model)

This class is used to parse the IIS constraints and print them in a nice way Most functions here are just copied from linopy 0.2.x.

InputDataChecks(config, optimization_setup)

This class checks if the input data (folder/file structure, system.py settings, element definitions, etc.) is defined correctly.

ScenarioDict(init_dict, optimization_setup, ...)

Dictionary for the scenario analysis that has some convenience functions.

ScenarioUtils()

This class handles some stuff for scenarios to tidy up scripts.

StringUtils()

This class handles strings for logging and filenames to tidy up scripts.

Exceptions

OptimizationError([status])

Exception raised when the optimization problem is infeasible.
class zen_garden.utils.IISConstraintParser(iis_file, model)

This class is used to parse the IIS constraints and print them in a nice way Most functions here are just copied from linopy 0.2.x.

__init__(iis_file, model)

Initializes the IIS constraint parser.

Parameters:

  • iis_file – The file containing the IIS

  • model – The model to which the IIS belongs

static get_label_position(constraints, value)

Get tuple of name and coordinate for variable labels.

Parameters:

  • constraints – The constraints object

  • value – The value to get the label for

Returns:

The name and coordinate of the variable

static print_coord(coord)

Print the coordinates.

Parameters:

coord – The coordinates to print

Returns:

The string representation of the coordinates

print_single_constraint(constraint, coord)

Print a single constraint based on the constraint object.

Parameters:

  • constraint – The constraint object

  • coord – The coordinates of the constraint

Returns:

The string representation of the constraint

static print_single_expression(c, v, model)

This is a linopy routine but without max terms Print a single linear expression based on the coefficients and variables.

Parameters:

  • c – The coefficients of the expression

  • v – The variables of the expression

  • model – The model to which the expression belongs

Returns:

The string representation of the expression

read_labels()

Reads the labels from the IIS file.

Returns:

A list of labels

write_gurobi_iis()

Writes IIS to file.

write_parsed_output(outfile=None)

Writes the parsed output to a file.

Parameters:

outfile – The file to write to

class zen_garden.utils.InputDataChecks(config, optimization_setup)

This class checks if the input data (folder/file structure, system.py settings, element definitions, etc.) is defined correctly.

__init__(config, optimization_setup)

Initialize the class.

Parameters:

  • config – config object used to extract the analysis, system and solver dictionaries

  • optimization_setup – OptimizationSetup instance

static check_carrier_configuration(input_carrier, output_carrier, reference_carrier, name)

Check the chosen input/output/reference carrier combination.

Parameters:

  • input_carrier – input carrier of conversion technology

  • output_carrier – output carrier of conversion technology

  • reference_carrier – reference carrier of technology

  • name – name of conversion technology

check_dataset()

Ensures that the dataset chosen in the config does exist and contains a system.py file.

static check_duplicate_indices(df_input, file_name, folder_path)

Checks if df_input contains any duplicate indices and either removes them if they are of identical value or raises an error otherwise.

Parameters:

  • df_input – raw input dataframe

  • folder_path – the path of the folder containing the selected file

  • file_name – name of selected file

Returns:

df_input without duplicate indices

check_existing_carrier_data()

Checks the existing carrier data and only regards those carriers for which folders exist.

check_existing_technology_data()

This method checks the existing technology input data and only regards those technology elements for which folders containing the attributes.json file exist.

check_no_extra_config_fields(config, config_name='config')

Checks if the config object has no extra fields that are not defined in the default_config.

check_primary_folder_structure()

Checks if the primary folder structure (set_conversion_technology, set_transport_technology, …, energy_system) is provided correctly.

check_single_directed_edges(set_edges_input)

Checks if single-directed edges exist in the dataset (e.g. CH-DE exists, DE-CH doesn’t) and raises a warning.

Parameters:

set_edges_input – DataFrame containing set of edges defined in set_edges.csv

check_technology_selections()

Checks selection of different technologies in system.py file.

check_year_definitions()

Check if year-related parameters are defined correctly.

read_system_file(config)

Reads the system file and returns the system dictionary.

Parameters:

config – config object

exception zen_garden.utils.OptimizationError(status='The optimization is infeasible or unbounded, or finished with an error')

Exception raised when the optimization problem is infeasible.

__init__(status='The optimization is infeasible or unbounded, or finished with an error')

Initializes the class.

Parameters:

status – The message to display

class zen_garden.utils.ScenarioDict(init_dict, optimization_setup, paths)

Dictionary for the scenario analysis that has some convenience functions.

__init__(init_dict, optimization_setup, paths)

Initializes the dictionary from a normal dictionary.

Parameters:

  • init_dict – The dictionary to initialize from

  • optimization_setup – The optimization setup corresponding to the scenario

  • paths – The paths to the elements

static check_if_all_elements_in_model(scenario_dict, element_dict)

Checks if all elements in scenario_dict are present in the element_dict.

This is used to ensure that all elements in the scenario are defined in the model.

Parameters:

  • scenario_dict – Dictionary containing the scenario elements

  • element_dict – Dictionary containing the element definitions

static expand_lists(scenarios: dict)

Expand parameter lists in the all scenarios and return a new dict.

Parameters:

scenarios (dict) – The initial dict of scenarios

Returns:

The expanded dict, where all necessary parameters are expanded and subpaths are set

Return type:

dict

expand_subsets(init_dict)

Expands a dictionary, e.g. expands sets etc.

Parameters:

init_dict – The initial dict

Returns:

A new dict which can be used for the scenario analysis

get_default(element, param)

Return the name where the default value should be read out.

Parameters:

  • element – The element name

  • param – The parameter of the element

Returns: If the entry is overwritten by the scenario analysis the entry

and factor are returned, otherwise the default entry is returned with a factor of 1

get_param_file(element, param)

Return the file name where the parameter values should be read out.

Parameters:

  • element – The element name

  • param – The parameter of the element

Returns:

If the entry is overwritten by the scenario analysis the entry and factor are returned, otherwise the default entry is returned with a factor of 1

get_param_part_file(element, param)

Return the partial file name where the parameter values should be read out.

Parameters:

  • element – the element name

  • param – the parameter of the element for which the partial file name is returned

Returns:

If the entry is overwritten by the scenario analysis the entry, otherwise None.

update_config()

Updates the analysis, system, and solver in the config.

validate_dict(vali_dict)

Validates a dictionary, raises an error if it is not valid.

Parameters:

vali_dict – The dictionary to validate

static validate_file_name(fname)

Checks if the file name has an extension.

It is expected to not have an extension.

Parameters:

fname – The file name to validte

Returns:

The validated file name

class zen_garden.utils.ScenarioUtils

This class handles some stuff for scenarios to tidy up scripts.

__init__()

Initializes the class.

static clean_scenario_folder(config, out_folder)

Cleans scenario dict when overwritten.

Parameters:

  • config – config of optimization

  • out_folder – output folder

static get_scenarios(config, job_index)

Retrieves and overwrites the scenario dicts.

Parameters:

  • config – config of optimization

  • job_index – index of current job, if passed

Returns:

scenarios of optimization

Returns:

elements in scenario

static scenario_string(scenario)

Creates additional scenario string.

Parameters:

scenario – scenario name

Returns:

scenario string

class zen_garden.utils.StringUtils

This class handles strings for logging and filenames to tidy up scripts.

__init__()

Initializes the class.

classmethod generate_folder_path(config, scenario, scenario_dict, steps_horizon, step)

Generates the folder path for the results.

Parameters:

  • config – config of optimization

  • scenario – name of scenario

  • scenario_dict – current scenario dict

  • steps_horizon – all steps of horizon

  • step – current step of horizon

Returns:

scenario name in folder

Returns:

subfolder in results file

Returns:

mapping of parameters

static get_output_folder(analysis)

Return name of output folder.

Parameters:

analysis – analysis of optimization

Returns:

output folder

classmethod print_optimization_progress(scenario, steps_horizon, step, system)

Prints the current optimization progress.

Parameters:

  • scenario – string of scenario name

  • steps_horizon – all steps of horizon

  • step – current step of horizon

  • system – system of optimization

classmethod setup_model_folder(analysis, system)

Return model name while conducting some tests.

Parameters:

  • analysis – analysis of optimization

  • system – system of optimization

Returns:

model name

Returns:

output folder

classmethod setup_output_folder(analysis, system)

Return model name while conducting some tests.

Parameters:

  • analysis – analysis of optimization

  • system – system of optimization

Returns:

output folder

zen_garden.utils.align_like(da, other, fillna=0.0, astype=None)

Aligns a data array like another data array.

Parameters:

  • da – The data array to align

  • other – The data array to align to

  • fillna – The value to fill na values with

  • astype – The type to cast the data array to

Returns:

The aligned data array

zen_garden.utils.download_example_dataset(dataset)

Downloads a dataset example to the current working directory. The function downloads the ZEN-garden dataset examples from the ZEN-garden Zenodo repository. It then extracts the dataset specified by the user and saves it to the current working directory. In addition, it also downloads a config.json file and a Jupyter notebook demonstrating how to analyze the results of a model.

Parameters:

dataset (str) – Name of the dataset to be downloaded. The following options are currently available: “1_base_case”, “2_multi_year_optimization”, “3_reduced_import_availability”, “4_PWA_nonlinear_capex”, “5_multiple_time_steps_per_year”, “6_reduced_import_availability_yearly”, “7_time_series_aggregation”, “8_yearly_variation”, “9_myopic_foresight”, “10_brown_field”, “11_multi_scenario”, “12_multiple_in_output_carriers_conversion”, “13_yearly_interpolation”, “14_retrofitting_and_fuel_substitution”, “15_unit_consistency_expected_error”

Returns:

str: The local path of the copied example str: The local path of the copied config.json

Return type:

tuple

Raises:

FileNotFoundError – If either the dataset or the config file could not be found in the Zenodo repository.

Examples

Basic usage example:

>>> from zen_garden.dataset_examples import download_dataset_example
>>> download_dataset_example("1_base_case")
zen_garden.utils.get_inheritors(klass)

Get all child classes of a given class.

Parameters:

klass – The class to get all children

Returns:

All children as a set

zen_garden.utils.get_label_position(obj, label: int)

Get dict of index and coordinate for variable or constraint labels.

zen_garden.utils.linexpr_from_tuple_np(tuples, coords, model)

Transforms tuples of (coeff, var) into a linopy linear expression.

Uses numpy broadcasting.

Parameters:

  • tuples – Tuple of (coeff, var)

  • coords – The coordinates of the final linear expression

  • model – The model to which the linear expression belongs

Returns:

A linear expression

zen_garden.utils.lp_sum(exprs, dim='_term')

Sum of linear expressions with lp.expressions.merge, returns 0 if list is emtpy.

Parameters:

  • exprs – The expressions to sum

  • dim – Along which dimension to merge

Returns:

The sum of the expressions

zen_garden.utils.reformat_slicing_index(index, component) → tuple[str]

Reformats the slicing index to a tuple of strings that is readable by pytables :param index: slicing index of the resulting dataframe :param component: component for which the index is reformatted :return: reformatted index.

zen_garden.utils.setup_logger(level=20)

Set up logger.

Parameters:

level – logging level

zen_garden.utils.slice_df_by_index(df, index_tuple) → dict

Recreate the slicing index from a tuple of strings and slice the dataframe.

Parameters:

  • df – dataframe to be sliced

  • index_tuple – tuple of strings representing the slicing index

Returns:

sliced dataframe.

zen_garden.utils.xr_like(fill_value, dtype, other, dims)

Create an xarray with fill value and dtype like the other object.

Only contains the given dimensions.

Parameters:

  • fill_value – The value to fill the data with

  • dtype – dtype of the data

  • other – The other object to use as base

  • dims – The dimensions to use

Returns:

An object like the other object but only containing the given dimensions