API Reference

Complete API documentation for all r2x-reeds classes and functions.

Parser

class r2x_reeds.ReEDSParser(config, data_store, *, name=None, auto_add_composed_components=True, skip_validation=False)[source]

Bases: BaseParser

Parser for ReEDS model data following r2x-core framework patterns.

The parser builds an infrasys.System from ReEDS model output by:

  1. Component Building (build_system_components): - Regions from hierarchy data (buses with regional attributes) - Generators split into renewable (aggregated by tech-region) and non-renewable (with vintage) - Transmission interfaces and lines with bi-directional ratings - Loads with peak demand by region - Reserves by transmission region and type - Emissions as supplemental attributes on generators

  2. Time Series Attachment (build_time_series): - Load profiles filtered by weather year and solve year - Renewable capacity factors from CF data - Reserve requirements calculated from wind/solar/load contributions

  3. Post-Processing (post_process_system): - System metadata and description

Key Implementation Details

  • Renewable generators are aggregated by technology and region (no vintage)

  • Non-renewable generators retain vintage information

  • Reserve requirements are calculated dynamically based on wind capacity, solar capacity, and load data with configurable percentage contributions

  • Time series data is filtered to match configured weather years and solve years

  • Component caches are used during building for efficient cross-referencing

param config:

ReEDS-specific configuration with solve years, weather years, etc.

type config:

ReEDSConfig

param data_store:

Initialized DataStore with ReEDS file mappings loaded

type data_store:

DataStore

param name:

Name for the system being built

type name:

str, optional

param auto_add_composed_components:

Whether to automatically add composed components

type auto_add_composed_components:

bool, default=True

param skip_validation:

Skip Pydantic validation for performance (use with caution)

type skip_validation:

bool, default=False

Examples

Basic usage:

>>> import json
>>> from pathlib import Path
>>> from r2x_core.store import DataStore
>>> from r2x_reeds.config import ReEDSConfig
>>> from r2x_reeds.parser import ReEDSParser
>>>
>>> # Load defaults and create DataStore
>>> defaults = ReEDSConfig.load_defaults()
>>> mapping_path = ReEDSConfig.get_file_mapping_path()
>>> data_folder = Path("tests/data/test_Pacific")
>>>
>>> # Create config (defaults loaded separately, not passed to config)
>>> config = ReEDSConfig(
...     solve_years=2030,
...     weather_years=2012,
...     case_name="High_Renewable",
... )
>>>
>>> # Create DataStore from file mapping
>>> data_store = DataStore.from_json(mapping_path, folder=data_folder)
>>>
>>> # Create parser and build system
>>> parser = ReEDSParser(config, data_store, name="ReEDS_System")
>>> system = parser.build_system()

Initialize ReEDS parser.

validate_inputs()[source]

Validate input data before building system.

Return type:

None

build_system_components()[source]

Create all system components from ReEDS data.

Components are built in dependency order: regions → generators → transmission → loads → reserves → emissions

Return type:

None

build_time_series()[source]

Attach time series data to components.

Return type:

None

post_process_system()[source]

Perform post-processing on the built system.

Return type:

None

Parameters:

  • config (ReEDSConfig)

  • data_store (DataStore)

  • name (str | None)

  • auto_add_composed_components (bool)

  • skip_validation (bool)

Configuration

pydantic model r2x_reeds.ReEDSConfig[source]

Configuration for ReEDS model parser.

This configuration class defines all parameters needed to parse ReEDS model data, including year information and model-specific settings. Model-specific defaults and constants should be loaded using the load_defaults() class method and used in parser logic.

Parameters:

  • solve_years (int | list[int]) – Model solve year(s) (e.g., 2030, [2030, 2040, 2050])

  • weather_years (int | list[int]) – Weather data year(s) used for time series profiles (e.g., 2012, [2007, 2012])

  • case_name (str, optional) – Name of the ReEDS case

  • scenario (str, optional) – Scenario identifier

Examples

Single year:

>>> config = ReEDSConfig(
...     solve_years=2030,
...     weather_years=2012,
...     case_name="High_Renewable",
... )

