r2x-core 0.4.0

Extensible framework for building power system model translators with plugin architecture

r2x-core

Extensible framework for power system model translation

R2X Core is a model-agnostic framework for building power system model translators. It provides the core infrastructure, data models, plugin architecture, and APIs that enable translation between different power system modeling platforms.

About R2X Core

R2X Core serves as the foundation for building translators between power system models like ReEDS, PLEXOS, SWITCH, Sienna, and more. It provides a plugin-based architecture where you can register parsers, exporters, and transformations to create custom translation workflows.

Features

• Capability-based plugin architecture - Plugins implement only the hooks they need (validate, prepare, build, transform, translate, export, cleanup)
• Declarative rule system - Define model translations through configuration, not code
• Rule filters for selective translation - Composable filters to control which components rules process
• Standardized component models - Power system components via infrasys
• Multiple file format support - Native support for CSV, HDF5, Parquet, JSON, and XML
• Configurable HDF5 reader - Flexible configuration-driven approach for any HDF5 structure
• Type-safe configuration - Pydantic-based PluginConfig with automatic validation
• Per-unit system - Automatic unit handling with device-base, natural units, and system-base display modes
• Flexible data store - Automatic format detection, intelligent caching, and component tracking
• Entry point discovery - External packages can register plugins via setuptools/pyproject.toml entry points

Installation

pip install r2x-core

Or with uv:

uv add r2x-core

Python version support: 3.11, 3.12, 3.13

Quick Start

Using the DataStore

The DataStore provides a high-level interface for managing and loading data files:

from r2x_core import DataStore, DataFile

# Create a DataStore pointing to your data directory
store = DataStore(path="/path/to/data")

# Add files to the store
data_file = DataFile(name="generators", fpath="gen.csv")
store.add_data(data_file)

# Or add multiple files at once
files = [
    DataFile(name="generators", fpath="gen.csv"),
    DataFile(name="loads", fpath="load.csv"),
    DataFile(name="buses", fpath="buses.h5")
]
store.add_data(*files)

# Read data from the store
gen_data = store.read_data("generators")

# List all available data files
available_files = store.list_data()

# Remove a data file
store.remove_data("generators")

Building a Model Translator with Plugins

Create a plugin to translate power system models:

from r2x_core import Plugin, PluginConfig, PluginContext, Rule, System, DataStore
from rust_ok import Ok

# Define type-safe configuration
class MyModelConfig(PluginConfig):
    input_folder: str
    model_year: int
    scenario: str = "base"

# Implement your translator plugin
class MyModelTranslator(Plugin[MyModelConfig]):
    def on_prepare(self):
        # Load data and setup resources
        return Ok(None)

    def on_build(self):
        # Create system from input data
        system = System(name=f"{self.config.scenario}_{self.config.model_year}")
        return Ok(system)

    def on_translate(self):
        # Define translation rules
        rules = [
            Rule(
                name="translate_generators",
                source_type="SourceGenerator",
                target_type="Generator",
                version=1,
                field_map={
                    "name": "name",
                    "capacity": "p_max_mw",
                    "location": "zone",
                }
            ),
        ]
        # Apply rules to create target system
        return Ok(self.system)

# Execute the translation
config = MyModelConfig(input_folder="/path/to/data", model_year=2030)
context = PluginContext(config=config)
plugin = MyModelTranslator.from_context(context)
result = plugin.run()
print(f"Translated system: {result.system.name}")

Plugin Registration and Discovery

Register plugins via pyproject.toml entry points for automatic discovery:

[project.entry-points.r2x_plugin]
my_model_translator = "my_package.plugins:MyModelTranslator"
my_model_builder = "my_package.plugins:MyModelBuilder"

The plugin system automatically discovers and introspects plugins to extract their capabilities:

from r2x_core import Plugin

# Get plugin metadata programmatically
config_type = MyModelTranslator.get_config_type()
print(f"Config type: {config_type.__name__}")

# Discover which hooks are implemented
hooks = MyModelTranslator.get_implemented_hooks()
print(f"Implemented hooks: {hooks}")
# Output: ['on_prepare', 'on_build', 'on_translate']

# Introspect config fields
import inspect
fields = config_type.model_fields
for field_name, field_info in fields.items():
    print(f"  {field_name}: {field_info.annotation}")

Plugins are discovered, instantiated, and executed through a shared registry that handles dependency injection and lifecycle management.

Documentation

Comprehensive documentation is available at nrel.github.io/r2x-core:

• Getting Started Tutorial - Step-by-step guide to building your first translator
• Installation Guide - Detailed installation instructions and options
• How-To Guides - Task-oriented guides for common workflows:
  • Read Data Files
  • Configure Data Files
  • Define Rule Mappings
  • Apply Rules
  • Register Plugins
  • Manage DataStores
  • Manage Systems
  • Convert Units
• Explanations - Deep dives into key concepts:
  • Plugin System Architecture
  • Rule System Architecture
  • Unit System Design
  • HDF5 Reader System
  • Data Management
• Tutorials - In-depth walkthroughs:
  • Plugin System
  • Plugin Context
  • Plugin Discovery
  • Working with Units
• API Reference - Complete API documentation

Roadmap

Curious about what we're working on? Check out the roadmap:

• Active issues - Issues that we are actively working on
• Prioritized backlog - Issues we'll be working on next
• Nice-to-have - Features or fixes anyone can start working on (please let us know before you do)
• Ideas - Future work or ideas for R2X Core

Contributing

We welcome contributions! Please see our Contributing Guide for guidelines on how to contribute to R2X Core.

License

R2X Core is released under the BSD 3-Clause License. See LICENSE.txt for details.