### Expected Java Version Output

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/home/installation.md

This is an example of the expected output when checking the Java version. It indicates that Java is installed and provides version details.

```text
java version "1.8.0_341"
Java(TM) SE Runtime Environment (build 1.8.0_341-b10)
Java HotSpot(TM) 64-Bit Server VM (build 25.341-b10, mixed mode)
```

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

### Verify Installation

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/home/installation.md

Checks the installed Snakemake version to confirm successful environment setup.

```bash
snakemake --version
```

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

### Serve Documentation Locally

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/community/contributing.md

Build and serve the documentation locally using mkdocs. This command starts a development server.

```bash
.../pypsa-earth/doc (pypsa-earth-docs) % mkdocs serve
```

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

### Install Documentation Dependencies

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/community/contributing.md

Install all required Python packages for documentation building using pip. Ensure the conda environment is active.

```bash
.../pypsa-earth % pip install -r doc/requirements.txt
```

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

### Check Java Installation

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/home/installation.md

Confirm if Java is installed on your system by checking its version. PyPSA-Earth requires Java redistribution to function correctly.

```bash
java --version
```

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

### Install pre-commit hook

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/community/contributing.md

Install the pre-commit utility to automatically lint and format code contributions according to project guidelines.

```bash
conda install -c conda-forge pre-commit

```

```bash
pip install pre-commit

```

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

### Install Mamba and Create Environment

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/home/installation.md

Installs mamba for faster package management and creates the PyPSA-Earth environment using a platform-specific lock file. Ensure you activate the environment after creation.

```bash
conda install -c conda-forge mamba

mamba env create -f envs/linux-64.lock.yaml  # select the appropriate file for your platform

conda activate pypsa-earth
```

```bash
conda env create -f envs/linux-64.lock.yaml

conda activate pypsa-earth
```

```bash
conda install -c conda-forge mamba

mamba env create -f envs/environment.yaml
```

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

### Copy Default Configuration

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/user-guide/customization/basic-setup.md

Create a local configuration file by copying the default settings. This is the starting point for all customizations.

```bash
cp config.default.yaml config.yaml
```

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

### Clone Documentation Repository

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/tutorials/examples.md

Clone the documentation repository to access the provided notebooks and setup instructions.

```bash
git clone https://github.com/pypsa-meets-earth/documentation.git
```

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

### Verify Java Installation

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/README.md

Checks if Java is installed and its version. This is a prerequisite for certain functionalities.

```bash
.../pypsa-earth % java -version
```

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

### Install and Use Pre-commit Hooks

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/configtables/snippets/README.md

Install pre-commit hooks for automatic regeneration of configuration snippets upon committing changes to config.default.yaml.

```bash
# Install pre-commit hooks (one-time setup)
pip install pre-commit
pre-commit install

# Now snippets update automatically on commit!
git add config.default.yaml
git commit -m "Update config"  # Snippets auto-update before commit
```

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

### Install Jupyter Lab

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/home/installation.md

Installs Jupyter Lab and its IPython kernel for the PyPSA-Earth environment, enabling the use of Jupyter notebooks.

```bash
ipython kernel install --user --name=pypsa-earth
jupyter lab
```

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

### Install Mamba for Faster Installation

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/README.md

Installs Mamba, a faster alternative to Conda, for environment creation. This is an optional step for faster installations.

```bash
(base) conda install -c conda-forge mamba
```

```bash
.../pypsa-earth % mamba env create -f envs/{{your operating system}}64.lock.yaml
```

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

### Configure Solver in config.yaml

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/user-guide/customization/running-models.md

Specify the optimization solver to be used for the model run. This example sets the solver to 'glpk'.

```yaml
solver:
  name: glpk
```

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

### Monte Carlo / Global Sensitivity Analysis Setup

Source: https://context7.com/pypsa-meets-earth/pypsa-earth/llms.txt

This script performs global sensitivity analysis using Latin Hypercube Sampling (LHS) to vary uncertain parameters like load profiles and renewable capacity factors simultaneously.

