Copyright Georgia Tech 2024

<!-- -->

ML4OPF

ML4OPF is a Python package for developing machine learning proxy models for optimal power flow. It is built on top of PyTorch and PyTorch Lightning, and is designed to be modular and extensible. The main components are:

• formulations: The main interface to the OPF formulations ACOPF, DCOPF, and Economic Dispatch.

  • Each OPF formulation has three main component classes: OPFProblem, OPFViolation, and OPFModel. The OPFProblem class loads and parses data from disk, the OPFViolation class calculates constraints residuals, incidence matrices, objective value, etc., and the OPFModel class is an abstract base class for proxy models.

• loss_functions: Various loss functions including LDFLoss and the self-supervised ObjectiveLoss.

• layers: Various feasibility recovery layers including BoundRepair and HyperSimplexRepair.

• models: Various proxy models including BasicNeuralNet, LDFNeuralNet, and E2ELR.

• parsers: Parsers for data generated by AI4OPT/PGLearn.jl.

• viz: Visualization helpers for plots and tables.

Documentation based on docstrings is live here.

Installation

To install ml4opf on macOS (CPU/MPS) and Windows (CPU), run: ```bash pip install git+ssh://git@github.com/AI4OPT/ML4OPF.git

or, to install with optional dependencies (options: "all", "dev", "viz"):

pip install "ml4opf[all] @ git+ssh://git@github.com/AI4OPT/ML4OPF.git" If you don't already have PyTorch on Linux (CPU/CUDA/ROCm) or Windows (CUDA), make sure to provide the correct `--index-url` which you can find [here](https://pytorch.org/get-started/locally/). For example, to install from scratch with CUDA 12.6 and all optional dependencies: bash pip install "ml4opf[all] @ git+ssh://git@github.com/AI4OPT/ML4OPF.git" \ --index-url https://download.pytorch.org/whl/cu126 \ --extra-index-url https://pypi.python.org/simple/ ```

For development, the recommended installation method is using Conda environment files provided at environment.yml and environment_cuda.yml: bash git clone git@github.com:AI4OPT/ML4OPF.git # clone this repo cd ML4OPF # cd into the repo conda env create -f environment.yml # create the environment conda activate ml4opf # activate the environment pip install -e ".[all]" # install ML4OPF

Usage

Training a BasicNeuralNet for ACOPF

```python import torch

load data

from ml4opf import ACProblem

data_path = ...

problem = ACProblem(data_path)

make a basic neural network model

from ml4opf.models.basic_nn import ACBasicNeuralNet # requires pytorch-lightning

config = { "optimizer": "adam", "learningrate": 1e-3, "loss": "mse", "hiddensizes": [500,300,500], "activation": "sigmoid", "boundrepair": "none" # optionally clamp outputs to bounds (choices: "sigmoid", "relu", "clamp") }

model = ACBasicNeuralNet(config, problem)

model.train(trainerkwargs={'maxepochs': 100, 'accelerator': 'auto'}) # pass args to the PyTorch Lightning Trainer

evals = model.evaluate_model()

from ml4opf.viz import makestatsdf print(makestatsdf(evals))

model.savecheckpoint("./basic300bus") # creates a folder called "basic_300bus" with a file "trainer.ckpt" in it. ```

Manually Loading Data

```python import torch

from ml4opf import ACProblem

data_path = ...

parse HDF5/JSON

problem = ACProblem(data_path)

get train/test set:

traindata = problem.traindata testdata = problem.testdata

traindata['input/pd'].shape # torch.Size([52863, 201]) testdata['input/pd'].shape # torch.Size([5000, 201])

if needed, convert the HDF5 data to a tree dictionary instead of a flat dictionary:

from ml4opf.parsers import PGLearnParser h5tree = PGLearnParser.maketree(traindata) # this tree structure should # exactly mimic the # structure of the HDF5 file. h5tree['input']['pd'].shape # torch.Size([52863, 201]) ```

Acknowledgements

This material is based upon work supported by the National Science Foundation AI Institute for Advances in Optimization (AI4OPT) under Grant No. 2112533 and the National Science Foundation Graduate Research Fellowship under Grant No. DGE-2039655. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation.