SOCOPF

Sub-modules

ml4opf.formulations.soc.model

ml4opf.formulations.soc.problem

SOCOPF Problem data class

ml4opf.formulations.soc.violation

Class interface for SOCOPF constraints, objective, etc.

Classes

class SOCModel

Browse git

OPFModel for SOCOPF

Ancestors

• OPFModel
• abc.ABC

Subclasses

• PerfectSOCModel
• SOCBasicNeuralNet

Class variables

var problem : SOCProblem

var violation : SOCViolation

Methods

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

Browse git

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

Args

pd : Tensor

Active power demand per load.

qd : Tensor

Reactive power demand per load.

Returns

dict[str, Tensor]

Dictionary containing the predicted primal solution.

pg: Active power generation per generator or per bus.

qg: Reactive power generation per generator or per bus.

w: Squared voltage magnitude per bus.

wr: Real part of the voltage phasor.

wi: Imaginary part of the voltage phasor.

Inherited members

• OPFModel:
  • evaluate_model
  • load_from_checkpoint
  • save_checkpoint

class SOCProblem (data_directory: str, dataset_name: str = 'SOCOPF', **parse_kwargs)

Browse git

OPFProblem for SOCOPF

Ancestors

• OPFProblem
• abc.ABC

Instance variables

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

Browse git

Default combos for SOCOPF:

• input: pd, qd

• target: pg, qg, w, wr, wi

prop default_order : list[str]

Browse git

Default order for SOCOPF: input, target

prop feasibility_check : dict[str, str]

Browse git

Default feasibility check for SOCOPF:

• termination_status: "LOCALLY_SOLVED"

• primal_status: "FEASIBLE_POINT"

• dual_status: "FEASIBLE_POINT"

prop violation : SOCViolation

Browse git

SOCViolation object, created upon first access.

Inherited members

• OPFProblem:
  • make_dataset
  • parse
  • slice_batch
  • slice_tensor

class SOCViolation (data: dict)

Browse git

OPFViolation for SOCOPF

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

Ancestors

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

Methods

def angle_difference_residual(self, wr: torch.Tensor, wi: torch.Tensor, clamp: bool = False) ‑> torch.Tensor

Browse git

Compute the angle difference bound residual.

def balance_residual(self,
pd: torch.Tensor,
qd: torch.Tensor,
pg: torch.Tensor,
qg: torch.Tensor,
w: torch.Tensor,
pf: torch.Tensor,
pt: torch.Tensor,
qf: torch.Tensor,
qt: torch.Tensor,
clamp: bool = False,
embed_method: str = 'pad') ‑> tuple[torch.Tensor, torch.Tensor]

Browse git

Calculate the power balance residual.

Component-wise tensors are first embedded to the bus level using embed_method.

The shunt parameters $g_s, b_s$ are assumed to be constant, matching the reference case.

$$\text{p_viol} = \text{pg_bus} - \text{pd_bus} - \text{pt_bus} - \text{pf_bus} - \text{gs_bus} \times \text{vm}^2$$ $$\text{q_viol} = \text{qg_bus} - \text{qd_bus} - \text{qt_bus} - \text{qf_bus} + \text{bs_bus} \times \text{vm}^2$$

Args

pd : Tensor

Active power demand per bus. (batch_size, nbus)

qd : Tensor

Reactive power demand per bus. (batch_size, nbus)

pg : Tensor

Active power generation per generator. (batch_size, ngen)

qg : Tensor

Reactive power generation per generator. (batch_size, ngen)

vm : Tensor

Voltage magnitude per bus. (batch_size, nbus)

pf : Tensor

Active power flow from bus per branch. (batch_size, nbranch)

pt : Tensor

Active power flow to bus per branch. (batch_size, nbranch)

qf : Tensor

Reactive power flow from bus per branch. (batch_size, nbranch)

qt : Tensor

Reactive power flow to bus per branch. (batch_size, nbranch)

clamp : bool, optional

Apply an absolute value to the residual. Defaults to False.

embed_method : str, optional

Embedding method for bus-level components. Defaults to 'pad'. Must be one of 'pad', 'dense_matrix', or 'matrix. See IncidenceMixin.*_to_bus.

Returns

Tensor

Power balance residual for active power. (batch_size, nbus)

Tensor

Power balance residual for reactive power. (batch_size, nbus)

def calc_violations(self,
pd: torch.Tensor,
qd: torch.Tensor,
pg: torch.Tensor,
qg: torch.Tensor,
w: torch.Tensor,
wr: torch.Tensor,
wi: torch.Tensor,
flows: tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor] | None = None,
reduction: str | None = 'mean',
clamp: bool = True) ‑> dict[str, torch.Tensor]

Browse git

Calculate the violation of all the constraints.

The reduction is applied across the component dimension - e.g., 'mean' will do violation.mean(dim=1) where each violation is (batch, components)

Args

pd : Tensor

Real power demand. (batch, loads)

qd : Tensor

Reactive power demand. (batch, loads)

pg : Tensor

Real power generation. (batch, gens)

qg : Tensor

Reactive power generation. (batch, gens)