```yaml

```

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

### Configure Countries for Tutorial Model

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/tutorials/electricity-model.md

Specify the countries to include in the model run. This example limits the scope to Nigeria and Benin.

```yaml
countries: ["NG", "BJ"]
```

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

### Load and Analyze a Solved Network

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/tutorials/electricity-model.md

Load a previously solved PyPSA network from a file using `pypsa.Network` for analysis in Python. This is the starting point for exploring simulation results.

```python
import pypsa

network = pypsa.Network("results/networks/elec_s_6_ec_lcopt_Co2L-4H.nc")
```

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

### Configure Scenario Options

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/tutorials/electricity-model.md

Define the scenario parameters, including the number of clusters and optimization options. This example uses 6 clusters and the 'Co2L-4H' optimization.

```yaml
scenario:
clusters: [6]
opts: [Co2L-4H]
```

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

### Compute Renewable Capacity Factors - Python

Source: https://context7.com/pypsa-meets-earth/pypsa-earth/llms.txt

Uses AtLite to compute hourly capacity factor time-series and installable potentials for renewable energy sources. Converts ERA5 weather data into usable profiles and land-use-constrained potentials for each network bus.

```python
import xarray as xr

# Output file structure for, e.g., solar:
ds = xr.open_dataset("resources/profile_solar.nc")
print(ds)
# Dimensions: (bus: 48, time: 8760)
# Data variables:
#   profile       (bus, time)   float32  – per-unit hourly availability [0–1]
#   p_nom_max     (bus,)        float32  – max installable capacity [MW] from land use
#   average_distance (bus,)    float32  – avg distance to grid node [km]
#   weight        (bus,)        float32  – area weight per bus
```

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

### Load and Analyze Energy Summary Data with Pandas

Source: https://context7.com/pypsa-meets-earth/pypsa-earth/llms.txt

Load energy summary data from a CSV file using pandas and analyze supply by carrier. This example demonstrates accessing specific rows and columns to view energy production figures.

```python
import pandas as pd

# Example: load energy summary for full model area
energy = pd.read_csv(
    "results/ng_bj_test/summaries/elec_s_10_ec_lcopt_Co2L-3h_all",
    index_col=[0, 1],
)
print(energy.loc["Supply", :])
#                    ng_bj_test
# solar              28450.0    [GWh/yr]
# onwind             15200.0
# OCGT                 420.0
# hydro               3100.0

costs = pd.read_csv(
    "results/ng_bj_test/summaries/elec_s_10_ec_lcopt_Co2L-3h_all",
    index_col=[0, 1],
)

```

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

### Run Tutorial Model with Specific Config

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/tutorials/electricity-model.md

Run the tutorial model using the `config.tutorial.yaml` file directly. This is useful for testing the tutorial case and will trigger data loading if specified.

```bash
snakemake -j 1 solve_all_networks --configfile config.tutorial.yaml
```

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

### Run Tutorial Model

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/home/quick-start.md

Execute the tutorial workflow for the Nigerian power system. This command downloads data, builds the network, runs optimization, and generates results.

```bash
snakemake -call results/NG/networks/elec_s_6_ec_lcopt_Co2L-4H.nc --configfile config.tutorial.yaml
```

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

### Set Temporal Scope for Simulation

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/tutorials/electricity-model.md

Define the start and end dates for the simulation's temporal scope. This example sets the scope to a single week for quick completion.

```yaml
snapshots:
start: "2013-03-1"
end: "2013-03-7"
```

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

### Activate Environment and Copy Config

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/tutorials/electricity-model.md

Activate the conda environment and copy the tutorial configuration file to `config.yaml`. Back up any existing `config.yaml` if necessary.

```bash
conda activate pypsa-earth
```

```bash
cp config.tutorial.yaml config.yaml
```

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

### Install OpenJDK in Conda Environment

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/home/installation.md

Install the OpenJDK package within your conda environment using mamba. This is recommended for Linux and macOS users who need to install Java.

```bash
mamba install -c conda-forge openjdk
```

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

