# Interface Configuration Guide

This guide provides detailed documentation for the `Interface_RDM.xlsx` configuration file.

## Overview

`Interface_RDM.xlsx` is the central configuration file that controls all aspects of the OSeMOSYS-RDM workflow. It contains multiple sheets, each handling different configuration aspects.

## Sheet Reference

| Sheet | Purpose |
|-------|---------|
| Setup | Main execution parameters |
| To_Print | Output variables to export |
| Uncertainty_Table | RDM uncertainty definitions |
| Params_Sets_Vari | Parameter-set mappings |

## Setup Sheet

### Parameter Reference

#### Execution Control

| Parameter | Type | Values | Description |
|-----------|------|--------|-------------|
| Run_Base_Future | String | Yes/No | Execute baseline scenario |
| Run_RDM | String | Yes/No | Execute RDM experiment |
| Scenario_to_Reproduce | String | Experiment/All/{name} | Which scenarios to run |

#### Solver Configuration

| Parameter | Type | Values | Description |
|-----------|------|--------|-------------|
| Solver | String | glpk/cbc/cplex/gurobi | Optimization solver |
| Threads_CPLEX_Gurobi | Integer | ≥1 | Number of threads allocated to CPLEX or Gurobi per solve. Ignored for single-thread solvers (CBC, GLPK). See [Parallel Execution](rdm-pipeline.md#parallel-execution) for sizing guidance. |
| Time_CBC | Integer | seconds | Maximum solve time for CBC solver (passed as `sec` parameter). Ignored for other solvers. |
| OSeMOSYS_Model_Name | String | filename | Model formulation file (e.g., `model.v.5.4.txt`) |

#### Model Settings

| Parameter | Type | Values | Description |
|-----------|------|--------|-------------|
| Region | String | Any | Model region identifier |
| Timeslices_model | Integer | 1-8760 | Number of time slices |

#### RDM Settings

| Parameter | Type | Values | Description |
|-----------|------|--------|-------------|
| Number_of_Runs | Integer | ≥1 | Number of futures to generate |
| Parallel_Use | Integer | ≥1 | Batch size for parallelization |
| Experiment_ID | String | Any | Unique experiment identifier |
| Initial_Year_of_Uncertainty | Integer | Year | Global uncertainty start year |

#### EV UDC Sign Correction

| Parameter | Type | Values | Description |
|-----------|------|--------|-------------|
| EV_Conventional_Patterns | String | Substrings | Semicolon-separated patterns for conventional technologies (e.g., `DSL;DSH;GSL`) |
| EV_Electric_Pattern | String | Substring | Pattern for electric technologies (e.g., `ELC`) |
| EV_UDCs | String | Names | Semicolon-separated EV penetration UDC constraint names |

```{note}
These three fields configure automatic post-perturbation sign correction for UDC EV penetration coefficients. If any field is empty, the correction is skipped. See the [RDM Pipeline](rdm-pipeline.md) for a full explanation of the mathematical context.
```

### Example Configuration

```
Solver: cplex
Threads_CPLEX_Gurobi: 4
Time_CBC: 3600
Run_Base_Future: Yes
Run_RDM: Yes
Region: UGA
OSeMOSYS_Model_Name: model.v.5.4.txt
Timeslices_model: 48
Number_of_Runs: 100
Parallel_Use: 10
Scenario_to_Reproduce: Experiment
Experiment_ID: 1
Initial_Year_of_Uncertainty: 2025
```

## To_Print Sheet

Controls which OSeMOSYS output variables are exported.

### Structure

| Column | Description |
|--------|-------------|
| Parameter | OSeMOSYS variable name |
| Print | Mark with an **X** to include in output (not Yes/No) |

```{note}
To enable an output parameter for printing, place an **X** in the Print column. Do not use "Yes" or "No".
```

### Common Output Variables

#### Cost Variables
- `TotalDiscountedCost`
- `CapitalInvestment`
- `OperatingCost`
- `AnnualFixedOperatingCost`
- `AnnualVariableOperatingCost`

#### Capacity Variables
- `TotalCapacityAnnual`
- `NewCapacity`
- `AccumulatedNewCapacity`

#### Activity Variables
- `ProductionByTechnology`
- `TotalAnnualTechnologyActivityByMode`
- `RateOfActivity`
- `UseByTechnology`

#### Emission Variables
- `AnnualEmissions`
- `AnnualTechnologyEmission`

#### Trade Variables
- `Export`
- `Import`

## Uncertainty_Table Sheet

Defines all uncertain parameters for RDM analysis.

### Column Definitions

#### Identification

| Column | Type | Description |
|--------|------|-------------|
| X_Num | Integer | Unique identifier (1, 2, 3, ...) |
| X_Category | String | Grouping category |
| X_Plain_English_Description | String | Human-readable description |
| XLRM_ID | String | Optional XLRM framework ID |

#### Mathematical Specification

| Column | Type | Description |
|--------|------|-------------|
| X_Mathematical_Type | String | Variation method |
| Explored_Parameter_of_X | String | What aspect to vary |
| Min_Value | Float | Lower bound (multiplier or absolute value) |
| Max_Value | Float | Upper bound (multiplier or absolute value) |
| Dependency | String | `YES` if the next row is a complementary dependent (default: `NO`) |

#### OSeMOSYS Mapping

| Column | Type | Description |
|--------|------|-------------|
| Involved_Scenarios | String | Semicolon-separated scenario list |
| Involved_First_Sets_in_Osemosys | String | Primary set elements |
| Involved_Second_Sets_in_Osemosys | String | Secondary set elements |
| Involved_Third_Sets_in_Osemosys | String | Tertiary set elements |
| Exact_Parameters_Involved_in_Osemosys | String | OSeMOSYS parameter names |

```{important}
**Multiple Values in Columns:**
- When specifying multiple values in the columns mentioned above (sets, scenarios, parameters), separate them with ` ; ` (space-semicolon-space)
- The spaces before and after the semicolon are **required**
- Example: `PWRSOL001 ; PWRSOL002` (correct) vs `PWRSOL001;PWRSOL002` (incorrect)
- **Note:** The option "All" is not valid. You must specify each value individually.
```

#### Temporal Settings

| Column | Type | Description |
|--------|------|-------------|
| Initial_Year_of_Uncertainty | Integer | Year uncertainty begins |

### X_Mathematical_Type Options

#### Time_Series

Non-linear interpolation from current trajectory to modified final value.

```
Original: 2025: 100 → 2030: 120 → 2050: 200
Modified (mult=1.2): 2025: 100 → 2030: 124 → 2050: 240
```

**Use for:** Cost projections, demand growth, efficiency improvements

#### Constant

Maintains value constant from uncertainty start year.

```
Original: 2025: 100 → 2030: 100 → 2050: 100
Result: Values frozen at start year level
```

**Use for:** Fixed policy constraints, technology limits

#### Linear

Linear interpolation to modified final value.

```
Original: 2025: 100 → 2050: 200
Modified: Linear path from 100 to 240
```

**Use for:** Simple linear projections

#### Logistic

S-curve (sigmoid) trajectory.

```
Slow start → Rapid middle growth → Saturation
```

**Use for:** Technology adoption curves, market penetration

#### Step

Sets an absolute target value from the uncertainty start year onwards. Unlike other types, `Min_Value` and `Max_Value` represent **absolute values** (not multipliers).

```
Original: 2025: 100 → 2026: 50 → 2027: 0 → ... → 2050: 0
Step (value=25): 2025: 25 → 2026: 25 → ... → 2050: 25
```

**Use for:** Parameters where the baseline final value is 0 and multipliers cannot generate variability (since 0 x multiplier = 0). Typical cases include imports or technologies that are phased out in the baseline but may continue in alternative futures.

```{important}
When using `Step`, the `Min_Value` and `Max_Value` columns define the **absolute range** of the target value (e.g., 5 to 50 PJ), not a multiplier range. The LHS-sampled value is applied directly from `Initial_Year_of_Uncertainty` onwards.
```

#### Timeslices_Curve

Modifies time slice profiles using predefined curves.

```
References: shape_of_demand.csv
Selects curve based on LHS sample
```

**Use for:** Demand shape uncertainty, load profiles

### Explored_Parameter_of_X Options

| Value | Description |
|-------|-------------|
| Final_Value | Modify the final year value (rescales each annual delta by `m_new/m_original`) |
| Final_Value_Multiplicative | Multiply the baseline by a year-dependent ramp (1.0 at `Initial_Year_of_Uncertainty`, sampled multiplier at the last year). Preserves codos/inflexiones by construction — use this when the baseline is non-monotonic (codos, plateaus, or magnitudes `< 1` like `InputActivityRatio`/`OutputActivityRatio`). |
| Multiplier | Apply constant multiplier |
| Change_Curve | Change the profile/shape |

```{tip}
**When to choose `Final_Value` vs `Final_Value_Multiplicative` for `Time_Series`:**

- `Final_Value` works well for **monotonic** baselines with non-trivial slope (e.g., demand growing roughly linearly). It rescales each year's incremental change so the trajectory still ends at `final × multiplier`.
- `Final_Value_Multiplicative` is the **shape-preserving** choice. Pick it whenever the baseline has codos, plateaus, or operates in `[0, 1]` (activity ratios). Each baseline point is scaled by a linear ramp that grows from 1.0 at the uncertainty year to the sampled multiplier at the last year — the geometry of the baseline (relative drops, plateaus, peaks) is preserved exactly.
```

### Example Entries

#### Fuel Cost Uncertainty

```
X_Num: 1
X_Category: Fuel Costs
X_Plain_English_Description: Natural gas import price
X_Mathematical_Type: Time_Series
Explored_Parameter_of_X: Final_Value
Min_Value: 0.7
Max_Value: 1.5
Involved_Scenarios: Scenario1 ; Scenario2
Involved_First_Sets_in_Osemosys: IMPNATGAS
Exact_Parameters_Involved_in_Osemosys: VariableCost
Initial_Year_of_Uncertainty: 2025
```

#### Technology Limit Uncertainty

```
X_Num: 2
X_Category: Technology Limits
X_Plain_English_Description: Solar PV maximum installable capacity
X_Mathematical_Type: Time_Series
Explored_Parameter_of_X: Final_Value
Min_Value: 0.5
Max_Value: 2.0
Involved_Scenarios: Scenario1
Involved_First_Sets_in_Osemosys: PWRSOL001 ; PWRSOL002
Exact_Parameters_Involved_in_Osemosys: TotalAnnualMaxCapacity
Initial_Year_of_Uncertainty: 2025
```

#### Demand Shape Uncertainty

```
X_Num: 3
X_Category: Demand
X_Plain_English_Description: Electricity demand profile shape
X_Mathematical_Type: Timeslices_Curve
Explored_Parameter_of_X: Change_Curve
Min_Value: 1
Max_Value: 10
Involved_Scenarios: Scenario1
Involved_First_Sets_in_Osemosys: ELCDEM
Involved_Second_Sets_in_Osemosys: All
Exact_Parameters_Involved_in_Osemosys: SpecifiedDemandProfile
Initial_Year_of_Uncertainty: 2025
```

#### Zero-Baseline Parameter (Step Function)

When the baseline value drops to 0 (e.g., imports phased out after 2026), use `Step` with absolute values:

```
X_Num: 4
X_Category: Imports
X_Plain_English_Description: Fuel imports continuation beyond phase-out
X_Mathematical_Type: Step
Explored_Parameter_of_X: Final_Value
Min_Value: 5
Max_Value: 50
Involved_Scenarios: Scenario1
Involved_First_Sets_in_Osemosys: IMPFUEL001
Exact_Parameters_Involved_in_Osemosys: TotalTechnologyAnnualActivityUpperLimit
Initial_Year_of_Uncertainty: 2025
```

Here, `Min_Value: 5` and `Max_Value: 50` are absolute values (e.g., PJ), not multipliers.

#### Complementary Dependency Between Parameters

When two parameters must preserve a share constraint (e.g., `primary + dependent = constant`), set `Dependency: YES` on the primary row. The dependent row (immediately after) will automatically adjust its values to preserve the additive constraint:

```
X_Num: 5
X_Category: Technology Share
X_Plain_English_Description: Solar share of total capacity
X_Mathematical_Type: Time_Series
Explored_Parameter_of_X: Final_Value
Min_Value: 0.7
Max_Value: 1.3
Dependency: YES
Involved_Scenarios: Scenario1
Involved_First_Sets_in_Osemosys: PWRSOL001
Exact_Parameters_Involved_in_Osemosys: UDCMultiplierTotalCapacity
Initial_Year_of_Uncertainty: 2025

X_Num: 6
X_Category: Technology Share
X_Plain_English_Description: Wind share (complement of solar)
X_Mathematical_Type: Time_Series
Explored_Parameter_of_X: Final_Value
Min_Value: 0.7
Max_Value: 1.3
Dependency: NO
Involved_Scenarios: Scenario1
Involved_First_Sets_in_Osemosys: PWRWND001
Exact_Parameters_Involved_in_Osemosys: UDCMultiplierTotalCapacity
Initial_Year_of_Uncertainty: 2025
```

Row 6 (wind) values are computed as: `new_dep(t) = baseline_dep(t) + (new_primary(t) - baseline_primary(t))`, so their sum remains constant.

## Params_Sets_Vari Sheet

Maps parameters to their dependent sets for correct data manipulation.

### Structure

| Column | Description |
|--------|-------------|
| parameter | OSeMOSYS parameter name |
| Number | Count of dependent sets (1-3) |
| Set1 | First set type |
| Set2 | Second set type (if applicable) |
| Set3 | Third set type (if applicable) |

### Set Type Values

- `TECHNOLOGY`
- `FUEL` / `COMMODITY`
- `YEAR`
- `TIMESLICE`
- `MODE_OF_OPERATION`
- `EMISSION`
- `REGION`
- `STORAGE`

### Example Entries

```
parameter: VariableCost
Number: 2
Set1: TECHNOLOGY
Set2: MODE_OF_OPERATION

parameter: CapacityFactor
Number: 2
Set1: TECHNOLOGY
Set2: TIMESLICE

parameter: SpecifiedDemandProfile
Number: 2
Set1: FUEL
Set2: TIMESLICE
```

## Validation Tips

### Before Running

1. **Check solver availability**: Ensure selected solver is installed
2. **Verify scenario files**: Confirm `.txt` files exist in `0_Scenarios/`
3. **Validate sets**: Check that referenced sets exist in scenario files
4. **Check parameter names**: Ensure exact OSeMOSYS parameter names

### Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| "Parameter not found" | Typo in parameter name | Check exact OSeMOSYS spelling |
| "Set not found" | Set element doesn't exist | Verify in scenario file |
| "NaN values" | Formula error in Excel | Check cell references |
| "Index out of range" | Missing set mapping | Add to Params_Sets_Vari |