vm : Tensor

Voltage magnitude. (batch, buses)

va : Tensor, optional

Voltage angle. (batch, buses)

dva : Tensor, optional

Voltage angle difference. (batch, branches)

flows : tuple[Tensor, Tensor, Tensor, Tensor], optional

Power flows. (pf, pt, qf, qt)

reduction : str, optional

Reduction method. Defaults to 'mean'. Must be one of 'mean', 'sum', 'none'.

clamp : bool, optional

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

Returns

• dict[str, Tensor]: Dictionary of violations.

vm_lower: Voltage magnitude lower bound violation.

vm_upper: Voltage magnitude upper bound violation.

pg_lower: Real power generation lower bound violation.

pg_upper: Real power generation upper bound violation.

qg_lower: Reactive power generation lower bound violation.

qg_upper: Reactive power generation upper bound violation.

thrm_1: Thermal limit from violation.

thrm_2: Thermal limit to violation.

p_balance: Real power balance violation.

q_balance: Reactive power balance violation.

dva_lower: Voltage angle difference lower bound violation.

dva_upper: Voltage angle difference upper bound violation.

def flows_from_voltage(self, w: torch.Tensor, wr: torch.Tensor, wi: torch.Tensor) ‑> tuple[torch.Tensor, torch.Tensor, torch.Tensor, torch.Tensor]

Browse git

Compute the power flows.

Returns

Tensor

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

Tensor

Real power flow per branch ( $\mathbf{p}_t$ ). (batch_size, nbranch)

Tensor

Reactive power flow per branch ( $\mathbf{q}_f$ ). (batch_size, nbranch)

Tensor

Reactive power flow per branch ( $\mathbf{q}_t$ ). (batch_size, nbranch)

def jabr_residual(self, w: torch.Tensor, wr: torch.Tensor, wi: torch.Tensor, clamp: bool = False) ‑> torch.Tensor

Browse git

Compute the Jabr constraint residual.

$$g_{\text{jabr}} = \text{wr}^2 + \text{wi}^2 - \text{w}_{fr} * \text{w}_{to}$$

Args

w : Tensor

Squared voltage magnitude per bus. (batch_size, nbus)

wr : Tensor

Real part of the voltage phasor. (batch_size, nbus)

wi : Tensor

Imaginary part of the voltage phasor. (batch_size, nbus)

clamp : bool, optional

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

Returns

Tensor

Jabr constraint residual. (batch_size, nbus)

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

Browse git

Compute the objective function given the active power generation per generator.

Args

pg : Tensor

Active power generation per generator. (batch_size, ngen)

Returns

Tensor

Objective function value. (batch_size)

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

Browse git

Calculate the active 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)

def qg_bound_residual(self, qg: torch.Tensor, clamp: bool = False) ‑> tuple[torch.Tensor, torch.Tensor]

Browse git

Calculate the reactive power generation bound residual.

$$g_{\text{lower}} = \text{qmin} - \text{qg}$$ $$g_{\text{upper}} = \text{qg} - \text{qmax}$$

Args

qg : Tensor

Reactive 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)

def thermal_residual(self,
pf: torch.Tensor,
pt: torch.Tensor,
qf: torch.Tensor,
qt: torch.Tensor,
clamp: bool = False) ‑> tuple[torch.Tensor, torch.Tensor]

Browse git

Calculate the thermal limit residual.

$$g_{\text{thrm}_1} = \text{pf}^2 + \text{qf}^2 - \text{s1max}$$ $$g_{\text{thrm}_2} = \text{pt}^2 + \text{qt}^2 - \text{s2max}$$

Args

pf : Tensor

Active power flow from bus per branch. (batch_size, nbranch)

pt : Tensor

Active power flow to bus per branch. (batch_size, nbranch)

qf : Tensor

Reactive power flow from bus per branch. (batch_size, nbranch)

qt : Tensor

Reactive power flow to bus per branch. (batch_size, nbranch)

clamp : bool, optional

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

Returns

Tensor

Thermal limit residual for from branch. (batch_size, nbranch)

Tensor

Thermal limit residual for to branch. (batch_size, nbranch)

def w_bound_residual(self, w: torch.Tensor, clamp: bool = False) ‑> tuple[torch.Tensor, torch.Tensor]

Browse git

Calculate the bound residual of w.

Returns

Tensor

Lower bound residual. (batch_size, nbranch)

Tensor

Upper bound residual. (batch_size, nbranch)

def wi_bound_residual(self, wr: torch.Tensor, clamp: bool = False) ‑> tuple[torch.Tensor, torch.Tensor]

Browse git

Calculate the bound residual of wi.

Returns

Tensor

Lower bound residual. (batch_size, nbranch)

Tensor

Upper bound residual. (batch_size, nbranch)

def wr_bound_residual(self, wr: torch.Tensor, clamp: bool = False) ‑> tuple[torch.Tensor, torch.Tensor]

Browse git

Calculate the bound residual of wr.

Returns

Tensor

Lower bound residual. (batch_size, nbranch)

Tensor

Upper bound residual. (batch_size, nbranch)

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