### Creating iesopt Example Configuration in Python

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_53.ipynb

This Python code demonstrates how to use the 'iesopt.make_example' function to generate a local configuration file based on a predefined example, specifically example 53 which deals with grid tariffs.

```python
config = iesopt.make_example("53_grid_tariffs", "opt")
```

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

### Import iesopt Library

Source: https://github.com/ait-energy/iesopt/blob/main/docs/index.md

Imports the iesopt library into the current Python session. The first time this is run in a new environment, it triggers the setup and precompilation of the underlying Julia environment, which can take several minutes.

```python
import iesopt
```

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

### Launch Python REPL using uv

Source: https://github.com/ait-energy/iesopt/blob/main/docs/index.md

Starts an interactive Python session (REPL) within the uv-managed environment. This allows for direct execution of Python code and is used here to trigger the initial setup of the iesopt Julia environment.

```bash
(yourenvname) user@PCNAME:~/your/current/path$ uv run python
```

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

### Setting IESopt Core Version in .env (Initial Example)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/python/configuration.md

Shows how to set the version of the IESopt.jl Julia package using the IESOPT_CORE environment variable in a .env file. This is a basic example for initial setup.

```text
IESOPT_CORE = 2.0.0
```

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

### Initialize uv Environment

Source: https://github.com/ait-energy/iesopt/blob/main/docs/index.md

Initializes a new uv environment in the current directory, creating a basic project structure including a sample Python file.

```bash
uv init
```

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

### Creating IESopt Example Configuration in Python

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_52.ipynb

Uses the `iesopt.make_example` function to create a local copy of the configuration and data files for the "52_simple_ev" example, specifying the "opt" type.

```python
config = iesopt.make_example("52_simple_ev", "opt")
```

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

### Create Example Configuration File

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/custom_results_1.ipynb

Uses the iesopt library to create an example configuration file for a specific tutorial case ('48_custom_results') in a designated directory.

```python
config_file = iesopt.make_example(
    "48_custom_results", dst_dir="ex_custom_results", dst_name="config"
)
```

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

### Creating IESopt Example Configuration (Python)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_54.ipynb

Generates a local configuration object for the '54_simple_roomtemperature' example model, specifying the 'opt' scenario.

```python
config = iesopt.make_example("54_simple_roomtemperature", "opt")
```

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

### Example for the `config` section in the top-level YAML configuration file.

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Illustrates a comprehensive example of the `config` section, including general settings, optimization parameters, file references, results configuration, and path definitions.

```yaml
config:
  general:
    version:
      core: 1.1.0
      python: 1.4.7
    name:
      model: FarayOptIndustry
      scenario: Base_2022_LOW
  optimization:
    problem_type: LP
    snapshots:
      count: 168
  files:
    data: inputs_2022.csv
  results:
    enabled: true
  paths:
    files: data/
    templates: templates/
    components: model/
    results: out/
```

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

### Sync Dependencies with uv

Source: https://github.com/ait-energy/iesopt/blob/main/docs/index.md

Installs or updates dependencies based on the project's lock file (uv.lock). This command is essential after cloning a repository or modifying dependencies to ensure all required packages are installed.

```bash
uv sync
```

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

### Creating Local Copy of IESopt Example Configuration - Python

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_55.ipynb

This Python code uses the `iesopt.make_example` function to generate a local configuration dictionary based on the specified example number ('55_annuity') and optimization mode ('opt'). This configuration is then used to run the model.

```python
config = iesopt.make_example("55_annuity", "opt")
```

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

### Example content of `global_params_scenarioHIGH.iesopt.param.yaml`.

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Provides an example of the content for an external YAML file used to store global parameters, including comments for units and explanations.

```yaml
ng_emission_factor: 0.202  # t CO2 / MWh_ng
co2_cost: 125              # EUR / t CO2
elec_cost: null            # EUR / MWh_el
```

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

### Example for the `version` section.

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Focuses specifically on the `version` subsection within the `config` section, showing how to specify the versions of the core IESopt framework and the Python interface for reproducibility.

```yaml
config:
  general:
    version:
      core: 1.1.0
      python: 1.4.7
```

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

### Install Pre-commit Hooks with uv

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/dev/general.md

Installs the configured pre-commit hooks using the uv run command, ensuring code quality checks run automatically before commits.

```Bash
uv run pre-commit install
```

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

### Run Python Script using uv

Source: https://github.com/ait-energy/iesopt/blob/main/docs/index.md

Executes a specified Python script (hello.py) within the uv-managed environment. This is a way to test if the environment is set up correctly and scripts can be run.

```bash
uv run hello.py
```

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

### Add iesopt Dependency using uv

Source: https://github.com/ait-energy/iesopt/blob/main/docs/index.md

Adds the 'iesopt' package as a dependency to the current uv environment. This command installs the package and updates the project's lock file (uv.lock).

```bash
uv add iesopt
```

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

### Markdown Structure for Q&A User Guides (Markdown)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/user_guides/toc_qna.md

