Metadata-Version: 2.3
Name: r2x-reeds
Version: 0.6.0
Summary: ReEDS model plugin
Keywords: ReEDS
Author: pesap, kodiobika, mcllerena
Author-email: pesap <pesap@users.noreply.github.com>, kodiobika <kodiobika@users.noreply.github.com>, mcllerena <mcllerena@users.noreply.github.com>
License: BSD 3-Clause License
         
         Copyright (c) 2025, Alliance for Sustainable Energy LLC, All rights reserved.
         
         Redistribution and use in source and binary forms, with or without
         modification, are permitted provided that the following conditions are met:
         
         1. Redistributions of source code must retain the above copyright notice, this
            list of conditions and the following disclaimer.
         
         2. Redistributions in binary form must reproduce the above copyright notice,
            this list of conditions and the following disclaimer in the documentation
            and/or other materials provided with the distribution.
         
         3. Neither the name of the copyright holder nor the names of its
            contributors may be used to endorse or promote products derived from
            this software without specific prior written permission.
         
         THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
         AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
         IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
         DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
         FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
         DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
         SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
         CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
         OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
         OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Topic :: File Formats :: JSON
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Typing :: Typed
Requires-Dist: r2x-core>=0.4.1,<1.0.0
Maintainer: pesap, kodiobika, mcllerena
Maintainer-email: pesap <pesap@users.noreply.github.com>, kodiobika <kodiobika@users.noreply.github.com>, mcllerena <mcllerena@users.noreply.github.com>
Requires-Python: >=3.11, <3.14
Description-Content-Type: text/markdown

<div align="center">

# r2x-reeds

**ReEDS parser and transforms plugin for the `r2x-core` plugin framework.**

[![CI](https://img.shields.io/github/actions/workflow/status/NREL/r2x-reeds/ci.yaml?branch=main&label=CI)](https://github.com/NREL/r2x-reeds/actions/workflows/ci.yaml)
[![Actions Quality](https://img.shields.io/github/actions/workflow/status/NREL/r2x-reeds/workflow-quality.yaml?branch=main&label=actions-quality)](https://github.com/NREL/r2x-reeds/actions/workflows/workflow-quality.yaml)
[![Python](https://img.shields.io/badge/python-3.11%20to%203.13-blue)](https://pypi.org/project/r2x-reeds/)
[![PyPI](https://img.shields.io/pypi/v/r2x-reeds)](https://pypi.org/project/r2x-reeds/)
[![License](https://img.shields.io/badge/license-BSD--3--Clause-green)](./LICENSE.txt)
[![codecov](https://codecov.io/gh/NREL/r2x-reeds/branch/main/graph/badge.svg)](https://codecov.io/gh/NREL/r2x-reeds)
[![Documentation](https://github.com/NREL/r2x-reeds/actions/workflows/docs.yaml/badge.svg?branch=main)](https://nrel.github.io/r2x-reeds/)

</div>

> [!WARNING]
> This project is currently optimized for internal R2X workflows. You are welcome
> to use it, but APIs and behavior may continue to evolve as `r2x-core` evolves.

`r2x-reeds` integrates [NREL ReEDS](https://github.com/NREL/ReEDS-2.0) model data
with `r2x-core` and `infrasys`. It provides a parser plugin for building
`infrasys.System` objects from ReEDS data, plus a set of reusable post-parse
transforms for common system-modification workflows.

<p align="center">
  <a href="#quickstart">Quickstart</a> ·
  <a href="#installation">Installation</a> ·
  <a href="#what-it-provides">What It Provides</a> ·
  <a href="#usage-with-r2x-core">Usage with r2x-core</a> ·
  <a href="#development">Development</a> ·
  <a href="#license">License</a>
</p>

## Quickstart

Install:

```bash
pip install r2x-reeds
```

Parse a ReEDS run directory into an `infrasys.System`:

```python
from pathlib import Path

from r2x_core import DataStore, PluginContext
from r2x_reeds import ReEDSConfig, ReEDSParser

run_path = Path("path/to/reeds_run")

config = ReEDSConfig(
    solve_year=2030,
    weather_year=2012,
    case_name="test_Pacific",
)
ctx = PluginContext(
    config=config,
    store=DataStore.from_plugin_config(config, path=run_path),
)

system = ReEDSParser.from_context(ctx).run().system
print(system.name)
```

## Installation

### From PyPI

Python requirement: `>=3.11, <3.14`.

```bash
pip install r2x-reeds
```

Using `uv`:

```bash
uv add r2x-reeds
```

### From Source

```bash
git clone https://github.com/NREL/r2x-reeds.git
cd r2x-reeds
uv sync --all-groups
```

## What It Provides

- `ReEDSParser`: reads ReEDS outputs and inputs (CSV/HDF5-backed mappings) into
  `infrasys.System` components and time series.
- `ReEDSUpgrader` and `run_reeds_upgrades(...)`: input version-detection and
  upgrade pipeline run during parser lifecycle.
- Plugin entry point for `r2x-core` under the `r2x_plugin` group:
  - `reeds-parser = r2x_reeds:ReEDSParser`
- Transform entry points under `r2x.transforms`:
  - `add-pcm-defaults`
  - `add-emission-cap`
  - `add-electrolyzer-load`
  - `add-purchaser-load`
  - `add-ccs-credit`
  - `break-gens`
  - `add-imports`
  - `add-optimal-siting`

## Usage with r2x-core

`r2x-reeds` follows the `r2x-core` plugin lifecycle.

- Build parser instances with `PluginContext`.
- Run lifecycle hooks with `.run()`.
- Configure parsing through `ReEDSConfig`.
- Apply optional `r2x.transforms` after parsing for scenario/system modifiers.

## Development

Install dev dependencies:

```bash
uv sync --all-groups
```

Run the same checks used in CI:

```bash
uv run prek run --all-files --hook-stage pre-push
```

Targeted commands:

```bash
uv run pytest -q -m "not slow" --maxfail=1 --disable-warnings
uv run ty check ./src/r2x_reeds/
```

## License

BSD 3-Clause. See `LICENSE.txt`.
