OEDISI-Components

Key Workflows

Repository-wide automation:

• lint-format.yml - Code quality enforcement using pre-commit hooks (ruff, trailing whitespace, YAML validation). Runs on every push.
• publish-on-version-matrix.yml - Builds and publishes Docker images when version_matrix.csv changes. Triggered on main branch push or manual workflow dispatch.
• update-components-submodules.yml - Automatically updates all component submodules under Components/. Scheduled weekly (Monday 8 AM UTC) or triggered manually.
• update-version-matrix.yml - Updates version_matrix.csv from working tree and submodule release tags. Creates a pull request with changes. Triggered on release published events or manual workflow dispatch.

Integration Test Status

Workflow	Components	Status	Uses Multi-contianer Setup
RunExample	broker, lindistflow_federate, LocalFeeder, measuring_federate, recorder, wls_federate		False
TestDOPFOMOO	broker, LocalFeeder, measuring_federate, recorder, omoo_federate		False

Component Status

Component	Version	Tests	Config files	Docker	Maintainer
Broker					Joseph.McKinsey@nlr.gov
LinDistFlow					Joseph.McKinsey@nlr.gov
LocalFeeder					Joseph.McKinsey@nlr.gov
Measuring					Joseph.McKinsey@nlr.gov
OMOO					Joseph.McKinsey@nlr.gov
Recorder					Joseph.McKinsey@nlr.gov
WLS					Joseph.McKinsey@nlr.gov
PNNL-DOPF-ADMM					tylor.slay@pnnl.gov
PNNL-Hub-Voltage		-			tylor.slay@pnnl.gov
PNNL-Hub-Control		-			tylor.slay@pnnl.gov
PNNL-Hub-Power		-			tylor.slay@pnnl.gov
PNNL-DSSE-EKF					tylor.slay@pnnl.gov
PNNL-Imputation-FFNN		-	-	-	tylor.slay@pnnl.gov
PNNL-Profiler-SDV		-	-	-	tylor.slay@pnnl.gov
NLP-DOPF					-
NLP-DSSE					-
ORNL-EV-PSO					liub@ornl.gov
ORNL-DOPF-PSO					liub@ornl.gov
ORNL-DSSE-GNWLS					liub@ornl.gov
Player					tylor.slay@pnnl.gov
PNNL-SWOD					tylor.slay@pnnl.gov

Repository Structure

This repository is organized as a Python repository containing components for power system co-simulation. See the Component Status table above for test and Docker build status for each component.

Components:

• broker - Central orchestration service for HELICS federates
• lindistflow_federate - Optimal power flow using linear distflow
• localfeeder - OpenDSS-based distribution feeder simulator
• measuring_federate - Sensor simulation with noise injection
• omoo_federate - Online model-based optimal operation
• recorder - Data recording for co-simulation outputs
• wls_federate - Weighted least squares state estimation
• pnnl-dopf-admm - Distributed OPF using ADMM
• pnnl-hub-voltage - Voltage aggregation and distribution hub
• pnnl-hub-control - Control aggregation and distribution hub
• pnnl-hub-power - Power aggregation and distribution hub
• pnnl-dsse-ekf - Extended Kalman Filter state estimation
• pnnl-imputation-ffnn - Feed-forward neural network for data imputation
• pnnl-profiler-sdv - Synthetic data generation via profiling
• nlpdopf - NLP-based distributed optimal power flow
• nlpdsse - NLP-based distribution system state estimation
• ornl-ev-pso - PSO-based EV charging optimization
• ornl-dopf-pso - PSO-based distributed optimal power flow
• ornl-dsse-gnwls - Gauss-Newton WLS state estimation
• player - Dataset playback federate for replaying recorded HELICS co-simulation data
• pnnl-emt-swod - Transient sliding wave oscillation detection (SWOD) federate

Each component includes:

• pyproject.toml for modern Python packaging (PEP 621)
• Comprehensive test suite with pytest
• Individual README documentation
• Standardized code quality tools (mypy, pytest, black, isort)
• Dockerfile for containerization
• GitHub Actions workflow for automated testing

Continuous Integration

Current CI coverage includes:

• Component unit tests on Python 3.11 and 3.13
• Integration/API and DOPF workflows using current supported environments
• Lint and formatting checks via pre-commit
• Component metadata and Dockerfile verification workflows

Additionally:

• Dockerfile Verification: Ensures all components have valid Dockerfiles
• Integration Tests: End-to-end system testing

Adding A Submodule Under Components

Some components can be managed in separate repositories and included here as git submodules under Components/.

Add The Submodule

git submodule add https://github.com/<org>/<repo> Components/<component-name>
git submodule update --init --recursive
git add .gitmodules Components/<component-name>
git commit -m "Add <component-name> as submodule"

Notes:

• Commit both .gitmodules and the gitlink entry at Components/<component-name>.
• The submodule should include its own README.md and Dockerfile.
• Include component_definition.json.

Workflows Applied To Submodules

Submodules under Components/ are validated by the same repository workflows as in-repo components:

• verify-components.yml (via reusable_verify_components.yml)
  • Checks README.md for all Components/* directories.
  • Checks component_definition.json for all Components/* directories except broker.
• verify-dockerfiles.yml (via reusable_verify_dockerfiles.yml)
  • Checks Dockerfile for all Components/* directories.

These reusable workflows use actions/checkout with submodules: recursive, so submodule contents are available during file existence checks.

Workflow Scope Clarification

• Verification workflows in this repository validate submodule metadata files and Dockerfile presence.
• Unit or integration tests for submodule code are not automatically run here unless explicitly added to this repository's test workflows.
• If the submodule has its own CI (recommended), link its badges in the Component Status table.

Quick Start - Development Installation

Install all components in editable mode from the repository root:

# Install all components for development
pip install -e Components/broker -e Components/lindistflow_federate -e Components/LocalFeeder \
            -e Components/measuring_federate -e Components/omoo_federate \
            -e Components/recorder -e Components/wls_federate

# Or install with dev dependencies
pip install -e "Components/broker[dev]" -e "Components/lindistflow_federate[dev]" \
            -e "Components/LocalFeeder[dev]" -e "Components/measuring_federate[dev]" \
            -e "Components/omoo_federate[dev]" -e "Components/recorder[dev]" \
            -e "Components/wls_federate[dev]"

Running Tests

Run all tests from the repository root:

pytest Components/

Run tests for a specific component:

pytest Components/broker/tests/
pytest Components/wls_federate/tests/

Run with coverage:

pytest --cov=Components --cov-report=html Components/

Code Quality

The repository enforces code quality standards through automated linting and formatting via GitHub Actions and pre-commit hooks.

GitHub Actions Lint Workflow (.github/workflows/lint-format.yml):

• Runs on every push and can be triggered manually
• Uses Python 3.13 to ensure compatibility with latest standards
• Executes all pre-commit hooks to validate code quality

Pre-commit Hooks (.pre-commit-config.yaml):

• Standard hooks: Trailing whitespace removal, EOF fixing, YAML validation, large file detection
• Ruff: Modern Python linter and formatter (replaces flake8, black, isort)
  • ruff check --fix: Automatic fixing of linting issues
  • ruff format: Code formatting for consistency

To set up pre-commit hooks locally:

pip install pre-commit
pre-commit install

# Run manually on all files
pre-commit run --all-files

Install and Running Locally

1. Initialize Submodules

Before installing or running any components, ensure all Git submodules are initialized and updated:

git submodule update --init --recursive

2. Installation

Install the component dependencies in editable mode (recommended for development):

uv sync --all-extras
uv pip install -e Components/broker \
            -e Components/lindistflow_federate \
            -e Components/LocalFeeder \
            -e Components/measuring_federate \
            -e Components/recorder \
            -e Components/wls_federate

To install development tools as well:

uv pip install pytest mypy ruff pre-commit

3. Running Scenarios

You can test and run co-simulation scenarios locally using oedisi build and run commands.

First, build the co-simulation configuration from a scenario JSON file:

uv run oedisi build --system scenarios/system.json

Then, run the co-simulation:

uv run oedisi run

3. Cleanup

Sometimes a federate will break and leave a broker running that needs to be stopped to start a new co-simulation.

pkill -9 helics_broker
pkill -9 python

The output data will be stored in the outputs/ directory.