This markdown snippet illustrates a suggested structure for the Q&A user guides. It outlines sections like Title header, Intro (including a formatted Question and Answer), Details, Summary, and Conclusion, providing a template for organizing the content derived from user interactions.

```markdown
# Title header

## Intro

**Question:**  
> I'm moving from hourly to daily time steps in my IESopt model. How should I adjust my input data, especially capacities and costs, to ensure accurate results? Should I express capacities as energy per time step (e.g., kWh/day) instead of power (kW)?

**Answer:**  
> When working with IESopt models, it's crucial to understand how the model interprets units of power and energy, especially when changing the duration of your time steps (snapshots). Here's how to approach this:

## Details

_... a more detailed answer and further explanations go here ..._

## Summary

_... a summary goes here ..._

_... often this is the place for further notes, comments, key takeaways ..._

### Conclusion

_... and finally a 1-3 sentence conclusion ..._
```

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

### Example for file-based `parameters` section.

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Shows how to specify global parameters by referencing an external YAML file containing the parameter definitions instead of defining them inline.

```yaml
parameters: global_params_scenarioHIGH.iesopt.param.yaml
```

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

### Example for a `dict`-based `parameters` section.

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Demonstrates how to define global parameters directly within the `parameters` section using a dictionary structure, including default values like `null`.

```yaml
parameters:
  ng_emission_factor: 0.202
  co2_cost: 125
  elec_cost: null
```

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

### IESopt BibTeX Citation

Source: https://github.com/ait-energy/iesopt/blob/main/docs/index.md

Provides the standard BibTeX entry for citing the IESopt software in academic or technical publications. This format is commonly used with LaTeX and other citation management tools.

```bibtex
@misc{iesopt,\n    author = {Strömer, Stefan and Schwabeneder, Daniel and contributors},\n    title = {{IES}opt: Integrated Energy System Optimization},\n    organization = {AIT Austrian Institute of Technology GmbH},\n    url = {https://github.com/ait-energy/iesopt},\n    type = {Software},\n    year = {2021-2024},\n}
```

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

### Configuring CPLEX Solver in YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/user_guides/general/solvers.md

Example YAML configuration for the CPLEX solver, defining parameters such as thread count, LP method, solution type, barrier convergence tolerance, and feasibility tolerance.

```yaml
solver:
  name: cplex
  attributes:
    threads: 4
    lpmethod: 4
    solutiontype: 2
    barrier_convergetol: 1.e-5
    feasopt_tolerance: 1.e-6
```

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

### Markdown Template for Project References

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/references/projects.md

This template provides the required structure and fields for adding a new project reference entry to the documentation. It includes placeholders for the project slug, title, homepage URL, funding information, description, and AIT contact.

```markdown
(references-projects-project-slug-title)=
### Project Slug Title

:**title**: Full Project Title
:**homepage**: [something.com](https://www.something.com/)
:**funding**: [ffg.at](https://projekte.ffg.at/projekt/XXXXXXXXX)
:**description**: some copy-pasted, or other sort of short description / abstract goes here
:**AIT contact**: F. Lastname

---

```

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

### Configuring Gurobi Solver (Fallback) in YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/user_guides/general/solvers.md

Fallback YAML configuration for the Gurobi solver, setting method, crossover, homogeneous barrier, and tolerances, often used as an alternative setup.

```yaml
solver:
  name: gurobi
  attributes:
    Crossover: 0
    Method: 2
    BarHomogeneous: 1
    BarConvTol: 1.e-5
    FeasibilityTol: 1.e-5
    OptimalityTol: 1.e-5
    Threads: 8
    Seed: 1234
```

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

### Importing IESopt Library - Python

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_55.ipynb

This Python line imports the main IESopt library, making its functions and classes available for use in the script.

```python
import iesopt
```

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

### Configuring HiGHS Solver in YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/user_guides/general/solvers.md

Example YAML configuration for the HiGHS solver, setting parameters like thread count, solver type, crossover, tolerances, and random seed for optimization.

```yaml
solver:
  name: highs
  attributes:
    threads: 4
    solver: "ipm"
    run_crossover: "off"
    small_matrix_value: 1e-6
    large_matrix_value: 1e9
    primal_feasibility_tolerance: 1e-5
    dual_feasibility_tolerance: 1e-5
    ipm_optimality_tolerance: 1e-4
    parallel: "on"
    random_seed: 1234
```

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

### Configuring Performance Settings IESopt YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Example YAML configuration for the `performance` section under `config.general`. It shows how to disable `string_names` for potential performance improvements and explicitly enable the IESopt `logfile`.

```yaml
config:
  general:
    performance:
      string_names: false
      logfile: true
```

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

### Access Component Constraint Dual using get()

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/custom_results_1.ipynb

Uses the generic get() method with the mode='dual' argument to retrieve the dual value for a specific constraint ('nodalbalance') of a component ('grid').