Multiple years:

>>> config = ReEDSConfig(
...     solve_years=[2030, 2040, 2050],
...     weather_years=[2007, 2012],
...     case_name="Multi_Year_Analysis",
... )

Load model defaults separately for use in parser:

>>> # Load defaults using the class method
>>> defaults = ReEDSConfig.load_defaults()
>>> excluded_techs = defaults.get("excluded_techs", [])
>>>
>>> # Create config (no defaults field)
>>> config = ReEDSConfig(
...     solve_years=2030,
...     weather_years=2012,
... )

See also

r2x_core.plugin_config.PluginConfig

Base configuration class

r2x_reeds.parser.ReEDSParser

Parser that uses this configuration

load_defaults

Class method to load default constants from JSON

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

  • case_name (str | None)

  • scenario (str)

  • solve_year (int | list[int])

  • weather_year (int | list[int])

field case_name: Annotated[str | None, Field(default=None, description='Case name')] = None

Case name

field scenario: Annotated[str, Field(default='base', description='Scenario identifier')] = 'base'

Scenario identifier

field solve_year: Annotated[int | list[int], Field(description='Model solve year(s) - automatically converted to list')] [Required]

Model solve year(s) - automatically converted to list

field weather_year: Annotated[int | list[int], Field(description='Weather data year(s) - automatically converted to list')] [Required]

Weather data year(s) - automatically converted to list

DEFAULTS_FILE_NAME: ClassVar[str] = 'defaults.json'
FILE_MAPPING_NAME: ClassVar[str] = 'file_mapping.json'
property primary_solve_year: int

Get the primary (first) solve year.

Returns:

The first solve year in the list

Return type:

int

property primary_weather_year: int

Get the primary (first) weather year.

Returns:

The first weather year in the list

Return type:

int

Component Models

Generator

pydantic model r2x_reeds.ReEDSGenerator[source]

ReEDS generator component.

Represents a generation resource in the ReEDS model.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

  • capacity (float)

  • forced_outage_rate (float | None)

  • fuel_price (float | None)

  • fuel_type (str | None)

  • heat_rate (float | None)

  • max_age (int | None)

  • min_capacity_factor (float | None)

  • planned_outage_rate (float | None)

  • region (r2x_reeds.models.components.ReEDSRegion)

  • retirement_year (int | None)

  • technology (str | None)

  • vintage (str | None)

  • vom_cost (float | None)

field capacity: Annotated[float, Field(description='Existing capacity in MW', ge=0)] [Required]

Existing capacity in MW

Constraints:

  • ge = 0

field forced_outage_rate: Annotated[float | None, Field(None, description='Forced outage rate (fraction)', ge=0, le=1)] = None

Forced outage rate (fraction)

Constraints:

  • ge = 0

  • le = 1

field fuel_price: Annotated[float | None, Field(None, description='Fuel price in $/MMBtu', ge=0)] = None

Fuel price in $/MMBtu

Constraints:

  • ge = 0

field fuel_type: Annotated[str | None, Field(None, description="Fuel type (e.g., 'coal', 'gas')")] = None

Fuel type (e.g., ‘coal’, ‘gas’)

field heat_rate: Annotated[float | None, Field(None, description='Heat rate in MMBtu/MWh', ge=0)] = None

Heat rate in MMBtu/MWh

Constraints:

  • ge = 0

field max_age: Annotated[int | None, Field(None, description='Maximum age in years', ge=0)] = None

Maximum age in years

Constraints:

  • ge = 0

field min_capacity_factor: Annotated[float | None, Field(None, description='Minimum capacity factor', ge=0, le=1)] = None

Minimum capacity factor

Constraints:

  • ge = 0

  • le = 1

field planned_outage_rate: Annotated[float | None, Field(None, description='Planned outage rate (fraction)', ge=0, le=1)] = None

Planned outage rate (fraction)

Constraints:

  • ge = 0

  • le = 1

field region: Annotated[ReEDSRegion, Field(description='ReEDS region where generator is located')] [Required]

ReEDS region where generator is located

