VeraGridEngine.Simulations.PowerFlow.NumericalMethods package

Submodules

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions module

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.active_power_mismatch(slip: float, u: complex, Rs: float, Xs: float, Xm: float, Rr: float, Xr: float, P: float, Sr: float) → float[source]
Parameters:

  • slip

  • u

  • Rs

  • Xs

  • Xm

  • Rr

  • Xr

  • P

  • Sr

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.asynchronous_gen_currents(voltage: ndarray[tuple[Any, ...], dtype[complex128]], Rs: float, Xs: float, Xm: float, Rr: float, Xr: float, P: float, Sr: float, y0: complex = 0j) → ndarray[tuple[Any, ...], dtype[complex128]][source]

Compute ABC injections with one slip and the existing single-cage model.

Parameters:

  • voltage – Three phase-to-ground voltages in pu.

  • Rs – Stator resistance in machine pu.

  • Xs – Stator reactance in machine pu.

  • Xm – Magnetising reactance in machine pu.

  • Rr – Rotor resistance in machine pu.

  • Xr – Rotor reactance in machine pu.

  • P – Positive-sequence electrical active injection in MW, as in PF AS mode.

  • Sr – Machine rated power in MVA.

  • y0 – Effective zero-sequence admittance in machine pu (zero for D/Y).

Returns:

Phase current injections in MW / pu voltage, as used by the ABC residual.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.asynchronous_gen_q(u: complex, Rs: float, Xs: float, Xm: float, Rr: float, Xr: float, P: float, Sr: float) → float[source]
Parameters:

  • u

  • Rs

  • Xs

  • Xm

  • Rr

  • Xr

  • P

  • Sr

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.asynchronous_impedance(slip: float, Rs: float, Xs: float, Xm: float, Rr: float, Xr: float) → complex[source]

Return the existing single-cage equivalent on the machine base.

Parameters:

  • slip – Sequence slip (s for positive sequence, 2-s for negative).

  • Rs – Stator resistance in pu.

  • Xs – Stator reactance in pu.

  • Xm – Magnetising reactance in pu.

  • Rr – Rotor resistance in pu.

  • Xr – Rotor reactance in pu.

Returns:

