ZEN-garden: Zero emissions Energy Networks

https://zen-garden.readthedocs.io/en/latest/
Admin
ZEN-garden is a project for Zero emissions Energy Networks, offering comprehensive documentation...
Tokens:97,216
Snippets:1,088
Trust Score:9.6
Update:3 months ago
Show doc for...
Tokens:
Raw
### Setup and Install Pre-commit Hooks

Source: https://zen-garden.readthedocs.io/en/latest/files/developer_guide/contributing.html

Install the development dependencies and set up pre-commit hooks. These hooks will automatically run Ruff and Black before each commit.

```bash
pip install -e[dev]
pre-commit install
```

--------------------------------

### Run ZEN-garden with example dataset

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.runner.html

Demonstrates how to download an example dataset and then run ZEN-garden using that dataset. Ensure the example dataset is downloaded before calling the run function.

```python
>>> from zen_garden import run, download_example_dataset
>>> download_example_dataset("1_base_case")
>>> run("1_base_case")

```

--------------------------------

### Download Example Dataset

Source: https://zen-garden.readthedocs.io/en/latest/files/quick_start/building_models.html

Download a specific example dataset, such as '1_base_case', to use as a template for your model. You can change the --dataset argument to download other available examples.

```bash
zen-example --dataset="1_base_case"
```

--------------------------------

### List Installed Packages

Source: https://zen-garden.readthedocs.io/en/latest/files/quick_start/installation.html

Verify the ZEN-garden installation by listing all installed packages in the current environment. 'zen_garden' should appear in the output.

```bash
conda list

```

--------------------------------

### Run ZEN-garden Example via Command Line

Source: https://zen-garden.readthedocs.io/en/latest/files/quick_start/summary.html

Use these commands to download an example dataset, run ZEN-garden, and open the visualization platform. The visualization platform can be accessed at http://localhost:8000/.

```bash
zen-example --dataset="1_base_case"
zen-garden --dataset="1_base_case"
zen-visualization
```

--------------------------------

### Download Example Dataset with zen_garden.utils

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.utils.html

Downloads a specified dataset example from the ZEN-garden Zenodo repository to the current working directory. It also downloads a config.json file and a demonstration Jupyter notebook.

```python
from zen_garden.dataset_examples import download_dataset_example
download_dataset_example("1_base_case")
```

--------------------------------

### Run ZEN-garden Example via Python Script

Source: https://zen-garden.readthedocs.io/en/latest/files/quick_start/summary.html

This Python script downloads an example dataset, runs ZEN-garden, and uses the Results class to analyze model outputs, specifically extracting total capacity.

```python
from zen_garden import download_example_dataset, run, Results

# dataset name
dataset = "1_base_case"

# download example dataset to current working directory
download_example_dataset(dataset)

# run ZEN-garden
run(dataset=dataset)

# load results
r = Results(f"./outputs/{dataset}")

# extract optimal capacities
print(r.get_total("capacity"))
```

--------------------------------

### zen_garden.utils.download_example_dataset

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.utils.html

Downloads example datasets, configuration files, and demonstration notebooks from the ZEN-garden Zenodo repository.

```APIDOC
## download_example_dataset

### Description
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

### Raises
- **FileNotFoundError**: If either the dataset or the config file could not be found in the Zenodo repository.

### Examples
Basic usage example:
```python
>>> from zen_garden.dataset_examples import download_dataset_example
>>> download_dataset_example("1_base_case")
```
```

--------------------------------

### Basic ZEN-garden CLI Usage Example

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.cli.zen_garden_cli.html

Demonstrates a basic command-line invocation of ZEN-garden, specifying a configuration file and a dataset.

```bash
zen-garden --config=".\config.json" --dataset="1_base_case"
```

--------------------------------

### download_example_dataset

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.utils.html

Downloads a specified example dataset to the current working directory.

```APIDOC
## download_example_dataset

### Description
Downloads a dataset example to the current working directory.

### Parameters
* **dataset** (str) - The name of the dataset to download.

### Returns
None
```

--------------------------------

### Class Docstring Template

Source: https://zen-garden.readthedocs.io/en/latest/files/developer_guide/documentation.html

Use this template for documenting classes. Include a one-line summary, detailed description of purpose, setup, features, and important attributes/methods. Document arguments, potential exceptions, related classes/functions, and provide an example. 'Todo' items are for internal notes.