```python
model.results.get("component", "grid", "con", "nodalbalance", mode="dual")
```

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

### LLM Prompt for Assisted Documentation Writing (Text)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/user_guides/toc_qna.md

This text snippet provides a base prompt designed for use with a Large Language Model (LLM) to assist in converting user interactions and Q&A into concise user guides or tutorials. It instructs the LLM to act as a seasoned developer, focus on the core topic, keep the output short and simple, use markdown format, and base the content on a provided chat exchange.

```text
You are a seasoned developer and work on energy system optimization models; write a short and concise tutorial / user-guide based on the interaction of a user with our support and Q&A team, that covers the discussed topic and addresses the initial problem or misunderstanding. Make sure to keep it short. Use simple and generally understandable wording. You can assume basic familiarity with programming, especially with Python. Output everything in markdown format. Start the tutorial with a proper short first-level header, followed by a "virtual question" that a user might ask themself. Base that question on the submitted information - no need to repeat any question directly verbatim. Remove all names from your answer if there are any. Header texts should start with an upper case letter, but use proper English case (mostly lower) for all other words.

Background information is available in the following documentation: https://ait-energy.github.io/iesopt/

The exchange below in triple quotes is the chat that you can use:

"""
... add stuff here ...
"""
```

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

### Example IESopt Result Folder Structure Text

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Illustrates the typical folder structure created by IESopt for storing model run results. It shows how the configured model name creates a subdirectory and how the scenario name (with the timestamp placeholder replaced) is used as the base filename for result and log files.

```text
.
├── data/
│   └── ...
├── out/
│   ├── FarayOptIndustry/
│   │   ├── Base_2022_LOW_T-2024_09_11_09520837.iesopt.result.jld2
│   │   ├── Base_2022_LOW_T-2024_09_11_09520837.iesopt.log
│   │   ├── Base_2022_LOW_T-2024_09_11_09520837.highs.log
│   │   └── ...
│   └── FarayOptIndustry_Baseline/
│       └── ...
└── config.iesopt.yaml
```

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

### Configuring Model Name and Scenario IESopt YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Example YAML configuration for the `name` section under `config.general`. It sets the `model` name and a dynamic `scenario` name using the `$TIME$` placeholder, which is replaced by a timestamp during the model build.

```yaml
config:
  general:
    name:
      model: FarayOptIndustry
      scenario: Base_2022_LOW_T-$TIME$
```

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

### Defining Components Directly in IESOPT YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Provides a basic example of defining a model component directly within the `components` section of the top-level IESOPT configuration file, specifying its type and carrier.

```yaml
components:
  main_grid_node:
    type: Node
    carrier: electricity
```

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

### Accessing IESopt File Results using get() - Python

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/custom_results_1.ipynb

Show how to retrieve a specific result from the loaded IESopt results object using the `get()` method with hierarchical keys as arguments.

```python
results.get("component", "storage", "exp", "setpoint")
```

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

### Installing Non-Registered Package (IESopt.jl) from GitHub in .env

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/python/configuration.md

Configures IESOPT_CORE to point to a non-registered version of IESopt.jl hosted on GitHub, specifying a branch or tag using a URL in the .env file. This allows using development or feature branches.

```text
IESOPT_CORE = https://github.com/ait-energy/IESopt.jl#super-important-feature
```

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

### Access Component Variable using get() (Primal)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/custom_results_1.ipynb

Uses the generic get() method to retrieve the primal value of a specific variable ('setpoint') for a component ('storage') and field type ('exp').

```python
model.results.get("component", "storage", "exp", "setpoint")
```

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

### Configure Results Output - Memory Only (YAML)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

An example configuration for the `results` section, enabling results extraction (`enabled: true`) but storing them only in memory (`memory_only: true`) without writing to disk.

```yaml
config:\n  results:\n    enabled: true\n    memory_only: true
```

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

### Defining Optional Parameters for Heat Pump - YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/tutorials/templates_1.md

Defines the parameters for the heat pump component, including optional parameters like `p_nom_max` for sizing and internal parameters starting with an underscore (`_inputs`, `_capacity`, `_conversion`, `_invest`) for internal logic and state management.

```yaml
parameters:
  p_nom: null
  p_nom_max: null
  electricity_from: null
  heat_from: null
  heat_to: null
  cop: null
  _inputs: null
  _conversion: null
  _capacity: null
  _invest: null
```

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

### Example iesopt Top-Level Configuration Structure (YAML)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/dev/updating.md

Illustrates the structure of the `config` section in the iesopt top-level YAML file, specifically showing how verbosity settings are nested under `general`. This structure is relevant for understanding how to access and modify these settings programmatically using the `config` keyword argument in Python.

```yaml
config:
  general:
    verbosity:
      core: info
```

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

### Configuring Custom Objectives in YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Allows defining custom objective expressions for the optimization problem. This is an advanced feature. The example shows creating an objective based on CO2 emissions.

```yaml
config:
  optimization:
    objectives:
      emissions: [co2_emissions.exp.value]
```

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