Terminal sequence impedance in pu.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.compute_asynchronous_generator_q(V: ndarray[tuple[Any, ...], dtype[complex128]], gen_bus_idx: ndarray[tuple[Any, ...], dtype[int64]], gen_active: ndarray[tuple[Any, ...], dtype[bool]], gen_types, Rs: ndarray[tuple[Any, ...], dtype[float64]], Xs: ndarray[tuple[Any, ...], dtype[float64]], Xm: ndarray[tuple[Any, ...], dtype[float64]], Rr: ndarray[tuple[Any, ...], dtype[float64]], Xr: ndarray[tuple[Any, ...], dtype[float64]], P: ndarray[tuple[Any, ...], dtype[float64]], Snom: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Compute the voltage-dependent reactive power of asynchronous generators.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.compute_asynchronous_generator_q_per_bus(nbus: int, V: ndarray[tuple[Any, ...], dtype[complex128]], gen_bus_idx: ndarray[tuple[Any, ...], dtype[int64]], gen_active: ndarray[tuple[Any, ...], dtype[bool]], gen_types, Rs: ndarray[tuple[Any, ...], dtype[float64]], Xs: ndarray[tuple[Any, ...], dtype[float64]], Xm: ndarray[tuple[Any, ...], dtype[float64]], Rr: ndarray[tuple[Any, ...], dtype[float64]], Xr: ndarray[tuple[Any, ...], dtype[float64]], P: ndarray[tuple[Any, ...], dtype[float64]], Snom: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Compute the voltage-dependent asynchronous generator Q summed by bus.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.compute_current(Ybus: csc_matrix, V: ndarray[tuple[Any, ...], dtype[complex128]]) → ndarray[tuple[Any, ...], dtype[complex128]][source]

Compute the current from the admittance matrix and the voltage :param Ybus: Admittance matrix :param V: Voltage vector :return: Calculated current injections

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.compute_fx(Scalc: ndarray[tuple[Any, ...], dtype[complex128]], Sbus: ndarray[tuple[Any, ...], dtype[complex128]], idx_dP: ndarray[tuple[Any, ...], dtype[int64]], idx_dQ: ndarray[tuple[Any, ...], dtype[int64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Compute the NR-like error function f = [βˆ†P(pqpv), βˆ†Q(pq)] :param Scalc: Calculated power injections :param Sbus: Specified power injections :param idx_dP: Array of node indices updated with dP (pvpq) :param idx_dQ: Array of node indices updated with dQ (pq) :return: error

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.compute_fx_error(fx: ndarray[tuple[Any, ...], dtype[float64]]) → float[source]

Compute the infinite norm of fx this is the same as max(abs(fx)) :param fx: vector :return: infinite norm

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.compute_power(Ybus: csc_matrix, V: ndarray[tuple[Any, ...], dtype[complex128]]) → ndarray[tuple[Any, ...], dtype[complex128]][source]

Compute the power from the admittance matrix and the voltage :param Ybus: Admittance matrix :param V: Voltage vector :return: Calculated power injections

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.compute_zip_current(S0: ndarray[tuple[Any, ...], dtype[complex128]], I0: ndarray[tuple[Any, ...], dtype[complex128]], Y0: ndarray[tuple[Any, ...], dtype[complex128]], Vm: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[complex128]][source]

Compute the equivalent current injection :param S0: Base power (P + jQ) :param I0: Base current (Ir + jIi) :param Y0: Base admittance (G + jB) :param Vm: voltage module, for the 3ph power flow the complete voltage phasor is used (Vm + Va) :return: complex current injection

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.compute_zip_power(S0: ndarray[tuple[Any, ...], dtype[complex128]], I0: ndarray[tuple[Any, ...], dtype[complex128]], Y0: ndarray[tuple[Any, ...], dtype[complex128]], Vm: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[complex128]][source]

Compute the equivalent power injection :param S0: Base power (P + jQ) :param I0: Base current (Ir + jIi) :param Y0: Base admittance (G + jB) :param Vm: voltage module, for the 3ph power flow the complete voltage phasor is used (Vm + Va) :return: complex power injection

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.expand(n, arr: ndarray[tuple[Any, ...], dtype[float64]], idx: ndarray[tuple[Any, ...], dtype[int64]], default: float) → ndarray[tuple[Any, ...], dtype[float64]][source]

Expand array :param n: number of elements :param arr: short array :param idx: indices in the longer array :param default: default value for the longer array :return: longer array

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.expand_magnitudes(magnitude: ndarray[tuple[Any, ...], dtype[complex128]], lookup: ndarray[tuple[Any, ...], dtype[int64]])[source]
Parameters:

  • magnitude

  • lookup

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.floating_star_currents(Va, Vb, Vc, Istar_a, Istar_b, Istar_c, Vn0) → Tuple[complex, complex, complex, complex][source]

Given the phase voltages and currents of a floating star connected current load, this function calculates the phase currents (Ia, Ib, Ic) and the neutral voltage (Vn), such that they meet the condition that the current flowing through the neutral point is equal to zero, since the neutral point of the star is floating -> In = Ia + Ib + Ic = 0 :param Va: Phase A load voltage :param Vb: Phase B load voltage :param Vc: Phase C load voltage :param Istar_a: Phase A load current :param Istar_b: Phase B load current :param Istar_c: Phase C load current :param Vn0: Last-iteration neutral point voltage or

just the center of the phase voltages (Va,Vb,Vc) at the first iteration

Returns:

Ia, Ib, Ic, Vn

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.floating_star_powers(Ua, Ub, Uc, Sa, Sb, Sc) → Tuple[complex, complex, complex, complex][source]

Given the phase voltages and complex powers of a floating star connected power load, this function calculates the phase currents (Ia, Ib, Ic) and the neutral voltage (Un), such that they meet the condition that the current flowing through the neutral point is equal to zero, since the neutral point of the star is floating -> In = Ia + Ib + Ic = 0 :param Ua: Phase A load voltage :param Ub: Phase B load voltage :param Uc: Phase C load voltage :param Sa: Phase A load complex power :param Sb: Phase B load complex power :param Sc: Phase C load complex power :return: Ia, Ib, Ic, Un

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.get_If(k: ndarray[tuple[Any, ...], dtype[int64]], V: ndarray[tuple[Any, ...], dtype[complex128]], yff: ndarray[tuple[Any, ...], dtype[complex128]], yft: ndarray[tuple[Any, ...], dtype[complex128]], F: ndarray[tuple[Any, ...], dtype[int64]], T: ndarray[tuple[Any, ...], dtype[int64]])[source]
Parameters:

  • k

  • V

  • yff

  • yft

  • F

  • T

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.get_It(k: ndarray[tuple[Any, ...], dtype[int64]], V: ndarray[tuple[Any, ...], dtype[complex128]], ytf: ndarray[tuple[Any, ...], dtype[complex128]], ytt: ndarray[tuple[Any, ...], dtype[complex128]], F: ndarray[tuple[Any, ...], dtype[int64]], T: ndarray[tuple[Any, ...], dtype[int64]])[source]
Parameters:

  • k

  • V

  • ytf

  • ytt

  • F

  • T

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.get_Sf(k: ndarray[tuple[Any, ...], dtype[int64]], Vm: ndarray[tuple[Any, ...], dtype[float64]], V: ndarray[tuple[Any, ...], dtype[complex128]], yff: ndarray[tuple[Any, ...], dtype[complex128]], yft: ndarray[tuple[Any, ...], dtype[complex128]], F: ndarray[tuple[Any, ...], dtype[int64]], T: ndarray[tuple[Any, ...], dtype[int64]])[source]
Parameters:

  • k

  • Vm

  • V

  • yff

  • yft

  • F

  • T

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.get_St(k: ndarray[tuple[Any, ...], dtype[int64]], Vm: ndarray[tuple[Any, ...], dtype[float64]], V: ndarray[tuple[Any, ...], dtype[complex128]], ytf: ndarray[tuple[Any, ...], dtype[complex128]], ytt: ndarray[tuple[Any, ...], dtype[complex128]], F: ndarray[tuple[Any, ...], dtype[int64]], T: ndarray[tuple[Any, ...], dtype[int64]])[source]
Parameters:

  • k

  • Vm

  • V

  • ytf

  • ytt

  • F

  • T

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.polar_to_rect(Vm: ndarray[tuple[Any, ...], dtype[float64]], Va: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[complex128]][source]

Convert polar to rectangular coordinates :param Vm: Module :param Va: Angle in radians :return: Polar vector

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.power_flow_post_process_linear(Sbus: ndarray[tuple[Any, ...], dtype[complex128]], V: ndarray[tuple[Any, ...], dtype[complex128]], active: ndarray[tuple[Any, ...], dtype[int64]], X: ndarray[tuple[Any, ...], dtype[float64]], tap_module: ndarray[tuple[Any, ...], dtype[float64]], tap_angle: ndarray[tuple[Any, ...], dtype[float64]], F: ndarray[tuple[Any, ...], dtype[int64]], T: ndarray[tuple[Any, ...], dtype[int64]], branch_rates: ndarray[tuple[Any, ...], dtype[float64]], Sbase: float)[source]
Parameters:

  • Sbus

  • V

  • active

  • X

  • tap_module

  • tap_angle

  • F

  • T

  • branch_rates

  • Sbase

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.power_flow_post_process_nonlinear(Sbus: ndarray[tuple[Any, ...], dtype[complex128]], V: ndarray[tuple[Any, ...], dtype[complex128]], F: ndarray[tuple[Any, ...], dtype[int64]], T: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]], vd: ndarray[tuple[Any, ...], dtype[int64]], Ybus: csc_matrix, Yf: csc_matrix, Yt: csc_matrix, Yshunt_bus: ndarray[tuple[Any, ...], dtype[complex128]], branch_rates: ndarray[tuple[Any, ...], dtype[float64]], Sbase: float)[source]
Parameters:

  • Sbus

  • V

  • F

  • T

  • pv

  • vd

  • Ybus

  • Yf

  • Yt

  • Yshunt_bus

  • branch_rates

  • Sbase

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.power_flow_post_process_nonlinear_3ph(Sbus: ndarray[tuple[Any, ...], dtype[complex128]], V: ndarray[tuple[Any, ...], dtype[complex128]], Vn_floating: ndarray[tuple[Any, ...], dtype[complex128]], F: ndarray[tuple[Any, ...], dtype[int64]], T: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]], vd: ndarray[tuple[Any, ...], dtype[int64]], Ybus: csc_matrix, Yf: csc_matrix, Yt: csc_matrix, Yshunt_bus: ndarray[tuple[Any, ...], dtype[complex128]], branch_rates: ndarray[tuple[Any, ...], dtype[float64]], Sbase: float, bus_lookup: ndarray[tuple[Any, ...], dtype[int64]], branch_lookup: ndarray[tuple[Any, ...], dtype[int64]])[source]
Parameters:

  • Sbus

  • V

  • Vn_floating

  • F

  • T

  • pv

  • vd

  • Ybus

  • Yf

  • Yt

  • Yshunt_bus

  • branch_rates

  • Sbase

  • bus_lookup

  • branch_lookup

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.solve_slip(f, a, b, tol, max_iter, u, Rs, Xs, Xm, Rr, Xr, P, Sr)[source]
Parameters:

  • f

  • a

  • b

  • tol

  • max_iter

  • u

  • Rs

  • Xs

  • Xm

  • Rr

  • Xr

  • P

  • Sr

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.split_bus_quantity(Qbus: ndarray[tuple[Any, ...], dtype[float64]], gen_bus_idx: ndarray[tuple[Any, ...], dtype[int64]], Qmin_gen: ndarray[tuple[Any, ...], dtype[float64]], Qmax_gen: ndarray[tuple[Any, ...], dtype[float64]], gen_status: ndarray[tuple[Any, ...], dtype[bool]], control_mode_int_gen: ndarray[tuple[Any, ...], dtype[int64]], Q0_gen: ndarray[tuple[Any, ...], dtype[float64]], Vset_gen: ndarray[tuple[Any, ...], dtype[float64]], k_droop_gen: ndarray[tuple[Any, ...], dtype[float64]], dead_band_gen: ndarray[tuple[Any, ...], dtype[float64]], batt_bus_idx: ndarray[tuple[Any, ...], dtype[int64]], Qmin_batt: ndarray[tuple[Any, ...], dtype[float64]], Qmax_batt: ndarray[tuple[Any, ...], dtype[float64]], batt_status: ndarray[tuple[Any, ...], dtype[bool]], control_mode_int_batt: ndarray[tuple[Any, ...], dtype[int64]], Q0_batt: ndarray[tuple[Any, ...], dtype[float64]], v_ctrl_val_gen: int, qv_droop_val_gen: int, Vm: ndarray[tuple[Any, ...], dtype[float64]], atol: float = 1e-12) → Tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Split a per-bus reactive power quantity among online generators and batteries.

The function separates generator-like elements into two families:

  1. Generators.

  2. Batteries.

Both families are treated as reactive power providers connected to buses. The bus-level reactive power Qbus is split among all online controlling elements at each bus, regardless of whether the element is a generator or a battery.

Online non-controlling generators and online non-controlling batteries are assigned their initial reactive power set point Q0. Their contribution is subtracted from the bus reactive power before the controlling elements share the remaining value.

For each bus i, the fixed non-controlling contribution is:

Qfixed_i = \sum_{k \in G_i,\ online,\ not\ controlling} Q0^{gen}_k + \sum_{m \in B_i,\ online,\ not\ controlling} Q0^{batt}_m

The reactive power left for controlling elements is:

Qctrl_i = Qbus_i - Qfixed_i

The aggregate controlling limits include both generators and batteries:

Qctrl^{min}_i = \sum_{k \in G_i,\ online,\ controlling} Qmin^{gen}_k + \sum_{m \in B_i,\ online,\ controlling} Qmin^{batt}_m

Qctrl^{max}_i = \sum_{k \in G_i,\ online,\ controlling} Qmax^{gen}_k + \sum_{m \in B_i,\ online,\ controlling} Qmax^{batt}_m

The normalized sharing factor at each bus is:

r_i = \frac{ Qctrl_i - Qctrl^{min}_i }{ Qctrl^{max}_i - Qctrl^{min}_i }

after clipping Qctrl_i to the aggregate controlling capability.

Final assignments are:

  • Offline generators receive zero.

  • Offline batteries receive zero.

  • Online non-controlling generators receive Q0_gen.

  • Online non-controlling batteries receive Q0_batt.

  • Online controlling generators share the residual bus Q using their own Qmin_gen and Qmax_gen.

  • Online controlling batteries share the residual bus Q using their own Qmin_batt and Qmax_batt.

This function assumes that generators and batteries use the same reactive power sign convention as Qbus.

This function assumes that all arrays have compatible sizes and that gen_bus_idx and batt_bus_idx contain valid zero-based bus indices. Input validation should be done by the caller or by a Python wrapper outside this Numba function.

Parameters:

  • Qbus (Vec) – Total reactive generator-like power requested at each bus.

  • gen_bus_idx (IntVec) – Bus index of each generator.

  • Qmin_gen (Vec) – Minimum reactive power limit of each generator.

  • Qmax_gen (Vec) – Maximum reactive power limit of each generator.

  • gen_status (BoolVec) – Generator status vector. True means online.

  • control_mode_int_gen (BoolVec) – Generator control flag. True means the generator participates in reactive power sharing.

  • Q0_gen (Vec) – Initial or fixed reactive power set point of each generator.

  • Vset_gen (Vec) – Voltage set point of each generator.

  • k_droop_gen (Vec) – QV droop constant of each generator.

  • dead_band_gen (Vec) – QV droop dead band of each generator.

  • batt_bus_idx (IntVec) – Bus index of each battery.

  • Qmin_batt (Vec) – Minimum reactive power limit of each battery.

  • Qmax_batt (Vec) – Maximum reactive power limit of each battery.

  • batt_status (BoolVec) – Battery status vector. True means online.

  • control_mode_int_batt (BoolVec) – Battery control flag. True means the battery participates in reactive power sharing.

  • Q0_batt (Vec) – Initial or fixed reactive power set point of each battery.

  • v_ctrl_val_gen

  • qv_droop_val_gen

  • Vm (Vec) – Converged voltage magnitude per bus.

  • atol (float) – Tolerance used to detect zero aggregate reactive range.

Returns:

Reactive power assigned to generators and batteries.

Return type:

Tuple[Vec, Vec]

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.split_reactive_power_between_generators_and_batteries(Qbus: ndarray[tuple[Any, ...], dtype[float64]], Qfixed_bus: ndarray[tuple[Any, ...], dtype[float64]], gen_bus_idx: ndarray[tuple[Any, ...], dtype[int64]], Qmin_gen: ndarray[tuple[Any, ...], dtype[float64]], Qmax_gen: ndarray[tuple[Any, ...], dtype[float64]], gen_status: ndarray[tuple[Any, ...], dtype[bool]], control_mode_int_gen: ndarray[tuple[Any, ...], dtype[int64]], Q0_gen: ndarray[tuple[Any, ...], dtype[float64]], Vset_gen: ndarray[tuple[Any, ...], dtype[float64]], k_droop_gen: ndarray[tuple[Any, ...], dtype[float64]], dead_band_gen: ndarray[tuple[Any, ...], dtype[float64]], batt_bus_idx: ndarray[tuple[Any, ...], dtype[int64]], Qmin_batt: ndarray[tuple[Any, ...], dtype[float64]], Qmax_batt: ndarray[tuple[Any, ...], dtype[float64]], batt_status: ndarray[tuple[Any, ...], dtype[bool]], control_mode_int_batt: ndarray[tuple[Any, ...], dtype[int64]], Q0_batt: ndarray[tuple[Any, ...], dtype[float64]], v_ctrl_val_gen: int, qv_droop_val_gen: int, Vm: ndarray[tuple[Any, ...], dtype[float64]], enforce_q_limits: bool = True, atol: float = 1e-12) → Tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Split solved bus reactive power between generator-like controlling devices.

This routine is the reactive-power post-processing counterpart of the generator/battery bus split. Unlike the generic quantity split, it starts from an already compiled fixed bus contribution Qfixed_bus that includes load-like injections, fixed current/admittance terms, and non-controlling generator-like set points captured by the numerical circuit compilation.

The controlling residual at each bus is therefore:

Qctrl_i = Qbus_i - Qfixed_i - Qdroop_i

where Qdroop_i is the contribution of droop-controlled generators evaluated at the solved voltage magnitude.

Online voltage-controlled generators and batteries share that residual subject to their aggregate limits. Online non-controlling generators and batteries keep their compiled set points. Offline devices receive zero.

Parameters:

  • Qbus – Solved nodal reactive power injection.

  • Qfixed_bus – Fixed compiled reactive contribution per bus.

  • gen_bus_idx – Generator bus index.

  • Qmin_gen – Generator minimum reactive power.

  • Qmax_gen – Generator maximum reactive power.

  • gen_status – Generator active status.

  • control_mode_int_gen – Generator control mode codes.

  • Q0_gen – Generator fixed reactive set point.

  • Vset_gen – Generator voltage set points.

  • k_droop_gen – Generator droop coefficients.

  • dead_band_gen – Generator droop dead bands.

  • batt_bus_idx – Battery bus index.

  • Qmin_batt – Battery minimum reactive power.

  • Qmax_batt – Battery maximum reactive power.

  • batt_status – Battery active status.

  • control_mode_int_batt – Battery control mode codes.

  • Q0_batt – Battery fixed reactive set point.

  • v_ctrl_val_gen – Integer code for voltage control.

  • qv_droop_val_gen – Integer code for QV droop control.

  • Vm – Solved bus voltage magnitudes.

  • enforce_q_limits – Clip voltage-controller Q reports to the declared capability limits.

  • atol – Numerical zero tolerance.

Returns:

Tuple with generator and battery reactive power vectors.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.split_slack_bus_quantity_between_generators_and_batteries(Qbus: ndarray[tuple[Any, ...], dtype[float64]], Qfixed_bus: ndarray[tuple[Any, ...], dtype[float64]], slack_bus_mask: ndarray[tuple[Any, ...], dtype[bool]], gen_bus_idx: ndarray[tuple[Any, ...], dtype[int64]], Qmin_gen: ndarray[tuple[Any, ...], dtype[float64]], Qmax_gen: ndarray[tuple[Any, ...], dtype[float64]], gen_status: ndarray[tuple[Any, ...], dtype[bool]], Q0_gen: ndarray[tuple[Any, ...], dtype[float64]], batt_bus_idx: ndarray[tuple[Any, ...], dtype[int64]], Qmin_batt: ndarray[tuple[Any, ...], dtype[float64]], Qmax_batt: ndarray[tuple[Any, ...], dtype[float64]], batt_status: ndarray[tuple[Any, ...], dtype[bool]], Q0_batt: ndarray[tuple[Any, ...], dtype[float64]], atol: float = 1e-12) → Tuple[ndarray[tuple[Any, ...], dtype[float64]], ndarray[tuple[Any, ...], dtype[float64]]][source]

Split one solved bus quantity among online generator-like devices at slack buses.

This helper is used after the main power-flow post-processing to reconstruct the per-device values that belong to slack buses. The solved bus quantities are already correct, but the slack balancing residual can remain attached only to the bus result instead of being reassigned to the connected online generators and batteries.

The split is performed independently at every slack bus. Devices connected to non-slack buses preserve their input values Q0_gen and Q0_batt. Online devices connected to slack buses share the residual bus quantity after subtracting the fixed bus contribution Qfixed_bus. Offline devices receive zero.

Parameters:

  • Qbus – Solved per-bus quantity to reconstruct.

  • Qfixed_bus – Fixed per-bus contribution that does not belong to the participating slack devices.

  • slack_bus_mask – Boolean mask marking the slack buses.

  • gen_bus_idx – Generator bus index.

  • Qmin_gen – Generator lower bound for the reconstructed quantity.

  • Qmax_gen – Generator upper bound for the reconstructed quantity.

  • gen_status – Generator active status.

  • Q0_gen – Generator baseline values kept at non-slack buses.

  • batt_bus_idx – Battery bus index.

  • Qmin_batt – Battery lower bound for the reconstructed quantity.

  • Qmax_batt – Battery upper bound for the reconstructed quantity.

  • batt_status – Battery active status.

  • Q0_batt – Battery baseline values kept at non-slack buses.

  • atol – Numerical zero tolerance.

Returns:

Tuple with generator and battery reconstructed values.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.voltage_pdc_droop(ut: complex, un: complex, u_setpoint_min: float, u_setpoint_max: float, u_setpoint: float, Pdc_setpoint: float, S_r: float, droop: float, P_min: float, P_max: float, S_base: float) → float[source]

Find the actual DC power output for converters controlled with a voltage droop, where the converter terminal sits on the positive pole.

Implements Pdc = Pdc_setp - Pdroop * (Vdc_setp - Vdc) with the voltage being the difference Vdc = Re(ut - un) where un = 0 for monopolar converters

Parameters:

  • ut – Actual voltage value at the pole terminal [pu]

  • un – Actual voltage value at the return/negative terminal [pu]

  • u_setpoint_min – Minimum voltage setpoint [pu]

  • u_setpoint_max – Maximum voltage setpoint [pu]

  • u_setpoint – Specified voltage setpoint [pu]

  • Pdc_setpoint – Specified dispatch DC power [MW]

  • S_r – Rated apparent power [MVA]

  • droop – Voltage droop value [%]

  • P_min – Minimum DC power the converter can inject/absorb [MW]

  • P_max – Maximum DC power the converter can inject/absorb [MW]

  • S_base – Base power of the network [MVA]

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.voltage_pdc_droop_neg(ut: complex, un: complex, u_setpoint_min: float, u_setpoint_max: float, u_setpoint: float, Pdc_setpoint: float, S_r: float, droop: float, P_min: float, P_max: float, S_base: float) → float[source]

Find the actual DC power output for converters controlled with a voltage droop, where the converter terminal sits on the negative pole

The measured voltage is flipped, Vdc = Re(un - ut), so it enters the droop law as a positive magnitude

Parameters:

  • ut – Actual voltage value at the pole terminal [pu]

  • un – Actual voltage value at the return/negative terminal [pu]

  • u_setpoint_min – Minimum voltage setpoint [pu]

  • u_setpoint_max – Maximum voltage setpoint [pu]

  • u_setpoint – Specified voltage setpoint [pu]

  • Pdc_setpoint – Specified dispatch DC power [MW]

  • S_r – Rated apparent power [MVA]

  • droop – Voltage droop value [%]

  • P_min – Minimum DC power the converter can inject/absorb [MW]

  • P_max – Maximum DC power the converter can inject/absorb [MW]

  • S_base – Base power of the network [MVA]

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.common_functions.voltage_q_droop(ut: complex, u_setpoint_min: float, u_setpoint_max: float, u_setpoint: float, Q_setpoint: float, S_r: float, droop: float, Q_min: float, Q_max: float, S_base: float)[source]

Find the actual reactive power output for generators controlled with a voltage droop. :param ut: Actual voltage value at the terminal [pu] :param u_setpoint_min: Minimum voltage setpoint [pu] :param u_setpoint_max: Maximum voltage setpoint [pu] :param u_setpoint: Specified voltage setpoint [pu] :param Q_setpoint: Specified dispatch reactive power [MVAr] :param S_r: Rated apparent power [MVA] :param droop: Voltage droop value [%] :param Q_min: Minimum reactive power the converter can inject/absorb [MVAr] :param Q_max: Maximum reactive power the converter can inject/absorb [MVAr] :param S_base: Base power of the network [MVA]

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.converter_fault_controls module

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.converter_fault_controls.current_limit_logic(Iqcmd, vdlq, vdlp, is_blocked)[source]
VeraGridEngine.Simulations.PowerFlow.NumericalMethods.converter_fault_controls.genstat(ur, ui, iq_ref, id_ref, Sn, is_blocked)[source]
VeraGridEngine.Simulations.PowerFlow.NumericalMethods.converter_fault_controls.reec_d(u, Vpf, Qpf, Ppf, vblkl, vblkh)[source]
VeraGridEngine.Simulations.PowerFlow.NumericalMethods.converter_fault_controls.regc_c(Iqcmd, Ipcmd)[source]
VeraGridEngine.Simulations.PowerFlow.NumericalMethods.converter_fault_controls.vdl(x, points)[source]

Linear approximation with clamping. points: list of (x_i, y_i), sorted by x_i

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.converter_fault_controls.wecc_wt_type_4b(V_measured, Vpf, St_vsc_pf, S_base_vg, S_rated_vsc, vblkl, vblkh=1.2)[source]

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.converter_fault_controls_no_ifs module

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.converter_fault_controls_no_ifs.genstat(ur, ui, iq_ref, id_ref, Sn)[source]
Parameters:

  • ur

  • ui

  • iq_ref

  • id_ref

  • Sn

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.converter_fault_controls_no_ifs.reec_d(u, Vpf, Paux, Qext, Pref)[source]
Parameters:

  • u

  • Vpf

  • Paux

  • Qext

  • Pref

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.converter_fault_controls_no_ifs.regc_c(Iqcmd, ir, ii, ur, ui, fref, Fnom, Vt, Ipcmd, is_blocked)[source]
Parameters:

  • Iqcmd

  • ir

  • ii

  • ur

  • ui

  • fref

  • Fnom

  • Vt

  • Ipcmd

  • is_blocked

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.converter_fault_controls_no_ifs.wecc_wt_type_4b_no_ifs(V_measured, P_measured, Q_measured, S_base_vg, S_rated_vsc, Vpf)[source]
Parameters:

  • V_measured

  • P_measured

  • Q_measured

  • S_base_vg

  • S_rated_vsc

  • Vpf

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.discrete_controls module

class VeraGridEngine.Simulations.PowerFlow.NumericalMethods.discrete_controls.DiscreteShuntControlState(nc: NumericalCircuit)[source]

Bases: object

Python-side state holder for discrete shunt controls.

The packed arrays owned by this class are consumed by the Numba kernel so the formulations only need to keep a lightweight wrapper object.

apply(Vm: ndarray[tuple[Any, ...], dtype[float64]], adm: AdmittanceMatrices | AdmittanceMatricesFast, yshunt_bus: ndarray[tuple[Any, ...], dtype[complex128]] | None = None) → bool[source]

Apply one discrete shunt control step.

Parameters:

  • Vm – Voltage magnitude vector.

  • adm – Admittance container updated in place.

  • yshunt_bus – Optional external shunt-bus vector that must remain synchronized with adm.Yshunt_bus.

Returns:

True if any discrete shunt changed state, False otherwise.

get_shunt_step() → ndarray[tuple[Any, ...], dtype[int64]][source]

Get the mutable shunt step vector.

Returns:

Current discrete shunt step vector.

class VeraGridEngine.Simulations.PowerFlow.NumericalMethods.discrete_controls.QvDroopControlState(S0: ndarray[tuple[Any, ...], dtype[complex128]], nc: NumericalCircuit)[source]

Bases: object

Python-side state holder for generator QV droop controls.

The arrays are allocated once and the numerical update remains delegated to the Numba kernel.

apply(S0: ndarray[tuple[Any, ...], dtype[complex128]], Vm: ndarray[tuple[Any, ...], dtype[float64]]) → bool[source]

Apply one QV droop control step.

Parameters:

  • S0 – Specified bus power updated in place.

  • Vm – Voltage magnitude vector.

Returns:

True if any droop generator changed, False otherwise.

get_generator_q() → ndarray[tuple[Any, ...], dtype[float64]][source]

Get the per-generator reactive power buffer.

Returns:

Generator reactive power vector.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.discrete_controls.compute_slack_distribution(Scalc: ndarray[tuple[Any, ...], dtype[complex128]], vd: ndarray[tuple[Any, ...], dtype[int64]], bus_installed_power: ndarray[tuple[Any, ...], dtype[float64]]) → Tuple[bool, ndarray[tuple[Any, ...], dtype[float64]]][source]

Slack distribution logic :param Scalc: Computed power array :param vd: slack indices :param bus_installed_power: Amount of installed power :return: is slack division possible?

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.discrete_controls.control_discrete_shunts(Vm: ndarray[tuple[Any, ...], dtype[float64]], shunt_discrete_ctrl_idx: ndarray[tuple[Any, ...], dtype[int64]], shunt_discrete_bus_idx: ndarray[tuple[Any, ...], dtype[int64]], shunt_discrete_vmax: ndarray[tuple[Any, ...], dtype[float64]], shunt_discrete_vmin: ndarray[tuple[Any, ...], dtype[float64]], shunt_step: ndarray[tuple[Any, ...], dtype[int64]], shunt_g_steps: ndarray, shunt_b_steps: ndarray, shunt_n_steps: ndarray[tuple[Any, ...], dtype[int64]], sbase: float)[source]

Control discrete shunts within the numerical method. The sparse Ybus diagonal update is returned to the caller and applied outside numba. :param Vm: Voltage module array. :param shunt_discrete_ctrl_idx: Array of controlled shunt indices in the full shunt arrays. :param shunt_discrete_bus_idx: Array of bus indices for the controlled shunts. :param shunt_discrete_vmax: Array of upper voltage bounds for the controlled shunts. :param shunt_discrete_vmin: Array of lower voltage bounds for the controlled shunts. :param shunt_step: Array of current shunt steps in the full shunt arrays (changed inside). :param shunt_g_steps: Packed cumulative G steps for the controlled shunts. :param shunt_b_steps: Packed cumulative B steps for the controlled shunts. :param shunt_n_steps: Number of valid steps for each controlled shunt. :param sbase: Base power. :return: changed bus indices, Ybus diagonal increments, number of changed shunts.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.discrete_controls.control_q_direct(V, Vm, Vset, Q, Qmax, Qmin, types, original_types, verbose=False)[source]

Change the buses type in order to control the generators reactive power. :param V: Array of complex voltages :param Vm: Array of voltage modules (for speed) :param Vset: array of voltage Set points :param Q: Array of reactive power values per bus :param Qmax: Array of Qmax per bus :param Qmin: Array of Qmin per bus :param types: Array of bus types :param original_types: Array of original bus types :param verbose: More info? :return:

Vnew (list): New voltage values

Qnew (list): New reactive power values

types_new (list): Modified types array

any_control_issue (bool): Was there any control issue?

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.discrete_controls.control_q_for_generalized_method(Scalc: ndarray[tuple[Any, ...], dtype[complex128]], S0: ndarray[tuple[Any, ...], dtype[complex128]], pv: ndarray[tuple[Any, ...], dtype[int64]], i_u_vm: ndarray[tuple[Any, ...], dtype[int64]], i_k_q: ndarray[tuple[Any, ...], dtype[int64]], Qmin: ndarray[tuple[Any, ...], dtype[float64]], Qmax: ndarray[tuple[Any, ...], dtype[float64]])[source]

Control of reactive power within the numerical method Assume we only want to change regular PV buses to PQ buses (as in the conventional method) :param Scalc: Calculated power array (changed inside) :param S0: Specified power array (changed inside) :param pv: array of pv bus indices (changed inside) :param i_u_vm: array of buses with unknown Vm (changed inside) :param i_k_q: array of buses with known Q (changed inside) :param Qmin: Array of lower bus reactive power limits per bus in p.u. :param Qmax: Array of upper bus reactive power limits per bus in p.u. :return: list of changed buses, i_u_vm, i_k_q

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.discrete_controls.control_q_inside_method(Scalc: ndarray[tuple[Any, ...], dtype[complex128]], S0: ndarray[tuple[Any, ...], dtype[complex128]], pv: ndarray[tuple[Any, ...], dtype[int64]], pq: ndarray[tuple[Any, ...], dtype[int64]], pqv: ndarray[tuple[Any, ...], dtype[int64]], p: ndarray[tuple[Any, ...], dtype[int64]], Qmin: ndarray[tuple[Any, ...], dtype[float64]], Qmax: ndarray[tuple[Any, ...], dtype[float64]])[source]

Control of reactive power within the numerical method :param Scalc: Calculated power array (changed inside) :param S0: Specified power array (changed inside) :param pv: array of pv bus indices (changed inside) :param pq: array of pq bus indices (changed inside) :param pqv: array of pqv bus indices (changed inside) :param p: array of p bus indices (changed inside) :param Qmin: Array of lower reactive power limits per bus in p.u. :param Qmax: Array of upper reactive power limits per bus in p.u. :return: any change?, Scalc, Sbus, pv, pq, pqv, p

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.discrete_controls.get_q_increment(V1, V2, k)[source]

Logistic function to get the Q increment gain using the difference between the current voltage (V1) and the target voltage (V2).

The gain varies between 0 (at V1 = V2) and inf (at V2 - V1 = inf).

The default steepness factor k was set through trial an error. Other values may be specified as a PowerFlowOptions.

Arguments:

V1 (float): Current voltage

V2 (float): Target voltage

k (float, 30): Steepness factor

Returns:

Q increment gain

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.discrete_controls.update_qv_droop_generators(S0: ndarray[tuple[Any, ...], dtype[complex128]], Q0: ndarray[tuple[Any, ...], dtype[float64]], generator_q: ndarray[tuple[Any, ...], dtype[float64]], qv_droop_bus_idx: ndarray[tuple[Any, ...], dtype[int64]], qv_droop_gen_idx: ndarray[tuple[Any, ...], dtype[int64]], generator_bus_idx: ndarray[tuple[Any, ...], dtype[int64]], generator_k_droop: ndarray[tuple[Any, ...], dtype[float64]], generator_dead_band: ndarray[tuple[Any, ...], dtype[float64]], generator_v: ndarray[tuple[Any, ...], dtype[float64]], generator_qmin: ndarray[tuple[Any, ...], dtype[float64]], generator_qmax: ndarray[tuple[Any, ...], dtype[float64]], Vm: ndarray[tuple[Any, ...], dtype[float64]]) → bool[source]

Update generators with QV droop control within the numerical method. :param S0: Specified power array (changed inside). :param Q0: Initial specified reactive power per bus. :param generator_q: Reactive power per generator (changed inside). :param qv_droop_bus_idx: Buses hosting QV droop generators. :param qv_droop_gen_idx: Generator indices with QV droop control. :param generator_bus_idx: Generator-to-bus map. :param generator_k_droop: Generator droop gain. :param generator_dead_band: Generator dead-band. :param generator_v: Generator voltage set point. :param generator_qmax: Generator reactive power upper limit (p.u.). :param generator_qmin: Generator reactive power lower limit (p.u.). :param Vm: Voltage module array. :return: Was there any change?

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.fast_decoupled module

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.fast_decoupled.FDPF(nc: NumericalCircuit, Vbus: ndarray[tuple[Any, ...], dtype[complex128]], S0: ndarray[tuple[Any, ...], dtype[complex128]], I0: ndarray[tuple[Any, ...], dtype[complex128]], Y0: ndarray[tuple[Any, ...], dtype[complex128]], Ybus: csc_matrix, Yf: csc_matrix, Yt: csc_matrix, Yshunt_bus: ndarray[tuple[Any, ...], dtype[complex128]], B1: csc_matrix, B2: csc_matrix, pv_: ndarray[tuple[Any, ...], dtype[int64]], pq_: ndarray[tuple[Any, ...], dtype[int64]], pqv_: ndarray[tuple[Any, ...], dtype[int64]], p_: ndarray[tuple[Any, ...], dtype[int64]], vd_: ndarray[tuple[Any, ...], dtype[int64]], Qmin: ndarray[tuple[Any, ...], dtype[float64]], Qmax: ndarray[tuple[Any, ...], dtype[float64]], bus_installed_power: ndarray[tuple[Any, ...], dtype[float64]], tol: float = 1e-09, max_it: float = 100, control_q: bool = False, distribute_slack: bool = False) → NumericPowerFlowResults[source]

Fast decoupled power flow :param nc: NumericalCircuit instance :param Vbus: array of initial voltages :param S0: array of power Injections :param I0: array of current Injections :param Y0: array of admittance Injections :param Ybus: Admittance matrix :param Yf: Admittance from matrix :param Yt: Admittance to matrix :param Yshunt_bus: Array of shunts to add to the diagonal (from shunt devices) :param B1: B’ matrix for the fast decoupled algorithm :param B2: B’’ matrix for the fast decoupled algorithm :param pv_: Array with the indices of the PV buses :param pq_: Array with the indices of the PQ buses :param pqv_: Array with the indices of the PQV buses :param p_: Array with the indices of the P buses :param vd_: Array with the indices of the VD buses :param Qmin: Minimum voltage :param Qmax: Maximum voltage :param tol: Tolerance :param bus_installed_power: Array of installed power per bus :param max_it: maximum number of iterations :param control_q: Control Q method :param distribute_slack: Distribute Slack method :return: NumericPowerFlowResults instance

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.gauss_power_flow module

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.gauss_power_flow.gausspf(nc: NumericalCircuit, Ybus: csc_matrix, Yf: csc_matrix, Yt: csc_matrix, Yshunt_bus: ndarray[tuple[Any, ...], dtype[complex128]], S0: ndarray[tuple[Any, ...], dtype[complex128]], I0: ndarray[tuple[Any, ...], dtype[complex128]], Y0: ndarray[tuple[Any, ...], dtype[complex128]], V0: ndarray[tuple[Any, ...], dtype[complex128]], pv: ndarray[tuple[Any, ...], dtype[int64]], pq: ndarray[tuple[Any, ...], dtype[int64]], p: ndarray[tuple[Any, ...], dtype[int64]], pqv: ndarray[tuple[Any, ...], dtype[int64]], vd: ndarray[tuple[Any, ...], dtype[int64]], bus_installed_power: ndarray[tuple[Any, ...], dtype[float64]], Qmin: ndarray[tuple[Any, ...], dtype[float64]], Qmax: ndarray[tuple[Any, ...], dtype[float64]], tol=0.001, max_it=50, control_q=False, distribute_slack=False, verbose=False, logger: Logger = None) → NumericPowerFlowResults[source]

Gauss-Seidel Power flow :param nc: NumericalCircuit :param Ybus: Admittance matrix :param Yf: Admittance from matrix :param Yt: Admittance to matrix :param Yshunt_bus: Vector of admittance due to devices :param S0: Power Injections array :param I0: Current Injections array :param Y0: Admittance Injections array :param V0: Voltage seed solution array :param pv: array of pv-node indices :param pq: array of pq-node indices :param p: array of p-node indices :param pqv: array of pqv-node indices :param vd: array of vd-node indices :param bus_installed_power: array of bus installed power :param Qmin: Minimum Q limits per bus :param Qmax: Maximum Q limits per bus :param tol: Tolerance :param max_it: Maximum number of iterations :param control_q: Control Q limits? :param distribute_slack: Distribute Slack? :param verbose: Verbose? :param logger: Logger to store the debug information :return: NumericPowerFlowResults instance

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr module

DPRHEM power-flow solver.

This module implements VeraGrid’s Dynamic Power Restart HELM variant and the remote-voltage PVQ/P extension. The comments in the coefficient code refer to these two papers:

The important modelling rule is that every DPR segment solves one fixed algebraic model. Discrete controls are therefore applied only between fixed-model DPR solves, never inside a coefficient recurrence.

class VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.DprAdmittanceControlView(Ybus: csc_matrix, Yshunt_bus: ndarray[tuple[Any, ...], dtype[complex128]])[source]

Bases: object

Hold the admittance references that discrete shunt control mutates.

The existing shunt-control wrapper only needs Ybus and Yshunt_bus. DPRHEM receives those as raw arguments, so this small view lets the control code update the active matrices without moving the outer control loop back to the worker.

Ybus: csc_matrix
Yshunt_bus: ndarray[tuple[Any, ...], dtype[complex128]]
class VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.DprCoefficientPath(U: ndarray, X: ndarray, Q: ndarray, V: ndarray[tuple[Any, ...], dtype[complex128]], iterations: int, converged: bool, segments: list[DprSegmentResult])[source]

Bases: object

Result of a DPRHEM coefficient solve with the accepted restart path.

Parameters:

  • U – Last segment voltage coefficients in reduced no-slack coordinates.

  • X – Last segment reciprocal-conjugate voltage coefficients in reduced no-slack coordinates.

  • Q – Last segment reactive-power coefficients in reduced no-slack coordinates.

  • V – Final full voltage vector.

  • iterations – Total coefficient orders consumed by the fixed-model solve.

  • converged – True if the final voltage satisfies the requested tolerance.

  • segments – Accepted DPRHEM segments for this fixed algebraic model.

Q: ndarray
U: ndarray
V: ndarray[tuple[Any, ...], dtype[complex128]]
X: ndarray
converged: bool
iterations: int
segments: list[DprSegmentResult]
class VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.DprSegmentResult(U: ndarray, X: ndarray, Q: ndarray, V: ndarray[tuple[Any, ...], dtype[complex128]], iterations: int, norm_f: float, converged: bool, improved: bool)[source]

Bases: object

Result of one DPRHEM segment.

Parameters:

  • U – Voltage coefficients in reduced no-slack coordinates.

  • X – Reciprocal-conjugate voltage coefficients in reduced no-slack coordinates.

  • Q – PV reactive power coefficients in reduced no-slack coordinates.

  • V – Full voltage vector selected as the segment output.

  • iterations – Number of computed/accepted coefficient orders.

  • norm_f – Power-flow mismatch norm of V.

  • converged – True if norm_f satisfies the requested tolerance.

  • improved – True if the segment found a better voltage than its input germ.

Q: ndarray
U: ndarray
V: ndarray[tuple[Any, ...], dtype[complex128]]
X: ndarray
converged: bool
improved: bool
iterations: int
norm_f: float
VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.conv1(A, B, c)[source]

Performs the convolution of A* and B

DPRHEM keeps the reciprocal-conjugate series X(s) = 1 / conj(U(s)) used by HELM. This convolution forms the lower-order part of conj(U) * X; the current-order term is handled explicitly after solving U[c].

Parameters:

  • A – Coefficients matrix 1 (orders, buses)

  • B – Coefficients matrix 2 (orders, buses)

  • c – order of the coefficients

Returns:

Array with the convolution for the buses given by β€œindices”

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.conv2(A, B, c, indices)[source]

Performs the convolution of A and B

This is used in the PV and remote P recurrences for the already-known part of X(s) * Q(s). The current-order unknown reactive coefficient is placed as a matrix unknown instead of being included in this convolution.

Parameters:

  • A – Coefficients matrix 1 (orders, buses)

  • B – Coefficients matrix 2 (orders, buses)

  • c – order of the coefficients

  • indices – bus indices array

Returns:

Array with the convolution for the buses given by β€œindices”

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.conv3(A, B, c, indices)[source]

Performs the convolution of A and B*

This supports the voltage-magnitude equations from conventional PV HELM and from the remote-voltage paper’s PVQ buses. The matrix contains the current-order linear terms; this helper returns only lower-order products.

Parameters:

  • A – Coefficients matrix 1 (orders, buses)

  • B – Coefficients matrix 2 (orders, buses)

  • c – order of the coefficients

  • indices – bus indices array

Returns:

Array with the convolution for the buses given by β€œindices”

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.dpr_angle_guard(V: ndarray[tuple[Any, ...], dtype[complex128]], sl: ndarray[tuple[Any, ...], dtype[int64]], no_slack: ndarray[tuple[Any, ...], dtype[int64]]) → bool[source]

Apply the DPRHEM voltage-angle physical-branch guard.

Parameters:

  • V – Full voltage vector to test.

  • sl – Slack bus indices.

  • no_slack – Non-slack bus indices.

Returns:

True if all non-slack voltage angles are within +/- 90 degrees of the slack angle.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.dpr_build_matrix(Yred: csc_matrix, Ysh: ndarray[tuple[Any, ...], dtype[complex128]], U0: ndarray[tuple[Any, ...], dtype[complex128]], Sini_rhs: ndarray[tuple[Any, ...], dtype[complex128]], pv: ndarray[tuple[Any, ...], dtype[int64]], pqv: ndarray[tuple[Any, ...], dtype[int64]], p: ndarray[tuple[Any, ...], dtype[int64]], npv: int, npqv: int, np_control_q: int, npqpv: int) → csc_matrix[source]

Build the real sparse DPRHEM segment matrix.

The copied base HELM matrix is modified according to the paper’s shifted-germ model: the initial physical power state Sini introduces a diagonal term multiplying conj(U[n]). The right-hand side then carries only lower-order terms and the direction power S_target - Sini.

Parameters:

  • Yred – Reduced series admittance matrix.

  • Ysh – Reduced shunt admittance vector.

  • U0 – Segment voltage germ in reduced coordinates.

  • Sini_rhs – Conjugated initial complex power in reduced coordinates.

  • pv – Reduced PV bus indices.

  • pqv – Reduced PVQ bus indices.

  • p – Reduced P bus indices.

  • npv – Number of PV buses.

  • npqv – Number of PVQ buses.

  • np_control_q – Number of controlled reactive power unknowns.

  • npqpv – Number of non-slack buses.

Returns:

Real sparse CSC matrix.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.dpr_classical_no_load_germ(Yseries: csc_matrix, Vset: ndarray[tuple[Any, ...], dtype[complex128]], sl: ndarray[tuple[Any, ...], dtype[int64]], no_slack: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]]) → ndarray[tuple[Any, ...], dtype[complex128]][source]