```python
"""
One-line summary of the class.

One or more paragraphs describing the high-level structure and function
of the class. The following information should be included:

(1) what is the overall function of the class, i.e. why was it created?
(2) how is the class set up? What are the structures and basic principles
of the class? This description should allow new developers to be able
to scroll through the class and understand the basic function and setup.
(3) What features does the class have? This description should enable new
developers to identify whether a class is relevant for their programming
task.
(4) what are the most important attributes of the class? Do any rules govern
these attributes? These can also be listed under the attributes section
below.
(5) what are the most important methods of the class? Do these follow any
specific logic?

Attributes:
    attr1 (type): Description of `attr1`. Make sure to properly indent each
        new line by four spaces when using multi-line descriptions.
    attr2 (type): Description of `attr2`.

Args:
    param1 (type): Description of `param1`. Parameters include any inputs
        to the __init__ function.
    param2 (type, optional): Description of `param2`. Defaults to None.

Raises:
    ValueError: Outline conditions under which error is raised.
    RuntimeError: Outline conditions under which error is raised.

See Also:
    RelatedClass: List all inherited classes here and give a brief
        explanation why.
    relatedfunction(): List all related functions here and give a
        brief explanation of the relationship.

Example:
    Example usage of the class.

    >>> obj = ClassName(param1, param2)
    >>> obj.method1("value")

Todo:
    - List items here.
    - These will not appear in the online documentation
"""

```

--------------------------------

### Basic Usage of zen-example CLI

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.cli.zen_example_cli.html

Demonstrates the basic command-line usage for downloading a dataset example. Specify the dataset name using the `--dataset` argument.

```bash
>>> zen-example --dataset="1_base_case"

```

--------------------------------

### Get storage level start and end time steps

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.postprocess.results.solution_loader.html

Returns a dictionary mapping years to time steps that define the start and end of storage levels. This is crucial for analyzing storage components within the solution.

```python
solution_loader.get_time_steps_storage_level_startend_year(scenario)
```

--------------------------------

### Install ZEN-garden Package

Source: https://zen-garden.readthedocs.io/en/latest/files/quick_start/installation.html

Install the ZEN-garden Python package using pip after activating the conda environment.

```bash
pip install zen-garden

```

--------------------------------

### Unit Conversion Calculation Example

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/06_unit_handling.html

This example demonstrates the calculation of a conversion multiplier between two units, Euro/MWh and Euro/GW/hour. It shows how to derive the multiplier by comparing their dimensionalities.

```text
Euro/MWh
=> [currency]^1 [mass]^-1 [length]^-2 [time]^2
= [currency]^1 [[mass]^1 [length]^2 [time]^-3]^-1 [time]^-1
=> Euro/GW/hour

(Euro/GW/hour)/(Euro/MWh) = (MW)/(GW) = 0.001
```

--------------------------------

### Install pycallgraph2 and graphviz

Source: https://zen-garden.readthedocs.io/en/latest/files/developer_guide/tips_and_tricks.html

Install the necessary packages for creating call graphs using Anaconda. Ensure the ZEN-garden environment is activated before running these commands.

```bash
conda install -c conda-forge graphviz
conda install conda-forge::pycallgraph2
```

--------------------------------

### Run Operation-Only Example

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/08_operation_only.html

Execute the operation-only version of the example dataset. This command runs a single operational scenario using default parameter values.

```bash
zen-garden --dataset="5_multiple_time_steps_per_year"
zen-operation --dataset="5_multiple_time_steps_per_year"
zen-visualization

```

--------------------------------

### InputDataChecks.__init__

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.utils.html

Initializes the InputDataChecks class with configuration and optimization setup.

```APIDOC
## InputDataChecks.__init__

### Description
Initialize the class.

### Parameters
* **config** – config object used to extract the analysis, system and solver dictionaries.
* **optimization_setup** – OptimizationSetup instance.
```

--------------------------------

### Create ZEN-garden Conda Environment

Source: https://zen-garden.readthedocs.io/en/latest/files/developer_guide/installation.html

Install the conda environment for ZEN-garden using the provided YAML file. This command installs the package and all its dependencies.

```bash
conda env create -f zen_garden_env.yml
```

--------------------------------

### Basic zen-visualization CLI Usage

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.cli.zen_visualization_cli.html

This example shows how to invoke the zen-visualization CLI from a command line prompt. Ensure the `zen-visualization` command is available in your system's PATH.

```bash
>>> zen-visualization

```

--------------------------------

### Example: Overwriting Time-Dependent Parameter

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/04_scenario_analysis.html

This example shows how to overwrite a time-dependent parameter like `demand_yearly_variation` by specifying a file for it.

```json
{"example": {
    "electricity": {
        "demand_yearly_variation":{
            "file":"demand_yearly_variation_high"
            }
        }
    }


```

--------------------------------

### Example: High Gas Price Scenario

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/04_scenario_analysis.html

This example demonstrates how to define a scenario named 'high_gas_price' to adjust the import price of natural gas using multiple overwriting options.

