API Reference

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

Parser

class r2x_reeds.ReEDSParser(config, *, store, auto_add_composed_components=True, skip_validation=False, overrides=None, **kwargs)[source]

Bases: BaseParser

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

This parser builds an infrasys.System from ReEDS model output through three main phases:

  1. Component Building (build_system_components()): - Regions from hierarchy data 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 (postprocess_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 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

param **kwargs:

Additional keyword arguments passed to parent BaseParser

system

The constructed power system model

Type:

infrasys.System

config

The ReEDS configuration instance

Type:

ReEDSConfig

data_store

The DataStore for accessing ReEDS data files

Type:

DataStore

build_system()

Build and return the complete infrasys.System

build_system_components()[source]

Construct all system components (regions, generators, transmission, loads, reserves)

Return type:

Result[None, ParserError]

build_time_series()[source]

Attach time series data to components

Return type:

Result[None, ParserError]

postprocess_system()[source]

Apply post-processing steps to the system

Return type:

Result[None, ParserError]

See also

BaseParser

Parent class with core system building logic

ReEDSConfig

Configuration class for ReEDS parser

DataStore

Data storage and access interface

Examples

Build a ReEDS system from test data:

>>> from pathlib import Path
>>> from r2x_core.store import DataStore
>>> from r2x_reeds.config import ReEDSConfig
>>> from r2x_reeds.parser import ReEDSParser
>>>
>>> config = ReEDSConfig(solve_years=2030, weather_years=2012, case_name="High_Renewable")
>>> mapping_path = ReEDSConfig.get_file_mapping_path()
>>> data_folder = Path("tests/data/test_Pacific")
>>> data_store = DataStore.from_json(mapping_path, path=data_folder)
>>> parser = ReEDSParser(config, store=data_store, name="ReEDS_System")
>>> system = parser.build_system()

Notes

The parser uses internal caches for regions and generators to optimize cross-referencing during component construction. These caches are populated during build_system_components() and are used for all subsequent operations.

Initialize the ReEDS parser with configuration and data access.

param config:

Configuration object specifying solve years, weather years, case name, and scenario

type config:

ReEDSConfig

param store:

Initialized DataStore with ReEDS file mappings and data access

type store:

DataStore

param auto_add_composed_components:

Whether to automatically add composed components to the system, by default True

type auto_add_composed_components:

bool, optional

param skip_validation:

Skip Pydantic validation for performance (use with caution), by default False

type skip_validation:

bool, optional

param overrides:

Configuration overrides to apply, by default None

type overrides:

dict[str, Any] | None, optional

param **kwargs:

Additional keyword arguments passed to parent BaseParser class

system

The constructed power system model (populated by build_system())

Type:

infrasys.System

config

The ReEDS configuration instance

Type:

ReEDSConfig

data_store

The DataStore for accessing ReEDS data files

Type:

DataStore

validate_inputs()[source]

Validate input data and configuration before building the system.

Performs comprehensive validation including: - Presence of required datasets - Validity of configured solve and weather years - Loading and parsing of configuration assets - Rule validation from parser configuration

Returns:

Ok() if all validation checks pass, Err() with detailed error message otherwise

Return type:

Result[None, ParserError]

Raises:

ParserError – If required datasets are missing, configured years don’t exist in data, or configuration files cannot be loaded

prepare_data()[source]

Prepare and normalize configuration, time arrays, and component datasets.

Initializes internal caches and datasets required for component building: - Parser context with configuration and defaults - Time indices and calendar mappings for the weather year - Generator datasets separated into variable and non-variable groups - Hydro capacity factor data for budget calculations - Reserve requirement configuration and costs

Returns:

Ok() on successful preparation, Err() with ParserError if any step fails

Return type:

Result[None, ParserError]

Notes

This method must be called after validate_inputs() and before build_system_components(). It populates internal caches used throughout the build process.

build_system_components()[source]

Create all system components from ReEDS data in dependency order.

Builds the complete set of power system components by calling builder methods in sequence: regions, generators, transmission interfaces/lines, loads, reserves, and emissions. Each step validates success before proceeding to the next.

Returns:

Ok() if all components created successfully, Err() with ParserError listing any creation failures

Return type:

Result[None, ParserError]

Notes

Components are built in strict dependency order: 1. Regions (required by all other components) 2. Generators (requires regions) 3. Transmission interfaces and lines 4. Loads (requires regions) 5. Reserves and reserve regions (requires transmission regions) 6. Emissions (requires generators)

build_time_series()[source]

Attach time series data to all system components in a specific sequence.

Populates time series data for various component types in dependency order: 1. Reserve membership associations (which reserves apply to which generators) 2. Load profiles (hourly demand by region) 3. Renewable capacity factors (hourly availability for wind/solar) 4. Reserve requirement profiles (dynamic requirements based on load/wind/solar) 5. Hydro budget constraints (daily energy constraints by month)

Time series data is filtered to match configured weather and solve years, and multiple time series per component are supported for multi-year scenarios.

Returns:

Ok() if all time series attached successfully, Err() with ParserError if any attachment step fails

Return type:

Result[None, ParserError]

Raises:

ParserError – If required time series datasets are empty or mismatched with configured years

postprocess_system()[source]

Perform post-processing and finalization of the constructed system.

Sets system-level metadata and logs summary statistics: - Data format version (from repository commit hash) - System description incorporating case name, scenario, solve/weather years - Component statistics and system validation information

This is the final step after components and time series are built, ensuring the system is properly documented and ready for export.

Returns:

Ok() on successful post-processing, Err() with ParserError if metadata application fails

Return type:

Result[None, ParserError]

Notes

This method should be called after both build_system_components() and build_time_series() have completed successfully.

Parameters:

  • config (ReEDSConfig)

  • store (DataStore)

  • auto_add_composed_components (bool)

  • skip_validation (bool)

  • overrides (dict[str, Any] | None)

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]