### Defining IESopt Asset Template with Internal Annuity Calculation - YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_55.ipynb

This YAML snippet defines an IESopt template named 'Asset'. It includes parameters for connection points and investment details. A `prepare` function calculates the annuity based on 'capex', 'lifetime', and 'wacc' using the `IESU.annuity` utility and sets the value of the private parameter '_annuity', which is then used as the cost for the 'invest' Decision component.

```yaml
parameters:
  from: null
  to: null
  invest: null
  _annuity: null

components:
  asset:
    type: Connection
    node_from: <from>
    node_to: <to>
    capacity: <self>.invest:value
  
invest:
    type: Decision
    lb: 0
    ub: 100
    cost: <_annuity>

functions:
  prepare: |
    capex = this.get("invest")["capex"]
    lifetime = this.get("invest")["lifetime"]
    annuity = IESU.annuity(capex; lifetime=lifetime, rate=this.get("wacc"))
    this.set("_annuity", annuity)
```

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

### Updating Julia Package from Python

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/python/configuration.md

Provides a Python code snippet using the iesopt library to force an update of a specific Julia package (like "IESopt") within the Julia environment managed by iesopt. This is useful for updating packages installed from non-registered sources like GitHub.

```python
import iesopt
iesopt.julia.seval('import Pkg; Pkg.update("IESopt")')
```

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

### Selecting specific components using regex anchors (Python)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/custom_results_2.ipynb

Demonstrates using regular expression anchors (`^` for start, `$` for end) to match components exactly by name ('elec'), preventing partial matches like 'electrolysis'.

```python
other_model.results.overview("h2_south|^elec$", temporal=True, mode="primal").head()
```

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

### Running IESopt Model and Querying Results - Python

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_55.ipynb

This Python snippet executes the IESopt model using the previously generated configuration, setting the core verbosity to 'error'. It then accesses the model's results, converts them to a pandas DataFrame, and queries for the 'value' field of the 'pipeline.invest' component in 'primal' mode.

```python
model = iesopt.run(config, config={"general.verbosity.core": "error"})

model.results.to_pandas().query(
    "component == 'pipeline.invest' and field == 'value' and mode == 'primal'"
)
```

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

### Configure CSV Reader - Ignore Comments (YAML)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Configures the CSV reader within the `_csv_config` section to ignore lines starting with '#' by setting the `comment` parameter. This is useful for handling commented-out rows in input CSV files.

```yaml
config:\n  files:\n    _csv_config:\n      comment: "#"
```

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

### Example Profile with node_from (YAML)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/user_guides/qna/profiles_sign.md

This YAML snippet defines a fixed time series Profile named 'myprofile' for the 'electricity' carrier. It is connected to the 'elec_grid_node' using `node_from`. Positive values in the `value` list indicate energy drawn from the node (consumption), while negative values indicate energy injected into the node (generation).

```YAML
myprofile:
  type: Profile
  carrier: electricity
  node_from: elec_grid_node
  value: [100, -50, 150, -75]  # in kW
```

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

### Modeling Output-Dependent Marginal Costs in IESopt YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/user_guides/qna/dynamic_marginal_costs.md

This YAML configuration demonstrates how to split a single conceptual unit with output-dependent marginal costs into two distinct IESopt 'Unit' definitions. The first unit ('unit_pool_1') represents the low-cost output range up to a specific capacity limit, while the second unit ('unit_pool_2') represents the higher-cost output for the remaining capacity. This setup allows the optimizer to prioritize the lower-cost unit first.

```YAML
unit_pool_1:
  type: Unit
  inputs: {}                    # fill this with the original configuration
  outputs: {}                   # fill this with the original configuration
  conversion: foo -> bar        # fill this with the original configuration
  capacity: 5 out:electricity
  marginal_cost: 5 per out:electricity

unit_pool_2:
  type: Unit
  inputs: {}                    # fill this with the original configuration
  outputs: {}                   # fill this with the original configuration
  conversion: foo -> bar        # fill this with the original configuration
  capacity: 95 out:electricity  # `100 - 5` MW, assuming 100 MW is the max.
  marginal_cost: 10 per out:electricity
```

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

### Build Documentation Locally with Sphinx and uv

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/dev/general.md

Builds the project documentation locally using Sphinx via uv run, with options for strict checking, failing on warnings, a fresh environment, and keeping going on errors.

```Bash
uv run sphinx-build --nitpicky --fail-on-warning --fresh-env --keep-going --builder html docs/ docs/_build/html
```

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

### Importing iesopt Library in Python

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_53.ipynb

This Python snippet shows the standard way to import the necessary 'iesopt' library, which is the first step to using the framework for energy system optimization.

```python
import iesopt
```

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

### Create Development Virtual Environment with uv

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/dev/general.md

Uses the uv tool to synchronize dependencies and create the project's development virtual environment in the .venv folder.

```Bash
uv sync
```

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