```json
{"high_gas_price":
    {"natural_gas":
        {"price_import": {
            "default": "attributes_high",
            "default_op": 1.5,
            "file": "price_import_high",
            "part_file": "price_import_high_part",
            "file_op": 0.9
            }
        }
    }
}

```

--------------------------------

### Basic Time Parameters Configuration

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/05_time_series_aggregation.html

Configure the reference year, number of years to optimize, and the interval between these years for a standard optimization setup.

```json
"reference_year": 2020,
"optimized_years": 4,
"interval_between_years": 10

```

--------------------------------

### Adding a New Parameter to the Optimization Setup

Source: https://zen-garden.readthedocs.io/en/latest/files/developer_guide/adding_param_variable_constraint.html

Call this method within the `construct_params` classmethod to add a newly defined parameter to the optimization setup. Ensure the name matches the one used in `store_input_data` and specify relevant index names and a documentation string.

```python
optimization_setup.parameters.add_parameter(
    name="availability_import_yearly",
    index_names=["set_carriers", "set_nodes", "set_time_steps_yearly"],
    doc='Parameter which specifies the maximum energy that can be imported from outside the system boundaries for the entire year',
    calling_class=cls)

```

--------------------------------

### Navigate to ZEN-garden Docs Directory

Source: https://zen-garden.readthedocs.io/en/latest/files/developer_guide/documentation.html

Change the current directory to the docs folder within the ZEN-garden installation. This is a prerequisite for building the documentation.

```bash
cd <path-to-ZEN-garden>\docs

```

--------------------------------

### Example IIS Output in ZEN-garden

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/09_handle_infeasibilities.html

This output represents an Irreducible Inconsistent Subsystem (IIS) generated by ZEN-garden for an infeasible Gurobi model. It details the constraints and their specific components that collectively lead to the infeasibility.

```text
constraint_availability_import:
    [heat, CH, 0]:    1.0 flow_import[heat, CH, 0] <= 0
    [heat, DE, 0]:    1.0 flow_import[heat, DE, 0] <= 0
    [natural_gas, CH, 0]:    1.0 flow_import[natural_gas, CH, 0] <= 0
    [natural_gas, DE, 0]:    1.0 flow_import[natural_gas, DE, 0] <= 0

constraint_cost_shed_demand:
    [heat, CH, 0]:  1.0 shed_demand[heat, CH, 0] = 0
    [heat, DE, 0]:  1.0 shed_demand[heat, DE, 0] = 0
    [natural_gas, CH, 0]:   1.0 shed_demand[natural_gas, CH, 0] = 0
    [natural_gas, DE, 0]:   1.0 shed_demand[natural_gas, DE, 0] = 0

constraint_nodal_energy_balance:
    [heat, CH, 0]:  1.0 flow_conversion_output[natural_gas_boiler, heat, CH, 0] + 1.0 flow_import[heat, CH, 0] - 1.0 flow_export[heat, CH, 0] + 1.0 shed_demand[heat, CH, 0] = 10
    [heat, DE, 0]:  1.0 flow_conversion_output[natural_gas_boiler, heat, DE, 0] + 1.0 flow_import[heat, DE, 0] - 1.0 flow_export[heat, DE, 0] + 1.0 shed_demand[heat, DE, 0] = 100
    [natural_gas, CH, 0]:   -1.0 flow_conversion_input[natural_gas_boiler, natural_gas, CH, 0] + 1.0 flow_transport[natural_gas_pipeline, DE-CH, 0] - 1.0 flow_transport_loss[natural_gas_pipeline, CH-DE, 0] - 1.0 flow_transport[natural_gas_pipeline, CH-DE, 0] - 1.0 flow_storage_charge[natural_gas_storage, CH, 0] + 1.0 flow_storage_discharge[natural_gas_storage, CH, 0] + 1.0 flow_import[natural_gas, CH, 0] - 1.0 flow_export[natural_gas, CH, 0] + 1.0 shed_demand[natural_gas, CH, 0] = 0
    [natural_gas, DE, 0]:   -1.0 flow_conversion_input[natural_gas_boiler, natural_gas, DE, 0] + 1.0 flow_transport[natural_gas_pipeline, CH-DE, 0] - 1.0 flow_transport_loss[natural_gas_pipeline, DE-CH, 0] - 1.0 flow_transport[natural_gas_pipeline, DE-CH, 0] - 1.0 flow_storage_charge[natural_gas_storage, DE, 0] + 1.0 flow_storage_discharge[natural_gas_storage, DE, 0] + 1.0 flow_import[natural_gas, DE, 0] - 1.0 flow_export[natural_gas, DE, 0] + 1.0 shed_demand[natural_gas, DE, 0] = 0

constraint_carrier_conversion:
    [natural_gas_boiler, natural_gas, CH, 0]:       1.0 flow_conversion_input[natural_gas_boiler, natural_gas, CH, 0] - 1.1 flow_conversion_output[natural_gas_boiler, heat, CH, 0] = 0
    [natural_gas_boiler, natural_gas, DE, 0]:       1.0 flow_conversion_input[natural_gas_boiler, natural_gas, DE, 0] - 1.1 flow_conversion_output[natural_gas_boiler, heat, DE, 0] = 0

constraint_couple_storage_level:
    [natural_gas_storage, CH, 0]:   1.0 storage_level[natural_gas_storage, CH, 0] - 1.0 storage_level[natural_gas_storage, CH, 0] - 0.9747 flow_storage_charge[natural_gas_storage, CH, 0] + 1.026 flow_storage_discharge[natural_gas_storage, CH, 0] = 0
    [natural_gas_storage, DE, 0]:   1.0 storage_level[natural_gas_storage, DE, 0] - 1.0 storage_level[natural_gas_storage, DE, 0] - 0.9747 flow_storage_charge[natural_gas_storage, DE, 0] + 1.026 flow_storage_discharge[natural_gas_storage, DE, 0] = 0

constraint_transport_technology_losses_flow:
    [natural_gas_pipeline, CH-DE, 0]:       1.0 flow_transport_loss[natural_gas_pipeline, CH-DE, 0] - 0.0255 flow_transport[natural_gas_pipeline, CH-DE, 0] = 0
    [natural_gas_pipeline, DE-CH, 0]:       1.0 flow_transport_loss[natural_gas_pipeline, DE-CH, 0] - 0.0255 flow_transport[natural_gas_pipeline, DE-CH, 0] = 0

```