Build the flat classical HELM germ used when no voltage estimate is supplied.

The DPRHEM paper compares against a classical HELM-like flat start. For VeraGrid integration the normal path uses use_classical_germ=False so stored/user voltage guesses can seed the first DPR segment.

Parameters:

  • Yseries – Series admittance matrix kept for interface symmetry with the shifted-germ path.

  • Vset – Voltage set-point vector.

  • sl – Slack bus indices.

  • no_slack – Non-slack bus indices.

  • pv – PV bus indices kept for interface symmetry.

Returns:

Safe full voltage germ.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.dpr_known_inverse_voltage_coefficient(U: ndarray, X: ndarray, order: int) → ndarray[source]

Compute the known part of X[order] before U[order] is solved.

The copied base HELM formulation uses X(s) = 1 / conj(U(s)). At a given order, the part containing conj(U[order]) is moved to the left-hand side of the DPRHEM matrix. This function returns the remaining lower-order convolution.

Parameters:

  • U – Voltage coefficients.

  • X – Reciprocal-conjugate voltage coefficients.

  • order – Coefficient order being solved.

Returns:

Known lower-order contribution to X[order].

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.dpr_power_mismatch(Ybus: csc_matrix, V: ndarray[tuple[Any, ...], dtype[complex128]], S0: ndarray[tuple[Any, ...], dtype[complex128]], no_slack: ndarray[tuple[Any, ...], dtype[int64]], pq: ndarray[tuple[Any, ...], dtype[int64]], pqv: ndarray[tuple[Any, ...], dtype[int64]], Vset: ndarray[tuple[Any, ...], dtype[complex128]]) → float[source]

