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.
- Typed components with pint validation: Base models derive from
pydanticand usepintquantities whenever a physical unit is involved. - Efficient time-series storage: Time series arrays and their metadata are stored by the
Rust-backed
infrastorepackage (HDF5 arrays plus a SQLite database). - 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
Systemclasses, override component addition logic, or ship supplemental attributes alongside the core storage.
pip install git+https://github.com/NREL/infrasys.git@mainDon’t forget to install pre-commit hooks so your push meets project quality checks:
pre-commit installfrom 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(...).
- 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 time-series storage backend, serialization, and
behavior in
docs/explanation.
To build the docs locally, install docs extras and run make html from the docs directory.
- Clone this repository and install the dev dependency group before hacking:
pip install -e ".[dev]"- Run the test suite and coverage reporting via:
pytestinfrasys depends on the Rust infrastore package for its time series backend. During
local development this is resolved from a sibling checkout via [tool.uv.sources]:
[tool.uv.sources]
infrastore = { path = "../infrastore/crates/infrastore-py" }-
Clone the
infrastorerepository next to this one so the relative path resolves:git clone https://github.com/NatLabRockies/infrastore.git ../infrastore
-
Make sure a Rust toolchain is installed (
uvcompiles the extension withmaturin):curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
-
Sync the environment.
uvbuilds the Rust extension and installs everything fromuv.lock:uv sync
-
After editing the Rust source, rebuild and reinstall the compiled extension — a plain
uv syncwill not rebuild an unchanged-version path dependency:uv sync --reinstall-package infrastore
You can confirm the rebuild picked up your changes, e.g.:
uv run python -c "import time_series_store as t; print(t.TimeSeriesStore.add_time_series.__doc__)"
With the environment synced, run the suite through uv:
uv run pytest- Formatting and linting are managed by
ruffand configured through itspyproject.tomlsection. Keep your hooks healthy by installing them viapre-commit install(see Getting started) and runningpre-commit run --all-filesbefore pushing.
infrasys is being developed under NREL Software Record SWR-24-42. Report issues and feature
requests at https://github.com/NatLabRockies/infrasys/issues.
Review the docs/reference and docs/how_tos material before submitting a change so your
diff is aligned with the project conventions.
infrasys is released under the BSD 3-Clause License. See LICENSE.txt for details.