--------------------------------

### Navigate to Data Directory

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/01_analyze_outputs.html

Use this command in the terminal to change the current directory to the 'data' folder containing input and output files for the example model.

```bash
cd /path/to/your/data

```

--------------------------------

### Postprocess Class

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.postprocess.postprocess.html

Initializes the Postprocess class for handling optimization results. It takes the optimization setup, scenarios, model name, and optional subfolder, scenario name, and parameter map as input.

```APIDOC
## Postprocess.__init__()

### Description
Initializes the Postprocess class for handling optimization results.

### Parameters
* **optimization_setup** (OptimizationSetup_) - The optimization setup.
* **scenarios** (scenarios) - The scenarios.
* **model_name** (model_name) - The name of the model used to name the output folder.
* **subfolder** (subfolder, optional) - The subfolder used for the results.
* **scenario_name** (scenario_name, optional) - The name of the current scenario.
* **param_map** (param_map, optional) - A dictionary mapping the parameters to the scenario names.
```

--------------------------------

### Run ZEN-garden Model from Python Script

Source: https://zen-garden.readthedocs.io/en/latest/files/quick_start/running_models.html

Execute a ZEN-garden model programmatically using the Python API. Ensure ZEN-garden is installed in the environment.

```python
from zen_garden import run
import os

os.chdir("<data>")
run(dataset = "1_base_case")
```

--------------------------------

### Install Pre-commit Hooks

Source: https://zen-garden.readthedocs.io/en/latest/files/developer_guide/installation.html

Set up the pre-commit hooks in your newly created conda environment. This helps maintain code quality by running checks before commits.

```bash
pre-commit install
```

--------------------------------

### Input, Output, and Reference Carriers Example

Source: https://zen-garden.readthedocs.io/en/latest/files/zen_garden_in_detail/input_structure.html

Defines the input, output, and reference energy carriers for a technology. These attributes accept a list of strings, as technologies can have multiple input or output carriers.

```json
"reference_carrier": {
  "default_value": [
    "ammonia"
  ]
},
"input_carrier": {
  "default_value": [
    "hydrogen",
    "electricity"
  ]
},
"output_carrier": {
  "default_value": [
    "ammonia"
  ]
}
```

--------------------------------

### Get System Configurations

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.postprocess.results.results.html

Extracts system configurations from a specified scenario. If no scenario name is provided, it defaults to the first scenario. This is useful for ensuring the tractability of model configurations.

```python
from zen_garden.postprocess.results.results import Results
r = Results(path='<result_folder>')
r.get_system() # system configurations of first scenario
r.get_system('scenario_name') # system configuration of "scenario_name"
```

--------------------------------

### Check Conda Installation

Source: https://zen-garden.readthedocs.io/en/latest/files/quick_start/installation.html

Verify if Anaconda is installed on your system by checking its version.

```bash
conda --version

```

--------------------------------

### Set and List Expansion Example

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/04_scenario_analysis.html