Compute the VeraGrid power-flow mismatch norm.

Parameters:

  • Ybus – Complete admittance matrix.

  • V – Full voltage vector.

  • S0 – Specified complex bus powers.

  • no_slack – Original non-slack bus indices.

  • pq – Original PQ bus indices.

  • pqv – Original remote-voltage controlled bus indices.

  • Vset – Voltage set-point vector.

Returns:

Power-flow mismatch norm.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.dpr_reduced_bus_indices(no_slack: ndarray[tuple[Any, ...], dtype[int64]], pq: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]], pqv: ndarray[tuple[Any, ...], dtype[int64]], p: ndarray[tuple[Any, ...], dtype[int64]]) → tuple[ndarray[tuple[Any, ...], dtype[int64]], ndarray[tuple[Any, ...], dtype[int64]], ndarray[tuple[Any, ...], dtype[int64]], ndarray[tuple[Any, ...], dtype[int64]], ndarray[tuple[Any, ...], dtype[int64]]][source]

Convert original bus indices into the reduced no-slack indexing used by HELM.

Parameters:

  • no_slack – Original non-slack bus indices.

  • pq – Original PQ bus indices.

  • pv – Original PV bus indices.

  • pqv – Original PQV bus indices.

  • p – Original P bus indices.

Returns:

Reduced PQ, PV, PQV and P indices, plus original sorted non-slack indices.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.dpr_residual_ratio(previous_norm: float, candidate_norm: float, tolerance: float) → float[source]

Compute the residual-ratio indicator used by the DPRHEM restart rule.

Parameters:

  • previous_norm – Previous order mismatch norm.

  • candidate_norm – Current order mismatch norm.

  • tolerance – Target mismatch tolerance.

Returns:

Residual-ratio value.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.dpr_safe_voltage_germ(V: ndarray[tuple[Any, ...], dtype[complex128]], no_slack: ndarray[tuple[Any, ...], dtype[int64]]) → ndarray[tuple[Any, ...], dtype[complex128]][source]

Make a voltage germ safe for reciprocal-voltage calculations.

Parameters:

  • V – Full voltage vector candidate.

  • no_slack – Original non-slack bus indices.

Returns:

Full voltage vector with non-zero non-slack entries.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.dpr_select_candidate(Ybus: csc_matrix, Vgerm: ndarray[tuple[Any, ...], dtype[complex128]], Vset: ndarray[tuple[Any, ...], dtype[complex128]], U: ndarray, order: int, sl: ndarray[tuple[Any, ...], dtype[int64]], no_slack: ndarray[tuple[Any, ...], dtype[int64]], pqpv_original: ndarray[tuple[Any, ...], dtype[int64]], S0: ndarray[tuple[Any, ...], dtype[complex128]], pq: ndarray[tuple[Any, ...], dtype[int64]], pqv: ndarray[tuple[Any, ...], dtype[int64]]) → tuple[ndarray[tuple[Any, ...], dtype[complex128]], float, bool][source]

Select the best valid truncated segment voltage.

The paper evaluates at s = 1. The extra smaller scales are a guarded fallback for VeraGrid’s very large PEGASE cases where the local segment radius is visibly below one; the selected state is still restarted through the same paper power-space update.

Parameters:

  • Ybus – Complete admittance matrix.

  • Vgerm – Full segment voltage germ.

  • Vset – Full voltage set-point vector.

  • U – Voltage coefficients.

  • order – Highest available coefficient order.

  • sl – Slack bus indices.

  • no_slack – Non-slack bus indices.

  • pqpv_original – Original sorted non-slack bus indices.

  • S0 – Specified power target.

  • pq – Original PQ bus indices.

  • pqv – Original PVQ bus indices.

Returns:

