DCOPF

Sub-modules

ml4opf.formulations.dc.model

Base class for DCOPF proxy models

ml4opf.formulations.dc.problem

DCOPF Problem data class

ml4opf.formulations.dc.violation

Class interface for DCOPF constraints, objective, etc.

Classes

class DCModel

Browse git

OPFModel for DCOPF

Ancestors

• OPFModel
• abc.ABC

Subclasses

• PerfectDCModel
• DCBasicNeuralNet

Class variables

var problem : DCProblem

var violation : DCViolation

Methods

def evaluate_model(self, reduction: str | None = None, inner_reduction: str | None = None) ‑> dict[str, torch.Tensor]

Browse git

Evaluate the model on the test data.

Args

reduction : str, optional

Reduction method for the metrics. Defaults to None. Must be one of "mean", "sum","max", "none". If specified, each value in the returned dictionary will be a scalar. Otherwise, they are arrays of shape (n_test_samples,)

inner_reduction : str, optional

Reduction method for turning metrics calculated per component to per sample. Defaults to None. Must be one of "mean", "sum","max", "none".

Returns

dict[str, Tensor]

Dictionary containing Tensor metrics of the model's performance.

pg_lower: Generator lower bound violation.

pg_upper: Generator upper bound violation.

dva_lower: Angle difference limit lower bound violation.

dva_upper: Angle difference limit upper bound violation.

pf_lower: Flow limit lower bound violation.

pf_upper: Flow limit upper bound violation.

p_balance: Power balance violation.

pg_mae: Mean absolute error of the real power generation.

va_mae: Mean absolute error of the voltage angle. (if not bus-wise and va not in predictions, skipped)

pf_mae: Mean absolute error of the real power flow.

obj_mape: Mean absolute percent error of the objective value.

def predict(self, pd: torch.Tensor) ‑> dict[str, torch.Tensor]

Browse git

Predict the DCOPF primal solution for a given set of loads.

Args

pd : Tensor

Active power demand per load.

Returns

dict[str, Tensor]

Dictionary containing the predicted primal solution.

pg: Active power generation per generator or per bus.

va: Voltage angle per bus.

Inherited members

• OPFModel:
  • load_from_checkpoint
  • save_checkpoint

class DCProblem (data_directory: str, dataset_name: str = 'DCOPF', **parse_kwargs)

Browse git

OPFProblem for DCOPF

Ancestors

• OPFProblem
• abc.ABC

Instance variables

prop default_combos : dict[str, list[str]]

Browse git

Default combos for DCOPF:

• input: pd

• target: pg, va

prop default_order : list[str]

Browse git

Default order for DCOPF. input, target

prop feasibility_check : dict[str, str]

Browse git

Default feasibility check for DCOPF:

• termination_status: "OPTIMAL"

• primal_status: "FEASIBLE_POINT"

• dual_status: "FEASIBLE_POINT"

prop violation : DCViolation

Browse git

OPFViolation object for DCOPF constraint calculations.

Inherited members

• OPFProblem:
  • make_dataset
  • parse
  • slice_batch
  • slice_tensor

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

Browse git

OPFViolation for DCPPowerModel/DCOPF

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

Ancestors

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

Methods

def angle_difference(self, va: torch.Tensor) ‑> torch.Tensor

Browse git

Compute the angle differences per branch given the voltage angles per bus.

The branch indices are assumed to be constant for the batch, matching the reference case.

$$\text{dva} = \boldsymbol{\theta}_{f} - \boldsymbol{\theta}_{t}$$

Args

va : Tensor

Voltage angles per bus ( $\boldsymbol{\theta}$ ). (batch_size, nbus)

Returns

Tensor

Angle differences per branch. (batch_size, nbranch)

def balance_residual(self,
pd: torch.Tensor,
pg: torch.Tensor,
pf: torch.Tensor,
embed_method: str = 'pad',
clamp: bool = True) ‑> torch.Tensor

Browse git

Compute power balance residual.

$$\text{g_balance} = \text{pg_bus} - \text{pd_bus} - \text{gs_bus} - \text{pf_bus} - \text{pt_bus}$$

Args

pd : Tensor

Power demand per bus. (batch_size, nbus)

pg : Tensor

Power generation per generator. (batch_size, ngen)

pf : Tensor

Power flow per branch. (batch_size, nbranch)

embed_method : str, optional

Embedding method to convert component-wise values to bus-wise – one of "pad", "dense_matrix", or "matrix". Defaults to "pad".

clamp : bool, optional

Clamp to extract only violations. Defaults to True.

Returns

Tensor

Power balance residual. (batch_size, nbus)

def calc_violations(self,
pd: torch.Tensor,
pg: torch.Tensor,
va: torch.Tensor,
pf: torch.Tensor | None = None,
reduction: str = 'mean',
clamp: bool = True,
embed_method: str = 'pad') ‑> dict[str, torch.Tensor]

Browse git

Compute all DCOPF violations.

Args

pd : Tensor

