Module `ml4opf.formulations.violation`

Abstract base class for OPFViolation classes.

Each formulation should define a class that inherits from OPFViolation and implements the following methods:

calc_violations: Calculate the violations of all the constraints. Returns a dictionary of tensors.
violations_shapes: Return the shapes of the violations as a dictionary.
objective: Compute the objective value for a batch of samples.

Classes

class OPFViolation (data: dict[str, torch.Tensor])

The OPFViolation class is where all the problem expressions (objective, constraints, etc.) are defined. The classes provide a convenient interface for when the only varying quantity in the formulation per sample is the load demand pd. If other quantities vary, the user should use the functional interface at ml4opf.functional.

When clamp is true, the values of g(x) are clamped to be non-negative and the values of h(x) are absolute-valued. Otherwise the raw values are returned.

OPFViolation is a torch.nn.Module; all tensors used in computation are registered as non-persistent buffers. To move the module to a different device, use .to(device) as you would with any other nn.Module. Make sure that when you pass data to OPFViolation, it is on the same device as OPFViolation.

Initialize internal Module state, shared by both nn.Module and ScriptModule.

Ancestors

torch.nn.modules.module.Module
abc.ABC

Subclasses

Class variables

var SUPPORTED_REDUCTIONS

Static methods

def clamped_bound_residual(x: torch.Tensor, xmin: torch.Tensor, xmax: torch.Tensor, clamp: bool): Browse git
def reduce_violation(violation: torch.Tensor, reduction: str, dim: int = 1): Browse git

Apply mean/sum/max to a single tensor.
def reduce_violations(violations: dict[str, torch.Tensor], reduction: str, dim: int = 1): Browse git

Apply mean/sum/max to every value in a dictionary.

Instance variables

prop adjacency_matrix : torch.Tensor

Sparse adjacency matrix.

Each row corresponds to a bus and each column corresponds to a bus. The value is 1 if there is a branch between the buses, and 0 otherwise.

Args

fbus : Tensor: From bus indices. (nbranch,)
tbus : Tensor: To bus indices. (nbranch,)
n_bus : int: Number of buses.
n_branch : int: Number of branches.

Returns

Tensor: Sparse adjacency matrix. (nbus, nbus)

prop adjacency_matrix_dense : torch.Tensor

prop branch_from_incidence : torch.Tensor

Sparse branch from incidence matrix.

Each row corresponds to a bus and each column corresponds to a branch. The value is 1 if the branch is from the bus, and 0 otherwise.

Returns

Tensor: Sparse branch from incidence matrix. (nbus, nbranch)

prop branch_from_incidence_dense : torch.Tensor

prop branch_incidence : torch.Tensor

Sparse branch incidence matrix.

Each row corresponds to a bus and each column corresponds to a branch. The value is 1 if the branch is from the bus, -1 if the branch is to the bus, and 0 otherwise.

Returns

Tensor: Sparse branch incidence matrix. (nbus, nbranch)

prop branch_incidence_dense : torch.Tensor

prop branch_to_incidence : torch.Tensor

Sparse branch to incidence matrix.

Each row corresponds to a bus and each column corresponds to a branch. The value is 1 if the branch is to the bus, and 0 otherwise.

Returns

Tensor: Sparse branch to incidence matrix. (nbus, nbranch)

prop branch_to_incidence_dense : torch.Tensor

prop generator_incidence : torch.Tensor

Sparse generator incidence matrix.

Each row corresponds to a bus and each column corresponds to a generator. The value is 1 if the generator is at the bus, and 0 otherwise.

Returns

Tensor: Sparse generator incidence matrix. (nbus, ngen)

prop generator_incidence_dense : torch.Tensor

prop load_incidence : torch.Tensor

Sparse load incidence matrix.

Each row corresponds to a bus and each column corresponds to a load. The value is 1 if the load is at the bus, and 0 otherwise.

Returns

Tensor: Sparse load incidence matrix. (nbus, nload)

prop load_incidence_dense : torch.Tensor

Methods

def branch_from_to_bus(self, pf_or_qf: torch.Tensor, method: str = 'pad') ‑> torch.Tensor

Embed batched branch-wise values to batched bus-wise.

The default method "pad" sums over any flows on branches from the same bus. The matrix methods "dense_matrix" and "matrix" use the incidence matrix.

Args

pf_or_qf : Tensor: Branch-wise values. (batch, nbranch)
method : str: Method to use. Supported: ['pad', 'dense_matrix', 'matrix']

Returns

Tensor: Bus-wise values. (batch, nbus)

def branch_to_to_bus(self, pt_or_qt: torch.Tensor, method: str = 'pad') ‑> torch.Tensor

Embed batched branch-wise values to batched bus-wise.

The default method "pad" sums over any flows on branches to the same bus. The matrix methods "dense_matrix" and "matrix" use the incidence matrix.

Args

pt_or_qt : Tensor: Branch-wise values. (batch, nbranch)
method : str: Method to use. Supported: ['pad', 'dense_matrix', 'matrix']

Returns

Tensor: Bus-wise values. (batch, nbus)

def calc_violations(self, *args, reduction: str = 'mean', clamp: bool = True) ‑> dict[str, torch.Tensor]

Calculate the violations of the constraints. Returns a dictionary of tensors.

def forward(self, *args, **kwargs) ‑> Callable[..., Any]

Pass-through for OPFViolation.calc_violations()

def gen_to_bus(self, pg_or_qg: torch.Tensor, method: str = 'pad') ‑> torch.Tensor

Embed generator-wise values to bus-wise.

The default method "pad" sums over any generators at the same bus. The matrix methods "dense_matrix" and "matrix" use the incidence matrix.

Args

pg_or_qg : Tensor: Generator-wise values. (batch, ngen)
method : str: Method to use. Supported: ['pad', 'dense_matrix', 'matrix']

Returns

Tensor: Bus-wise values. (batch, nbus)

def load_to_bus(self, pd_or_qd: torch.Tensor, method: str = 'pad') ‑> torch.Tensor

Embed load-wise values to bus-wise.

The default method "pad" sums over any loads at the same bus. The matrix methods "dense_matrix" and "matrix" use the incidence matrix.

Args

pd_or_qd : Tensor: Load-wise values. (batch, ngen)
method : str: Method to use. Supported: ['pad', 'dense_matrix', 'matrix']

Returns

Tensor: Bus-wise values. (batch, nbus)

def objective(self, *args) ‑> torch.Tensor

Compute the objective value for a batch of samples.

def violation_shapes(self) ‑> dict[str, int]

Return the shapes of the violations returned by OPFViolation.calc_violations().