Candidate voltage, mismatch norm and validity flag.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.dpr_solve_segment(Ybus: csc_matrix, Yseries: csc_matrix, Vgerm: ndarray[tuple[Any, ...], dtype[complex128]], Vset: ndarray[tuple[Any, ...], dtype[complex128]], S0: ndarray[tuple[Any, ...], dtype[complex128]], Ysh0: ndarray[tuple[Any, ...], dtype[complex128]], pq: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]], pqv: ndarray[tuple[Any, ...], dtype[int64]], p: ndarray[tuple[Any, ...], dtype[int64]], sl: ndarray[tuple[Any, ...], dtype[int64]], no_slack: ndarray[tuple[Any, ...], dtype[int64]], pq_reduced: ndarray[tuple[Any, ...], dtype[int64]], pv_reduced: ndarray[tuple[Any, ...], dtype[int64]], pqv_reduced: ndarray[tuple[Any, ...], dtype[int64]], p_reduced: ndarray[tuple[Any, ...], dtype[int64]], pqpv_original: ndarray[tuple[Any, ...], dtype[int64]], tolerance: float, max_order: int, current_norm: float, allow_dynamic_restart: bool = True) → DprSegmentResult[source]

Solve one DPRHEM shifted-germ segment.

Parameters:

  • Ybus – Complete admittance matrix.

  • Yseries – Series-only admittance matrix.

  • Vgerm – Full voltage germ for this segment.

  • Vset – Voltage set-point vector.

  • S0 – Specified complex target powers.

  • Ysh0 – Bus shunt admittance vector.

  • pq – Original PQ bus indices.

  • pv – Original PV bus indices.

  • pqv – Original PVQ bus indices.

  • p – Original P bus indices.

  • sl – Slack bus indices.

  • no_slack – Original non-slack bus indices.

  • pq_reduced – Reduced PQ bus indices.

  • pv_reduced – Reduced PV bus indices.

  • pqv_reduced – Reduced PVQ bus indices.

  • p_reduced – Reduced P bus indices.

  • pqpv_original – Original sorted non-slack bus indices.

  • tolerance – Target mismatch tolerance.

  • max_order – Maximum coefficient order for this segment.

  • current_norm – Mismatch norm at the germ.

  • allow_dynamic_restart – Stop early when the DPR residual-ratio rule asks for a restart.

Returns:

Segment result.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.dpr_voltage_is_valid(V: ndarray[tuple[Any, ...], dtype[complex128]]) → bool[source]

Check that a DPR voltage candidate is numerically usable.

Parameters:

V – Full voltage vector candidate.

Returns:

True if the voltage can safely be used in sparse nonlinear calculations.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.helm_coefficients_dpr(Ybus: csc_matrix, Yseries: csc_matrix, V0: ndarray[tuple[Any, ...], dtype[complex128]] | None, Vset: ndarray[tuple[Any, ...], dtype[complex128]], S0: ndarray[tuple[Any, ...], dtype[complex128]], Ysh0: ndarray[tuple[Any, ...], dtype[complex128]], pq: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]], pqv: ndarray[tuple[Any, ...], dtype[int64]], p: ndarray[tuple[Any, ...], dtype[int64]], sl: ndarray[tuple[Any, ...], dtype[int64]], no_slack: ndarray[tuple[Any, ...], dtype[int64]], tolerance: float = 1e-06, max_coeff: int = 30, restart_order: int = 6, max_restarts: int = 20, use_classical_germ: bool = False, allow_dynamic_restart: bool = True, verbose: bool = False, logger: Logger = None) → tuple[ndarray, ndarray, ndarray, ndarray[tuple[Any, ...], dtype[complex128]], int, bool][source]

Compute DPRHEM coefficients and final voltage state.

This keeps the original tuple-returning interface. Use helm_coefficients_dpr_path() when the accepted DPR restart segments are needed, for example by DPR sigma analysis.

Parameters:

  • Ybus – Complete admittance matrix.

  • Yseries – Series-only admittance matrix.

  • V0 – Voltage estimate/set-point vector.

  • Vset – Voltage set-point vector.

  • S0 – Specified complex bus powers.

  • Ysh0 – Bus shunt admittance vector.

  • pq – Original PQ bus indices.

  • pv – Original PV bus indices.

  • pqv – Original PVQ bus indices.

  • p – Original P bus indices.

  • sl – Slack bus indices.

  • no_slack – Original non-slack bus indices.

  • tolerance – Target mismatch tolerance.

  • max_coeff – Total coefficient budget across restarts.

  • restart_order – Maximum coefficient order per segment.

  • max_restarts – Maximum number of DPRHEM restarts.

  • use_classical_germ – Use the classical no-load germ instead of the supplied voltage estimate.

  • allow_dynamic_restart – Let the residual-ratio rule truncate a segment and restart from its best voltage.

  • verbose – Store debug information.

  • logger – Logger object.

Returns:

Last segment U, X, Q, final voltage, total iterations and convergence flag.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.helm_coefficients_dpr_path(Ybus: csc_matrix, Yseries: csc_matrix, V0: ndarray[tuple[Any, ...], dtype[complex128]] | None, Vset: ndarray[tuple[Any, ...], dtype[complex128]], S0: ndarray[tuple[Any, ...], dtype[complex128]], Ysh0: ndarray[tuple[Any, ...], dtype[complex128]], pq: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]], pqv: ndarray[tuple[Any, ...], dtype[int64]], p: ndarray[tuple[Any, ...], dtype[int64]], sl: ndarray[tuple[Any, ...], dtype[int64]], no_slack: ndarray[tuple[Any, ...], dtype[int64]], tolerance: float = 1e-06, max_coeff: int = 30, restart_order: int = 6, max_restarts: int = 20, use_classical_germ: bool = False, allow_dynamic_restart: bool = True, verbose: bool = False, logger: Logger = None) → DprCoefficientPath[source]

Compute DPRHEM coefficients, final voltage state and accepted restart path.

Parameters:

  • Ybus – Complete admittance matrix.

  • Yseries – Series-only admittance matrix.

  • V0 – Voltage estimate/set-point vector.

  • S0 – Specified complex bus powers.

  • Ysh0 – Bus shunt admittance vector.

  • pq – Original PQ bus indices.

  • pv – Original PV bus indices.

  • pqv – Original PVQ bus indices.

  • p – Original P bus indices.

  • sl – Slack bus indices.

  • no_slack – Original non-slack bus indices.

  • tolerance – Target mismatch tolerance.

  • max_coeff – Total coefficient budget across restarts.

  • restart_order – Maximum coefficient order per segment.

  • max_restarts – Maximum number of DPRHEM restarts.

  • use_classical_germ – Use the classical no-load germ instead of the supplied voltage estimate.

  • allow_dynamic_restart – Let the residual-ratio rule truncate a segment and restart from its best voltage.

  • verbose – Store debug information.

  • logger – Logger object.

Returns:

DPRHEM coefficient path for one fixed algebraic model.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.helm_dpr(nc: NumericalCircuit, Ybus: csc_matrix, Yf: csc_matrix, Yt: csc_matrix, Yshunt_bus: ndarray[tuple[Any, ...], dtype[complex128]], Yseries: csc_matrix, V0: ndarray[tuple[Any, ...], dtype[complex128]] | None, S0: ndarray[tuple[Any, ...], dtype[complex128]], Ysh0: ndarray[tuple[Any, ...], dtype[complex128]], pq: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]], vd: ndarray[tuple[Any, ...], dtype[int64]], no_slack: ndarray[tuple[Any, ...], dtype[int64]], pqv: ndarray[tuple[Any, ...], dtype[int64]] | None = None, p: ndarray[tuple[Any, ...], dtype[int64]] | None = None, tolerance: float = 1e-06, max_coefficients: int = 30, use_pade: bool = True, restart_order: int = 6, max_restarts: int = 20, use_classical_germ: bool = False, control_q: bool = False, Qmin: ndarray[tuple[Any, ...], dtype[float64]] | None = None, Qmax: ndarray[tuple[Any, ...], dtype[float64]] | None = None, control_discrete_shunts: bool = False, control_qv_droop: bool = False, distributed_slack: bool = False, bus_installed_power: ndarray[tuple[Any, ...], dtype[float64]] | None = None, controls_tol: float = 0.001, max_control_restarts: int = 3, verbose: int = 0, logger: Logger = None) → NumericPowerFlowResults[source]

Solve power flow with DPRHEM and apply discrete controls at DPR restart boundaries.

Parameters:

  • nc – Numerical circuit island.

  • Ybus – Complete admittance matrix.

  • Yf – Branch-from admittance matrix.

  • Yt – Branch-to admittance matrix.

  • Yshunt_bus – Bus shunt admittance vector.

  • Yseries – Series-only admittance matrix.

  • V0 – Voltage estimate/set-point vector.

  • S0 – Specified complex bus powers in p.u.

  • Ysh0 – Bus shunt admittance vector including branch shunt legs.

  • pq – PQ bus indices.

  • pv – PV bus indices.

  • vd – Slack bus indices.

  • no_slack – Sorted PQ/PV bus indices.

  • tolerance – Target mismatch tolerance.

  • max_coefficients – Total coefficient budget for each fixed-control DPR solve.

  • use_pade – Kept for interface compatibility; restarts use direct summation.

  • restart_order – Maximum coefficient order per DPR segment.

  • max_restarts – Maximum DPR restart count for each fixed-control solve.

  • use_classical_germ – Use the classical flat germ instead of the supplied voltage estimate.

  • control_q – Apply PV-to-PQ reactive limit control at accepted DPR states.

  • pqv – PQV bus indices used by the Q-limit control.

  • p – P bus indices used by the Q-limit control.

  • Qmin – Minimum reactive power limits in p.u.

  • Qmax – Maximum reactive power limits in p.u.

  • control_discrete_shunts – Apply discrete shunt controls at accepted DPR states.

  • control_qv_droop – Apply generator QV droop controls at accepted DPR states.

  • distributed_slack – Apply one distributed slack correction at an accepted DPR state.

  • bus_installed_power – Installed power per bus for distributed slack participation.

  • controls_tol – Residual threshold below which discrete controls are trusted.

  • max_control_restarts – Maximum outer restarts caused by controls.

  • verbose – Verbosity flag.

  • logger – Logger object.

Returns:

Numeric power-flow results.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.helm_dpr_fixed_model(nc: NumericalCircuit, Ybus: csc_matrix, Yf: csc_matrix, Yt: csc_matrix, Yshunt_bus: ndarray[tuple[Any, ...], dtype[complex128]], Yseries: csc_matrix, V0: ndarray[tuple[Any, ...], dtype[complex128]] | None, S0: ndarray[tuple[Any, ...], dtype[complex128]], Ysh0: ndarray[tuple[Any, ...], dtype[complex128]], pq: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]], vd: ndarray[tuple[Any, ...], dtype[int64]], no_slack: ndarray[tuple[Any, ...], dtype[int64]], pqv: ndarray[tuple[Any, ...], dtype[int64]] | None = None, p: ndarray[tuple[Any, ...], dtype[int64]] | None = None, tolerance: float = 1e-06, max_coefficients: int = 30, use_pade: bool = True, restart_order: int = 6, max_restarts: int = 20, use_classical_germ: bool = False, verbose: int = 0, logger: Logger = None) → NumericPowerFlowResults[source]

Solve one fixed-control power flow model with the DPRHEM variant in this module.