Demonstrates how list expansion is performed first when both set and list expansion are used. This results in scenarios where 'file_op' values are applied simultaneously across technologies, excluding specified carriers.

```json
{
    "example": {
        "set_carriers": {
            "price_import": {
                "file_op": [1.5, 2.5, 3.5],
                "exclude": ["carrier1", "carrier2"]
            }
        }
    }
}

```

--------------------------------

### setup_logger

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.utils.html

Sets up the logger with a specified logging level.

```APIDOC
## setup_logger

### Description
Set up logger.

### Parameters
* **level** (int, optional) - The logging level. Defaults to None.

### Returns
logging.Logger - The configured logger object.
```

--------------------------------

### Add Non-Indexed Set to Optimization Setup

Source: https://zen-garden.readthedocs.io/en/latest/files/developer_guide/adding_param_variable_constraint.html

Use this method to add a set that is not indexed by any other set. Ensure the name is unique within the optimization setup.

```python
optimization_setup.sets.add_set(
    name="set_conversion_technologies",
    data=energy_system.set_conversion_technologies,
    doc="Set of conversion technologies")
```

--------------------------------

### Run Visualization Platform

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/01_analyze_outputs.html

Execute this command in the terminal after activating the ZEN-garden environment to launch the visualization platform. It will typically open in a new browser tab.

```bash
zen-visualization

```

--------------------------------

### Get component by name

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.postprocess.results.solution_loader.html

Retrieves a specific component object from a scenario using its name. Ensure the component name is accurate to get the correct component details.

```python
scenario.get_component(component_name)
```

--------------------------------

### Run Original Model via Command Line

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/08_operation_only.html

Execute the original ZEN-garden model using the command line. Ensure you are in the correct directory and specify the dataset.

```bash
cd "<data>"
zen-garden --dataset="<dataset>"
```

--------------------------------

### List Expansion for System and Analysis Settings

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/04_scenario_analysis.html

Illustrates using list expansion for system and analysis settings when no files are read. The syntax differs slightly from parameter list expansion.

```json
{
    "example": {
        "system": {
            "key": {
                "value": [1, 2, 3],
                "value_fmt": "new_value_{}"
                }
            }
        }
    }
}

```

--------------------------------

### Run Visualization Platform with Custom Output Folder

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/01_analyze_outputs.html

Use this command to specify an alternative folder for solutions if they are not located in the default './outputs' directory. Replace '<path to your solutions folder>' with the actual path.

```bash
zen-visualization -o <path to your solutions folder>

```

--------------------------------

### create_zen_garden_cli()

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.cli.zen_garden_cli.html

The main entry point for the zen-garden command-line interface, responsible for setting up the parser, resolving job indices, and initiating the run.

```APIDOC
## create_zen_garden_cli()

### Description
Entry point for the zen-garden command-line interface. This function creates the command-line interface for running ZEN-garden. It first sets up an argument parser; extracts the job index (either from the input flax directly or from an environment variable), and then calls the `zen_garden.run()` function.

### Parameters
#### Query Parameters
- **--config** (str, optional) - Path to a Python or JSON configuration file. If not provided, the configuration is read from the current working directory.
- **--dataset** (str, optional) - Path to the dataset directory. Overrides `config.analysis.dataset` in the configuration file.
- **--folder_output** (str, optional) - Path to the output directory. Overrides output-related settings in the configuration file. If not specified, output is written to the current working directory.
- **--job_index** (str, optional) - Comma-separated list of scenario or job indices to execute. If not provided, the value is read from the environment variable specified by `--job_index_var`.
- **--job_index_var** (str, optional) - Name of the environment variable containing the job index. Defaults to `SLURM_ARRAY_TASK_ID`.

### Returns
None

### Examples
Basic usage in a command line prompt:
```
>>> zen-garden --config=".\config.json" --dataset="1_base_case"
```
```

--------------------------------

### Build Local HTML Documentation

Source: https://zen-garden.readthedocs.io/en/latest/files/developer_guide/documentation.html

Build the local HTML version of the documentation. After running this command, the documentation will be available in the 'docs/build/html' folder.

```bash
make html

```

--------------------------------

### Default config.json Structure

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/02_change_configuration.html

This is an example of a default config.json file, illustrating the nested structure for analysis and solver configurations. It shows how to set parameters like dataset, solver name, and various solver options.

```json
{
  "analysis": {
    "dataset": "5_multiple_time_steps_per_year"
  },
  "solver": {
    "name": "gurobi",
    "solver_options": {
      "Method": 2,
      "NodeMethod": 2,
      "BarHomogeneous": 1,
      "DualReductions": 0,
      "Threads": 128,
      "Crossover": 0,
      "ScaleFlag": 2,
      "BarOrder": 0
    },
    "save_duals": false,
    "use_scaling": false,
    "run_diagnostics": true,
    "scaling_include_rhs": true
  }
}
```

