### Install and Setup Pre-commit Hooks

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/developer_guide/contributing.rst

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

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

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

### Download Example Dataset

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/quick_start/building_models.rst

Command to download a specific example dataset, such as '1_base_case', for use with ZEN-garden. Replace '1_base_case' with the desired dataset name.

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

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

### Install ZEN-garden Package

Source: https://github.com/zen-universe/zen-garden/blob/main/README.md

Install the ZEN-garden package using pip for immediate use without code modification.

```bash
pip install zen-garden
```

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

### Run ZEN-garden Example Dataset via CLI

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/quick_start/summary.rst

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
```

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

### Run ZEN-garden Example Dataset via Python Script

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/quick_start/summary.rst

This Python script downloads an example dataset, runs ZEN-garden, and analyzes the results using the Results class. It extracts and prints the total capacity from the model outputs.

```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"))
```

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

### Python Hello World Example

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/developer_guide/documentation.rst

A simple Python code snippet demonstrating basic output. This is often used as a minimal example within documentation.

```python
import numpy as np
print("Hello World")

```

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

### ZEN-garden System Configurations in system.json

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/02_change_configuration.rst

This is an example of the system.json file, which defines technologies, regions, temporal resolution, and spatial aggregation parameters for the model.

```JSON
{
    "set_conversion_technologies": [
        "natural_gas_boiler",
        "photovoltaics",
        "heat_pump"
    ],
    "set_storage_technologies": [
        "natural_gas_storage"
    ],
    "set_transport_technologies": [
        "natural_gas_pipeline"
    ],
    "set_nodes": [
        "DE",
        "CH"
    ],
    "reference_year": 2023,
    "unaggregated_time_steps_per_year": 96,
    "aggregated_time_steps_per_year": 96,
    "conduct_time_series_aggregation": false,
    "optimized_years": 3,
    "interval_between_years": 1,
    "use_rolling_horizon": false,
    "years_in_rolling_horizon": 1
}
```

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

### Install Graphviz and PyCallGraph2

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/developer_guide/tips_and_tricks.rst

Installs the necessary packages for creating call graphs using Anaconda.

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

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

### List Installed Packages

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/quick_start/installation.rst

Check if 'zen_garden' is present in the list of installed packages to verify successful installation. Run this command within the activated conda environment.

```shell
conda list
```

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

### Example: High Gas Price Scenario

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/04_scenario_analysis.rst

This example demonstrates overwriting the 'price_import' parameter for 'natural_gas' to simulate a high gas price scenario using multiple 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
                }
            }
        }
    }
}
```

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

### Extended Infeasible Model Constraints Example

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/09_handle_infeasibilities.rst

An expanded set of constraints for the original example, demonstrating how additional constraints might not resolve infeasibility.

```text
x <= y    (I)
x >= 5    (II)
y <= 0    (III)
...
x >= -5    (IV)
x + y <= 100     (V)
x + y >= -50     (VI)
```

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

### Navigate to Data Directory

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/01_analyze_outputs.rst

Use this command in the terminal to navigate to the directory containing the input data for the example model and the output folder.

```text
cd /path/to/your/data
```

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

### Install Pre-commit Hooks

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/developer_guide/installation.rst

Install the pre-commit hooks within the activated conda environment to ensure code quality and consistency.

```bash
pre-commit install
```

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

### Navigate to Docs Directory

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/developer_guide/documentation.rst

Use this command to change your current directory to the docs folder within the ZEN-garden installation.

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

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

### Modifying config.json for Analysis and Solver Settings

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/02_change_configuration.rst

Example config.json file demonstrating how to specify analysis and solver configurations, including dataset selection, solver options, and saving preferences.

```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
  }
}

```

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

### Infeasible Model Constraints Example

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/09_handle_infeasibilities.rst

Illustrates a simple set of constraints that lead to an infeasible optimization problem.

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

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

### Run ZEN-garden Model from Python

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/quick_start/running_models.rst

Execute a ZEN-garden model programmatically using Python. Ensure ZEN-garden is installed and the data path is correctly set.