field retirement_year: Annotated[int | None, Field(None, description='Planned retirement year')] = None

Planned retirement year

field technology: Annotated[str | None, Field(None, description='ReEDS technology type')] = None

ReEDS technology type

field vintage: Annotated[str | None, Field(None, description='Vintage bin identifier')] = None

Vintage bin identifier

field vom_cost: Annotated[float | None, Field(None, description='Variable O&M cost in $/MWh', ge=0)] = None

Variable O&M cost in $/MWh

Constraints:

  • ge = 0

Region (Bus)

pydantic model r2x_reeds.ReEDSRegion[source]

ReEDS regional component.

Represents a geographic region in the ReEDS model with various regional attributes and hierarchies.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

  • cc_region (str | None)

  • cendiv (str | None)

  • country (str | None)

  • h2ptc_region (str | None)

  • hurdle_region (str | None)

  • interconnect (str | None)

  • max_active_power (float | None)

  • nerc_region (str | None)

  • state (str | None)

  • timezone (str | None)

  • transmission_group (str | None)

  • transmission_region (str | None)

  • usda_region (str | None)

field cc_region: Annotated[str | None, Field(None, description='Climate change region')] = None

Climate change region

field cendiv: Annotated[str | None, Field(None, description='Census division')] = None

Census division

field country: Annotated[str | None, Field(None, description='Country code')] = None

Country code

field h2ptc_region: Annotated[str | None, Field(None, description='H2 PTC region')] = None

H2 PTC region

field hurdle_region: Annotated[str | None, Field(None, description='Hurdle rate region')] = None

Hurdle rate region

field interconnect: Annotated[str | None, Field(None, description='Interconnection (eastern, western, texas)')] = None

Interconnection (eastern, western, texas)

field max_active_power: Annotated[float | None, Field(None, description='Peak demand in MW', ge=0)] = None

Peak demand in MW

Constraints:

  • ge = 0

field nerc_region: Annotated[str | None, Field(None, description='NERC region')] = None

NERC region

field state: Annotated[str | None, Field(None, description='State abbreviation')] = None

State abbreviation

field timezone: Annotated[str | None, Field(None, description='Time zone identifier')] = None

Time zone identifier

field transmission_group: Annotated[str | None, Field(None, description='Transmission group')] = None

Transmission group

field transmission_region: Annotated[str | None, Field(None, description='Transmission planning region')] = None

Transmission planning region

field usda_region: Annotated[str | None, Field(None, description='USDA region')] = None

USDA region

Transmission Line

pydantic model r2x_reeds.ReEDSTransmissionLine[source]

ReEDS transmission line component.

Represents a transmission line connection between two regions.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

  • distance_miles (float | None)

  • hurdle_rate (float | None)

  • interface (r2x_reeds.models.components.ReEDSInterface)

  • line_cost_per_mw_mile (float | None)

  • line_type (str | None)

  • losses (float | None)

  • max_active_power (r2x_reeds.models.base.FromTo_ToFrom)

  • voltage (float | None)

field distance_miles: Annotated[float | None, Field(None, description='Distance in miles', ge=0)] = None

Distance in miles

Constraints:

  • ge = 0

field hurdle_rate: Annotated[float | None, Field(None, description='Hurdle rate forward direction', ge=0)] = None

Hurdle rate forward direction

Constraints:

  • ge = 0

field interface: Annotated[ReEDSInterface, Field(description='Interface connecting two regions')] [Required]

Interface connecting two regions

field line_cost_per_mw_mile: Annotated[float | None, Field(None, description='Cost per MW-mile', ge=0)] = None

Cost per MW-mile

Constraints:

  • ge = 0

field line_type: Annotated[str | None, Field(None, description='Line type (AC/DC)')] = None

Line type (AC/DC)

field losses: Annotated[float | None, Field(None, description='Transmission losses (fraction)', ge=0, le=1)] = None

Transmission losses (fraction)

Constraints:

  • ge = 0

  • le = 1

field max_active_power: Annotated[FromTo_ToFrom, Field(description='Transfer capacity limit in MW')] [Required]

Transfer capacity limit in MW

