BMOPFTools.jl

KO | EN

gitlite — search

#hacktoberfest #react #ai #android #machine-learning #deep-learning #macos #windows #awesome #cli #awesome-list #security #openai #mcp

(★ 10)

A Julia library used to develop and analyse benchmark datasets for distribution optimal power flow.

BMOPFTools.jl Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

> [!WARNING]  
> This project is currently ongoing rapid development and may have breaking changes made directly to main. Use at your own risk until further notice. OpenDSS ingestion now goes through [PowerIO.jl](https://github.com/eigenergy/PowerIO.jl) (the earlier PowerModelsDistribution-based `from_pmd` parser has been removed).

[![Documentation](https://github.com/frederikgeth/BMOPFTools.jl/actions/workflows/documentation.yml/badge.svg)](https://github.com/frederikgeth/BMOPFTools.jl/actions/workflows/documentation.yml) [![CI](https://github.com/frederikgeth/BMOPFTools.jl/actions/workflows/ci.yml/badge.svg)](https://github.com/frederikgeth/BMOPFTools.jl/actions/workflows/ci.yml) [![codecov](https://codecov.io/gh/frederikgeth/BMOPFTools.jl/graph/badge.svg)](https://codecov.io/gh/frederikgeth/BMOPFTools.jl)

# BMOPFTools.jl

A Julia library for **parsing, validating, analysing and reporting** on
BMOPF-format distribution network datasets — the JSON data model developed by
the IEEE Task Force on *Benchmarking Multiconductor OPF for Distribution
Systems* for up-to-four-wire optimal power flow, currently hosted at
https://github.com/frederikgeth/bmopf-report.

The network data model is a plain `Dict{String,Any}` that mirrors the BMOPF
JSON schema exactly: no wrapper types, so data flows naturally between JSON,
the `to_pmd` PowerModelsDistribution export, and your own code.

## IEEE PES Task Force

**Benchmarking Multiconductor OPF for Distribution Systems**

| Role | Name | Affiliation |
|---|---|---|
| Chair | Matthew Deakin | Newcastle University, UK |
| Co-chair | Frederik Geth | University of Queensland, Australia |
| Secretary | Amrit Pandey | University of Vermont, USA |

## Motivation

Reliable benchmarks are essential for validating and comparing power system
algorithms, yet unbalanced distribution networks have historically
lacked a common, open benchmark format.  This repository is part of the IEEE
PES Task Force effort to fill that gap — motivated by the success of
community benchmark libraries such as [PGLib](https://power-grid-lib.github.io/)
in the broader power systems and optimisation communities.

BMOPFTools provides the tooling needed to convert real utility-derived OpenDSS
networks into clean, spec-conformant BMOPF benchmark cases, validate them
against the data model, and confirm that they are well-posed OPF instances
before publication.  The resulting benchmark cases — together with the larger
source networks and the generation pipeline that produces them — live in the
companion
[BMOPFDraftData](https://github.com/frederikgeth/BMOPFDraftData) repository, so
they can be versioned and licensed independently of this tooling. This
repository keeps only the small fixtures the test suite needs (under
`test/data/`).

The embedded IVR-EN engine is also extensible from downstream Julia packages:
it supports staged JuMP construction, typed device-formulation replacement,
semantic parameter/coefficient registries, and explicit integration with
DiffOpt-compatible models. BMOPFTools supplies the physics substrate and
diagnostics; downstream research packages retain ownership of bilevel semantics
and sensitivity algorithms.

## Licensing

**Code** — BSD-3-Clause License.

**Benchmark cases and task force outputs** — the licence is inherited from
each dataset's upstream source and therefore differs **per dataset**. The
generated benchmark cases (in [BMOPFDraftData](https://github.com/frederikgeth/BMOPFDraftData))
are derivatives and carry the same licence as their source. Every data
directory contains a `License.md`/`license.md` with the exact terms and
citation; the licence is also stamped into each generated case's `meta.license`
field.

The only network data bundled in *this* repository is the small set of fixtures
the test suite runs against, under `test/data/`:

| Fixture (`test/data/…`) | Licence | Commercial use | Source |
|---|---|---|---|
| `ENWL` | CC BY 4.0 | yes | CSIRO four-wire LV dataset, [10.25919/jaae-vc35](https://doi.org/10.25919/jaae-vc35) |
| `LV`, `MV`, `Master.dss` (combined), `MVLVmeshed` | **CC BY-NC-SA 4.0** | **no** (non-commercial, share-alike) | CSIRO Australian MV/LV feeder set, [10.25919/ghnz-bk28](https://doi.org/10.25919/ghnz-bk28) |
| `SWER`, `pf_comparison`, small fixtures | CC BY 4.0 | yes | authored for BMOPFTools |

The full benchmark library and the larger source networks that feed the
output-generation pipeline are **not** bundled here — they live in the
companion
[BMOPFDraftData](https://github.com/frederikgeth/BMOPFDraftData) repository
alongside the pipeline that consumes them, including `ENWLvariants` (CC BY 4.0,
same CSIRO DOI as `ENWL`) and `dsuite_networks_scaled_v1.1` (CC BY 4.0, D-Suite
LV networks, Newcastle University,
[10.25405/data.ncl.27175317](https://doi.org/10.25405/data.ncl.27175317)).

Task force outputs (`docs/taskforce_feedback.md`) are CC BY 4.0. Note that
CC BY-NC-SA derivatives must be redistributed under the same
non-commercial/share-alike terms — plan accordingly if you are building a
commercial offering on these cases.

## What it does

```
OpenDSS .dss ──(from_dss / PowerIO.jl)──► BMOPF Dict{String,Any} ◄── parse_bmopf ◄── BMOPF JSON
                                                 │               └──── write_bmopf
                                                 │ analyze
                                                 ▼
                                          SummaryReport ──► render
                                                 │ fix_case
                                                 ▼
                                         net′ (repaired)
                                                 │ add_generators / add_ibrs  (optional DER)
                                                 ▼
                                          net′ + DERs
                                                 │ augment_case
                                                 ▼
                                    net″ (benchmark-ready) ──► write_bmopf
                                                 │ solve_opf / solve_pf / to_pmd
                                                 ▼
                                        result Dict{String,Any}
                                                 │ profile_solution
                                                 ▼
                                       SolutionReport ──► render_solution
```

- **Conversion**: `from_dss` (via [PowerIO.jl](https://github.com/eigenergy/PowerIO.jl))
  translates OpenDSS networks into BMOPF dicts, handling earth-terminal
  conventions, grounding reactors, and transformer impedance bases. `to_pmd`
  exports a BMOPF dict to a PowerModelsDistribution ENGINEERING model.
- **Validation**: required fields, spec conformance (configuration/arity
  rules, terminal types), referential and dimensional integrity, domain
  plausibility, redundancy.
- **Analysis**: inventory, voltage levels, connectivity/topology, diversity,
  operational loading, infeasibility preflight, data **provenance**
  (sequence-derived impedances, Kron-reduction likelihood, earthing-system
  tagging, OpenDSS default fingerprints, regulator patterns) and
  **benchmark readiness**.
- **Reporting**: every `analyze` run produces a `SummaryReport` with a
  complete catalogue of stable, documented finding codes, rendered to
  terminal or Markdown.
- **Case preparation**: `fix_case` (structural repairs — remove inert
  elements, convert near-zero impedance lines to switches, drop disconnected
  islands) and `augment_case` (standards-grounded gap-filling — inject
  voltage bounds, infer thermal limits, add slack generation) prepare a raw
  import for use as an OPF benchmark.  Both return a `TransformationManifest`
  audit trail.
- **Solution profiling**: given a BMOPF network and an OPF result dict,
  `profile_solution` flags bound violations, near-active constraints,
  constraint residuals, and solution-quality issues without access to solver
  internals.

## Installation

### Prerequisites

BMOPFTools requires **Julia ≥ 1.10**. If you don't have Julia yet, install it
with [juliaup](https://github.com/JuliaLang/juliaup), the official version
manager — on Windows via the
[Microsoft Store](https://apps.microsoft.com/detail/9NJNWW8PVKMN) (or
`winget install julia -s msstore`), on macOS/Linux via
`curl -fsSL https://install.julialang.org | sh` — or grab an installer from
[julialang.org/downloads](https://julialang.org/downloads/).

A note on the code blocks below: `julia` blocks are **Julia code** — run
`julia` in your terminal first, then type them at the `julia>` prompt — while
`sh` blocks go in your system terminal (Command Prompt / PowerShell / bash).
Completely new to Julia? The
[Installation & first steps](https://frederikgeth.github.io/BMOPFTools.jl/docs/installation/)
docs page walks through all of this, and the official
[Getting Started](https://docs.julialang.org/en/v1/manual/getting-started/)
guide and [julialang.org/learning](https://julialang.org/learning/) cover the
language basics.

### Installing the package

BMOPFTools is not yet in the General registry (Julia's default package
catalogue), so install it from this Git URL:

```julia
using Pkg
Pkg.add(url = "https://github.com/frederikgeth/BMOPFTools.jl")
```

Parsing, validation, analysis, reporting, OpenDSS ingestion (`from_dss`, via
the [PowerIO.jl](https://github.com/eigenergy/PowerIO.jl) dependency), and the
`to_pmd` exporter work out of the box. One capability pulls in extra tooling,
activated only when you load it:

- **OPF / power flow** (`solve_opf`, `solve_pf`, `solve_feasibility_opf`) is a
  package extension that activates once **JuMP** and a solver such as **Ipopt**
  are present — `Pkg.add(["JuMP", "Ipopt"])`.

> [!TIP]
> Because breaking changes land directly on `main` (see the warning above),
> pin a revision when you need reproducibility:
> `Pkg.add(url = "https://github.com/frederikgeth/BMOPFTools.jl", rev = "<commit-sha>")`.

## Quickstart

Analysing an existing BMOPF JSON case:

```julia
using BMOPFTools

net    = parse_bmopf("case.json")
report = analyze(net)
render(report, stdout)              # terminal report
render(report, "case_report.md")    # Markdown report

errors(report)                      # findings with ERROR severity
report.results[:provenance]["convention"]
```

Profiling an OPF result dict (requires `solve_opf` or any compatible solver):

```julia
using BMOPFTools, JuMP, Ipopt

net    = parse_bmopf("case.json")
result = solve_opf(net; optimizer=Ipopt.Optimizer)

report = profile_solution(net, result)
render_solution(report, "solution.md")

errors(report)    # bound violations and infeasibility findings
warnings(report)  # near-active bounds and residual warnings
```

Converting from OpenDSS (via PowerIO.jl):

```julia
using BMOPFTools

net    = from_dss("Master.dss")     # parsed in-process by PowerIO.jl
net′,  fix_mf  = fix_case(net)
net″,  aug_mf  = augment_case(net′)
write_bmopf("case.json", net″)
```

## Development

The dependencies are declared in `Project.toml`: the core runtime pulls in
`Graphs`, `JSON3`, `JSONSchema`, `PowerIO`, `TOML`, and the standard libraries;
`JuMP`/`Ipopt` are weak dependencies behind the OPF extension (see
[Installation](#installation)). The test suite skips the power-flow comparison
tests when `OpenDSSDirect` is absent.

```sh
# full test suite (from the package root)
julia --project=. -e "using Pkg; Pkg.test()"
```

The benchmark-generation pipeline (`scripts/generate_output.jl`,
`scripts/run_benchmark.jl` and friends) runs against the full source networks
and writes the benchmark library, both of which live in
[BMOPFDraftData](https://github.com/frederikgeth/BMOPFDraftData) — run it from
there. One-off data-migration scripts live in `scripts/oneoff/`.

## Documentation

Build the documentation locally:

```sh
julia --project=docs -e 'using Pkg; Pkg.develop(path="."); Pkg.instantiate()'
julia --project=docs docs/make.jl
# open docs/build/index.html
```

Pages: data-model conventions, the conversion guide (every deliberate
`from_dss`/`to_pmd` decision), the analysis/report guide, the **complete
finding-code reference** (128 codes), methodology notes with literature
references, the case augmentation guide (`fix_case` + `augment_case`), the
OPF guide, and the OPF result dictionary reference.

`docs/taskforce_feedback.md` collects implementation feedback on the Task
Force draft specification.

## Examples

- `examples/lv1_14bus_walkthrough.jl` — step-by-step tour of every analysis
  on a real 14-bus LV feeder.

## Case file overview

Converted benchmark cases and their original OpenDSS source networks live in the
companion [BMOPFDraftData](https://github.com/frederikgeth/BMOPFDraftData)
repository. The small OpenDSS fixtures this package's test suite runs against
are in `test/data/`.

## How to contribute

BMOPFTools is a community-driven initiative and contributions of all kinds are
welcome — bug reports, new network cases, tooling, and documentation. See
[`CONTRIBUTING.md`](CONTRIBUTING.md) for the workflow, and the **Reference →
Developer guide** section of the documentation for the full style guide,
versioning policy, and scope notes.

By contributing data you agree to release it under CC BY 4.0; by contributing
code you agree to the BSD-3-Clause licence.

## Citation

This repository is not static; please include the version number when citing
it in scholarly work.  Case files carry original-source attribution in their
headers — cite those sources when using specific networks.

## Special thanks to 
(in alphabetic order)
Archie Chapman
Mohamed Numair
Samuel Talkington
Sleiman Mhanna
Tomislav Antić

BMOPFTools.jl

BMOPFTools.jl Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

BMOPFTools.jl

BMOPFTools.jl Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README