```python
from zen_garden import run
import os

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

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

### Add Variable to Optimization Setup

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/developer_guide/adding_param_variable_constraint.rst

Use this method to add a new variable to the optimization setup. Specify the model, name, index sets, bounds, documentation, and unit category.

```python
optimization_setup.variables.add_variable(
        model,
        name="flow_import",
        index_sets=cls.create_custom_set(["set_carriers", "set_nodes", "set_time_steps_operation"], optimization_setup),
        bounds=(0,np.inf),
        doc="node- and time-dependent carrier import from the grid",
        unit_category={"energy_quantity": 1, "time": -1})
```

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

### Add Parameter to Optimization Setup

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/developer_guide/adding_param_variable_constraint.rst

Use this method to add a new parameter to the optimization setup. Ensure the name matches the one defined in `store_input_data`. The `index_names` specify the dimensions of the parameter, and `calling_class` refers to the class invoking the method.

```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)
```

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

### Unit Conversion Example: Euro/MWh to Euro/GW/hour

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/06_unit_handling.rst

Demonstrates how to convert units like Euro/MWh to a base unit combination like Euro/GW/hour by comparing dimensionalities and calculating a multiplier.

```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
```

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

### Run Scenarios in Parallel (Slurm)

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/04_scenario_analysis.rst

Demonstrates running scenarios in parallel on Slurm systems using the --array argument with start, stop, step, and max concurrent jobs.

```bash
zen-garden --array=start-stop:step%Nmax
```

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

### Defining New Units with Pint

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/06_unit_handling.rst

Provides an example of how to define new units like 'Euro' and 'pkm' using the 'pint' package, specifying their dimensionality and alternative names.

```text
Euro = [currency] = EURO = Eur
pkm = [mileage] = passenger_km = passenger_kilometer
```

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

### Minimal ZEN-garden Plugin Example

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/developer_guide/implementing_plugins.rst

This Python snippet shows a basic plugin structure. It registers two callback functions, `first_method`, to different events using the `EventPublisher.register` decorator. Ensure `EventPublisher` and the relevant `TestEvent` are imported.

```python
# tests/unit_tests/fake_plugin/plugin.py
from zen_garden.plugin_system.events import EventPublisher
from tests.unit_tests.test_events import TestEvent

config = {}


@EventPublisher.register(TestEvent.test_event1)
def first_method(**kwargs):
    pass

@EventPublisher.register(TestEvent.test_event2)
def first_method(**kwargs):
    pass

```

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

### Example II: Time Series Aggregation Configuration (Rolling Horizon)

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/05_time_series_aggregation.rst

Configuration for a scenario with a rolling horizon, including parameters for the rolling window size and decision saving interval.

```json
"reference_year": 2020,
    "optimized_years": 4,
    "interval_between_years": 10,
    "use_rolling_horizon": True,
    "years_in_rolling_horizon": 2,
    "interval_between_optimizations": 1