### Importing iesopt Library (Python)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_54.ipynb

Imports the necessary `iesopt` library to access its functions for creating and running energy system optimization models.

```python
import iesopt
```

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

### Complete IESopt Model Configuration File (YAML)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/first_model.ipynb

This comprehensive YAML snippet shows a full IESopt model configuration file. It includes optimization settings, carrier definitions (electricity, gas), and various components: Nodes (elec_grid, gas_grid, storage), a Connection (conn), Profiles (demand, photovoltaic, gas_market), and a Unit (gasturbine). It demonstrates setting component types, carriers, connections between nodes, capacities, profile values (fixed and time series), and special profile modes like 'create'.

```yaml
config:
  optimization:
    problem_type: LP
    snapshots:
      count: 24

carriers:
  electricity: {}
  gas: {}

components:
  elec_grid:                # the unique name of this component
    type: Node              # the type of this component
    carrier: electricity    # this (Node-specific) parameter fixes the carrier to be electricity

  gas_grid:                 # the unique name of this component
    type: Node              # the type of this component
    carrier: gas            # this (Node-specific) parameter fixes the carrier to be electricity

  storage:
    type: Node
    carrier: electricity
    has_state: true         # this allows this Node to have an "internal state"
    state_lb: 0             # the state can not drop below 0
    state_ub: 50            # a maximum of 50 electricity can be stored    
   
  conn:
    type: Connection
    node_from: elec_grid    # energy flows from HERE
    node_to: storage        # to THERE
    capacity: 15            # with a maximum capacity of +-15 units of electricity

  demand:
    type: Profile           # the type is now "Profile"
    carrier: electricity
    value: 5                # this models a fixed demand of 5 units of electricity during every Snapshot
    node_from: elec_grid    # this tells MFC that this Profile draws energy from "elec_grid"

  # We can also set the "value" of a Profile to a time series, as can be seen:
  photovoltaic:
    type: Profile
    carrier: electricity
    value: [0,0,0,0,0,1,2,3,4,5,8,12,12,12,8,5,4,3,2,1,0,0,0,0]
    node_to: elec_grid      # now feeding INTO "elec_grid"

  gas_market:
    type: Profile
    carrier: gas
    mode: create            # this changes the mode from the default ("fixed") to "create"
    cost: 100               # this specifies the "cost of gas"
    node_to: gas_grid

  gasturbine:
    type: Unit
    inputs: {gas: gas_grid}
    outputs: {electricity: elec_grid}
    conversion: 1 gas -> 0.40 electricity
    capacity: 100 out:electricity
```

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

### Loading Components from Files and Defining Directly in IESOPT YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Demonstrates using `load_components` to import components from external CSV files located in the configured components path, alongside defining additional components directly in the `components` section of the main IESOPT configuration file.

```yaml
load_components:
  - units.csv
  - nodes.csv
  - profiles.csv

components:
  co2_emissions:
    type: Profile
    carrier: co2
    mode: destroy
    node_from: total_co2
    cost: 100
```

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

### Rough outline of a simple `config.iesopt.yaml`.

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Shows the basic structure of the top-level IESopt configuration file, including the `config`, `carriers`, and `components` sections.

```yaml
config:
  optimization:
    problem_type: LP
    snapshots:
      count: 24

carriers:
  electricity: {}

components:
  main_grid_node:
    type: Node
    carrier: electricity
```

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

### Loading Components Using Regex Patterns in IESOPT YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Shows how to use a regular expression pattern within the `load_components` section to selectively load component files from the components path, demonstrating filtering by filename and directory structure using platform-independent path separators.

```yaml
load_components:
  - ^09[/\]((?!snapshots\.csv$).)*\.csv$
```

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

### Clean Documentation Build Directory with uv

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/dev/general.md

Cleans the documentation build directory before rebuilding, using the make command within the docs directory via uv run.

```Bash
uv run make -C docs clean
```

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

### Importing IESopt Library in Python

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_52.ipynb

Imports the necessary `iesopt` library to interact with the IESopt modeling framework in Python.

```python
import iesopt
```

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

### Running IESopt Optimization Script (Shell)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/first_model.ipynb

Executes the main Python script (`main.py`) to run the IESopt optimization model. Assumes `main.py` and the model file (`my_first_model.iesopt.yaml`) are located in the current directory. Requires a correct Python environment to be active.

```shell
python ./main.py
```

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

### Run Pytest Test Suite with uv

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/dev/general.md

Runs the project's test suite using pytest via the uv run command and prints a coverage report.

```Bash
uv run pytest
```

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

### Running IESopt Model and Querying Results (Python)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_54.ipynb

Executes the IESopt model with the generated configuration, suppressing core verbosity, and then queries the results to extract the primal state values for the 'house' component.

```python
model = iesopt.run(config, config={"general.verbosity.core": "error"})

model.results.to_pandas().query(
    "component == 'house' and field == 'state' and mode == 'primal'"
)
```

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