Power demand per bus. (batch_size, nbus)

pg : Tensor

Power generation per generator. (batch_size, ngen)

va : Tensor

Voltage angles per bus. (batch_size, nbus)

pf : Tensor, optional

Power flow per branch. Defaults to None.

reduction : str, optional

Reduction method. Defaults to "mean".

clamp : bool, optional

Clamp to extract only violations. Defaults to True.

embed_method : str, optional

Method to convert component-wise values to bus-wise – one of "pad", "dense_matrix", or "matrix". Defaults to "pad".

Returns

dict[str, Tensor]

Dictionary of all violations:

• "pg_lower": Lower bound violation of power generation. (batch_size, ngen)

• "pg_upper": Upper bound violation of power generation. (batch_size, ngen)

• "dva_lower": Lower bound violation of voltage angle difference. (batch_size, nbranch)

• "dva_upper": Upper bound violation of voltage angle difference. (batch_size, nbranch)

• "pf_lower": Lower bound violation of power flow. (batch_size, nbranch)

• "pf_upper": Upper bound violation of power flow. (batch_size, nbranch)

• "p_balance": Power balance violation. (batch_size, nbus)

• "ohm": Ohm's law violation. (batch_size, nbranch)

def dva_bound_residual(self, dva: torch.Tensor, clamp: bool = False) ‑> torch.Tensor

Browse git

Calculate the voltage angle difference bound residual.

$$g_{\text{lower}} = \text{angmin} - \text{dva}$$ $$g_{\text{upper}} = \text{dva} - \text{angmax}$$

Args

dva : Tensor

Voltage angle differences per branch. (batch_size, nbranch)

clamp : bool, optional

Clamp the residual to be non-negative (extract violations). Defaults to False.

Returns

Tensor

Lower bound residual. (batch_size, nbranch)

Tensor

Upper bound residual. (batch_size, nbranch)

def objective(self, pg: torch.Tensor) ‑> torch.Tensor

Browse git

Compute DCOPF objective function.

Cost is assumed to be constant for the batch, matching the reference case.

$$\text{objective} = \sum_i^n \text{cost}_{2,i} + \text{cost}_{1,i} \cdot \text{pg}_i$$

Args

pg : Tensor

Power generation per generator. (batch_size, ngen)

Returns

Tensor

Objective function value. (batch_size, 1)

def ohm_residual(self, pf: torch.Tensor, dva: torch.Tensor, clamp: bool = False) ‑> torch.Tensor

Browse git

Compute Ohm's law violation.

$$\text{g_ohm} = - b \cdot \text{dva} - \text{pf}$$

Args

pf : Tensor

Power flow per branch. (batch_size, nbranch)

dva : Tensor

Voltage angle differences per branch. (batch_size, nbranch)

clamp : bool, optional

Clamp to extract only violations. Defaults to False.

Returns

Tensor

Ohm's law violation. (batch_size, nbranch)

def pf_bound_residual(self, pf: torch.Tensor, clamp: bool = False) ‑> torch.Tensor

Browse git

Calculate the power flow bound residual.

$$g_{\text{lower}} = -\text{rate_a} - \text{pf}$$ $$g_{\text{upper}} = \text{pf} - \text{rate_a}$$

Args

pf : Tensor

Power flow per branch. (batch_size, nbranch)

clamp : bool, optional

Clamp the residual to be non-negative (extract violations). Defaults to False.

Returns

Tensor

Lower bound residual. (batch_size, nbranch)

Tensor

Upper bound residual. (batch_size, nbranch)

def pf_from_va(self, va: torch.Tensor) ‑> torch.Tensor

Browse git

Compute power flow given voltage angles.

$$\mathbf{p}_f = -\text{b} \cdot (\boldsymbol{\theta}_{f} - \boldsymbol{\theta}_{t})$$

Args

va : Tensor

Voltage angles per bus ( $\boldsymbol{\theta}$ ). (batch_size, nbus)

Returns

Tensor

Power flow per branch ( $\mathbf{p}_f$ ). (batch_size, nbranch)

def pg_bound_residual(self, pg: torch.Tensor, clamp: bool = False) ‑> torch.Tensor

Browse git

Calculate the power generation bound residual.

$$g_{\text{lower}} = \text{pmin} - \text{pg}$$ $$g_{\text{upper}} = \text{pg} - \text{pmax}$$

Args

pg : Tensor

Active power generation per generator. (batch_size, ngen)

clamp : bool, optional

Clamp the residual to be non-negative (extract violations). Defaults to False.

Returns

Tensor

Lower bound residual. (batch_size, ngen)

Tensor

Upper bound residual. (batch_size, ngen)

Inherited members

• OPFViolation:
  • adjacency_matrix
  • branch_from_incidence
  • branch_from_to_bus
  • branch_incidence
  • branch_to_incidence
  • branch_to_to_bus
  • forward
  • gen_to_bus
  • generator_incidence
  • load_incidence
  • load_to_bus
  • reduce_violation
  • reduce_violations
  • violation_shapes