```

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

### Example I: Time Series Aggregation Configuration (No Rolling Horizon)

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/05_time_series_aggregation.rst

Configuration for a scenario without a rolling horizon, specifying the reference year, number of optimized years, and the interval between years.

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

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

### Example scenarios_op.json Configuration

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/08_operation_only.rst

This JSON configuration defines an operational scenario named 'full_year' that runs the simulation with the full 8760 hours per year, disabling time-series aggregation. This is useful for testing the feasibility of aggregated results against a complete hourly dataset.

```json
{
  "full_year": {
    "system": {
      "conduct_time_series_aggregation": false,
      "aggregated_time_steps_per_year": 8760
    }
  }
}
```

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

### Get Component Names by Type

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/01_analyze_outputs.rst

Retrieve a list of component names (parameters, variables, duals, or sets) from the loaded results. Component descriptions can be found in the documentation on sets, parameters, variables, and constraints.

```python
r.get_component_names(<component_type>)
```

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

### Get Variable Names

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/01_analyze_outputs.rst

Specifically retrieve a list of all variable names used in the model. Dual variables, which start with 'constraint_', require adjusting ZEN-garden configurations to be viewed.

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

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

### Run ZEN-garden with the new dataset

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/03_add_technologies_carrier.rst

Execute the ZEN-garden model using the newly created dataset that includes the added technologies and carriers.

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

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

### Check Conda Installation

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/quick_start/installation.rst

Verify if Anaconda is installed on your system. This command should be run in a terminal or command prompt.

```shell
conda --version
```

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

### Run ZEN-visualization Platform

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/01_analyze_outputs.rst

Execute this command in the terminal to launch the ZEN-garden visualization platform. It will open in your default browser at http://localhost:8000/. To exit, press Control + C.

```bash
zen-visualization
```

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

### Add a Set to Optimization Setup

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/developer_guide/adding_param_variable_constraint.rst

Adds a set to the optimization setup, which is not indexed by any other set. Ensure the name is unique.

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

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

### Example I: Resulting Investigated Years (No Rolling Horizon)

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/05_time_series_aggregation.rst

The sequence of years investigated based on the configuration in Example I.

```text
[2020,2030,2040,2050]
```

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

### Build Local Documentation

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/developer_guide/documentation.rst

Execute this command to build the local documentation using Sphinx. The output will be available in the docs/build/html folder.

```bash
make html
```

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

### Basic ZEN-garden File Structure

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/quick_start/building_models.rst

Illustrates the high-level file organization for a ZEN-garden model, including the config file and dataset folder.

```text
<data>/
|--<dataset>/
|   |--energy_system/...
|   |--set_carriers/...
|   |--set_technologies/...
|   `--system.json
|
`--config.json
```

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

### Example II: Resulting Investigated Years (Rolling Horizon)

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/05_time_series_aggregation.rst

The sequence of investigated year subsets for each step in a rolling horizon scenario, as defined in Example II.

```text
[2020,2030]
    [2030,2040]
    [2040,2050]
    [2050]
```

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

### Run ZEN-visualization with Custom Output Folder

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/01_analyze_outputs.rst

If your results are in a different location, use this command to specify the path to your solutions folder.

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

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

### List Expansion for System and Analysis Settings

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/04_scenario_analysis.rst

Illustrates using list expansion for system and analysis settings, where a value can be a list with a format string for generating new values.

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

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

### Add an Indexed Set to Optimization Setup

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/developer_guide/adding_param_variable_constraint.rst

Adds a set to the optimization setup that is indexed by another set. This allows for data to be associated with specific elements of another set.

```python
optimization_setup.sets.add_set(
    name="set_reference_carriers",
    data=optimization_optimization_setup.get_attribute_of_all_elements(cls, "reference_carrier"),
    doc="set of all reference carriers correspondent to a technology. Indexed by set_technologies",
    index_set="set_technologies")
```

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

### Load ZEN-garden Results

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/01_analyze_outputs.rst

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

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

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

### Running zen-operation via Command Line

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/08_operation_only.rst

This command initiates an operational scenario simulation using the zen-operation wrapper. It requires navigating to the data directory, specifying the dataset, and providing the path to the operational scenarios configuration file.

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

```shell
zen-operation --dataset="<dataset>" --scenarios_op="scenarios_op.json"
```

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

### Run First Four Scenarios in Parallel (Slurm)

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/04_scenario_analysis.rst

Shows how to run the first four scenarios (indices 0-3) in parallel on Slurm systems using the --array argument with a range.

```bash
zen-garden --array=0-3
```

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

### Initialize Results Objects for Comparison

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/01_analyze_outputs.rst

Instantiate two Results objects from different result folders to prepare for comparison. Ensure paths point to valid simulation outputs.

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

```

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

### Infeasible Optimization Output

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/09_handle_infeasibilities.rst

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

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

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

### Enable scenario analysis in systems.json

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/04_scenario_analysis.rst

Set the 'conduct_scenario_analysis' configuration option to 'true' in your 'systems.json' file to enable the scenario tool.

```json
"conduct_scenario_analysis": true
```

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

### Successful Optimization Output

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/09_handle_infeasibilities.rst

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

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

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

### Infeasible or Unbounded Optimization Output

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/09_handle_infeasibilities.rst

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

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

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