### Serve Documentation Locally (PowerShell)

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/community/contributing.md

Alternative command for serving documentation locally on Windows using PowerShell. This is a workaround for potential 'make' issues.

```bash
1. If using Windows PowerShell, you can also run `mkdocs serve`.
```

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

### Install Conda-Lock

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/home/installation.md

Installs conda-lock, a tool used for generating reproducible environment lock files.

```bash
conda install conda-lock -c conda-forge
```

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

### Change Directory

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/tutorials/examples.md

Navigate into the newly created project directory.

```bash
cd pypsa-earth-project
```

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

### Navigate to Documentation Directory

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/community/contributing.md

Change the current directory to the 'doc' folder where mkdocs configuration resides.

```bash
.../pypsa-earth (pypsa-earth-docs) % cd doc
```

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

### Check Conda Installation

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/home/installation.md

Verify if the conda package manager is installed on your system. This is a prerequisite for managing Python packages for PyPSA-Earth.

```bash
conda --version
```

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

### Install IPython Kernel for Jupyter Lab

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/README.md

Installs the IPython kernel for PyPSA-Earth, enabling its use within Jupyter Lab. This is an optional step for using Jupyter notebooks.

```bash
.../pypsa-earth % ipython kernel install --user --name=pypsa-earth
```

```bash
.../pypsa-earth % jupyter lab
```

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

### Example of using {country} wildcard

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/user-guide/wildcards.md

Use the {country} wildcard to narrow down summary generation rules to specific countries or all countries. This example shows how to generate a summary for Germany.

```bash
snakemake -j 1 results/summaries/elec_s_all_lall_Co2L-3H_DE
```

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

### Create Project Directory

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/tutorials/examples.md

Use this command to create a new directory for your pypsa-earth project.

```bash
mkdir pypsa-earth-project
```

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

### Activate Conda Environment

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/community/contributing.md

Activate the newly created conda environment before installing packages.

```bash
.../pypsa-earth % conda activate pypsa-earth-docs
```

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

### Import and Use Helper Functions from _helpers.py

Source: https://context7.com/pypsa-meets-earth/pypsa-earth/llms.txt

Import various utility functions from the _helpers.py script for tasks such as logging configuration, reading configuration files, country code conversion, and aggregating network data.

```python
from _helpers import (
    configure_logging,
    create_logger,
    read_osm_config,
    check_config_version,
    update_cutout_config,
    two_2_three_digits_country,
    three_2_two_digits_country,
    two_digits_2_name_country,
    aggregate_p_nom,
    aggregate_p,
)
import pypsa

# Country code conversion
iso3 = two_2_three_digits_country("NG")     # → "NGA"
iso2 = three_2_two_digits_country("NGA")    # → "NG"
name = two_digits_2_name_country("NG")      # → "Nigeria"

# Read OSM/region configuration
world_iso = read_osm_config("world_iso")
# → {"Africa": {"DZ": "algeria", "NG": "nigeria", ...}, "Europe": {...}}

continent = read_osm_config("continent_regions")

# Aggregate installed and dispatched capacity from a solved network
n = pypsa.Network("results/.../networks/elec_s_10_ec_lcopt_Co2L-3h.nc")
p_nom_by_carrier = aggregate_p_nom(n)
print(p_nom_by_carrier)
# solar      5800.0
# onwind     3200.0
# OCGT          0.0

energy_by_carrier = aggregate_p(n)
print(energy_by_carrier)
# solar      28450000   [MWh/yr]
# onwind     15200000

# Version compatibility check (called at Snakefile startup)
import yaml
with open("config.yaml") as f:
    config = yaml.safe_load(f)
check_config_version(config)
# Logs error if config version != code version (0.8.0)

```

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

### Create Conda Environment (Windows)

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/README.md

Installs the Python package requirements for PyPSA-Earth on a Windows system using conda.

```bash
conda env create -f envs/win-64.lock.yaml
```

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

### Create Conda Environment (Linux)

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/README.md

