r2x-core 0.7.0

r2x-core

Extensible framework for building power system model translators

R2X Core provides the shared infrastructure for translating between power-system model formats. It gives translator authors a typed plugin lifecycle, a configuration-driven data loading layer, declarative rule mapping, unit-aware models, and versioned upgrade helpers.

Use it when you are building or extending translators for models such as ReEDS, PLEXOS, SWITCH, Sienna, or other infrasys-backed power-system workflows.

Install · Quickstart · Core concepts · Documentation · Development · Roadmap · Contributing · License

Install

pip install r2x-core

Or with uv:

uv add r2x-core

R2X Core supports Python 3.11, 3.12, and 3.13.

Quickstart

Load model input files

DataStore manages named DataFile definitions and reads them through the configured DataReader pipeline.

from r2x_core import DataFile, DataStore, TabularProcessing

store = DataStore(path="/path/to/data")
store.add_data([
    DataFile(
        name="generators",
        relative_fpath="gen.csv",
        proc_spec=TabularProcessing(
            column_mapping={"capacity_mw": "p_max_mw"},
            filter_by={"status": "active"},
        ),
    ),
    DataFile(name="loads", relative_fpath="load.parquet"),
])

generators = store.read_data("generators")
available = store.list_data()

Use relative_fpath for files under the store root, fpath for explicit paths, and ReaderConfig(kwargs=...) when the default reader needs format-specific options such as HDF5 dataset keys.

Build a class-based translator plugin

Class plugins implement only the lifecycle hooks they need. Hooks return Ok(...) or Err(...); Plugin.run() returns the final PluginContext and raises PluginError on the first hook failure.

from rust_ok import Ok

from r2x_core import Plugin, PluginConfig, PluginContext, System


class MyModelConfig(PluginConfig):
    input_folder: str
    model_year: int
    scenario: str = "base"


class MyModelTranslator(Plugin[MyModelConfig]):
    def on_build(self):
        system = System(name=f"{self.config.scenario}_{self.config.model_year}")
        return Ok(system)


config = MyModelConfig(input_folder="/path/to/data", model_year=2030)
context = PluginContext(config=config)
plugin = MyModelTranslator.from_context(context)
result = plugin.run()

print(result.system.name)

Create a function transform

For focused System -> System transformations, expose a plain function and register it through the r2x.transforms entry-point group.

from rust_ok import Ok, Result

from r2x_core import PluginConfig, System, expose_plugin


class ScaleConfig(PluginConfig):
    scale: float = 1.0


@expose_plugin
def scale_system(system: System, config: ScaleConfig) -> Result[System, str]:
    return Ok(system)

[project.entry-points."r2x.transforms"]
scale_system = "my_package.transforms:scale_system"

Core concepts

R2X Core builds on infrasys for System and Component primitives.

Documentation

Full documentation is available at natlabrockies.github.io/r2x-core, including tutorials, how-to guides, and the API reference.

Development

This repository uses uv and just for local automation.

just setup
just hooks
just test
just docs

Common tasks:

Roadmap

• Active issues
• Prioritized backlog
• Nice-to-have
• Ideas

Contributing

We welcome contributions. See the contributing guide for local setup, development workflow, and review expectations.

License

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