### Transport Technology Capacity Constraint

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/zen_garden_in_detail/mathematical_formulation.rst

This constraint limits the flow of transport technologies based on maximum load and installed capacity.

```mathematical
0 \leq F_{j,e,t,y} \leq m^{\mathrm{max}}_{j,e,t,y}S_{j,e,y}.
```

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

### ZEN-garden Configuration File Structure

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/02_change_configuration.rst

Illustrates the location of config.json and system.json within the ZEN-garden input data structure.

```text
<data>/
    |--<dataset>/
    |   |--energy_system/...
    |   |--set_carriers/...
    |   |--set_technologies/...
    |   `--system.json
    |
    `--config.json

```

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

### Get Capacity Units

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/dataset_examples/example_notebook.ipynb

Retrieves the units associated with a specific metric, in this case, 'carbon_intensity_carrier_import'. This helps in interpreting the data correctly.

```python
# get units of capacity
capacity_units = r.get_unit("carbon_intensity_carrier_import")
capacity_units
```

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

### Conversion Technology Capacity Constraint

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/zen_garden_in_detail/mathematical_formulation.rst

This constraint limits the reference flow of conversion technologies based on maximum load and installed capacity.

```mathematical
0 \leq G_{i,n,t,y}^{\mathrm{r}} \leq m^{\mathrm{max}}_{i,n,t,y}S_{i,n,y}.
```

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

### Run Specific Scenarios Sequentially

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/04_scenario_analysis.rst

Shows how to run a subset of scenarios sequentially using the --job_index argument with scenario indices.

```bash
zen-garden --job_index 1,4,7
```

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

### Run ZEN-garden with Default Configuration

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/quick_start/running_models.rst

Execute ZEN-garden without command-line flags. It will use the dataset specified in the 'analysis/dataset' entry of config.json.

```shell
zen-garden
```

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

### Get Annual Capacity of Technologies

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/01_analyze_outputs.rst

Retrieves the annual total capacity values for all technologies. This function returns a pandas multi-index DataFrame.

```python
r.get_total('capacity')
```

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

### Get Demand Time Series

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/dataset_examples/example_notebook.ipynb

Fetches the complete time series data for demand. This is useful for analyzing demand fluctuations over time.

```python
# get demand time series
demand_timeseries = r.get_full_ts("demand")
demand_timeseries
```

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

### Get Annual Demand

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/dataset_examples/example_notebook.ipynb

Retrieves the total annual demand value from the dataset. This function is useful for understanding overall demand figures.

```python
# get annual demand
demand_annual = r.get_total("demand")
demand_annual
```

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

### Get Total Capacity

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/dataset_examples/example_notebook.ipynb

Retrieves the total capacity value from the dataset using the Results object. Ensure the Results object is initialized.

```python
# get capacity 
capacity = r.get_total('capacity')
capacity
```

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

### Overwrite System and Analysis Settings

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/04_scenario_analysis.rst

Demonstrates how to overwrite specific system or analysis settings by providing a new value with the same type as the existing one.

```json
{
    "example": {
        "system": {
            "key": "new_value"
            },
        "natural_gas": {
            "price_import": {
                "file": "import_price_high",
                "file_op": 1.5
                }
            }
        }
    }
}
```

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

### Define Emissions Minimization Scenario

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/tutorial/08_operation_only.rst

Create a scenario file (e.g., scenarios_op.json) to define a new operational scenario. This example sets the objective to minimize 'total_carbon_emissions'.

```json
{
  "min_emissions": {
    "analysis": {
      "objective": "total_carbon_emissions"
    }
  }
}
```

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

### Storage Technology Charge/Discharge Constraint

Source: https://github.com/zen-universe/zen-garden/blob/main/docs/files/zen_garden_in_detail/mathematical_formulation.rst

This constraint limits the sum of charging and discharging flows for storage technologies, ensuring they do not exceed the maximum load multiplied by installed capacity.

```mathematical
0 \leq \underline{H}_{k,n,t,y}+\overline{H}_{k,n,t,y}\leq m_{k,n,t,y}S_{k,n,y}.
```