infrasys

infrasys is a lightweight data store that keeps track of components, their attributes, and time series for energy infrastructure models. The core package is opinionated about validation, unit handling, and data migration so that downstream modeling packages can focus on solving their domain problems instead of managing persistence concerns.

Highlights

• Typed components with pint validation: Base models derive from pydantic and use pint quantities whenever a physical unit is involved.
• Flexible time-series storage: Arrow, HDF5, Chronify, and in-memory backends are available via System configuration to match your compute environment.
• Efficient serialization: Components, supplemental attributes, and nested systems are serialized to JSON with automatic metadata and optional migration hooks.
• Designed for extension: Derive your own System classes, override component addition logic, or ship supplemental attributes alongside the core storage.

Getting started

Install

pip install git+https://github.com/NREL/infrasys.git@main
pip install "infrasys[chronify]"  # optional backend for Chronify/duckdb-based storage

Don’t forget to install pre-commit hooks so your push meets project quality checks:

pre-commit install

Quick example

from infrasys import Component, System
from infrasys.location import Location


class Bus(Component):
    voltage: float
    location: Location | None = None


system = System(name="demo-grid")
bus = Bus(name="bus-1", voltage=1.05, location=Location(x=0.0, y=0.0))
system.add_components(bus)
system.to_json("demo-grid/system.json")

Instantiate a System, add a few components, and dump everything to JSON. Time series data gets written to a sibling directory alongside the JSON file so you can externalize it with System.to_json(...) and System.from_json(...).

Documentation

• How To guides: step-by-step recipes in docs/how_tos.
• Tutorials: opinionated walkthroughs for custom systems under docs/tutorials.
• API Reference: auto-generated reference material lives in docs/reference.
• Explanation articles: deeper dives on the storage backends, migrations, and behavior in docs/explanation.

To build the docs locally, install docs extras and run make html from the docs directory.

Development

• Clone this repository and install the dev dependency group before hacking:

pip install -e ".[dev]"

• Run the test suite and coverage reporting via:

pytest

• Formatting and linting are managed by ruff and configured through its pyproject.toml section. Keep your hooks healthy by installing them via pre-commit install (see Getting started) and running pre-commit run --all-files before pushing.

Support & Contribution

infrasys is being developed under NREL Software Record SWR-24-42. Report issues and feature requests at https://github.com/NREL/infrasys/issues. Review the docs/reference and docs/how_tos material before submitting a change so your diff is aligned with the project conventions.

License

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