Parameters:

  • nc – Numerical circuit island.

  • Ybus – Complete admittance matrix.

  • Yf – Branch-from admittance matrix.

  • Yt – Branch-to admittance matrix.

  • Yshunt_bus – Bus shunt admittance vector.

  • Yseries – Series-only admittance matrix.

  • V0 – Voltage estimate/set-point vector.

  • S0 – Specified complex bus powers.

  • Ysh0 – Bus shunt admittance vector including branch shunt legs.

  • pq – PQ bus indices.

  • pv – PV bus indices.

  • vd – Slack bus indices.

  • no_slack – Sorted PQ/PV bus indices.

  • pqv – PVQ bus indices.

  • p – P bus indices.

  • tolerance – Target mismatch tolerance.

  • max_coefficients – Total coefficient budget.

  • use_pade – Kept for interface compatibility; restarts use direct summation.

  • restart_order – Maximum coefficient order per segment.

  • max_restarts – Maximum restart count.

  • use_classical_germ – Use the classical no-load germ instead of the supplied voltage estimate.

  • verbose – Verbosity flag.

  • logger – Logger object.

Returns:

Numeric power-flow results for the fixed model.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_dpr.pade4all(order, coeff_mat, s=1.0)[source]

Computes the β€œorder” PadΓ¨ approximant of the coefficients at the approximation point s

In DPRHEM this is only a local segment accelerator. It is not used to build one global PadΓ© approximation across restart boundaries because each restart changes the expansion center.

Arguments:

coeff_mat: coefficient matrix (order, buses) order: order of the series s: point of approximation (at 1 you get the voltage)

Returns:

Padè approximation at s for all the series

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow module

class VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow.HelmPreparation[source]

Bases: object

Uini
Vslack
Xini
Ysh
Yslack
nbus
npqpv
pq
pq_original
pqpv
pqpv_original
pv
sl
sys_mat_factorization
vec_P
vec_Q
vec_W
VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow.conv1(A, B, c)[source]

Performs the convolution of A* and B :param A: Coefficients matrix 1 (orders, buses) :param B: Coefficients matrix 2 (orders, buses) :param c: order of the coefficients :return: Array with the convolution for the buses given by β€œindices”

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow.conv1_old(A, B, c, indices)[source]

Performs the convolution of A* and B :param A: Coefficients matrix 1 (orders, buses) :param B: Coefficients matrix 2 (orders, buses) :param c: order of the coefficients :param indices: bus indices array :return: Array with the convolution for the buses given by β€œindices”

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow.conv2(A, B, c, indices)[source]

Performs the convolution of A and B :param A: Coefficients matrix 1 (orders, buses) :param B: Coefficients matrix 2 (orders, buses) :param c: order of the coefficients :param indices: bus indices array :return: Array with the convolution for the buses given by β€œindices”

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow.conv3(A, B, c, indices)[source]

Performs the convolution of A and B* :param A: Coefficients matrix 1 (orders, buses) :param B: Coefficients matrix 2 (orders, buses) :param c: order of the coefficients :param indices: bus indices array :return: Array with the convolution for the buses given by β€œindices”

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow.epsilon(Sn, n, E)[source]
Fast recursive Wynn’s epsilon algorithm from:

NONLINEAR SEQUENCE TRANSFORMATIONS FOR THE ACCELERATION OF CONVERGENCE AND THE SUMMATION OF DIVERGENT SERIES

by Ernst Joachim Weniger

Args:

Sn: sum of coefficients n: order E: Coefficients structure copy that is modified in this algorithm

Returns:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow.helm_coefficients_dY(dY, sys_mat_factorization, Uini, Xini, Yslack, Ysh, Ybus, vec_P, vec_Q, S0, vec_W, V0, Vslack, pq, pv, pqpv, npqpv, nbus, sl, pqpv_original, pq_original, tolerance=1e-06, max_coeff=10)[source]

Holomorphic Embedding LoadFlow Method as formulated by Josep Fanals Batllori in 2020 This function just returns the coefficients for further usage in other routines

Based on the paper: Novel AC Distribution Factor for Efficient Outage Analysis

Rui Yao, Senior Member, IEEE, and Feng Qiu, Senior Member, IEEE

Parameters:

  • dY

  • sys_mat_factorization – factorized HELM system matrix

  • Uini

  • Xini

  • Yslack

  • Ysh

  • Ybus

  • vec_P

  • vec_Q

  • S0 – vector of specified power

  • vec_W

  • V0 – vector of specified voltages

  • Vslack

  • pq – reduced scheme list of pq nodes

  • pv – reduced scheme list of pv nodes

  • pqpv – reduced scheme list of pq|pv nodes

  • npqpv – number of pq and pv nodes

  • nbus – number of nodes

  • pqpv – sorted list of pq and pv nodes

:param pq:list of pq nodes :param sl: list of slack nodes :param pqpv_original: sorted list of pq and pv nodes in the original order, considering slack :param pq_original: list of pq nodes in the original order, considering slack :param tolerance: target error (or tolerance) :param max_coeff: maximum number of coefficients :return: U, V, iter_, norm_f

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow.helm_coefficients_josep(Ybus: csc_matrix, Yseries: csc_matrix, V0: ndarray[tuple[Any, ...], dtype[complex128]], S0: ndarray[tuple[Any, ...], dtype[complex128]], Ysh0: ndarray[tuple[Any, ...], dtype[complex128]], pq: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]], sl: ndarray[tuple[Any, ...], dtype[int64]], no_slack: ndarray[tuple[Any, ...], dtype[int64]], tolerance=1e-06, max_coeff=30, verbose=False, stop_if_too_bad=False, logger: Logger = None)[source]

Holomorphic Embedding LoadFlow Method as formulated by Josep Fanals Batllori in 2020 This function just returns the coefficients for further usage in other routines :param Ybus: Admittance matrix :param Yseries: Admittance matrix of the series elements :param V0: vector of specified voltages :param S0: vector of specified power :param Ysh0: vector of shunt admittances (including the shunts of the Branches) :param pq: list of pq nodes :param pv: list of pv nodes :param sl: list of slack nodes :param no_slack: sorted list of pq and pv nodes :param tolerance: target error (or tolerance) :param max_coeff: maximum number of coefficients :param verbose: print intermediate information :param stop_if_too_bad: stop when things go wrong :param logger: Logger object to store the debug info :return: U, X, Q, V, iterations

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow.helm_josep(nc: NumericalCircuit, Ybus: csc_matrix, Yf: csc_matrix, Yt: csc_matrix, Yshunt_bus: ndarray[tuple[Any, ...], dtype[complex128]], Yseries: csc_matrix, V0: ndarray[tuple[Any, ...], dtype[complex128]], S0: ndarray[tuple[Any, ...], dtype[complex128]], Ysh0: ndarray[tuple[Any, ...], dtype[complex128]], pq: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]], vd: ndarray[tuple[Any, ...], dtype[int64]], no_slack: ndarray[tuple[Any, ...], dtype[int64]], tolerance: float = 1e-06, max_coefficients: int = 30, use_pade: bool = True, verbose: int = 0, logger: Logger = None) → NumericPowerFlowResults[source]

Holomorphic Embedding LoadFlow Method as formulated by Josep Fanals Batllori in 2020 :param nc: NumericalCircuit :param Ybus: Complete admittance matrix :param Yf: admittance from matrix :param Yt: admittance to matrix :param Yseries: Admittance matrix of the series elements :param V0: vector of specified voltages :param S0: vector of specified power :param Ysh0: vector of shunt admittances (including the shunt β€œlegs” of the pi Branches) :param pq: list of pq nodes :param pv: list of pv nodes :param vd: list of slack nodes :param no_slack: sorted list of pq and pv nodes :param tolerance: target error (or tolerance) :param max_coefficients: maximum number of coefficients :param use_pade: Use the PadΓ¨ approximation? otherwise, a simple summation is done :param verbose: print intermediate information :param logger: Logger object to store the debug info :return: V, converged, norm_f, Scalc, iter_, elapsed

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow.helm_preparation_dY(Yseries, V0, S0, Ysh0, pq, pv, sl, pqpv, verbose: int = 0, logger: Logger | None = None) → HelmPreparation[source]

This function returns the constant objects to run many HELM simulations

Based on the paper: Novel AC Distribution Factor for Efficient Outage Analysis

Rui Yao, Senior Member, IEEE, and Feng Qiu, Senior Member, IEEE

Parameters:

  • Yseries – Admittance matrix of the series elements

  • V0 – vector of specified voltages

  • S0 – vector of specified power

  • Ysh0 – vector of shunt admittances (including the shunts of the Branches)

  • pq – list of pq nodes

  • pv – list of pv nodes

  • sl – list of slack nodes

  • pqpv – sorted list of pq and pv nodes

  • verbose – print intermediate information

  • logger – Logger object to store the debug info

Returns:

U, X, Q, V, iterations

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow.pade4all(order, coeff_mat, s=1.0)[source]

Computes the β€œorder” PadΓ¨ approximant of the coefficients at the approximation point s

Arguments:

coeff_mat: coefficient matrix (order, buses) order: order of the series s: point of approximation (at 1 you get the voltage)

Returns:

Padè approximation at s for all the series

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.helm_power_flow.sigma_function(coeff_matU, coeff_matX, order, V_slack)[source]
Parameters:

  • coeff_matU – array with voltage coefficients

  • coeff_matX – array with inverse conjugated voltage coefficients

  • order – should be prof - 1

  • V_slack – slack bus voltage vector. Must contain only 1 slack bus

Returns:

sigma complex value

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.iwamoto_newton_raphson module

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.iwamoto_newton_raphson.IwamotoNR(nc: NumericalCircuit, Ybus: csc_matrix, Yf: csc_matrix, Yt: csc_matrix, Yshunt_bus: ndarray[tuple[Any, ...], dtype[complex128]], S0: ndarray[tuple[Any, ...], dtype[complex128]], V0: ndarray[tuple[Any, ...], dtype[complex128]], I0: ndarray[tuple[Any, ...], dtype[complex128]], Y0: ndarray[tuple[Any, ...], dtype[complex128]], pv_: ndarray[tuple[Any, ...], dtype[int64]], pq_: ndarray[tuple[Any, ...], dtype[int64]], pqv_: ndarray[tuple[Any, ...], dtype[int64]], p_: ndarray[tuple[Any, ...], dtype[int64]], vd_: ndarray[tuple[Any, ...], dtype[int64]], Qmin: ndarray[tuple[Any, ...], dtype[float64]], Qmax: ndarray[tuple[Any, ...], dtype[float64]], tol: float, max_it: int = 15, control_q: bool = False, robust: bool = False, logger: Logger = None) → NumericPowerFlowResults[source]