### Preparing Custom Heat Pump Configuration (Julia)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/tutorials/templates_1.md

This Julia code snippet defines the 'prepare' function. It determines if investment is enabled based on 'p_nom_max', sets the component's capacity accordingly, and configures the unit's inputs and conversion rule based on whether a heat input ('heat_from') is provided.

```Julia
# Determine if investment should be enabled, and set the parameter (used to enable `decision`).
invest = !isnothing(this.get("p_nom_max")) && this.get("p_nom_max") > this.get("p_nom")
this.set("_invest", invest)

if invest
    # Set the capacity to the size of the decision variable.
    myself = this.get("self")
    this.set("_capacity", "$(myself).decision:value")
else
    # Set the capacity to the value of `p_nom`.
    this.set("_capacity", this.get("p_nom"))
end

# Prepare some helper variables to make the code afterwards more readable.
elec_from = this.get("electricity_from")
heat_from = this.get("heat_from")
cop = this.get("cop")

# Handle the optional `heat_from` parameter.
if isnothing(heat_from)
    # If `heat_from` is not specified, we just use electricity as input.
    this.set("_inputs", "{electricity: $(elec_from)}")
    this.set("_conversion", "1 electricity -> $(cop) heat")
else
    # If `heat_from` is specified, we now have to account for two inputs.
    this.set("_inputs", "{electricity: $(elec_from), heat: $(heat_from)}")
    this.set("_conversion", "1 electricity + $(cop - 1) heat -> $(cop) heat")
end
```

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

### Load and Solve IESopt Model (Python)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/first_model.ipynb

This snippet imports the iesopt library, loads a model defined in a YAML file, solves it, and prints the resulting objective value. It demonstrates the basic workflow for running an IESopt model from Python.

```python
import iesopt

# Load and solve a model.
model = iesopt.run("my_first_model.iesopt.yaml")

print("Objective value:", model.objective_value)
```

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

### Configure IESopt Model Optimization (YAML)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/first_model.ipynb

This YAML snippet defines the general configuration for the IESopt model. It specifies the optimization problem type as Linear Programming (LP) and sets the number of time steps (snapshots) to 24, representing a full day.

```yaml
config:
  optimization:
    problem_type: LP
    snapshots:
      count: 24
```

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

### Running iesopt Model and Querying Results in Python

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_53.ipynb

This Python snippet executes the iesopt model using the previously generated configuration and then queries the results, specifically filtering for the 'state' field of the 'ev' component in the primal solution.

```python
model = iesopt.run(config, config={"general.verbosity.core": "error"})

model.results.to_pandas().query(
    "component == 'ev' and field == 'state' and mode == 'primal'"
)
```

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

### Run Tox Tests with uv

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/dev/general.md

Executes the test suite against all compatible Python versions defined in the tox configuration using uv run.

```Bash
uv run tox
```

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

### Clone iesopt Repository

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/dev/general.md

Clones the forked iesopt repository from GitHub to your local machine and navigates into the project directory.

```Bash
git clone https://github.com/your-username/iesopt.git
cd iesopt
```

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

### Adding Documentation to an IESopt Template YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/tutorials/templates_1.md

This YAML snippet shows the recommended structure for adding documentation comments at the beginning of an IESopt template file. It includes sections for the template title, description, parameters, components, and usage.

```YAML
# # Custom Heat Pump

# A (custom) heat pump that consumes electricity and heat, and produces heat.

# ## Parameters
# - `p_nom`: The nominal power (electricity) of the heat pump.
# - `electricity_from`: The `Node` that this heat pump is connected to for electricity input.
# - `heat_from`: The `Node` that this heat pump is connected to for heat input.
# - `heat_to`: The `Node` that this heat pump is connected to for heat output.
# - `cop`: The coefficient of performance of the heat pump.

# ## Components
# _to be added_

# ## Usage
# _to be added_

# ## Details
```

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

### Implementing Validation and Preparation Functions - YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/tutorials/templates_1.md

Defines the `validate` and `prepare` functions for the heat pump component. The `validate` function checks constraints on `p_nom_max`. The `prepare` function determines if investment is enabled, sets the capacity based on investment or `p_nom`, and handles the optional `heat_from` input by setting internal `_inputs` and `_conversion` parameters.