Base generator component with fields common to all generation types.

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)

  • capital_cost (float | None)

  • fom_cost (float | None)

  • forced_outage_rate (float | None)

  • fuel_price (float | None)

  • fuel_type (str | None)

  • heat_rate (float | None)

  • max_age (int | None)

  • planned_outage_rate (float | None)

  • region (r2x_reeds.models.components.ReEDSRegion)

  • retirement_year (int | None)

  • technology (str)

  • vintage (str | None)

  • vom_cost (float | None)

field capacity: Annotated[PositiveFloat, Unit('MW'), Field(description='Installed capacity', ge=0)] [Required]

Installed capacity

Constraints:

  • gt = 0

  • unit = MW

  • ge = 0

field capital_cost: Annotated[PositiveFloat | None, Unit('$/MW'), Field(description='Capital cost')] = None

Capital cost

Constraints:

  • unit = $/MW

field fom_cost: Annotated[PositiveFloat | None, Unit('$/MW/year'), Field(description='Fixed O&M')] = None

Fixed O&M

Constraints:

  • unit = $/MW/year

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

Forced outage rate

field fuel_price: Annotated[PositiveFloat | None, Unit('$/MMBtu'), Field(description='Fuel price')] = None

Fuel price

Constraints:

  • unit = $/MMBtu

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

Fuel type

field heat_rate: Annotated[PositiveFloat | None, Unit('MMBtu/MWh'), Field(description='Heat rate')] = None

Heat rate

Constraints:

  • unit = MMBtu/MWh

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

Maximum age

Constraints:

  • unit = years

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

Planned outage rate

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

ReEDS region

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

Planned retirement year

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

ReEDS technology type

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

Vintage bin identifier

field vom_cost: Annotated[PositiveFloat | None, Unit('$/MWh'), Field(description='Variable O&M')] = None

Variable O&M

Constraints:

  • unit = $/MWh

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(description='Climate change region')] = None

Climate change region

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

Census division

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

Country code

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

H2 PTC region

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

Hurdle rate region

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

Interconnection (eastern, western, texas)

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

Peak demand in MW

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

NERC region

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

State abbreviation

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

Time zone identifier

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

Transmission group

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

Transmission planning region

field usda_region: Annotated[str | None, Field(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(description='Distance in miles')] = None

Distance in miles

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

Hurdle rate forward direction

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(description='Cost per MW-mile')] = None

Cost per MW-mile

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

Line type (AC/DC)

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

Transmission losses (fraction)

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(description='Voltage level in kV')] = None

Voltage level in kV

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)

  • flex_cost (float | None)

  • or_load_percentage (float | None)

  • or_pv_percentage (float | None)

  • or_wind_percentage (float | None)

  • reg_cost (float | None)

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

  • reserve_type (r2x_reeds.models.enums.ReserveType)

  • season (str | None)

  • spin_cost (float | None)

  • 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(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 flex_cost: Annotated[float | None, Field(description='Flexibility reserve cost in $/MW from cost_opres files')] = None

Flexibility reserve cost in $/MW from cost_opres files

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

Proportion of load that contributes to the reserve requirement

field or_pv_percentage: Annotated[float | None, Field(description='Proportion of solar generation that contributes to the reserve requirement')] = None

Proportion of solar generation that contributes to the reserve requirement

field or_wind_percentage: Annotated[float | None, Field(description='Proportion of wind generation that contributes to the reserve requirement')] = None

Proportion of wind generation that contributes to the reserve requirement

field reg_cost: Annotated[float | None, Field(description='Regulation reserve cost in $/MW from cost_opres files')] = None

Regulation reserve cost in $/MW from cost_opres files

field region: Annotated[ReEDSReserveRegion | None, Field(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 season: Annotated[str | None, Field(description='Seasonal identifier for reserve requirement variations (summ/fall/wint/spri)')] = None

Seasonal identifier for reserve requirement variations (summ/fall/wint/spri)

field spin_cost: Annotated[float | None, Field(description='Spinning reserve cost in $/MW from cost_opres files')] = None

Spinning reserve cost in $/MW from cost_opres files

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(description='Maximum active power demand in MW')] = None

Maximum active power demand in MW

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

ReEDS region

Emission Rate

pydantic model r2x_reeds.ReEDSEmission[source]

ReEDS emission supplemental attribute.

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:

  • rate (float)

  • source (r2x_reeds.models.enums.EmissionSource)

  • type (r2x_reeds.models.enums.EmissionType)

field rate: Annotated[float, Unit('kg/MWh'), Field(description='Emission rate for emission type in kg/MWh')] [Required]

Emission rate for emission type in kg/MWh

Constraints:

  • unit = kg/MWh

field source: EmissionSource = EmissionSource.COMBUSTION
field type: EmissionType [Required]

Enumerations

Emission Type

class r2x_reeds.EmissionType(*values)[source]

Bases: str, Enum

Types of emissions tracked in power system models.

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

Reserve Type

class r2x_reeds.ReserveType(*values)[source]

Bases: str, Enum

Types of operating reserves.

REGULATION = 'REGULATION'
SPINNING = 'SPINNING'
NON_SPINNING = 'NON_SPINNING'
FLEXIBILITY = 'FLEXIBILITY'
CONTINGENCY = 'CONTINGENCY'
COMBO = 'COMBO'

Reserve Direction

class r2x_reeds.ReserveDirection(*values)[source]

Bases: str, Enum

Direction of reserve provision.

UP = 'Up'
DOWN = 'Down'

See Also