field voltage: Annotated[float | None, Field(None, description='Voltage level in kV', ge=0)] = None

Voltage level in kV

Constraints:

  • ge = 0

Reserve Requirement

pydantic model r2x_reeds.ReEDSReserve[source]

ReEDS operating reserve component.

Defines operating reserve requirements and parameters for the system.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

  • direction (r2x_reeds.models.enums.ReserveDirection)

  • duration (float | None)

  • load_risk (float | None)

  • max_requirement (float)

  • region (r2x_reeds.models.components.ReEDSReserveRegion | None)

  • reserve_type (r2x_reeds.models.enums.ReserveType)

  • time_frame (float)

  • vors (float)

field direction: Annotated[ReserveDirection, Field(description='Direction of reserve provision')] [Required]

Direction of reserve provision

field duration: Annotated[PositiveFloat | None, Field(None, description='Time over which the required response must be maintained in seconds')] = None

Time over which the required response must be maintained in seconds

field load_risk: Annotated[Percentage | None, Field(None, description='Proportion of load that contributes to the requirement')] = None

Proportion of load that contributes to the requirement

field max_requirement: Annotated[float, Field(description='Maximum reserve requirement', ge=0)] = 0

Maximum reserve requirement

Constraints:

  • ge = 0

field region: Annotated[ReEDSReserveRegion | None, Field(None, description='Reserve region where requirement applies')] = None

Reserve region where requirement applies

field reserve_type: Annotated[ReserveType, Field(description='Type of reserve')] [Required]

Type of reserve

field time_frame: Annotated[PositiveFloat, Field(description='Timeframe in which the reserve is required in seconds')] = 1e+30

Timeframe in which the reserve is required in seconds

Constraints:

  • gt = 0

field vors: Annotated[float, Field(description='Value of reserve shortage in $/MW. Positive value acts as soft constraint')] = -1

Value of reserve shortage in $/MW. Positive value acts as soft constraint

Demand Profile

pydantic model r2x_reeds.ReEDSDemand[source]

ReEDS electrical demand component.

Represents load/demand in a region.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

  • max_active_power (float | None)

  • region (r2x_reeds.models.components.ReEDSRegion)

field max_active_power: Annotated[float | None, Field(None, description='Maximum active power demand in MW', ge=0)] = None

Maximum active power demand in MW

Constraints:

  • ge = 0

field region: Annotated[ReEDSRegion, Field(description='ReEDS region')] [Required]

ReEDS region

Emission Rate

pydantic model r2x_reeds.ReEDSEmission[source]

Emission attribute attached to generators.

Represents emissions produced by generation resources.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Fields:

  • emission_type (r2x_reeds.models.enums.EmissionType)

  • rate (float)

field emission_type: Annotated[EmissionType, Field(description='Type of emission (e.g., CO2, NOx)')] [Required]

Type of emission (e.g., CO2, NOx)

field rate: Annotated[EmissionRate, Field(description='Amount of emission produced in kg/MWh')] [Required]

Amount of emission produced in kg/MWh

Constraints:

  • ge = 0

Enumerations

Emission Type

class r2x_reeds.EmissionType(*values)[source]

Bases: str, Enum

Types of emissions tracked in power system models.

CO2 = 'CO2'
NOX = 'NOx'
SO2 = 'SO2'
PM25 = 'PM2.5'
PM10 = 'PM10'
VOC = 'VOC'
NH3 = 'NH3'
CH4 = 'CH4'
N2O = 'N2O'

Reserve Type

class r2x_reeds.ReserveType(*values)[source]

Bases: str, Enum

Types of operating reserves.

REGULATION = 'Regulation'
SPINNING = 'Spinning'
NON_SPINNING = 'Non-Spinning'
FLEXIBILITY_UP = 'Flexibility_Up'
FLEXIBILITY_DOWN = 'Flexibility_Down'
CONTINGENCY = 'Contingency'

Reserve Direction

class r2x_reeds.ReserveDirection(*values)[source]

Bases: str, Enum

Direction of reserve provision.

UP = 'Up'
DOWN = 'Down'

See Also