```yaml
functions:
  validate: |
    # ... the previous validation code ...

    # Check if `p_nom_max` is either `nothing` or at least `p_nom`.
    @check isnothing(this.get("p_nom_max")) || (this.get("p_nom_max") isa Number && this.get("p_nom_max") >= this.get("p_nom"))
  prepare: |
    # Determine if investment should be enabled, and set the parameter (used to enable `decision`).
    invest = !isnothing(this.get("p_nom_max")) && this.get("p_nom_max") > this.get("p_nom")
    this.set("_invest", invest)

    if invest
        # Set the capacity to the size of the decision variable.
        myself = this.get("self")
        this.set("_capacity", "$(myself).decision:value")
    else
        # Set the capacity to the value of `p_nom`.
        this.set("_capacity", this.get("p_nom"))
    end

    # Prepare some helper variables to make the code afterwards more readable.
    elec_from = this.get("electricity_from")
    heat_from = this.get("heat_from")
    cop = this.get("cop")

    # Handle the optional `heat_from` parameter.
    if isnothing(heat_from)
        # If `heat_from` is not specified, we just use electricity as input.
        this.set("_inputs", "{electricity: $(elec_from)}")
        this.set("_conversion", "1 electricity -> $(cop) heat")
    else
        # If `heat_from` is specified, we now have to account for two inputs.
        this.set("_inputs", "{electricity: $(elec_from), heat: $(heat_from)}")
        this.set("_conversion", "1 electricity + $(cop - 1) heat -> $(cop) heat")
    end
```

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

### Defining Demand, PV, and Gas Market Profiles (IESopt YAML)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/first_model.ipynb

Defines three 'Profile' components: 'demand' (fixed electricity withdrawal from 'elec_grid'), 'photovoltaic' (time-series electricity injection into 'elec_grid'), and 'gas_market' (gas creation with cost into 'gas_grid'). Profiles represent energy sources or sinks. These are added under the 'components' section.

```YAML
  demand:
    type: Profile           # the type is now "Profile"
    carrier: electricity
    value: 5                # this models a fixed demand of 5 units of electricity during every Snapshot
    node_from: elec_grid    # this tells MFC that this Profile draws energy from "elec_grid"

  # We can also set the "value" of a Profile to a time series, as can be seen:
  photovoltaic:
    type: Profile
    carrier: electricity
    value: [0,0,0,0,0,1,2,3,4,5,8,12,12,12,8,5,4,3,2,1,0,0,0,0]
    node_to: elec_grid      # now feeding INTO "elec_grid"

  gas_market:
    type: Profile
    carrier: gas
    mode: create            # this changes the mode from the default ("fixed") to "create"
    cost: 100               # this specifies the "cost of gas"
    node_to: gas_grid
```

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

### Configuring Snapshots in YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Defines the time steps (Snapshots) for the optimization. Requires specifying the count of snapshots and optionally their names and weights (duration in hours).

```yaml
config:
  optimization:
    snapshots:
      count: 24
      weights: 4
```

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

### Defining Simple Grid Tariffs in YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_53.ipynb

This YAML snippet defines the components for a simple grid tariff model within an iesopt configuration, including grid nodes, connections for buying and selling electricity with associated energy costs, and a decision variable for the power peak consumption tariff.

```yaml
components:
  # ... other stuff ...

  grid_market:
    type: Node
    carrier: electricity

  grid_internal:
    type: Node
    carrier: electricity
  
  # NOTE: `0.05` (here ct/kWh) is the energy related tariff for consumption.
  grid_connection_buy:
    type: Connection
    node_from: grid_market
    node_to: grid_internal
    lb: 0
    ub: tariff_power_consumption:value
    cost: 0.05
  
  # NOTE: No power peak related cost for feeding electricity back to the grid.
  grid_connection_sell:
    type: Connection
    node_from: grid_internal
    node_to: grid_market
    lb: 0
    ub: 1000
    cost: 0.07

  # NOTE: This assumes `1000` (here kW) as maximum grid connection. `1.15` is the power peak related tariff.
  tariff_power_consumption:
    type: Decision
    lb: 0
    ub: 1000
    cost: 1.15
```

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

### Configuring Gurobi Solver in YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/user_guides/general/solvers.md

Standard YAML configuration for the Gurobi solver, specifying method, crossover, convergence tolerance, seed, and thread count.

```yaml
solver:
  name: gurobi
  attributes:
    Method: 2
    Crossover: 0
    BarConvTol: 1.e-6
    Seed: 123
    AggFill: 0
    PreDual: 0
    GURO_PAR_BARDENSETHRESH: 200
    Threads: 8
    Seed: 1234
```

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

### Configuring Gurobi Solver (NumFocus) in YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/user_guides/general/solvers.md

YAML configuration for the Gurobi solver with NumericFocus=3, suitable for models with challenging numerical properties, including specific tolerances and scaling.

```yaml
solver:
  name: gurobi
  attributes:
    NumericFocus: 3
    Method: 2
    Crossover: 0
    BarHomogeneous: 1
    BarConvTol: 1.e-5
    FeasibilityTol: 1.e-4
    OptimalityTol: 1.e-4
    ObjScale: -0.5
    Threads: 8
    Seed: 1234
```

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

### Defining Gas Grid and Stateful Storage Nodes (IESopt YAML)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/first_model.ipynb

Defines the 'gas_grid' Node for 'gas' and the 'storage' Node for 'electricity'. The storage node is configured as stateful with lower and upper bounds for its state (e.g., state of charge). These are added under the 'components' section.