--------------------------------

### IISConstraintParser.__init__

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.utils.html

Initializes the IIS constraint parser with the IIS file and the model.

```APIDOC
## IISConstraintParser.__init__

### Description
Initializes the IIS constraint parser.

### Parameters
* **iis_file** – The file containing the IIS.
* **model** – The model to which the IIS belongs.
```

--------------------------------

### IISConstraintParser.get_label_position

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.utils.html

Gets the tuple of name and coordinate for variable labels.

```APIDOC
## IISConstraintParser.get_label_position

### Description
Get tuple of name and coordinate for variable labels.

### Parameters
* **constraints** – The constraints object.
* **value** – The value to get the label for.

### Returns
tuple - The name and coordinate of the variable.
```

--------------------------------

### Initialize ZEN-garden Results Objects

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/01_analyze_outputs.html

Instantiate Results objects from specified folder paths to prepare for comparison.

```python
from zen_garden import Results
r1 = Results(path='<result_folder_1>')
r2 = Results(path='<result_folder_2>')

```

--------------------------------

### Run ZEN-garden with a Specific Config File

Source: https://zen-garden.readthedocs.io/en/latest/files/quick_start/running_models.html

Execute ZEN-garden, specifying both the configuration file and the dataset to use.

```bash
zen-garden --config="config.json" --dataset="1_base_case"
```

--------------------------------

### check_primary_folder_structure

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.utils.html

Validates the primary folder structure required for the system setup.

```APIDOC
## check_primary_folder_structure

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

### Returns
None
```

--------------------------------

### get_label_position

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.utils.html

Gets the dictionary of index and coordinate for variable or constraint labels.

```APIDOC
## get_label_position

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

### Parameters
* **obj** (object) - The object containing the labels.
* **label** (str) - The label to find the position for.

### Returns
dict - A dictionary containing the index and coordinate of the label.
```

--------------------------------

### Run ZEN-garden Model with New Dataset

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/03_add_technologies_carrier.html

Execute the ZEN-garden model with a specified dataset. Ensure you are in the directory containing `config.json` and the dataset folder.

```bash
zen-garden --dataset=tutorial_3_add_technologies_carrier

```

--------------------------------

### TechnologyRules.constraint_technology_capacity_lower_limit

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.model.technology.technology.html

Ensures that the installed capacity meets or exceeds the defined lower limit.

```APIDOC
## constraint_technology_capacity_lower_limit

### Description
Constraint that installed capacity must be >= the defined lower limit.

```

--------------------------------

### OptimizationSetup Class

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.optimization_setup.html

The OptimizationSetup class defines the optimization model for an energy system. It takes configuration and scenario data to set up, add elements, and solve the optimization problem.