Solves the power flow using a full Newton’s method with the Iwamoto optimal step factor. :param nc: NumericalCircuit instance :param Ybus: Admittance matrix :param Yf: Admittance from matrix :param Yt: Admittance to matrix :param S0: Array of nodal power Injections :param V0: Array of nodal voltages (initial solution) :param I0: Array of nodal current Injections :param Y0: Array of nodal admittance Injections :param pv_: Array with the indices of the PV buses :param pq_: Array with the indices of the PQ buses :param pqv_: Array with the indices of the PQV buses :param p_: Array with the indices of the P buses :param vd_: Array with the indices of the slack buses :param Qmin: Array of nodal minimum reactive power injections :param Qmax: Array of nodal maximum reactive power injections :param tol: Tolerance :param max_it: Maximum number of iterations :param control_q: Control reactive power? :param robust: use of the Iwamoto optimal step factor?. :param logger: Logger :return: Voltage solution, converged?, error, calculated power Injections

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.iwamoto_newton_raphson.mu(Ybus: csc_matrix, J: CSC, incS: ndarray[tuple[Any, ...], dtype[float64]], dV: ndarray[tuple[Any, ...], dtype[complex128]], dx: ndarray[tuple[Any, ...], dtype[float64]], block1_idx: ndarray[tuple[Any, ...], dtype[int64]], block2_idx: ndarray[tuple[Any, ...], dtype[int64]], block3_idx: ndarray[tuple[Any, ...], dtype[int64]])[source]

Calculate the Iwamoto acceleration parameter as described in: β€œA Load Flow Calculation Method for Ill-Conditioned Power Systems” by Iwamoto, S. and Tamura, Y.” :param Ybus: Admittance matrix :param J: Jacobian matrix :param incS: mismatch vector :param dV: voltage increment (in complex form) :param dx: solution vector as calculated dx = solve(J, incS) :param block1_idx: pv, pq, p, pqv :param block2_idx: pq, p :param block3_idx: pq, pqv :return: the Iwamoto’s optimal multiplier for ill conditioned systems

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.levenberg_marquadt_fx module

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.levenberg_marquadt_fx.levenberg_marquardt_fx(problem: PfFormulationTemplate, tol: float = 1e-06, max_iter: int = 10, verbose: int = 0, logger: Logger = <VeraGridEngine.basic_structures.Logger object>) → NumericPowerFlowResults[source]

Levenberg-Marquardt to solve:

min: error(f(x)) s.t.

f(x) = 0

From METHODS FOR NON-LINEAR LEAST SQUARES PROBLEMS by K. Madsen, H.B. Nielsen, O. Tingleff

Parameters:

  • problem – PfFormulationTemplate

  • tol – Error tolerance

  • max_iter – Maximum number of iterations

  • verbose – Display console information

  • logger – Logger instance

Returns:

ConvexMethodResult

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.linearized_power_flow module

class VeraGridEngine.Simulations.PowerFlow.NumericalMethods.linearized_power_flow.VscLinearModel(n_vsc: int)[source]

Bases: object

Linear (DC) representation of the VSC converters.

A converter moves power from its DC bus to its AC bus, and how much it moves is decided by its control mode, never by an impedance. Three behaviours cover every mode:

  • scheduled: it holds a P_dc or P_ac set point

  • droop (P-mode 3): it follows P = P0 + k Β· (theta_ctrl - theta_ac)

  • DC slack: it controls the DC voltage, so it has no schedule of its own and instead closes the power balance of its DC subgrid.

ctrl_bus: ndarray[tuple[Any, ...], dtype[int64]]
dc_island: ndarray[tuple[Any, ...], dtype[int64]]
is_dc_slack: ndarray[tuple[Any, ...], dtype[bool]]
is_droop: ndarray[tuple[Any, ...], dtype[bool]]
k_droop: ndarray[tuple[Any, ...], dtype[float64]]
p_set: ndarray[tuple[Any, ...], dtype[float64]]
VeraGridEngine.Simulations.PowerFlow.NumericalMethods.linearized_power_flow.acdc_lin_pf(nc: NumericalCircuit, Bbus: csc_matrix, Bf: csc_matrix, Gbus: csc_matrix, Gf: csc_matrix, ac: ndarray[tuple[Any, ...], dtype[int64]], dc: ndarray[tuple[Any, ...], dtype[int64]], vd: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]], S0: ndarray[tuple[Any, ...], dtype[complex128]], I0: ndarray[tuple[Any, ...], dtype[complex128]], Y0: ndarray[tuple[Any, ...], dtype[complex128]], V0: ndarray[tuple[Any, ...], dtype[complex128]], tau: ndarray[tuple[Any, ...], dtype[float64]]) → NumericPowerFlowResults[source]

Solves a linear-ACDC power flow. :param nc: :param Bbus: :param Bf: :param Gbus: :param Gf: :param ac: :param dc: :param vd: :param pv: :param S0: :param I0: :param Y0: :param V0: :param tau: :return:

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.linearized_power_flow.add_vsc_linear_terms(nc: NumericalCircuit, model: VscLinearModel, A: lil_matrix, pinned: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Add the converter behaviour to the linear (DC) power flow system.

Parameters:

  • nc – NumericalCircuit

  • model – VscLinearModel with the classification

  • A – system matrix being mounted, modified in place

  • pinned – per converter forced power in p.u., NaN where the converter is free. A droop converter is pinned once it reaches its rating.

Returns:

constant power injections caused by the converters, in p.u.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.linearized_power_flow.build_vsc_linear_model(nc: NumericalCircuit) → VscLinearModel[source]

Classify every converter for the linear power flow and label the DC subgrid it belongs to, so that the converter that fixes the DC voltage can later close that subgrid’s power balance.

Parameters:

nc – NumericalCircuit

Returns:

VscLinearModel

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.linearized_power_flow.compute_vsc_powers(nc: NumericalCircuit, model: VscLinearModel, va: ndarray[tuple[Any, ...], dtype[float64]], pinned: ndarray[tuple[Any, ...], dtype[float64]]) → ndarray[tuple[Any, ...], dtype[float64]][source]

Evaluate the power that every converter moves from its DC bus to its AC bus, given the solved bus angles.

Parameters:

  • nc – NumericalCircuit

  • model – VscLinearModel with the classification

  • va – solved bus angles in radians

  • pinned – per converter forced power in p.u., NaN where the converter is free

Returns:

converter powers in p.u.

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.linearized_power_flow.lacpf(nc: NumericalCircuit, Ybus: csc_matrix, Yf: csc_matrix, Yt: csc_matrix, Ys: csc_matrix, Yshunt_bus: ndarray[tuple[Any, ...], dtype[complex128]], S0: ndarray[tuple[Any, ...], dtype[complex128]], V0: ndarray[tuple[Any, ...], dtype[complex128]], pq: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]], vd: ndarray[tuple[Any, ...], dtype[int64]], logger: Logger) → NumericPowerFlowResults[source]

Linearized AC Load Flow

form the article:

Linearized AC Load Flow Applied to Analysis in Electric Power Systems

by: P. Rossoni, W. M da Rosa and E. A. Belati

Parameters:

  • nc – NumericalCircuit instance

  • Ybus – Admittance matrix

  • Yf – Admittance from matrix

  • Yt – Admittance to matrix

  • Ys – Admittance matrix of the series elements

  • Yshunt_bus – Admittance vector of the series elements per bus

  • S0 – Power Injections vector of all the nodes

  • V0 – Set voltages of all the nodes (used for the slack and PV nodes)

  • pq – list of indices of the pq nodes

  • pv – list of indices of the pv nodes

  • vd – Array with the indices of the slack buses

  • logger – Logger

Returns:

NumericPowerFlowResults

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.linearized_power_flow.linear_pf(nc: NumericalCircuit, Ybus: csc_matrix, Bpqpv: csc_matrix, Bref: csc_matrix, Bf: csc_matrix, S0: ndarray[tuple[Any, ...], dtype[complex128]], I0: ndarray[tuple[Any, ...], dtype[complex128]], Y0: ndarray[tuple[Any, ...], dtype[complex128]], V0: ndarray[tuple[Any, ...], dtype[complex128]], tau: ndarray[tuple[Any, ...], dtype[float64]], vd: ndarray[tuple[Any, ...], dtype[int64]], no_slack: ndarray[tuple[Any, ...], dtype[int64]], pq: ndarray[tuple[Any, ...], dtype[int64]], pv: ndarray[tuple[Any, ...], dtype[int64]]) → NumericPowerFlowResults[source]

Solves a linear-DC power flow. :param nc: NumericalCircuit instance :param Ybus: Normal circuit admittance matrix :param Bpqpv: Susceptance matrix reduced :param Bref: Susceptance matrix sliced for the slack node :param Bf: Susceptance matrix of the Branches to nodes (used to include the phase shifters) :param S0: Complex power Injections at all the nodes :param I0: Complex current Injections at all the nodes :param Y0: Complex admittance Injections at all the nodes :param V0: Array of complex seed voltage (it contains the ref voltages) :param tau: Array of branch angles :param vd: array of the indices of the slack nodes :param no_slack: array of the indices of the non-slack nodes :param pq: array of the indices of the pq nodes :param pv: array of the indices of the pv nodes :return: NumericPowerFlowResults instance

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.newton_raphson_fx module

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.newton_raphson_fx.newton_raphson_fx(problem: PfFormulationTemplate, tol: float = 1e-06, max_iter: int = 10, trust: float = 1.0, verbose: int = 0, logger: Logger = <VeraGridEngine.basic_structures.Logger object>) → NumericPowerFlowResults[source]

Newton-Raphson with Line search to solve:

min: error(g(x)) s.t.

g(x) = 0

Parameters:

  • problem – PfFormulationTemplate

  • tol – Error tolerance

  • max_iter – Maximum number of iterations

  • trust – trust amount in the derivative length correctness

  • verbose – Display console information

  • logger – Logger instance

Returns:

ConvexMethodResult

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.powell_fx module

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.powell_fx.compute_beta(a: ndarray[tuple[Any, ...], dtype[float64]], b: ndarray[tuple[Any, ...], dtype[float64]], delta: float)[source]

compute the beta parameter :param a: alpha + hsd :param b: hgn :param delta: trust region :return: beta value

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.powell_fx.compute_hdl(hgn: ndarray[tuple[Any, ...], dtype[float64]], hsd: ndarray[tuple[Any, ...], dtype[float64]], g: ndarray[tuple[Any, ...], dtype[float64]], alpha: float, delta: float, f_error: float) → Tuple[ndarray[tuple[Any, ...], dtype[float64]], float][source]

Compute the Hdl vector :param hgn: Hgn vector :param hsd: Hsd vector :param g: g vector :param alpha: alpha parameter :param delta: delta parameter (trust region size) :param f_error: error of the function top optimize :return: Hdl Vector, L(0) - L(hdl)

VeraGridEngine.Simulations.PowerFlow.NumericalMethods.powell_fx.powell_fx(problem: PfFormulationTemplate, tol: float = 1e-06, max_iter: int = 10, trust: float = 1.0, verbose: int = 0, logger: Logger = <VeraGridEngine.basic_structures.Logger object>) → NumericPowerFlowResults[source]

Powell’s Dog leg algorithm to solve:

min: error(f(x)) s.t.

f(x) = 0

From METHODS FOR NON-LINEAR LEAST SQUARES PROBLEMS by K. Madsen, H.B. Nielsen, O. Tingleff

Parameters:

  • problem – PfFormulationTemplate

  • tol – Error tolerance

  • max_iter – Maximum number of iterations

  • trust – trust amount in the derivative length correctness

  • verbose – Display console information

  • logger – Logger instance

Returns:

ConvexMethodResult

Module contents