```YAML
  gas_grid:                 # the unique name of this component
    type: Node              # the type of this component
    carrier: gas            # this (Node-specific) parameter fixes the carrier to be electricity

  storage:
    type: Node
    carrier: electricity
    has_state: true         # this allows this Node to have an "internal state"
    state_lb: 0             # the state can not drop below 0
    state_ub: 50            # a maximum of 50 electricity can be stored
```

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

### IESopt Template Structure with Functions Section (YAML)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/tutorials/templates_1.md

Outlines the basic YAML structure for an IESopt template, showing the placement of the 'parameters', 'component', and 'functions' sections, including placeholders for the validate, prepare, and finalize functions.

```YAML
# ... the whole docstring ...

parameters:
  # ...

component:
  # ...

functions:
  validate: |
    # ... we will put the validation code here ...
  prepare: |
    # ... we will put the preparation code here ...
  finalize: |
    # ... we will put the finalization code here ...
```

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

### IESopt Component Configuration (YAML)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_54.ipynb

Defines the components of the simple room temperature model, including a house node with temperature bounds, a heat pump unit converting electricity to heat, and a profile for passive temperature changes.

```yaml
components:
  # ... other stuff ...

  # NOTE: Constructing a simple "degree celsius" storage, ranging from 20 to 23 degrees.
  house:
    type: Node
    carrier: heat_degree_celsius
    has_state: true
    state_lb: 20
    state_ub: 23

  heatpump:
    type: Unit
    inputs: {electricity: grid}
    outputs: {heat_degree_celsius: house}
    conversion: 1 electricity -> cop@data * <degc_per_kWh> heat_degree_celsius
    capacity: 5 in:electricity
  
  # NOTE: Modeling this using `node_from` means it models the passive cooling of the house; negative values in
  #       `demand@data` therefore relate to passive heating (e.g., during summer times).
  passive_change:
    type: Profile
    carrier: heat_degree_celsius
    node_from: house
    value: demand@data
```

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

### Setting Addon Parameters in IESOPT YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Shows how to configure specific parameters for registered addons within the `addons` section of the IESOPT configuration file. This section is optional and the settings are specific to each addon.

```yaml
addons:
  ModifyHeatStorages:
    alpha: 0.93
    temperature: 60.0
```

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

### Querying Tariff Power Consumption Results in Python

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_53.ipynb

This Python code demonstrates how to query the iesopt model results specifically for the 'tariff_power_consumption' variable, which represents the power peak related tariff decision in the primal solution.

```python
model.results.to_pandas().query(
    "component == 'tariff_power_consumption' and fieldtype == 'var' and mode == 'primal'"
)
```

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

### Using a Custom Template in IESopt Configuration YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/tutorials/templates_1.md

This YAML snippet demonstrates how to instantiate a custom template (`CustomHeatPump`) within the `components` section of a main IESopt configuration file. It shows how to provide specific values for the parameters defined in the template.

```YAML
# other parts of the configuration file
# ...

components:
  # some other components
  # ...

  heat_pump:
    template: CustomHeatPump
    parameters:
      p_nom: 10
      electricity_from: electricity
      heat_from: ambient
      heat_to: heating
      cop: 3
```

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

### Running iesopt with Programmatic Config Overrides (Python)

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/dev/updating.md

Demonstrates how to use the `config` keyword argument with `iesopt.run` to programmatically modify top-level configuration options during parsing. This allows overriding settings like verbosity, snapshot count, or input file paths without changing the main YAML file.

```python
import iesopt

iesopt.run("my_config.iesopt.yaml", config = {
    "general.verbosity.core": "error",
    "optimization.snapshots.count": 168,
    "files.data_in": "scenario17/data.csv",
})
```

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

### Import iesopt Library

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/custom_results_1.ipynb

Imports the necessary iesopt library to begin working with models and results.

```python
import iesopt
```

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

### Defining EV Components in IESopt YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/notebooks/example_52.ipynb

Details the YAML configuration for an EV system in IESopt, including a 'Connection' component for the charger (with power limits and loss), a 'Node' component for the EV (representing storage with state bounds), and a 'Profile' component for EV demand.

```yaml
components:
  # ... other stuff ...

  # NOTE: This could be a `Unit` instead, to allow more complex behaviours.
  # This assumes a rated power of "40 kW" and only allows charging while the EV is actually connected.
  charger:
    type: Connection
    node_from: grid
    node_to: ev
    loss: 0.05
    lb: 0
    ub: 40.0 * connected@data

  ev:
    type: Node
    carrier: electricity
    has_state: true
    state_lb: 0
    state_ub: 100

  ev_demand:
    type: Profile
    carrier: electricity
    node_from: ev
    value: demand@data
```

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

### Configuring Solver Settings in YAML

Source: https://github.com/ait-energy/iesopt/blob/main/docs/pages/manual/yaml/top_level.md

Specifies the solver to use for the optimization problem. Allows setting the solver name, controlling log output, and passing additional attributes to the solver.

```yaml
config:
  optimization:
    solver:
      name: highs
      log: false
      attributes:
        solver: ipm
```