```APIDOC
## Class: OptimizationSetup

### Description
Class defining the optimization model. The class takes as inputs the properties of the optimization problem. The properties are saved in the dictionaries analysis and system which are passed to the class. After initializing the model, the class adds carriers and technologies to the model and returns it. The class also includes a method to solve the optimization problem.

### Methods

#### `__init__(self, config, scenario_dict: dict, input_data_checks)`

  * **Description**: Setup optimization of the energy system. This function sets up the optimization process for the energy system using the provided configuration, scenario data, and input data checks.
  * **Parameters**:
    * `config` (Config) – Config object used to extract the analysis, system, and solver dictionaries.
    * `scenario_dict` (dict) – Dictionary defining the scenario, including data such as resources, demand, etc.
    * `input_data_checks` (InputDataChecks) – Input data checks object to verify the integrity of the input data.

#### `add_carbon_emission_cumulative(self, decision_horizon)`

  * **Description**: Adds current emissions to existing emissions. This function adds carbon emissions from the current optimization step to the existing carbon emissions.
  * **Parameters**:
    * `decision_horizon` (list or int) – A list of the years to transfer emissions to existing emissions.
  * **Returns**: None

#### `add_element(self, element_class, name)`

  * **Description**: Add an element to the element_dict with the class labels as key.
  * **Parameters**:
    * `element_class` – Class of the element
    * `name` – Name of the element

#### `add_elements(self)`

  * **Description**: Set up the parameters, variables and constraints of the carriers.

#### `add_folder_paths(self, set_name, path, subsets=None)`

  * **Description**: Add file paths of element to paths dictionary.
  * **Parameters**:
    * `set_name` – name of set
    * `path` – path to folder
    * `subsets` – list of subsets

#### `add_new_capacity_addition(self, decision_horizon)`

  * **Description**: Adds the newly built capacity to the existing capacity. This function adds installed capacities from the current optimization step to existing capacities in the model. It also adds costs from the installed capacities to existing capacity investment. Capacity values whose magnitude is below that specified by the solver setting “rounding_decimal_points_capacity” are set to zero.
  * **Parameters**:
    * `decision_horizon` (list or int) – A list of the years to transfer installed capacities to existing capacities.
  * **Returns**: None

#### `add_results_of_optimization_step(self, step_horizon)`

  * **Description**: Adds capacity additions and carbon emissions to the next optimization step. This function takes the capacity additions and carbon emissions of the current optimization step and adds them to the existing capacity and existing emissions of the next optimization step. Values from the currently simulated year are added as existing capacities and emissions for future steps.
  * **Parameters**:
    * `step_horizon` (int) – The year index of the current optimization step. In myopic foresight, capacities and emissions from this step are added to existing capacities and emissions.
  * **Returns**: None

#### `append_attribute_of_element_to_dict(self, element, attribute_name, dict_of_attributes, dict_of_units, capacity_type=None)`

  * **Description**: Get attribute values of all elements in this class.
  * **Parameters**:
    * `element` – element of class
    * `attribute_name` (str) – str name of attribute
    * `dict_of_attributes` (dict) – dict of attribute values
    * `dict_of_units` (dict) – dict of attribute units
    * `capacity_type` – capacity type for which attribute extracted. If None, not listed in key
  * **Returns**: dict_of_attributes: dict of attribute values

#### `check_for_subindex(self, component_data, custom_set)`

  * **Description**: Check if the custom_set can be a subindex of component_data.
  * **Parameters**:
    * `component_data` – extracted data as pd.Series
    * `custom_set` – custom set as subindex of component_data
  * **Returns**: component_data: extracted subindexed data as pd.Series

#### `construct_optimization_problem(self)`

  * **Description**: Constructs the optimization problem.

#### `create_paths(self)`

  * **Description**: This method creates a dictionary with the paths of the data split by carriers, networks, technologies.

#### `get_all_elements(self, cls)`

  * **Description**: Get all elements of the class in the energy system.

```

--------------------------------

### Infeasible Optimization Output

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/09_handle_infeasibilities.html

Example of the output indicating that the optimization problem was found to be infeasible.

```plaintext
Optimization failed:
Status: warning
Termination condition: infeasible
```

--------------------------------

### Successful Optimization Output

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/09_handle_infeasibilities.html

Example of the output indicating a successful optimization with an optimal solution.

```plaintext
Optimization successful:
Status: ok
Termination condition: optimal
```

--------------------------------

### Initialize SolutionLoader

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.postprocess.results.solution_loader.html

Initializes the SolutionLoader with a given path to the solution files. Optionally, caching can be enabled or disabled.

```python
SolutionLoader(path, enable_cache=True)
```

--------------------------------

### Infeasible Constraints Example

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/09_handle_infeasibilities.html

Illustrates a set of constraints that are mutually exclusive, leading to an infeasible problem.

```plaintext
x <= y    (I)
x >= 5    (II)
y <= 0    (III)
```

--------------------------------

### Get Label Position with zen_garden.utils.get_label_position

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.utils.html

Obtains the dictionary of index and coordinate for variable or constraint labels.

```python
zen_garden.utils.get_label_position(_obj_, _label: int_)
```

--------------------------------

### zen_garden.preprocess.unit_handling

Source: https://zen-garden.readthedocs.io/en/latest/files/api/preprocess.html

File which contains the unit handling and scaling class.

```APIDOC
## Class: zen_garden.preprocess.unit_handling

### Description
Provides functionality for handling and scaling units within the data.

### Usage
Instantiate and use the classes within this file for unit management.
```

--------------------------------

### _get_lifetime_range

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.model.technology.technology.html

Gets the active year range of a technology, considering either its lifetime or depreciation time.

```APIDOC
## _get_lifetime_range

### Description
Get active year range of technology: either lifetime or depreciation time.

### Parameters
* **optimization_setup** – OptimizationSetup the technology is part of
* **tech** – name of the technology
* **year** – yearly time step
* **use_depreciation_time** – boolean indicating whether to use depreciation time instead of lifetime, namely for CAPEX calculation

### Returns
lifetime or depreciation time range of technology
```

--------------------------------

### Create ZEN-garden CLI Entry Point

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.cli.zen_garden_cli.html

The main entry point for the zen-garden command-line interface. It sets up the argument parser, extracts the job index, and calls the main run function.

