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

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

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

Each component has its own GitHub Actions workflow that:

• Runs tests on Python 3.10 and 3.11
• Performs type checking with mypy
• Generates code coverage reports
• Triggers on changes to component code

Additionally:

• Dockerfile Verification: Ensures all components have valid Dockerfiles
• Integration Tests: End-to-end system testing
• Docker Build Tests: Validates container builds

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

Installation

1. Install component dependencies. You can either:

   Option A: Install all components in editable mode (recommended for developers)

   pip install -e Components/broker \
               -e Components/LocalFeeder \
               -e Components/measuring_federate \
               -e Components/recorder \
               -e Components/wls_federate

2. Verify Installation development tools (optional):

   pip install pytest mypy ruff pre-commit