Installs the Python package requirements for PyPSA-Earth on a Linux system using conda.

```bash
conda env create -f envs/linux-64.lock.yaml
```

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

### Activate Environment and Solve Sector Networks

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/tutorials/sector-coupled-model.md

Activate the PyPSA-Earth environment and run the sector network solving process.

```bash
conda activate pypsa-earth
snakemake solve_sector_networks -j2 --configfile test/config.myopic.yaml
```

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

### Generate Workflow DAG

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/home/introduction.md

Generate a Directed Acyclic Graph (DAG) of the workflow for reproducibility. This requires Graphviz to be installed.

```bash
snakemake --dag networks/elec_s_128.nc | dot -Tpng -o workflow.png
```

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

### Apply Scenario Constraints with PyPSA

Source: https://context7.com/pypsa-meets-earth/pypsa-earth/llms.txt

Load a prepared network and print global constraints to verify scenario application. This script applies CO₂ limits, transmission expansion caps, and temporal aggregation.

```python
# Wildcard decoding examples:
# opts = "Co2L-3h"  →  CO₂ limit from config + 3-hour temporal resolution
# opts = "Co2L0.5"  →  50% of the config co2limit
# ll   = "copt"     →  cost-optimal transmission expansion (no cap)
# ll   = "v1.25"    →  line volume limit = 125% of today
# ll   = "c1.0"     →  line cost limit = 100% of today

# After prepare_network, the ready-to-solve network is:
# networks/elec_s{simpl}_{clusters}_ec_l{ll}_{opts}.nc
import pypsa

n = pypsa.Network("networks/elec_s_10_ec_lcopt_Co2L-3h.nc")
# Check that CO₂ constraint was applied
print(n.global_constraints)
#              type  carrier_attribute  sense  constant
# CO2Limit  primary_energy  co2_emissions  <=  7.75e+07
```

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

### Run the Full Model Workflow

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/doc/tutorials/electricity-model.md

Execute the complete PyPSA-Earth model workflow. This command builds and solves the electricity network based on the configuration.

```bash
snakemake -j 1 solve_all_networks
```

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

### Create Conda Environment (macOS)

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/README.md

Installs the Python package requirements for PyPSA-Earth on a non-ARM macOS system using conda.

```bash
conda env create -f envs/osx-64.lock.yaml
```

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

### Build Base Network Topology - Python

Source: https://context7.com/pypsa-meets-earth/pypsa-earth/llms.txt

Constructs the PyPSA network topology from cleaned OSM data. Establishes buses, AC lines, DC links, and transformers. Requires a pre-existing base network file.

```python
import pypsa

# The rule produces: networks/base.nc
# Load and inspect the base network after the rule has run:
n = pypsa.Network("networks/base.nc")

print(n.buses.head())
#          v_nom  x          y       country  carrier
# bus_id
# 180000   380.0  3.42       6.45    NG      AC
# 180001   220.0  3.38       6.51    NG      AC

print(n.lines[["bus0", "bus1", "s_nom", "length"]].head())
#          bus0    bus1    s_nom   length
# line_id
# 10001    180000  180003  300.0   85.4
```

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

### Configure Network Solving Options

Source: https://context7.com/pypsa-meets-earth/pypsa-earth/llms.txt

Key configuration options for the network solving process. These include solver selection, load shedding thresholds, and parameters for iterative expansion.

```python
# Key solving config:
# solving:
#   solver:
#     name: highs          # also: gurobi, cplex, glpk
#   options:
#     load_shedding: 1e4   # [EUR/MWh] — enables feasibility slack
#     clip_p_max_pu: 0.01  # zero-out near-zero capacity factors
#     skip_iterations: false
#     max_iterations: 6    # LTEP iterations
```

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

### Create Conda Environment (macOS ARM)

Source: https://github.com/pypsa-meets-earth/pypsa-earth/blob/main/README.md

Installs the Python package requirements for PyPSA-Earth on an ARM-based macOS system using conda.

```bash
conda env create -f envs/osx-arm64.lock.yaml
```