```python
def create_zen_garden_cli() -> None:
    """Entry point for the zen-garden command-line interface.

    This function creates the command-line interface for running
    ZEN-garden. It first sets up an argument parser; extracts the job index
    (either from the input flax directly or from an environment variable),
    and then calls the `zen_garden.run()` function.

    The `[project.scripts]` section of the pyproject.toml declares that this
    function will be called whenever a user enters `zen-garden` into the
    command prompt.
    """
    parser = build_parser()
    args = parser.parse_args()
    job_index = resolve_job_index(args.job_index, args.job_index_var)
    zen_garden.run(args.config, args.dataset, args.folder_output, job_index)
```

--------------------------------

### Get All Variable Names

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/01_analyze_outputs.html

Retrieve a list of all variable names used in the model. This is a specific application of `get_component_names`.

```python
r.get_component_names('variable')

```

--------------------------------

### Get Inheritors with zen_garden.utils.get_inheritors

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.utils.html

Retrieves all direct child classes of a given class. Returns the inheritors as a set.

```python
zen_garden.utils.get_inheritors(_klass_)
```

--------------------------------

### Load ZEN-garden Results

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/01_analyze_outputs.html

Import the Results class and load raw data from a specified results folder. Ensure the ZEN-garden environment is activated.

```python
from zen_garden import Results
r = Results(path='<result_folder>')

```

--------------------------------

### get_system

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.postprocess.results.results.html

Extracts system configurations from a specified scenario, ensuring model configurations are tractable. It retrieves settings from the `system.json` file.

```APIDOC
## get_system

### Description
Extract system configurations from a scenario. Extracts system configurations from the results of a scenario. This ensures the tractability of model configurations. System configurations are those specified in the `system.json` file of a given model.

### Method
GET (assumed)

### Endpoint
/results/system

### Parameters
#### Query Parameters
- **scenario_name** (str) - Optional - The name of the scenario for which to extract the system configuration. If no value is given, then the first scenario is used. Defaults to None.

### Response
#### Success Response (200)
- **system_config** (System) - System configuration object.

#### Response Example
{
  "system_config": {
    "name": "my_system",
    "version": "1.0"
  }
}
```

--------------------------------

### Infeasible or Unbounded Optimization Output

Source: https://zen-garden.readthedocs.io/en/latest/files/tutorial/09_handle_infeasibilities.html

Example of the output indicating that the optimizer could not determine if the problem was infeasible or unbounded.

```plaintext
Optimization failed:
Status: warning
Termination condition: infeasible_or_unbounded
```

--------------------------------

### solve

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.optimization_setup.html

Creates a model instance by assigning parameter values and initializing sets, preparing the system for solving the optimization problem.

```APIDOC
## solve()

### Description
Create model instance by assigning parameter values and initializing sets.
```

--------------------------------

### create_custom_set

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.model.element.html

Class method to create a custom set for a model component, taking a list of index names and the optimization setup.

```APIDOC
## create_custom_set

### Description
Creates custom set for model component.

### Parameters
* **list_index** (list) - List of names of indices.
* **optimization_setup** (OptimizationSetup) - The OptimizationSetup the element is part of.

### Returns
* **list_index** (list) - List of names of indices.
```

--------------------------------

### Method Docstring Template

Source: https://zen-garden.readthedocs.io/en/latest/files/developer_guide/documentation.html

Use this template for documenting methods. Provide a concise summary, detailed explanation of purpose and behavior, and list arguments, return values, and potential exceptions. Include basic usage examples. 'Todo' items are for internal notes and will not appear in documentation.

```python
"""
One-line summary of the method.

One or more paragraphs describing the method’s purpose, behavior, and any
important implementation details or side effects. This description
should enable users to understand what the method does and when to use it.

Args:
    param1 (type): Description of `param1`. Make sure to properly indent
        each new line by four spaces when including  multi-line
        descriptions.
    param2 (type, optional): Description of `param2`. Defaults to None.

Returns:
    return_type: Description of the return value.

Raises:
    SomeError: Description of conditions when this exception is raised.
    AnotherError: Description for another exception, if applicable.

Examples:
    Basic usage example:

    >>> obj = ClassName()
    >>> result = obj.method_name(param1, param2)
    >>> print(result)

Todo:
    - List any planned improvements or refactoring tasks here.
    - These will not show up in the documentation.
"""

```

--------------------------------

### Get Analysis Configuration

Source: https://zen-garden.readthedocs.io/en/latest/files/api/generated/zen_garden.postprocess.results.results.html

Retrieves analysis configurations for a specific scenario. If no scenario name is provided, it defaults to the first scenario.

```python
from zen_garden.postprocess.results.results import Results
r = Results(path='<result_folder>')
r.get_analysis() # analysis config of first scenario
r.get_analysis('scenario_name') # analysis config of "scenario_name"
```
Tokens:
Raw