Available powerflow algorithms

See also

Naming conventions: “solver” vs “algorithm” — explains the three distinct meanings of “solver” in lightsim2grid, how the AlgorithmType enum values are named, and the migration table from old names (KLU, SparseLU, DC, …) to the new canonical names.

Types of powerflow algorithms

LightSim2Grid supports five families of powerflow algorithms:

Gauss-Seidel: lightsim2grid.algorithm.GaussSeidelAlgo and lightsim2grid.algorithm.GaussSeidelSynchAlgo. Solve the AC powerflow using the iterative Gauss-Seidel method (see gausspf in MATPOWER).
DC approximation: solve the linearised (DC) power-flow equations using a direct sparse factorisation. Up to four linear-solver backends are available:
- lightsim2grid.algorithm.DC_SparseLU — Eigen SparseLU (always available)
- lightsim2grid.algorithm.DC_KLU — SuiteSparse KLU (when compiled with KLU)
- lightsim2grid.algorithm.DC_NICSLU — NICSLU (requires license + source build)
- lightsim2grid.algorithm.DC_CKTSO — CKTSO (requires license + source build)
Newton-Raphson (single slack): solves the full AC equations with a single slack bus. If multiple slack buses are present only the first is used; the others are treated as PV buses. Available with four linear-solver backends:
Newton-Raphson (distributed / multi-slack): solves the full AC equations with multiple slack buses. Available with four linear-solver backends:
Fast-Decoupled Powerflow (FDPF): the XB and BX variants of the fast-decoupled Newton-Raphson method. Available with four linear-solver backends each:

Warning

Algorithms based on NICSLU and CKTSO require a compilation from source. CKTSO algorithms are (for now) only tested on Linux.

Linear-solver diagnostics: `LinearSolverStats`

Every algorithm above is backed by a linear solver (SparseLU, KLU, NICSLU or CKTSO) whose analyze/factorize/refactorize/solve calls are counted and timed. Call get_linear_solver_stats() on a solver (e.g. env.backend._grid.get_solver().get_linear_solver_stats()) to get a lightsim2grid.algorithm.LinearSolverStats with:

nb_analyze / nb_factorize / nb_refactorize / nb_solve / nb_reset: how many times each was called. These accumulate over the whole lifetime of the solver object (not reset every powerflow), so a fallback or failure that fires occasionally is distinguishable from one that fires systematically.
nb_refactorize_failed / nb_fallback_factorize / nb_fallback_factorize_failed: see NRRefactorRetry_KLU below.
timer_initialize / timer_factor / timer_refactor / timer_solve: matching durations, reset every compute_pf/compute_pf_dc call like TimerJac (returned by get_timers_jacobian()), which these numbers also feed into.

The two-linear-solver Fast-Decoupled family (FDPF_XB_*/FDPF_BX_*) exposes this per solver instead, as get_linear_solver_stats_bp() / get_linear_solver_stats_bpp() (for B’ and B’’ respectively) on the concrete solver object.

Retrying a failed refactor: `NRRefactorRetry_*`

lightsim2grid.algorithm.NRRefactorRetry_KLU, NRRefactorRetry_CKTSO and NRRefactorRetry_NICSLU are Newton-Raphson (multi-slack) variants of NR_KLU / NR_CKTSO / NR_NICSLU: if a Jacobian refactorize() call fails, they fall back to a full factorize() (reusing the existing symbolic factorization) before reporting an error, instead of failing immediately. This is a defensive measure recommended by SuiteSparse’s own documentation for KLU, generalized here to any linear solver with a real factorize/refactorize distinction.

Note

There is no NRRefactorRetry_SparseLU: Eigen’s SparseLU has no cheaper “reuse pivot order” refactor – its factorize() and refactorize() are already the same call, so the fallback would be a no-op.

Note

These are registered by name only (not part of the AlgorithmType enum), the same way externally-loaded algorithm plugins are – select them with grid.change_algorithm("NRRefactorRetry_KLU") rather than via AlgorithmType.

Use LinearSolverStats (get_linear_solver_stats(), see above) to inspect how often the fallback actually fires: nb_refactorize_failed and nb_fallback_factorize stay at 0 on a grid where refactor never fails.

Default algorithm selection

By default, when KLU is available, lightsim2grid uses:

NR_KLU (AC multi-slack)
NRSing_KLU (AC single-slack, when only one slack bus is detected)
DC_KLU (DC approximation)

When KLU is not available (e.g. installed from PyPI without a source build), it falls back to:

NR_SparseLU
NRSing_SparseLU
DC_SparseLU

Correspondence between class and `AlgorithmType` enum

Python class	`AlgorithmType` enum value
`GaussSeidelAlgo`	`AlgorithmType.GaussSeidel`
`GaussSeidelSynchAlgo`	`AlgorithmType.GaussSeidelSynch`
`DC_SparseLU`	`AlgorithmType.DC_SparseLU`
`DC_KLU`	`AlgorithmType.DC_KLU`
`DC_NICSLU`	`AlgorithmType.DC_NICSLU`
`DC_CKTSO`	`AlgorithmType.DC_CKTSO`
`NRSing_SparseLU`	`AlgorithmType.NRSing_SparseLU`
`NRSing_KLU`	`AlgorithmType.NRSing_KLU`
`NRSing_NICSLU`	`AlgorithmType.NRSing_NICSLU`
`NRSing_CKTSO`	`AlgorithmType.NRSing_CKTSO`
`NR_SparseLU`	`AlgorithmType.NR_SparseLU`
`NR_KLU`	`AlgorithmType.NR_KLU`
`NR_NICSLU`	`AlgorithmType.NR_NICSLU`
`NR_CKTSO`	`AlgorithmType.NR_CKTSO`
`FDPF_XB_SparseLU`	`AlgorithmType.FDPF_XB_SparseLU`
`FDPF_BX_SparseLU`	`AlgorithmType.FDPF_BX_SparseLU`
`FDPF_XB_KLU`	`AlgorithmType.FDPF_XB_KLU`
`FDPF_BX_KLU`	`AlgorithmType.FDPF_BX_KLU`
`FDPF_XB_NICSLU`	`AlgorithmType.FDPF_XB_NICSLU`
`FDPF_BX_NICSLU`	`AlgorithmType.FDPF_BX_NICSLU`
`FDPF_XB_CKTSO`	`AlgorithmType.FDPF_XB_CKTSO`
`FDPF_BX_CKTSO`	`AlgorithmType.FDPF_BX_CKTSO`

Usage

The preferred way to select an algorithm is to pass algo_type when creating the backend:

import grid2op
import lightsim2grid
from lightsim2grid import LightSimBackend
from lightsim2grid.algorithm import AlgorithmType

env_name = "l2rpn_case14_sandbox"
env = grid2op.make(env_name,
                   backend=LightSimBackend(algo_type=AlgorithmType.NR_KLU))

You can also change the algorithm after creation, using lightsim2grid.lightSimBackend.LightSimBackend.set_algo_type():

import grid2op
import lightsim2grid
from lightsim2grid import LightSimBackend
from lightsim2grid.algorithm import AlgorithmType

env_name = "l2rpn_case14_sandbox"
env = grid2op.make(env_name, backend=LightSimBackend())

# switch to Gauss-Seidel
env.backend.set_algo_type(AlgorithmType.GaussSeidel)

# inspect which algorithms are available in this build
print(env.backend._grid.available_algorithm_names())

# tune solver parameters
env.backend.set_solver_max_iter(10000)
env.backend.set_tol(1e-7)

Warning

Do not call env.backend._grid.change_algorithm(...) directly: env.reset() rebuilds env.backend._grid from scratch and re-applies whatever algorithm was last set through set_algo_type() (or the algo_type kwarg at creation), so a change made directly on _grid is silently reverted on the next reset. Always go through set_algo_type (or the algo_type kwarg) so the change survives resets.

Note

For the complete list of available algorithm types, see lightsim2grid.algorithm.AlgorithmType. For an explanation of the naming convention and the three distinct meanings of “solver”, see Naming conventions: “solver” vs “algorithm”.

Fine-tuning the Newton-Raphson iteration

Every Newton-Raphson-based algorithm above (all the NR_* / NRSing_* classes) supports two independent, orthogonal knobs controlling how each iteration is taken:

ScalingPolicyType – whether/how the raw Newton step (dVa, dVm) is scaled down before being applied:
- NoScaling (default): the full step is applied (fastest per iteration, but can overshoot on a badly-conditioned grid).
- MaxVoltageChange: clamps the step so it never exceeds max_dVa (rad) / max_dVm (pu).
- LineSearch: an Armijo backtracking line search (constants ls_c / ls_rho).
- Iwamoto: the Iwamoto optimal multiplier (bounded by iw_mu_min / iw_mu_max).
RefactorPolicyType – whether the Jacobian is fully rebuilt and refactorized every iteration:
- AlwaysRefactor (default): rebuild and refactorize J every iteration.
- EveryN: refactorize only every refactor_every_n iterations, updating values only (cheaper, at the cost of a slightly stale factorization) in between.
- Chord: build and factorize J once, on the first iteration, then reuse that factorization for every subsequent one (the “chord method”).

The per-policy parameters (max_dVa, max_dVm, ls_c, ls_rho, ls_max_iter, iw_mu_min, iw_mu_max, refactor_every_n) are only read by their corresponding policy; changing them has no effect while a different policy is active.

Setting the policy on a raw solver object (see Use as Pandapower Solver) is direct:

from lightsim2grid.algorithm import NR_KLU, ScalingPolicyType, RefactorPolicyType

solver = NR_KLU()
solver.set_scaling_policy(ScalingPolicyType.LineSearch)
solver.set_refactor_policy(RefactorPolicyType.EveryN)
solver.set_refactor_every_n(5)

When going through a grid2op / LightSimBackend powerflow, use get_ac_algo_config() / set_ac_algo_config() (and their _dc_ counterparts for the DC solver) instead, which read/write a serialisable AlgoConfig:

import grid2op
from lightsim2grid import LightSimBackend
from lightsim2grid.algorithm import ScalingPolicyType

env = grid2op.make("l2rpn_case14_sandbox", backend=LightSimBackend())

config = env.backend.get_ac_algo_config()
# config.int_params  == [ScalingPolicyType, RefactorPolicyType, ls_max_iter, refactor_every_n]
# config.real_params == [max_dVa, max_dVm, ls_c, ls_rho, iw_mu_min, iw_mu_max]

int_params = list(config.int_params)
int_params[0] = int(ScalingPolicyType.LineSearch)
config.int_params = int_params  # reassign the whole list, see warning below
env.backend.set_ac_algo_config(config)

Unlike calling env.backend._grid.set_ac_algo_config(...) directly, which is silently reverted on the next env.reset(), going through the LightSimBackend methods above remembers the customization so it is re-applied after every env.reset() and preserved by backend.copy().

Warning

AlgoConfig.int_params / real_params are plain lists returned by value: config.int_params[0] = ... silently does nothing, because it mutates a temporary copy, not the object’s actual state. You must build the new list and reassign the whole attribute (config.int_params = int_params, as above) for the change to take effect.

Detailed API

Classes:

`AlgoConfig`	Serializable configuration blob for Newton-Raphson algorithm parameters: stores the scaling / refactor policy type and every associated parameter (see `lightsim2grid.algorithm.NR_SparseLU.get_scaling_policy_type()` and friends) as a single object.
`AlgoControl`	Change-tracking flags for one solver family (AC or DC), read via `lightsim2grid.network.LSGrid.get_ac_algo_controler()` / `lightsim2grid.network.LSGrid.get_dc_algo_controler()`.
`AlgorithmSelector`	This is a "wrapper" class that allows the user to perform some powerflow using the same API using different solvers.
`AlgorithmType`	This enum controls the powerflow algorithm you want to use.
`DC_CKTSO`	Alternative implementation of the DC solver, it uses the faster CKTSO solver available in the CKTSO library to solve for the DC voltage given the DC admitance matrix and the power injected at each nodes (requires a build from source).
`DC_KLU`	Alternative implementation of the DC solver, it uses the faster KLU solver available in the SuiteSparse library to solve for the DC voltage given the DC admitance matrix and the power injected at each nodes (can be unavailable if you build lightsim2grid from source).
`DC_NICSLU`	Alternative implementation of the DC solver, it uses the faster NICSLU solver available in the NICSLU library to solve for the DC voltage given the DC admitance matrix and the power injected at each nodes (requires a build from source).
`DC_SparseLU`	Default implementation of the DC solver, it uses the default Eigen sparse lu decomposition to solve for the DC voltage given the DC admitance matrix and the power injected at each nodes.
`ErrorType`	This enum controls the error encountered in the solver
`FDPFMethod`	This enum controls the type of method you can use for Fast Decoupled Powerflow (XB or BX)
`FDPF_BX_CKTSO`	Default implementation of the Fast Decoupled Powerflow solver (BX version: "alg 3" / "fdbx" in pypower / pandapower), it uses the fast CKTSO library for its underlying sparse matrix manipulation.
`FDPF_BX_KLU`	Default implementation of the Fast Decoupled Powerflow solver (BX version: "alg 3" / "fdbx" in pypower / pandapower), it uses the fast KLU library for its underlying sparse matrix manipulation.
`FDPF_BX_NICSLU`	Default implementation of the Fast Decoupled Powerflow solver (BX version: "alg 3" / "fdbx" in pypower / pandapower), it uses the fast NICSLU library for its underlying sparse matrix manipulation.
`FDPF_BX_SparseLU`	Default implementation of the Fast Decoupled Powerflow solver (BX version: "alg 3" / "fdbx" in pypower / pandapower), it uses the default Eigen sparse lu decomposition for its underlying sparse matrix manipulation.
`FDPF_XB_CKTSO`	Default implementation of the Fast Decoupled Powerflow solver (XB version: "alg 2" / "fdxb" in pypower / pandapower), it uses the fast CKTSO library for its underlying sparse matrix manipulation.
`FDPF_XB_KLU`	Default implementation of the Fast Decoupled Powerflow solver (XB version: "alg 2" / "fdxb" in pypower / pandapower), it uses the fast KLU library for its underlying sparse matrix manipulation.
`FDPF_XB_NICSLU`	Default implementation of the Fast Decoupled Powerflow solver (XB version: "alg 2" / "fdxb" in pypower / pandapower), it uses the fast NICSLU library for its underlying sparse matrix manipulation.
`FDPF_XB_SparseLU`	Default implementation of the Fast Decoupled Powerflow solver (XB version: "alg 2" / "fdxb" in pypower / pandapower), it uses the default Eigen sparse lu decomposition for its underlying sparse matrix manipulation.
`GaussSeidelAlgo`	Default implementation of the "Gauss Seidel" powerflow solver.
`GaussSeidelSynchAlgo`	Variant implementation of the "Gauss Seidel" powerflow solver, where every buses are updated at once (can be significantly faster than the `lightsim2grid.algorithm.GaussSeidelAlgo` for larger grid).
`LinearSolverStats`	Per-call counters and timings for a linear solver, as tracked by every built-in solver (`LinearSolverPolicy`) and by the `NRRefactorRetry_*` solvers' extra fallback bookkeeping (`RefactorRetryLinearSolver`).
`NRRefactorRetry_CKTSO`	Same as `lightsim2grid.algorithm.NR_CKTSO` (Newton Raphson, distributed slack, CKTSO linear solver), except that if a Jacobian refactorize() fails it falls back to a full factorize() (reusing the existing symbolic factorization) before giving up, rather than reporting an error immediately.
`NRRefactorRetry_KLU`	Same as `lightsim2grid.algorithm.NR_KLU` (Newton Raphson, distributed slack, KLU linear solver), except that if a Jacobian refactorize() fails it falls back to a full factorize() (reusing the existing symbolic factorization) before giving up, rather than reporting an error immediately.
`NRRefactorRetry_NICSLU`	Same as `lightsim2grid.algorithm.NR_NICSLU` (Newton Raphson, distributed slack, NICSLU linear solver), except that if a Jacobian refactorize() fails it falls back to a full factorize() before giving up, rather than reporting an error immediately.
`NRSing_CKTSO`	This classes implements the Newton Raphson algorithm, the faster CKTSO solver available in the CKTSO library for the linear algebra.
`NRSing_KLU`	This classes implements the Newton Raphson algorithm,the faster KLU solver available in the SuiteSparse library for the linear algebra.
`NRSing_NICSLU`	This classes implements the Newton Raphson algorithm, the faster NICSLU solver available in the NICSLU library for the linear algebra.
`NRSing_SparseLU`	This classes implements the Newton Raphson algorithm, using the default Eigen sparse solver available in Eigen for the linear algebra.
`NR_CKTSO`	This classes implements the Newton Raphson algorithm, allowing for distributed slack and using the faster CKTSO solver available in the CKTSO library for the linear algebra (requires a build from source)
`NR_KLU`	This classes implements the Newton Raphson algorithm, allowing for distributed slack and using the faster KLU solver available in the SuiteSparse library for the linear algebra (can be unavailable if you build lightsim2grid from source).
`NR_NICSLU`	This classes implements the Newton Raphson algorithm, allowing for distributed slack and using the faster NICSLU solver available in the NICSLU library for the linear algebra.
`NR_SparseLU`	This classes implements the Newton Raphson algorithm, allowing for distributed slack and using the default Eigen sparse solver available in Eigen for the linear algebra.
`RefactorPolicyType`	Jacobian refactorization strategy for the Newton-Raphson loop
`ScalingPolicyType`	Step-scaling strategy for the Newton-Raphson loop
`TimerJac`	Named timer record returned by `get_timers_jacobian()`, breaking down the plain `(timer_Fx, timer_solve, timer_check, timer_total_nr)` tuple of `get_timers()` into a finer-grained, named set of phases.

class lightsim2grid.algorithm.AlgoConfig

Serializable configuration blob for Newton-Raphson algorithm parameters: stores the scaling / refactor policy type and every associated parameter (see lightsim2grid.algorithm.NR_SparseLU.get_scaling_policy_type() and friends) as a single object.

Obtain via solver.get_config() or, going through a LightSimBackend, lightsim2grid.lightSimBackend.LightSimBackend.get_ac_algo_config().

Warning

int_params / real_params are plain lists returned by value: config.int_params[0] = ... silently does nothing, because it mutates a temporary copy, not the object’s actual state. You must build the new list and reassign the whole attribute (int_params = new_list; config.int_params = int_params) for the change to take effect.

Attributes:

`int_params`	Integer parameters, as a plain list -- `[ScalingPolicyType, RefactorPolicyType, ls_max_iter, refactor_every_n]` -- see `AlgoConfig`'s warning about reassigning the whole list to mutate it.
`real_params`	Real-valued parameters, as a plain list -- `[max_dVa, max_dVm, ls_c, ls_rho, iw_mu_min, iw_mu_max]` -- see `AlgoConfig`'s warning about reassigning the whole list to mutate it.

property int_params: Integer parameters, as a plain list – [ScalingPolicyType, RefactorPolicyType, ls_max_iter, refactor_every_n] – see AlgoConfig’s warning about reassigning the whole list to mutate it.

property real_params: Real-valued parameters, as a plain list – [max_dVa, max_dVm, ls_c, ls_rho, iw_mu_min, iw_mu_max] – see AlgoConfig’s warning about reassigning the whole list to mutate it.

class lightsim2grid.algorithm.AlgoControl

Change-tracking flags for one solver family (AC or DC), read via lightsim2grid.network.LSGrid.get_ac_algo_controler() / lightsim2grid.network.LSGrid.get_dc_algo_controler().

A grid modification (eg. disconnecting a line, changing a setpoint) sets one or more of these flags; the corresponding solver family reads and resets them the next time it runs a powerflow, so it only recomputes / re-stamps what actually changed since its last run (a plain change in dimension does not, by itself, imply the sparsity pattern changed, for instance). Each flag answers one narrow question about what kind of change happened – none of them say what changed, only that something in that category did.

Warning

This is read-only introspection: there is no way to set these flags from Python, and nothing in lightsim2grid resets them for you except the solver itself, on its next run of the family this instance tracks.

Methods:

`has_dimension_changed`(self)	Whether the number of buses (so the size of Ybus / Sbus) changed since the last powerflow of this solver family -- eg after a topology change that changes how many buses are in use.
`has_one_el_changed_bus`(self)	Whether at least one element (a generator, a load, one side of a line, ...) changed which bus it is connected to -- including being reconnected or disconnected -- since the last powerflow of this solver family.
`has_pq_changed`(self)	Whether the set of PQ buses (fixed reactive setpoint) changed since the last powerflow of this solver family -- the complement of `has_pv_changed()`.
`has_pv_changed`(self)	Whether the set of PV buses (voltage-regulated, see `lightsim2grid.elements.GenInfo.voltage_regulator_on`) changed since the last powerflow of this solver family.
`has_slack_participate_changed`(self)	Whether the set of generators participating in the distributed slack (see `lightsim2grid.elements.GenInfo.is_slack`) changed since the last powerflow of this solver family.
`has_slack_weight_changed`(self)	Whether the distributed-slack weight (see `lightsim2grid.elements.GenInfo.slack_weight`) of at least one participating generator changed since the last powerflow of this solver family.
`has_v_changed`(self)	Whether at least one generator's voltage setpoint (see `lightsim2grid.elements.GenInfo.target_vm_pu`) changed since the last powerflow of this solver family.
`has_ybus_some_coeffs_zero`(self)	Whether at least one coefficient of Ybus may have been set to exactly `0.` (and Ybus re-compressed to drop it) since the last powerflow of this solver family.
`need_recompute_sbus`(self)	Whether the bus injection vector (Sbus) needs recomputing before the next powerflow of this solver family -- eg a setpoint changed, but not necessarily the grid's topology.
`need_recompute_ybus`(self)	Whether the admittance matrix (Ybus) needs recomputing before the next powerflow of this solver family -- some of its coefficients changed, though not necessarily its sparsity pattern (see `ybus_change_sparsity_pattern()`).
`need_reset_solver`(self)	Whether the solver needs a full reset (discarding any cached factorization / matrix) before its next powerflow -- set for changes too disruptive to recompute incrementally.
`ybus_change_sparsity_pattern`(self)	Whether Ybus's sparsity pattern changed (which non-zero entries it has, not just their values) since the last powerflow of this solver family -- eg after a topology change.

has_dimension_changed(self: lightsim2grid.lightsim2grid_cpp.AlgoControl) → bool: Whether the number of buses (so the size of Ybus / Sbus) changed since the last powerflow of this solver family – eg after a topology change that changes how many buses are in use.

has_one_el_changed_bus(self: lightsim2grid.lightsim2grid_cpp.AlgoControl) → bool: Whether at least one element (a generator, a load, one side of a line, …) changed which bus it is connected to – including being reconnected or disconnected – since the last powerflow of this solver family.

has_pq_changed(self: lightsim2grid.lightsim2grid_cpp.AlgoControl) → bool: Whether the set of PQ buses (fixed reactive setpoint) changed since the last powerflow of this solver family – the complement of has_pv_changed().

has_pv_changed(self: lightsim2grid.lightsim2grid_cpp.AlgoControl) → bool: Whether the set of PV buses (voltage-regulated, see lightsim2grid.elements.GenInfo.voltage_regulator_on) changed since the last powerflow of this solver family.

has_slack_participate_changed(self: lightsim2grid.lightsim2grid_cpp.AlgoControl) → bool: Whether the set of generators participating in the distributed slack (see lightsim2grid.elements.GenInfo.is_slack) changed since the last powerflow of this solver family.

has_slack_weight_changed(self: lightsim2grid.lightsim2grid_cpp.AlgoControl) → bool: Whether the distributed-slack weight (see lightsim2grid.elements.GenInfo.slack_weight) of at least one participating generator changed since the last powerflow of this solver family.

has_v_changed(self: lightsim2grid.lightsim2grid_cpp.AlgoControl) → bool: Whether at least one generator’s voltage setpoint (see lightsim2grid.elements.GenInfo.target_vm_pu) changed since the last powerflow of this solver family.

has_ybus_some_coeffs_zero(self: lightsim2grid.lightsim2grid_cpp.AlgoControl) → bool: Whether at least one coefficient of Ybus may have been set to exactly 0. (and Ybus re-compressed to drop it) since the last powerflow of this solver family. Some solvers (notably the Newton-Raphson family) may need to recompute some cached state when this happens, even though it does not by itself change Ybus’s sparsity pattern.

need_recompute_sbus(self: lightsim2grid.lightsim2grid_cpp.AlgoControl) → bool: Whether the bus injection vector (Sbus) needs recomputing before the next powerflow of this solver family – eg a setpoint changed, but not necessarily the grid’s topology.

need_recompute_ybus(self: lightsim2grid.lightsim2grid_cpp.AlgoControl) → bool: Whether the admittance matrix (Ybus) needs recomputing before the next powerflow of this solver family – some of its coefficients changed, though not necessarily its sparsity pattern (see ybus_change_sparsity_pattern()).

need_reset_solver(self: lightsim2grid.lightsim2grid_cpp.AlgoControl) → bool: Whether the solver needs a full reset (discarding any cached factorization / matrix) before its next powerflow – set for changes too disruptive to recompute incrementally.

ybus_change_sparsity_pattern(self: lightsim2grid.lightsim2grid_cpp.AlgoControl) → bool: Whether Ybus’s sparsity pattern changed (which non-zero entries it has, not just their values) since the last powerflow of this solver family – eg after a topology change. This is a stronger condition than need_recompute_ybus(): a changed sparsity pattern requires the linear solver to redo its symbolic factorization, not just its numeric one.

class lightsim2grid.algorithm.AlgorithmSelector

This is a “wrapper” class that allows the user to perform some powerflow using the same API using different solvers. It is not recommended to use this wrapper directly. It is rather a class exported to be compatible with the env_lightsim2grid.backend._grid.get_solver() method.

Examples

This class is built to be used like this:

import grid2op
from lightsim2grid import LightSimBackend

env_name = ... # eg. "l2rpn_case14_test"
env = grid2op.make(env_name, backend=LightSimBackend())

anysolver = env.backend._grid.get_solver()

anysolver.get_type()  # type of solver currently used
anysolver.get_J()  # current Jacobian matrix, if available by the method

Methods:

`converged`(self)	Returns whether or not the solver has converged or not.
`get_J`(self)	Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_computation_time`(self)	Return the total computation time (in second) spend in the solver when performing a powerflow.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_fdpf_bx_lu`(self)	Low-level / internal primitive, not part of the stable public API: called directly by lightsim2grid's own machinery (eg `LightSimBackend`, the grid loaders, or another part of the C++ core) rather than meant for everyday use.
`get_fdpf_xb_lu`(self)	Low-level / internal primitive, not part of the stable public API: called directly by lightsim2grid's own machinery (eg `LightSimBackend`, the grid loaders, or another part of the C++ core) rather than meant for everyday use.
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver (LinearSolverStats).
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_q_to_J_col`(self)	bus_id -> Jacobian column of its reactive (q) unknown, currently always -1
`get_theta_to_J_col`(self)	bus_id -> Jacobian column of its voltage-angle (theta) unknown, -1 if none
`get_timers`(self)	TODO
`get_timers_jacobian`(self)	TODO
`get_timers_ptdf_lodf`(self)	TODO
`get_type`(self)	Retrieve the current solver used.
`get_vm_to_J_col`(self)	bus_id -> Jacobian column of its voltage-magnitude (vm) unknown, -1 if none

converged(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → bool: Returns whether or not the solver has converged or not.

get_J(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → scipy.sparse.csc_matrix[numpy.float64]: Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.

Note

Depending on the underlying solver used (eg lightsim2grid.algorithm.DC_SparseLU or lightsim2grid.algorithm.GaussSeidelAlgo) the jacobian matrix might be irrelevant and an attempt to use this function will throw a RuntimeError.

get_V(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_computation_time(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → float

Return the total computation time (in second) spend in the solver when performing a powerflow.

This is equivalent to the last (4th) element, timer_total_nr_, of the tuple returned by ***.get_timers().

get_error(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_fdpf_bx_lu(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU: Low-level / internal primitive, not part of the stable public API: called directly by lightsim2grid’s own machinery (eg LightSimBackend, the grid loaders, or another part of the C++ core) rather than meant for everyday use.

Warning

Argument validation here is deliberately minimal or absent, and its exact behavior / signature may change between releases without notice. Prefer the higher-level methods documented elsewhere on this class (or grid2op’s own API) unless you specifically need this one and understand what it does internally.

get_fdpf_xb_lu(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU: Low-level / internal primitive, not part of the stable public API: called directly by lightsim2grid’s own machinery (eg LightSimBackend, the grid loaders, or another part of the C++ core) rather than meant for everyday use.

Warning

Argument validation here is deliberately minimal or absent, and its exact behavior / signature may change between releases without notice. Prefer the higher-level methods documented elsewhere on this class (or grid2op’s own API) unless you specifically need this one and understand what it does internally.

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver (LinearSolverStats). All-zero if the active solver doesn’t track them (e.g. GaussSeidel, or the FDPF family which exposes get_linear_solver_stats_bp/_bpp on its own concrete Python type instead, since it holds two linear solvers).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_q_to_J_col(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column of its reactive (q) unknown, currently always -1

get_theta_to_J_col(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column of its voltage-angle (theta) unknown, -1 if none

get_timers(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → tuple[float, float, float, float]: TODO

get_timers_jacobian(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → lightsim2grid.lightsim2grid_cpp.TimerJac: TODO

get_timers_ptdf_lodf(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → tuple[float, float, float]: TODO

get_type(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → lightsim2grid.lightsim2grid_cpp.AlgorithmType

Retrieve the current solver used. This will return an instance of lightsim2grid.algorithm.AlgorithmType indicating which is the underlying solver in use.

This should be equivalent to lightsim2grid.network.LSGrid.get_algo_type()

get_vm_to_J_col(self: lightsim2grid.lightsim2grid_cpp.AlgorithmSelector) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column of its voltage-magnitude (vm) unknown, -1 if none

class lightsim2grid.algorithm.AlgorithmType

This enum controls the powerflow algorithm you want to use.

Members:

GaussSeidel : denotes the lightsim2grid.algorithm.GaussSeidelAlgo

GaussSeidelSynch : denotes the lightsim2grid.algorithm.GaussSeidelSynchAlgo

NR_SparseLU : Newton-Raphson (multi-slack) + SparseLU; see lightsim2grid.algorithm.NR_SparseLU

NRSing_SparseLU : Newton-Raphson (single-slack) + SparseLU; see lightsim2grid.algorithm.NRSing_SparseLU

DC_SparseLU : DC approximation + SparseLU; see lightsim2grid.algorithm.DC_SparseLU

FDPF_XB_SparseLU : Fast-Decoupled PF (XB) + SparseLU; see lightsim2grid.algorithm.FDPF_XB_SparseLU

FDPF_BX_SparseLU : Fast-Decoupled PF (BX) + SparseLU; see lightsim2grid.algorithm.FDPF_BX_SparseLU

NR_KLU : Newton-Raphson (multi-slack) + KLU; see lightsim2grid.algorithm.NR_KLU

NRSing_KLU : Newton-Raphson (single-slack) + KLU; see lightsim2grid.algorithm.NRSing_KLU

DC_KLU : DC approximation + KLU; see lightsim2grid.algorithm.DC_KLU

FDPF_XB_KLU : Fast-Decoupled PF (XB) + KLU; see lightsim2grid.algorithm.FDPF_XB_KLU

FDPF_BX_KLU : Fast-Decoupled PF (BX) + KLU; see lightsim2grid.algorithm.FDPF_BX_KLU

NR_NICSLU : Newton-Raphson (multi-slack) + NICSLU; see lightsim2grid.algorithm.NR_NICSLU

NRSing_NICSLU : Newton-Raphson (single-slack) + NICSLU; see lightsim2grid.algorithm.NRSing_NICSLU

DC_NICSLU : DC approximation + NICSLU; see lightsim2grid.algorithm.DC_NICSLU

FDPF_XB_NICSLU : Fast-Decoupled PF (XB) + NICSLU; see lightsim2grid.algorithm.FDPF_XB_NICSLU

FDPF_BX_NICSLU : Fast-Decoupled PF (BX) + NICSLU; see lightsim2grid.algorithm.FDPF_BX_NICSLU

NR_CKTSO : Newton-Raphson (multi-slack) + CKTSO; see lightsim2grid.algorithm.NR_CKTSO

NRSing_CKTSO : Newton-Raphson (single-slack) + CKTSO; see lightsim2grid.algorithm.NRSing_CKTSO

DC_CKTSO : DC approximation + CKTSO; see lightsim2grid.algorithm.DC_CKTSO

FDPF_XB_CKTSO : Fast-Decoupled PF (XB) + CKTSO; see lightsim2grid.algorithm.FDPF_XB_CKTSO

FDPF_BX_CKTSO : Fast-Decoupled PF (BX) + CKTSO; see lightsim2grid.algorithm.FDPF_BX_CKTSO

Custom : sentinel value for external/plugin solvers loaded via load_solver_plugin()

Attributes:

name

property name

class lightsim2grid.algorithm.DC_CKTSO

Alternative implementation of the DC solver, it uses the faster CKTSO solver available in the CKTSO library to solve for the DC voltage given the DC admitance matrix and the power injected at each nodes (requires a build from source).

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called DC_CKTSO

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.DC_CKTSO) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.DC_CKTSO) at creation time

Warning

This is a DC solver that uses the DC approximation. If you want to use this approximation, you need to specified it when you create the grid2op environment, for example with “param.ENV_DC=True”.

Otherwise, it is used internally to find good starting point to intialize the real AC solver.

Note

CKTSO is available at https://github.com/chenxm1986/cktso

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.DC_CKTSO, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.DC_CKTSO) → bool: Returns whether or not the solver has converged or not.

get_V(self: lightsim2grid.lightsim2grid_cpp.DC_CKTSO) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.DC_CKTSO) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.DC_CKTSO) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.DC_CKTSO) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.DC_CKTSO) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.DC_CKTSO) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.DC_CKTSO) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.DC_CKTSO) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.DC_CKTSO, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.DC_KLU

Alternative implementation of the DC solver, it uses the faster KLU solver available in the SuiteSparse library to solve for the DC voltage given the DC admitance matrix and the power injected at each nodes (can be unavailable if you build lightsim2grid from source).

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called DC_KLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.DC_KLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.DC_KLU) at creation time

Warning

This is a DC solver that uses the DC approximation. If you want to use this approximation, you need to specified it when you create the grid2op environment, for example with “param.ENV_DC=True”.

Otherwise, it is used internally to find good starting point to intialize the real AC solver.

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.DC_KLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.DC_KLU) → bool: Returns whether or not the solver has converged or not.

get_V(self: lightsim2grid.lightsim2grid_cpp.DC_KLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.DC_KLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.DC_KLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.DC_KLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.DC_KLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.DC_KLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.DC_KLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.DC_KLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.DC_KLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.DC_NICSLU

Alternative implementation of the DC solver, it uses the faster NICSLU solver available in the NICSLU library to solve for the DC voltage given the DC admitance matrix and the power injected at each nodes (requires a build from source).

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called DC_NICSLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.DC_NICSLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.DC_NICSLU) at creation time

Warning

This is a DC solver that uses the DC approximation. If you want to use this approximation, you need to specified it when you create the grid2op environment, for example with “param.ENV_DC=True”.

Otherwise, it is used internally to find good starting point to intialize the real AC solver.

Warning

Use this solver requires a compilation of lightsim2grid from source (see readme) AND an appropriate license for nicslu.

Note

NICSLU is available at https://github.com/chenxm1986/nicslu

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.DC_NICSLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.DC_NICSLU) → bool: Returns whether or not the solver has converged or not.

get_V(self: lightsim2grid.lightsim2grid_cpp.DC_NICSLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.DC_NICSLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.DC_NICSLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.DC_NICSLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.DC_NICSLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.DC_NICSLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.DC_NICSLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.DC_NICSLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.DC_NICSLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.DC_SparseLU

Default implementation of the DC solver, it uses the default Eigen sparse lu decomposition to solve for the DC voltage given the DC admitance matrix and the power injected at each nodes.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called DC_SparseLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.DC_SparseLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.DC_SparseLU) at creation time

Warning

This is a DC solver that uses the DC approximation. If you want to use this approximation, you need to specified it when you create the grid2op environment, for example with “param.ENV_DC=True”.

Otherwise, it is used internally to find good starting point to intialize the real AC solver.

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.DC_SparseLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.DC_SparseLU) → bool: Returns whether or not the solver has converged or not.

get_V(self: lightsim2grid.lightsim2grid_cpp.DC_SparseLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.DC_SparseLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.DC_SparseLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.DC_SparseLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.DC_SparseLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.DC_SparseLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.DC_SparseLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.DC_SparseLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.DC_SparseLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.ErrorType

This enum controls the error encountered in the solver

Members:

NoError : No error were encountered

SingularMatrix : The Jacobian matrix was singular and could not be factorized (most likely, the grid is not connex)

TooManyIterations : The solver reached the maximum number of iterations allowed

InifiniteValue : Some infinite values were encountered in the update vector (to update Vm or Va)

SolverAnalyze : The linear solver failed at the ‘analyze’ step (eg analyzePattern for Eigen, klu_analyze for KLU or Initialize for NICSLU

SolverFactor : The linear solver failed to factor the jacobian matrix (eg factorize for Eigen (first call), klu_factor for KLU or FactorizeMatrix for NICSLU (first call)

SolverReFactor : The linear solver failed to (re)factor the jacobian matrix (eg factorize for Eigen (later calls), klu_refactor for KLU or FactorizeMatrix for NICSLU (later calls)

SolverSolve : The linear solve failed to solve the linear system J.X = b (eg solve for Eigen, klu_solve for KLU or Solve for NICSLU

NotInitError : Attempt to perform some powerflow computation when the linear solver is not initiliazed

LicenseError : Impossible to use the linear solver as the license cannot be found (eg unable to locate the nicslu.lic file

Attributes:

name

property name

class lightsim2grid.algorithm.FDPFMethod

This enum controls the type of method you can use for Fast Decoupled Powerflow (XB or BX)

Members:

XB : denotes the XB method

BX : denotes the BX method

Attributes:

name

property name

class lightsim2grid.algorithm.FDPF_BX_CKTSO

Default implementation of the Fast Decoupled Powerflow solver (BX version: “alg 3” / “fdbx” in pypower / pandapower), it uses the fast CKTSO library for its underlying sparse matrix manipulation.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called FDPF_BX_CKTSO

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.FDPF_BX_CKTSO) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.FDPF_BX_CKTSO) at creation time

Warning

Use this solver requires a compilation of lightsim2grid from source (see readme) AND an appropriate license for cktso.

Note

CKTSO is available at https://github.com/chenxm1986/cktso

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_linear_solver_stats_bp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_linear_solver_stats_bpp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B'' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_CKTSO, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_CKTSO) → bool: Returns whether or not the solver has converged or not.

get_V(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_CKTSO) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_CKTSO) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_CKTSO) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_CKTSO) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_linear_solver_stats_bp(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_CKTSO) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bpp() for the B’’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_linear_solver_stats_bpp(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_CKTSO) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() for the B’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_CKTSO) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_CKTSO) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_CKTSO) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_CKTSO, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.FDPF_BX_KLU

Default implementation of the Fast Decoupled Powerflow solver (BX version: “alg 3” / “fdbx” in pypower / pandapower), it uses the fast KLU library for its underlying sparse matrix manipulation.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called FDPF_BX_KLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.FDPF_BX_KLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.FDPF_BX_KLU) at creation time

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_linear_solver_stats_bp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_linear_solver_stats_bpp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B'' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_KLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_KLU) → bool: Returns whether or not the solver has converged or not.

get_V(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_KLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_KLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_KLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_KLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_linear_solver_stats_bp(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_KLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bpp() for the B’’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_linear_solver_stats_bpp(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_KLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() for the B’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_KLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_KLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_KLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_KLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.FDPF_BX_NICSLU

Default implementation of the Fast Decoupled Powerflow solver (BX version: “alg 3” / “fdbx” in pypower / pandapower), it uses the fast NICSLU library for its underlying sparse matrix manipulation.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called FDPF_BX_NICSLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.FDPF_BX_NICSLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.FDPF_BX_NICSLU) at creation time

Warning

Use this solver requires a compilation of lightsim2grid from source (see readme) AND an appropriate license for nicslu.

Note

NICSLU is available at https://github.com/chenxm1986/nicslu

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_linear_solver_stats_bp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_linear_solver_stats_bpp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B'' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_NICSLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_NICSLU) → bool: Returns whether or not the solver has converged or not.

get_V(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_NICSLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_NICSLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_NICSLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_NICSLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_linear_solver_stats_bp(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_NICSLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bpp() for the B’’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_linear_solver_stats_bpp(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_NICSLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() for the B’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_NICSLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_NICSLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_NICSLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_NICSLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.FDPF_BX_SparseLU

Default implementation of the Fast Decoupled Powerflow solver (BX version: “alg 3” / “fdbx” in pypower / pandapower), it uses the default Eigen sparse lu decomposition for its underlying sparse matrix manipulation.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called FDPF_BX_SparseLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.FDPF_BX_SparseLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.FDPF_BX_SparseLU) at creation time

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`debug_get_Bp_python`(self)	Low-level / internal primitive, not part of the stable public API: called directly by lightsim2grid's own machinery (eg `LightSimBackend`, the grid loaders, or another part of the C++ core) rather than meant for everyday use.
`debug_get_Bpp_python`(self)	Low-level / internal primitive, not part of the stable public API: called directly by lightsim2grid's own machinery (eg `LightSimBackend`, the grid loaders, or another part of the C++ core) rather than meant for everyday use.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_linear_solver_stats_bp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_linear_solver_stats_bpp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B'' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU) → bool: Returns whether or not the solver has converged or not.

debug_get_Bp_python(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU) → scipy.sparse.csc_matrix[numpy.float64]: Low-level / internal primitive, not part of the stable public API: called directly by lightsim2grid’s own machinery (eg LightSimBackend, the grid loaders, or another part of the C++ core) rather than meant for everyday use.

Warning

Argument validation here is deliberately minimal or absent, and its exact behavior / signature may change between releases without notice. Prefer the higher-level methods documented elsewhere on this class (or grid2op’s own API) unless you specifically need this one and understand what it does internally.

debug_get_Bpp_python(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU) → scipy.sparse.csc_matrix[numpy.float64]: Low-level / internal primitive, not part of the stable public API: called directly by lightsim2grid’s own machinery (eg LightSimBackend, the grid loaders, or another part of the C++ core) rather than meant for everyday use.

Warning

Argument validation here is deliberately minimal or absent, and its exact behavior / signature may change between releases without notice. Prefer the higher-level methods documented elsewhere on this class (or grid2op’s own API) unless you specifically need this one and understand what it does internally.

get_V(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_linear_solver_stats_bp(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bpp() for the B’’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_linear_solver_stats_bpp(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() for the B’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.FDPF_BX_SparseLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.FDPF_XB_CKTSO

Default implementation of the Fast Decoupled Powerflow solver (XB version: “alg 2” / “fdxb” in pypower / pandapower), it uses the fast CKTSO library for its underlying sparse matrix manipulation.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called FDPF_XB_CKTSO

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.FDPF_XB_CKTSO) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.FDPF_XB_CKTSO) at creation time

Warning

Use this solver requires a compilation of lightsim2grid from source (see readme) AND an appropriate license for cktso.

Note

CKTSO is available at https://github.com/chenxm1986/cktso

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_linear_solver_stats_bp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_linear_solver_stats_bpp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B'' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_CKTSO, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_CKTSO) → bool: Returns whether or not the solver has converged or not.

get_V(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_CKTSO) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_CKTSO) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_CKTSO) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_CKTSO) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_linear_solver_stats_bp(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_CKTSO) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bpp() for the B’’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_linear_solver_stats_bpp(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_CKTSO) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() for the B’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_CKTSO) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_CKTSO) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_CKTSO) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_CKTSO, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.FDPF_XB_KLU

Default implementation of the Fast Decoupled Powerflow solver (XB version: “alg 2” / “fdxb” in pypower / pandapower), it uses the fast KLU library for its underlying sparse matrix manipulation.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called FDPF_XB_KLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.FDPF_XB_KLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.FDPF_XB_KLU) at creation time

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_linear_solver_stats_bp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_linear_solver_stats_bpp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B'' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_KLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_KLU) → bool: Returns whether or not the solver has converged or not.

get_V(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_KLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_KLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_KLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_KLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_linear_solver_stats_bp(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_KLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bpp() for the B’’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_linear_solver_stats_bpp(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_KLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() for the B’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_KLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_KLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_KLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_KLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.FDPF_XB_NICSLU

Default implementation of the Fast Decoupled Powerflow solver (XB version: “alg 2” / “fdxb” in pypower / pandapower), it uses the fast NICSLU library for its underlying sparse matrix manipulation.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called FDPF_XB_NICSLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.FDPF_XB_NICSLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.FDPF_XB_NICSLU) at creation time

Warning

Use this solver requires a compilation of lightsim2grid from source (see readme) AND an appropriate license for nicslu.

Note

NICSLU is available at https://github.com/chenxm1986/nicslu

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_linear_solver_stats_bp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_linear_solver_stats_bpp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B'' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_NICSLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_NICSLU) → bool: Returns whether or not the solver has converged or not.

get_V(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_NICSLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_NICSLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_NICSLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_NICSLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_linear_solver_stats_bp(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_NICSLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bpp() for the B’’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_linear_solver_stats_bpp(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_NICSLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() for the B’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_NICSLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_NICSLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_NICSLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_NICSLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.FDPF_XB_SparseLU

Default implementation of the Fast Decoupled Powerflow solver (XB version: “alg 2” / “fdxb” in pypower / pandapower), it uses the default Eigen sparse lu decomposition for its underlying sparse matrix manipulation.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called FDPF_XB_SparseLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.FDPF_XB_SparseLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.FDPF_XB_SparseLU) at creation time

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`debug_get_Bp_python`(self)	Low-level / internal primitive, not part of the stable public API: called directly by lightsim2grid's own machinery (eg `LightSimBackend`, the grid loaders, or another part of the C++ core) rather than meant for everyday use.
`debug_get_Bpp_python`(self)	Low-level / internal primitive, not part of the stable public API: called directly by lightsim2grid's own machinery (eg `LightSimBackend`, the grid loaders, or another part of the C++ core) rather than meant for everyday use.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_linear_solver_stats_bp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_linear_solver_stats_bpp`(self)	`FDPF_*` solvers only: per-call counters and timings for the B'' linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU) → bool: Returns whether or not the solver has converged or not.

debug_get_Bp_python(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU) → scipy.sparse.csc_matrix[numpy.float64]: Low-level / internal primitive, not part of the stable public API: called directly by lightsim2grid’s own machinery (eg LightSimBackend, the grid loaders, or another part of the C++ core) rather than meant for everyday use.

Warning

Argument validation here is deliberately minimal or absent, and its exact behavior / signature may change between releases without notice. Prefer the higher-level methods documented elsewhere on this class (or grid2op’s own API) unless you specifically need this one and understand what it does internally.

debug_get_Bpp_python(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU) → scipy.sparse.csc_matrix[numpy.float64]: Low-level / internal primitive, not part of the stable public API: called directly by lightsim2grid’s own machinery (eg LightSimBackend, the grid loaders, or another part of the C++ core) rather than meant for everyday use.

Warning

Argument validation here is deliberately minimal or absent, and its exact behavior / signature may change between releases without notice. Prefer the higher-level methods documented elsewhere on this class (or grid2op’s own API) unless you specifically need this one and understand what it does internally.

get_V(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_linear_solver_stats_bp(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bpp() for the B’’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_linear_solver_stats_bpp(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: FDPF_* solvers only: per-call counters and timings for the B’’ linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() for the B’ linear solver; get_linear_solver_stats() for the single-linear-solver equivalent used by every other solver family.

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.FDPF_XB_SparseLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.GaussSeidelAlgo

Default implementation of the “Gauss Seidel” powerflow solver. We do not recommend to use it as the Newton Raphson based solvers are usually much (much) faster.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called GaussSeidel

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.GaussSeidel) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.GaussSeidel) at creation time

Warning

It currently does not support distributed slack.

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelAlgo, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelAlgo) → bool: Returns whether or not the solver has converged or not.

get_V(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelAlgo) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelAlgo) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelAlgo) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelAlgo) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelAlgo) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelAlgo) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelAlgo) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelAlgo, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.GaussSeidelSynchAlgo

Variant implementation of the “Gauss Seidel” powerflow solver, where every buses are updated at once (can be significantly faster than the lightsim2grid.algorithm.GaussSeidelAlgo for larger grid). We still do not recommend to use it as the Newton Raphson based solvers are usually much (much) faster.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it called GaussSeidelSynch

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.GaussSeidelSynch) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.GaussSeidelSynch) at creation time

Warning

It currently does not support distributed slack.

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`reset`(self)	Reset the solver.
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelSynchAlgo, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelSynchAlgo) → bool: Returns whether or not the solver has converged or not.

get_V(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelSynchAlgo) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelSynchAlgo) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelSynchAlgo) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_error(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelSynchAlgo) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelSynchAlgo) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_timers(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelSynchAlgo) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

reset(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelSynchAlgo) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

solve(self: lightsim2grid.lightsim2grid_cpp.GaussSeidelSynchAlgo, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.LinearSolverStats

Per-call counters and timings for a linear solver, as tracked by every built-in solver (LinearSolverPolicy) and by the NRRefactorRetry_* solvers’ extra fallback bookkeeping (RefactorRetryLinearSolver).

Returned by get_linear_solver_stats() (or, for the fast-decoupled FDPF_* family, which holds two independent linear solvers, by get_linear_solver_stats_bp() / get_linear_solver_stats_bpp()).

The nb_* counters accumulate over the solver’s whole lifetime (across every compute_pf() call, not reset in between); the timer_* fields reset every compute_pf call, like get_timers_jacobian()’s TimerJac.

Attributes:

`nb_analyze`	Number of times the underlying linear solver's `analyze()` (symbolic factorization) was called.
`nb_factorize`	Number of times the underlying linear solver's `factorize()` (full numeric factorization) was called.
`nb_fallback_factorize`	number of times a failed `refactorize()` was retried with a full `factorize()` (`0` for every other solver, which does not retry).
`nb_fallback_factorize_failed`	number of times that fallback `factorize()` retry (see `nb_fallback_factorize`) itself failed (`0` for every other solver).
`nb_refactorize`	Number of times the underlying linear solver's `refactorize()` (cheaper, reusing the existing symbolic factorization / pivot order) was called.
`nb_refactorize_failed`	Number of times a `refactorize()` call failed (eg the matrix became too ill-conditioned for the reused pivot order).
`nb_reset`	Number of times `reset()` was called on the underlying linear solver (discarding any cached factorization).
`nb_solve`	Number of times the underlying linear solver's `solve()` was called.
`timer_factor`	Total time spent in the underlying linear solver's `factorize()` step (same value as `lightsim2grid.algorithm.LinearSolverStats.timer_factor`).
`timer_initialize`	Total time spent in the underlying linear solver's `analyze()` (symbolic factorization) step (same value as `lightsim2grid.algorithm.LinearSolverStats.timer_initialize`).
`timer_refactor`	Total time spent in the underlying linear solver's `refactorize()` step (same value as `lightsim2grid.algorithm.LinearSolverStats.timer_refactor`).
`timer_solve`	Total time spent in the underlying linear solver's `solve()` step (same value as `lightsim2grid.algorithm.LinearSolverStats.timer_solve` for NR-based solvers).

property nb_analyze: Number of times the underlying linear solver’s analyze() (symbolic factorization) was called.

property nb_factorize: Number of times the underlying linear solver’s factorize() (full numeric factorization) was called.

property nb_fallback_factorize

number of times a failed refactorize() was retried with a full factorize() (0 for every other solver, which does not retry).

Type:: NRRefactorRetry_* solvers only

property nb_fallback_factorize_failed

number of times that fallback factorize() retry (see nb_fallback_factorize) itself failed (0 for every other solver).

Type:: NRRefactorRetry_* solvers only

property nb_refactorize: Number of times the underlying linear solver’s refactorize() (cheaper, reusing the existing symbolic factorization / pivot order) was called.

property nb_refactorize_failed: Number of times a refactorize() call failed (eg the matrix became too ill-conditioned for the reused pivot order).

See also

nb_fallback_factorize, on the NRRefactorRetry_* solvers: a failed refactorize there is retried with a full factorize() before giving up.

property nb_reset: Number of times reset() was called on the underlying linear solver (discarding any cached factorization).

property nb_solve: Number of times the underlying linear solver’s solve() was called.

property timer_factor: Total time spent in the underlying linear solver’s factorize() step (same value as lightsim2grid.algorithm.LinearSolverStats.timer_factor). NR-only: -1. for Gauss-Seidel and DC solvers.

property timer_initialize: Total time spent in the underlying linear solver’s analyze() (symbolic factorization) step (same value as lightsim2grid.algorithm.LinearSolverStats.timer_initialize). NR-only: -1. for Gauss-Seidel and DC solvers.

property timer_refactor: Total time spent in the underlying linear solver’s refactorize() step (same value as lightsim2grid.algorithm.LinearSolverStats.timer_refactor). NR-only: -1. for Gauss-Seidel and DC solvers.

property timer_solve: Total time spent in the underlying linear solver’s solve() step (same value as lightsim2grid.algorithm.LinearSolverStats.timer_solve for NR-based solvers).

class lightsim2grid.algorithm.NRRefactorRetry_CKTSO

Same as lightsim2grid.algorithm.NR_CKTSO (Newton Raphson, distributed slack, CKTSO linear solver), except that if a Jacobian refactorize() fails it falls back to a full factorize() (reusing the existing symbolic factorization) before giving up, rather than reporting an error immediately.

Use get_linear_solver_stats() on the solver to inspect how often factor/refactor calls happen and how often the fallback fires (see lightsim2grid.algorithm.LinearSolverStats).

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_J`(self)	Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_config`(self)	Return a `lightsim2grid.algorithm.AlgoConfig` capturing every scaling/refactor policy type and parameter above, as a single serializable object.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_iw_mu_max`(self)	Maximum optimal multiplier for the `Iwamoto` scaling policy.
`get_iw_mu_min`(self)	Minimum optimal multiplier for the `Iwamoto` scaling policy.
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_ls_c`(self)	Armijo sufficient-decrease constant `c` for the `LineSearch` scaling policy.
`get_ls_max_iter`(self)	Maximum number of backtracking iterations for the `LineSearch` scaling policy.
`get_ls_rho`(self)	Backtracking factor `rho` (in `(0, 1)`) for the `LineSearch` scaling policy.
`get_max_dVa`(self)	Maximum voltage angle step (radian) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_max_dVm`(self)	Maximum voltage magnitude step (pu) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_q_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's reactive-power (Q) unknown -- currently always `-1`: no solver in this version stamps a reactive-power unknown as its own Jacobian column.
`get_refactor_every_n`(self)	Refactorize (full `factorize()`, not the cheaper `refactorize()`) every N-th iteration, for the `EveryN` refactor policy.
`get_refactor_policy`(self)	Return the current Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`): when the linear solver does a cheaper `refactorize()` instead of a full `factorize()`.
`get_scaling_policy_type`(self)	Return the current step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`): how the Newton-Raphson step is scaled down before being applied, if at all.
`get_theta_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-angle (theta) unknown, or `-1` if that bus has none (eg the slack bus, or a PQ-only DC solve).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`get_vm_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-magnitude (Vm) unknown, or `-1` if that bus has none (eg a PV bus).
`reset`(self)	Reset the solver.
`set_config`(self, config)	Restore every scaling/refactor policy type and parameter from a `lightsim2grid.algorithm.AlgoConfig` previously obtained from `get_config()`.
`set_iw_mu_max`(self, value)	Set `get_iw_mu_max()`.
`set_iw_mu_min`(self, value)	Set `get_iw_mu_min()`.
`set_ls_c`(self, value)	Set `get_ls_c()`.
`set_ls_max_iter`(self, value)	Set `get_ls_max_iter()`.
`set_ls_rho`(self, value)	Set `get_ls_rho()`.
`set_max_dVa`(self, value)	Set `get_max_dVa()`.
`set_max_dVm`(self, value)	Set `get_max_dVm()`.
`set_refactor_every_n`(self, value)	Set `get_refactor_every_n()`.
`set_refactor_policy`(self, policy)	Set the Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`).
`set_scaling_policy`(self, policy)	Set the step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`).
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → bool: Returns whether or not the solver has converged or not.

get_J(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → scipy.sparse.csc_matrix[numpy.float64]

Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.

The “jacobian” matrix is only available for some powerflow (the one based on the Newton Raphson algorithm) and we provide it only for the last computed iteration.

Note

It is using the “solver” labelling, as this is accessed from the solvers. Unlike get_Va()/get_Vm(), the Jacobian has no “gridmodel” labelled equivalent on lightsim2grid.network.LSGrid – only lightsim2grid.network.LSGrid.get_J_solver(), which keeps the solver labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_J_solver()

get_V(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_config(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → ls2g::AlgoConfig: Return a lightsim2grid.algorithm.AlgoConfig capturing every scaling/refactor policy type and parameter above, as a single serializable object.

See also

set_config() to restore it; going through a LightSimBackend instead of a raw solver object, see lightsim2grid.lightSimBackend.LightSimBackend.get_ac_algo_config().

get_error(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → float: Maximum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → float: Minimum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → float: Armijo sufficient-decrease constant c for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → int: Maximum number of backtracking iterations for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → float: Backtracking factor rho (in (0, 1)) for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → float: Maximum voltage angle step (radian) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → float: Maximum voltage magnitude step (pu) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_q_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s reactive-power (Q) unknown – currently always -1: no solver in this version stamps a reactive-power unknown as its own Jacobian column.

get_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → int: Refactorize (full factorize(), not the cheaper refactorize()) every N-th iteration, for the EveryN refactor policy. Only read while that policy is active (see set_refactor_policy()).

get_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → lightsim2grid.lightsim2grid_cpp.RefactorPolicyType: Return the current Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType): when the linear solver does a cheaper refactorize() instead of a full factorize().

get_scaling_policy_type(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → lightsim2grid.lightsim2grid_cpp.ScalingPolicyType: Return the current step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType): how the Newton-Raphson step is scaled down before being applied, if at all.

get_theta_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-angle (theta) unknown, or -1 if that bus has none (eg the slack bus, or a PQ-only DC solve). Only valid after a powerflow has been run.

get_timers(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

get_vm_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-magnitude (Vm) unknown, or -1 if that bus has none (eg a PV bus). Only valid after a powerflow has been run.

reset(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

set_config(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, config: ls2g::AlgoConfig) → None: Restore every scaling/refactor policy type and parameter from a lightsim2grid.algorithm.AlgoConfig previously obtained from get_config().

set_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_max().

set_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_min().

set_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_ls_c().

set_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, value: SupportsInt | SupportsIndex) → None: Set get_ls_max_iter().

set_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_ls_rho().

set_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVa().

set_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVm().

set_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, value: SupportsInt | SupportsIndex) → None: Set get_refactor_every_n().

set_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, policy: lightsim2grid.lightsim2grid_cpp.RefactorPolicyType) → None: Set the Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType). set_refactor_every_n() is only read by the EveryN policy.

set_scaling_policy(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, policy: lightsim2grid.lightsim2grid_cpp.ScalingPolicyType) → None: Set the step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType). The per-policy parameters below (set_max_dVa()/set_max_dVm(), set_ls_c()/ set_ls_rho()/set_ls_max_iter(), set_iw_mu_min()/set_iw_mu_max()) are only read by their corresponding policy; changing them has no effect while a different policy is active.

solve(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_CKTSO, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.NRRefactorRetry_KLU

Same as lightsim2grid.algorithm.NR_KLU (Newton Raphson, distributed slack, KLU linear solver), except that if a Jacobian refactorize() fails it falls back to a full factorize() (reusing the existing symbolic factorization) before giving up, rather than reporting an error immediately.

Use get_linear_solver_stats() on the solver to inspect how often factor/refactor calls happen and how often the fallback fires (see lightsim2grid.algorithm.LinearSolverStats).

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_J`(self)	Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_config`(self)	Return a `lightsim2grid.algorithm.AlgoConfig` capturing every scaling/refactor policy type and parameter above, as a single serializable object.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_iw_mu_max`(self)	Maximum optimal multiplier for the `Iwamoto` scaling policy.
`get_iw_mu_min`(self)	Minimum optimal multiplier for the `Iwamoto` scaling policy.
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_ls_c`(self)	Armijo sufficient-decrease constant `c` for the `LineSearch` scaling policy.
`get_ls_max_iter`(self)	Maximum number of backtracking iterations for the `LineSearch` scaling policy.
`get_ls_rho`(self)	Backtracking factor `rho` (in `(0, 1)`) for the `LineSearch` scaling policy.
`get_max_dVa`(self)	Maximum voltage angle step (radian) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_max_dVm`(self)	Maximum voltage magnitude step (pu) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_q_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's reactive-power (Q) unknown -- currently always `-1`: no solver in this version stamps a reactive-power unknown as its own Jacobian column.
`get_refactor_every_n`(self)	Refactorize (full `factorize()`, not the cheaper `refactorize()`) every N-th iteration, for the `EveryN` refactor policy.
`get_refactor_policy`(self)	Return the current Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`): when the linear solver does a cheaper `refactorize()` instead of a full `factorize()`.
`get_scaling_policy_type`(self)	Return the current step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`): how the Newton-Raphson step is scaled down before being applied, if at all.
`get_theta_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-angle (theta) unknown, or `-1` if that bus has none (eg the slack bus, or a PQ-only DC solve).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`get_vm_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-magnitude (Vm) unknown, or `-1` if that bus has none (eg a PV bus).
`reset`(self)	Reset the solver.
`set_config`(self, config)	Restore every scaling/refactor policy type and parameter from a `lightsim2grid.algorithm.AlgoConfig` previously obtained from `get_config()`.
`set_iw_mu_max`(self, value)	Set `get_iw_mu_max()`.
`set_iw_mu_min`(self, value)	Set `get_iw_mu_min()`.
`set_ls_c`(self, value)	Set `get_ls_c()`.
`set_ls_max_iter`(self, value)	Set `get_ls_max_iter()`.
`set_ls_rho`(self, value)	Set `get_ls_rho()`.
`set_max_dVa`(self, value)	Set `get_max_dVa()`.
`set_max_dVm`(self, value)	Set `get_max_dVm()`.
`set_refactor_every_n`(self, value)	Set `get_refactor_every_n()`.
`set_refactor_policy`(self, policy)	Set the Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`).
`set_scaling_policy`(self, policy)	Set the step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`).
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → bool: Returns whether or not the solver has converged or not.

get_J(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → scipy.sparse.csc_matrix[numpy.float64]

Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.

The “jacobian” matrix is only available for some powerflow (the one based on the Newton Raphson algorithm) and we provide it only for the last computed iteration.

Note

It is using the “solver” labelling, as this is accessed from the solvers. Unlike get_Va()/get_Vm(), the Jacobian has no “gridmodel” labelled equivalent on lightsim2grid.network.LSGrid – only lightsim2grid.network.LSGrid.get_J_solver(), which keeps the solver labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_J_solver()

get_V(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_config(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → ls2g::AlgoConfig: Return a lightsim2grid.algorithm.AlgoConfig capturing every scaling/refactor policy type and parameter above, as a single serializable object.

See also

set_config() to restore it; going through a LightSimBackend instead of a raw solver object, see lightsim2grid.lightSimBackend.LightSimBackend.get_ac_algo_config().

get_error(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → float: Maximum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → float: Minimum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → float: Armijo sufficient-decrease constant c for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → int: Maximum number of backtracking iterations for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → float: Backtracking factor rho (in (0, 1)) for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → float: Maximum voltage angle step (radian) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → float: Maximum voltage magnitude step (pu) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_q_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s reactive-power (Q) unknown – currently always -1: no solver in this version stamps a reactive-power unknown as its own Jacobian column.

get_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → int: Refactorize (full factorize(), not the cheaper refactorize()) every N-th iteration, for the EveryN refactor policy. Only read while that policy is active (see set_refactor_policy()).

get_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → lightsim2grid.lightsim2grid_cpp.RefactorPolicyType: Return the current Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType): when the linear solver does a cheaper refactorize() instead of a full factorize().

get_scaling_policy_type(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → lightsim2grid.lightsim2grid_cpp.ScalingPolicyType: Return the current step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType): how the Newton-Raphson step is scaled down before being applied, if at all.

get_theta_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-angle (theta) unknown, or -1 if that bus has none (eg the slack bus, or a PQ-only DC solve). Only valid after a powerflow has been run.

get_timers(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

get_vm_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-magnitude (Vm) unknown, or -1 if that bus has none (eg a PV bus). Only valid after a powerflow has been run.

reset(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

set_config(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, config: ls2g::AlgoConfig) → None: Restore every scaling/refactor policy type and parameter from a lightsim2grid.algorithm.AlgoConfig previously obtained from get_config().

set_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_max().

set_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_min().

set_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_c().

set_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, value: SupportsInt | SupportsIndex) → None: Set get_ls_max_iter().

set_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_rho().

set_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVa().

set_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVm().

set_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, value: SupportsInt | SupportsIndex) → None: Set get_refactor_every_n().

set_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, policy: lightsim2grid.lightsim2grid_cpp.RefactorPolicyType) → None: Set the Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType). set_refactor_every_n() is only read by the EveryN policy.

set_scaling_policy(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, policy: lightsim2grid.lightsim2grid_cpp.ScalingPolicyType) → None: Set the step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType). The per-policy parameters below (set_max_dVa()/set_max_dVm(), set_ls_c()/ set_ls_rho()/set_ls_max_iter(), set_iw_mu_min()/set_iw_mu_max()) are only read by their corresponding policy; changing them has no effect while a different policy is active.

solve(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_KLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.NRRefactorRetry_NICSLU

Same as lightsim2grid.algorithm.NR_NICSLU (Newton Raphson, distributed slack, NICSLU linear solver), except that if a Jacobian refactorize() fails it falls back to a full factorize() before giving up, rather than reporting an error immediately. For NICSLU, factorize() and refactorize() call the same underlying routine, so this fallback is effectively a no-op retry – included mainly for API symmetry with lightsim2grid.algorithm.NRRefactorRetry_KLU and lightsim2grid.algorithm.NRRefactorRetry_CKTSO.

Use get_linear_solver_stats() on the solver to inspect how often factor/refactor calls happen and how often the fallback fires (see lightsim2grid.algorithm.LinearSolverStats).

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_J`(self)	Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_config`(self)	Return a `lightsim2grid.algorithm.AlgoConfig` capturing every scaling/refactor policy type and parameter above, as a single serializable object.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_iw_mu_max`(self)	Maximum optimal multiplier for the `Iwamoto` scaling policy.
`get_iw_mu_min`(self)	Minimum optimal multiplier for the `Iwamoto` scaling policy.
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_ls_c`(self)	Armijo sufficient-decrease constant `c` for the `LineSearch` scaling policy.
`get_ls_max_iter`(self)	Maximum number of backtracking iterations for the `LineSearch` scaling policy.
`get_ls_rho`(self)	Backtracking factor `rho` (in `(0, 1)`) for the `LineSearch` scaling policy.
`get_max_dVa`(self)	Maximum voltage angle step (radian) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_max_dVm`(self)	Maximum voltage magnitude step (pu) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_q_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's reactive-power (Q) unknown -- currently always `-1`: no solver in this version stamps a reactive-power unknown as its own Jacobian column.
`get_refactor_every_n`(self)	Refactorize (full `factorize()`, not the cheaper `refactorize()`) every N-th iteration, for the `EveryN` refactor policy.
`get_refactor_policy`(self)	Return the current Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`): when the linear solver does a cheaper `refactorize()` instead of a full `factorize()`.
`get_scaling_policy_type`(self)	Return the current step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`): how the Newton-Raphson step is scaled down before being applied, if at all.
`get_theta_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-angle (theta) unknown, or `-1` if that bus has none (eg the slack bus, or a PQ-only DC solve).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`get_vm_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-magnitude (Vm) unknown, or `-1` if that bus has none (eg a PV bus).
`reset`(self)	Reset the solver.
`set_config`(self, config)	Restore every scaling/refactor policy type and parameter from a `lightsim2grid.algorithm.AlgoConfig` previously obtained from `get_config()`.
`set_iw_mu_max`(self, value)	Set `get_iw_mu_max()`.
`set_iw_mu_min`(self, value)	Set `get_iw_mu_min()`.
`set_ls_c`(self, value)	Set `get_ls_c()`.
`set_ls_max_iter`(self, value)	Set `get_ls_max_iter()`.
`set_ls_rho`(self, value)	Set `get_ls_rho()`.
`set_max_dVa`(self, value)	Set `get_max_dVa()`.
`set_max_dVm`(self, value)	Set `get_max_dVm()`.
`set_refactor_every_n`(self, value)	Set `get_refactor_every_n()`.
`set_refactor_policy`(self, policy)	Set the Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`).
`set_scaling_policy`(self, policy)	Set the step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`).
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → bool: Returns whether or not the solver has converged or not.

get_J(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → scipy.sparse.csc_matrix[numpy.float64]

Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.

The “jacobian” matrix is only available for some powerflow (the one based on the Newton Raphson algorithm) and we provide it only for the last computed iteration.

Note

It is using the “solver” labelling, as this is accessed from the solvers. Unlike get_Va()/get_Vm(), the Jacobian has no “gridmodel” labelled equivalent on lightsim2grid.network.LSGrid – only lightsim2grid.network.LSGrid.get_J_solver(), which keeps the solver labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_J_solver()

get_V(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_config(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → ls2g::AlgoConfig: Return a lightsim2grid.algorithm.AlgoConfig capturing every scaling/refactor policy type and parameter above, as a single serializable object.

See also

set_config() to restore it; going through a LightSimBackend instead of a raw solver object, see lightsim2grid.lightSimBackend.LightSimBackend.get_ac_algo_config().

get_error(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → float: Maximum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → float: Minimum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → float: Armijo sufficient-decrease constant c for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → int: Maximum number of backtracking iterations for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → float: Backtracking factor rho (in (0, 1)) for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → float: Maximum voltage angle step (radian) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → float: Maximum voltage magnitude step (pu) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_q_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s reactive-power (Q) unknown – currently always -1: no solver in this version stamps a reactive-power unknown as its own Jacobian column.

get_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → int: Refactorize (full factorize(), not the cheaper refactorize()) every N-th iteration, for the EveryN refactor policy. Only read while that policy is active (see set_refactor_policy()).

get_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → lightsim2grid.lightsim2grid_cpp.RefactorPolicyType: Return the current Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType): when the linear solver does a cheaper refactorize() instead of a full factorize().

get_scaling_policy_type(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → lightsim2grid.lightsim2grid_cpp.ScalingPolicyType: Return the current step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType): how the Newton-Raphson step is scaled down before being applied, if at all.

get_theta_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-angle (theta) unknown, or -1 if that bus has none (eg the slack bus, or a PQ-only DC solve). Only valid after a powerflow has been run.

get_timers(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

get_vm_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-magnitude (Vm) unknown, or -1 if that bus has none (eg a PV bus). Only valid after a powerflow has been run.

reset(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

set_config(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, config: ls2g::AlgoConfig) → None: Restore every scaling/refactor policy type and parameter from a lightsim2grid.algorithm.AlgoConfig previously obtained from get_config().

set_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_max().

set_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_min().

set_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_c().

set_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, value: SupportsInt | SupportsIndex) → None: Set get_ls_max_iter().

set_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_rho().

set_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVa().

set_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVm().

set_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, value: SupportsInt | SupportsIndex) → None: Set get_refactor_every_n().

set_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, policy: lightsim2grid.lightsim2grid_cpp.RefactorPolicyType) → None: Set the Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType). set_refactor_every_n() is only read by the EveryN policy.

set_scaling_policy(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, policy: lightsim2grid.lightsim2grid_cpp.ScalingPolicyType) → None: Set the step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType). The per-policy parameters below (set_max_dVa()/set_max_dVm(), set_ls_c()/ set_ls_rho()/set_ls_max_iter(), set_iw_mu_min()/set_iw_mu_max()) are only read by their corresponding policy; changing them has no effect while a different policy is active.

solve(self: lightsim2grid.lightsim2grid_cpp.NRRefactorRetry_NICSLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.NRSing_CKTSO

This classes implements the Newton Raphson algorithm, the faster CKTSO solver available in the CKTSO library for the linear algebra. It does not support the distributed slack, but can be slightly faster than the lightsim2grid.algorithm.NR_CKTSO .

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called NRSing_CKTSO

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.NRSing_CKTSO) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.NRSing_CKTSO) at creation time

Note

CKTSO is available at https://github.com/chenxm1986/cktso

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_J`(self)	Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_config`(self)	Return a `lightsim2grid.algorithm.AlgoConfig` capturing every scaling/refactor policy type and parameter above, as a single serializable object.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_iw_mu_max`(self)	Maximum optimal multiplier for the `Iwamoto` scaling policy.
`get_iw_mu_min`(self)	Minimum optimal multiplier for the `Iwamoto` scaling policy.
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_ls_c`(self)	Armijo sufficient-decrease constant `c` for the `LineSearch` scaling policy.
`get_ls_max_iter`(self)	Maximum number of backtracking iterations for the `LineSearch` scaling policy.
`get_ls_rho`(self)	Backtracking factor `rho` (in `(0, 1)`) for the `LineSearch` scaling policy.
`get_max_dVa`(self)	Maximum voltage angle step (radian) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_max_dVm`(self)	Maximum voltage magnitude step (pu) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_q_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's reactive-power (Q) unknown -- currently always `-1`: no solver in this version stamps a reactive-power unknown as its own Jacobian column.
`get_refactor_every_n`(self)	Refactorize (full `factorize()`, not the cheaper `refactorize()`) every N-th iteration, for the `EveryN` refactor policy.
`get_refactor_policy`(self)	Return the current Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`): when the linear solver does a cheaper `refactorize()` instead of a full `factorize()`.
`get_scaling_policy_type`(self)	Return the current step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`): how the Newton-Raphson step is scaled down before being applied, if at all.
`get_theta_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-angle (theta) unknown, or `-1` if that bus has none (eg the slack bus, or a PQ-only DC solve).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`get_vm_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-magnitude (Vm) unknown, or `-1` if that bus has none (eg a PV bus).
`reset`(self)	Reset the solver.
`set_config`(self, config)	Restore every scaling/refactor policy type and parameter from a `lightsim2grid.algorithm.AlgoConfig` previously obtained from `get_config()`.
`set_iw_mu_max`(self, value)	Set `get_iw_mu_max()`.
`set_iw_mu_min`(self, value)	Set `get_iw_mu_min()`.
`set_ls_c`(self, value)	Set `get_ls_c()`.
`set_ls_max_iter`(self, value)	Set `get_ls_max_iter()`.
`set_ls_rho`(self, value)	Set `get_ls_rho()`.
`set_max_dVa`(self, value)	Set `get_max_dVa()`.
`set_max_dVm`(self, value)	Set `get_max_dVm()`.
`set_refactor_every_n`(self, value)	Set `get_refactor_every_n()`.
`set_refactor_policy`(self, policy)	Set the Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`).
`set_scaling_policy`(self, policy)	Set the step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`).
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → bool: Returns whether or not the solver has converged or not.

get_J(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → scipy.sparse.csc_matrix[numpy.float64]

Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.

The “jacobian” matrix is only available for some powerflow (the one based on the Newton Raphson algorithm) and we provide it only for the last computed iteration.

Note

It is using the “solver” labelling, as this is accessed from the solvers. Unlike get_Va()/get_Vm(), the Jacobian has no “gridmodel” labelled equivalent on lightsim2grid.network.LSGrid – only lightsim2grid.network.LSGrid.get_J_solver(), which keeps the solver labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_J_solver()

get_V(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_config(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → ls2g::AlgoConfig: Return a lightsim2grid.algorithm.AlgoConfig capturing every scaling/refactor policy type and parameter above, as a single serializable object.

See also

set_config() to restore it; going through a LightSimBackend instead of a raw solver object, see lightsim2grid.lightSimBackend.LightSimBackend.get_ac_algo_config().

get_error(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → float: Maximum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → float: Minimum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → float: Armijo sufficient-decrease constant c for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → int: Maximum number of backtracking iterations for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → float: Backtracking factor rho (in (0, 1)) for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → float: Maximum voltage angle step (radian) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → float: Maximum voltage magnitude step (pu) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_q_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s reactive-power (Q) unknown – currently always -1: no solver in this version stamps a reactive-power unknown as its own Jacobian column.

get_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → int: Refactorize (full factorize(), not the cheaper refactorize()) every N-th iteration, for the EveryN refactor policy. Only read while that policy is active (see set_refactor_policy()).

get_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → lightsim2grid.lightsim2grid_cpp.RefactorPolicyType: Return the current Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType): when the linear solver does a cheaper refactorize() instead of a full factorize().

get_scaling_policy_type(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → lightsim2grid.lightsim2grid_cpp.ScalingPolicyType: Return the current step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType): how the Newton-Raphson step is scaled down before being applied, if at all.

get_theta_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-angle (theta) unknown, or -1 if that bus has none (eg the slack bus, or a PQ-only DC solve). Only valid after a powerflow has been run.

get_timers(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

get_vm_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-magnitude (Vm) unknown, or -1 if that bus has none (eg a PV bus). Only valid after a powerflow has been run.

reset(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

set_config(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, config: ls2g::AlgoConfig) → None: Restore every scaling/refactor policy type and parameter from a lightsim2grid.algorithm.AlgoConfig previously obtained from get_config().

set_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_max().

set_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_min().

set_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_ls_c().

set_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, value: SupportsInt | SupportsIndex) → None: Set get_ls_max_iter().

set_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_ls_rho().

set_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVa().

set_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVm().

set_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, value: SupportsInt | SupportsIndex) → None: Set get_refactor_every_n().

set_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, policy: lightsim2grid.lightsim2grid_cpp.RefactorPolicyType) → None: Set the Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType). set_refactor_every_n() is only read by the EveryN policy.

set_scaling_policy(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, policy: lightsim2grid.lightsim2grid_cpp.ScalingPolicyType) → None: Set the step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType). The per-policy parameters below (set_max_dVa()/set_max_dVm(), set_ls_c()/ set_ls_rho()/set_ls_max_iter(), set_iw_mu_min()/set_iw_mu_max()) are only read by their corresponding policy; changing them has no effect while a different policy is active.

solve(self: lightsim2grid.lightsim2grid_cpp.NRSing_CKTSO, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.NRSing_KLU

This classes implements the Newton Raphson algorithm,the faster KLU solver available in the SuiteSparse library for the linear algebra. It does not support the distributed slack, but can be slightly faster than the lightsim2grid.algorithm.NR_KLU.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called NRSing_KLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.NRSing_KLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.NRSing_KLU) at creation time

Note

This is the default solver used when available.

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_J`(self)	Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_config`(self)	Return a `lightsim2grid.algorithm.AlgoConfig` capturing every scaling/refactor policy type and parameter above, as a single serializable object.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_iw_mu_max`(self)	Maximum optimal multiplier for the `Iwamoto` scaling policy.
`get_iw_mu_min`(self)	Minimum optimal multiplier for the `Iwamoto` scaling policy.
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_ls_c`(self)	Armijo sufficient-decrease constant `c` for the `LineSearch` scaling policy.
`get_ls_max_iter`(self)	Maximum number of backtracking iterations for the `LineSearch` scaling policy.
`get_ls_rho`(self)	Backtracking factor `rho` (in `(0, 1)`) for the `LineSearch` scaling policy.
`get_max_dVa`(self)	Maximum voltage angle step (radian) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_max_dVm`(self)	Maximum voltage magnitude step (pu) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_q_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's reactive-power (Q) unknown -- currently always `-1`: no solver in this version stamps a reactive-power unknown as its own Jacobian column.
`get_refactor_every_n`(self)	Refactorize (full `factorize()`, not the cheaper `refactorize()`) every N-th iteration, for the `EveryN` refactor policy.
`get_refactor_policy`(self)	Return the current Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`): when the linear solver does a cheaper `refactorize()` instead of a full `factorize()`.
`get_scaling_policy_type`(self)	Return the current step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`): how the Newton-Raphson step is scaled down before being applied, if at all.
`get_theta_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-angle (theta) unknown, or `-1` if that bus has none (eg the slack bus, or a PQ-only DC solve).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`get_vm_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-magnitude (Vm) unknown, or `-1` if that bus has none (eg a PV bus).
`reset`(self)	Reset the solver.
`set_config`(self, config)	Restore every scaling/refactor policy type and parameter from a `lightsim2grid.algorithm.AlgoConfig` previously obtained from `get_config()`.
`set_iw_mu_max`(self, value)	Set `get_iw_mu_max()`.
`set_iw_mu_min`(self, value)	Set `get_iw_mu_min()`.
`set_ls_c`(self, value)	Set `get_ls_c()`.
`set_ls_max_iter`(self, value)	Set `get_ls_max_iter()`.
`set_ls_rho`(self, value)	Set `get_ls_rho()`.
`set_max_dVa`(self, value)	Set `get_max_dVa()`.
`set_max_dVm`(self, value)	Set `get_max_dVm()`.
`set_refactor_every_n`(self, value)	Set `get_refactor_every_n()`.
`set_refactor_policy`(self, policy)	Set the Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`).
`set_scaling_policy`(self, policy)	Set the step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`).
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → bool: Returns whether or not the solver has converged or not.

get_J(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → scipy.sparse.csc_matrix[numpy.float64]

Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.

The “jacobian” matrix is only available for some powerflow (the one based on the Newton Raphson algorithm) and we provide it only for the last computed iteration.

Note

It is using the “solver” labelling, as this is accessed from the solvers. Unlike get_Va()/get_Vm(), the Jacobian has no “gridmodel” labelled equivalent on lightsim2grid.network.LSGrid – only lightsim2grid.network.LSGrid.get_J_solver(), which keeps the solver labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_J_solver()

get_V(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_config(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → ls2g::AlgoConfig: Return a lightsim2grid.algorithm.AlgoConfig capturing every scaling/refactor policy type and parameter above, as a single serializable object.

See also

set_config() to restore it; going through a LightSimBackend instead of a raw solver object, see lightsim2grid.lightSimBackend.LightSimBackend.get_ac_algo_config().

get_error(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → float: Maximum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → float: Minimum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → float: Armijo sufficient-decrease constant c for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → int: Maximum number of backtracking iterations for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → float: Backtracking factor rho (in (0, 1)) for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → float: Maximum voltage angle step (radian) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → float: Maximum voltage magnitude step (pu) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_q_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s reactive-power (Q) unknown – currently always -1: no solver in this version stamps a reactive-power unknown as its own Jacobian column.

get_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → int: Refactorize (full factorize(), not the cheaper refactorize()) every N-th iteration, for the EveryN refactor policy. Only read while that policy is active (see set_refactor_policy()).

get_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → lightsim2grid.lightsim2grid_cpp.RefactorPolicyType: Return the current Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType): when the linear solver does a cheaper refactorize() instead of a full factorize().

get_scaling_policy_type(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → lightsim2grid.lightsim2grid_cpp.ScalingPolicyType: Return the current step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType): how the Newton-Raphson step is scaled down before being applied, if at all.

get_theta_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-angle (theta) unknown, or -1 if that bus has none (eg the slack bus, or a PQ-only DC solve). Only valid after a powerflow has been run.

get_timers(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

get_vm_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-magnitude (Vm) unknown, or -1 if that bus has none (eg a PV bus). Only valid after a powerflow has been run.

reset(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

set_config(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, config: ls2g::AlgoConfig) → None: Restore every scaling/refactor policy type and parameter from a lightsim2grid.algorithm.AlgoConfig previously obtained from get_config().

set_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_max().

set_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_min().

set_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_c().

set_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, value: SupportsInt | SupportsIndex) → None: Set get_ls_max_iter().

set_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_rho().

set_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVa().

set_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVm().

set_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, value: SupportsInt | SupportsIndex) → None: Set get_refactor_every_n().

set_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, policy: lightsim2grid.lightsim2grid_cpp.RefactorPolicyType) → None: Set the Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType). set_refactor_every_n() is only read by the EveryN policy.

set_scaling_policy(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, policy: lightsim2grid.lightsim2grid_cpp.ScalingPolicyType) → None: Set the step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType). The per-policy parameters below (set_max_dVa()/set_max_dVm(), set_ls_c()/ set_ls_rho()/set_ls_max_iter(), set_iw_mu_min()/set_iw_mu_max()) are only read by their corresponding policy; changing them has no effect while a different policy is active.

solve(self: lightsim2grid.lightsim2grid_cpp.NRSing_KLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.NRSing_NICSLU

This classes implements the Newton Raphson algorithm, the faster NICSLU solver available in the NICSLU library for the linear algebra. It does not support the distributed slack, but can be slightly faster than the lightsim2grid.algorithm.NR_NICSLU .

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called NRSing_NICSLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.NRSing_NICSLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.NRSing_NICSLU) at creation time

Warning

Use this solver requires a compilation of lightsim2grid from source (see readme) AND an appropriate license for nicslu.

Note

NICSLU is available at https://github.com/chenxm1986/nicslu

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_J`(self)	Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_config`(self)	Return a `lightsim2grid.algorithm.AlgoConfig` capturing every scaling/refactor policy type and parameter above, as a single serializable object.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_iw_mu_max`(self)	Maximum optimal multiplier for the `Iwamoto` scaling policy.
`get_iw_mu_min`(self)	Minimum optimal multiplier for the `Iwamoto` scaling policy.
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_ls_c`(self)	Armijo sufficient-decrease constant `c` for the `LineSearch` scaling policy.
`get_ls_max_iter`(self)	Maximum number of backtracking iterations for the `LineSearch` scaling policy.
`get_ls_rho`(self)	Backtracking factor `rho` (in `(0, 1)`) for the `LineSearch` scaling policy.
`get_max_dVa`(self)	Maximum voltage angle step (radian) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_max_dVm`(self)	Maximum voltage magnitude step (pu) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_q_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's reactive-power (Q) unknown -- currently always `-1`: no solver in this version stamps a reactive-power unknown as its own Jacobian column.
`get_refactor_every_n`(self)	Refactorize (full `factorize()`, not the cheaper `refactorize()`) every N-th iteration, for the `EveryN` refactor policy.
`get_refactor_policy`(self)	Return the current Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`): when the linear solver does a cheaper `refactorize()` instead of a full `factorize()`.
`get_scaling_policy_type`(self)	Return the current step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`): how the Newton-Raphson step is scaled down before being applied, if at all.
`get_theta_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-angle (theta) unknown, or `-1` if that bus has none (eg the slack bus, or a PQ-only DC solve).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`get_vm_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-magnitude (Vm) unknown, or `-1` if that bus has none (eg a PV bus).
`reset`(self)	Reset the solver.
`set_config`(self, config)	Restore every scaling/refactor policy type and parameter from a `lightsim2grid.algorithm.AlgoConfig` previously obtained from `get_config()`.
`set_iw_mu_max`(self, value)	Set `get_iw_mu_max()`.
`set_iw_mu_min`(self, value)	Set `get_iw_mu_min()`.
`set_ls_c`(self, value)	Set `get_ls_c()`.
`set_ls_max_iter`(self, value)	Set `get_ls_max_iter()`.
`set_ls_rho`(self, value)	Set `get_ls_rho()`.
`set_max_dVa`(self, value)	Set `get_max_dVa()`.
`set_max_dVm`(self, value)	Set `get_max_dVm()`.
`set_refactor_every_n`(self, value)	Set `get_refactor_every_n()`.
`set_refactor_policy`(self, policy)	Set the Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`).
`set_scaling_policy`(self, policy)	Set the step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`).
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → bool: Returns whether or not the solver has converged or not.

get_J(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → scipy.sparse.csc_matrix[numpy.float64]

Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.

The “jacobian” matrix is only available for some powerflow (the one based on the Newton Raphson algorithm) and we provide it only for the last computed iteration.

Note

It is using the “solver” labelling, as this is accessed from the solvers. Unlike get_Va()/get_Vm(), the Jacobian has no “gridmodel” labelled equivalent on lightsim2grid.network.LSGrid – only lightsim2grid.network.LSGrid.get_J_solver(), which keeps the solver labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_J_solver()

get_V(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_config(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → ls2g::AlgoConfig: Return a lightsim2grid.algorithm.AlgoConfig capturing every scaling/refactor policy type and parameter above, as a single serializable object.

See also

set_config() to restore it; going through a LightSimBackend instead of a raw solver object, see lightsim2grid.lightSimBackend.LightSimBackend.get_ac_algo_config().

get_error(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → float: Maximum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → float: Minimum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → float: Armijo sufficient-decrease constant c for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → int: Maximum number of backtracking iterations for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → float: Backtracking factor rho (in (0, 1)) for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → float: Maximum voltage angle step (radian) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → float: Maximum voltage magnitude step (pu) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_q_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s reactive-power (Q) unknown – currently always -1: no solver in this version stamps a reactive-power unknown as its own Jacobian column.

get_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → int: Refactorize (full factorize(), not the cheaper refactorize()) every N-th iteration, for the EveryN refactor policy. Only read while that policy is active (see set_refactor_policy()).

get_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → lightsim2grid.lightsim2grid_cpp.RefactorPolicyType: Return the current Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType): when the linear solver does a cheaper refactorize() instead of a full factorize().

get_scaling_policy_type(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → lightsim2grid.lightsim2grid_cpp.ScalingPolicyType: Return the current step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType): how the Newton-Raphson step is scaled down before being applied, if at all.

get_theta_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-angle (theta) unknown, or -1 if that bus has none (eg the slack bus, or a PQ-only DC solve). Only valid after a powerflow has been run.

get_timers(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

get_vm_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-magnitude (Vm) unknown, or -1 if that bus has none (eg a PV bus). Only valid after a powerflow has been run.

reset(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

set_config(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, config: ls2g::AlgoConfig) → None: Restore every scaling/refactor policy type and parameter from a lightsim2grid.algorithm.AlgoConfig previously obtained from get_config().

set_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_max().

set_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_min().

set_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_c().

set_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, value: SupportsInt | SupportsIndex) → None: Set get_ls_max_iter().

set_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_rho().

set_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVa().

set_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVm().

set_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, value: SupportsInt | SupportsIndex) → None: Set get_refactor_every_n().

set_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, policy: lightsim2grid.lightsim2grid_cpp.RefactorPolicyType) → None: Set the Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType). set_refactor_every_n() is only read by the EveryN policy.

set_scaling_policy(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, policy: lightsim2grid.lightsim2grid_cpp.ScalingPolicyType) → None: Set the step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType). The per-policy parameters below (set_max_dVa()/set_max_dVm(), set_ls_c()/ set_ls_rho()/set_ls_max_iter(), set_iw_mu_min()/set_iw_mu_max()) are only read by their corresponding policy; changing them has no effect while a different policy is active.

solve(self: lightsim2grid.lightsim2grid_cpp.NRSing_NICSLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.NRSing_SparseLU

This classes implements the Newton Raphson algorithm, using the default Eigen sparse solver available in Eigen for the linear algebra. It does not support the distributed slack, but can be slightly faster than the lightsim2grid.algorithm.NR_SparseLU .

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called NRSing_SparseLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.NRSing_SparseLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.NRSing_SparseLU) at creation time

Note

Available on all plateform, this is the default solver used when a distributed slack bus is detected and lightsim2grid.algorithm.NR_KLU is not found.

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_J`(self)	Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_config`(self)	Return a `lightsim2grid.algorithm.AlgoConfig` capturing every scaling/refactor policy type and parameter above, as a single serializable object.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_iw_mu_max`(self)	Maximum optimal multiplier for the `Iwamoto` scaling policy.
`get_iw_mu_min`(self)	Minimum optimal multiplier for the `Iwamoto` scaling policy.
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_ls_c`(self)	Armijo sufficient-decrease constant `c` for the `LineSearch` scaling policy.
`get_ls_max_iter`(self)	Maximum number of backtracking iterations for the `LineSearch` scaling policy.
`get_ls_rho`(self)	Backtracking factor `rho` (in `(0, 1)`) for the `LineSearch` scaling policy.
`get_max_dVa`(self)	Maximum voltage angle step (radian) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_max_dVm`(self)	Maximum voltage magnitude step (pu) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_q_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's reactive-power (Q) unknown -- currently always `-1`: no solver in this version stamps a reactive-power unknown as its own Jacobian column.
`get_refactor_every_n`(self)	Refactorize (full `factorize()`, not the cheaper `refactorize()`) every N-th iteration, for the `EveryN` refactor policy.
`get_refactor_policy`(self)	Return the current Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`): when the linear solver does a cheaper `refactorize()` instead of a full `factorize()`.
`get_scaling_policy_type`(self)	Return the current step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`): how the Newton-Raphson step is scaled down before being applied, if at all.
`get_theta_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-angle (theta) unknown, or `-1` if that bus has none (eg the slack bus, or a PQ-only DC solve).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`get_vm_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-magnitude (Vm) unknown, or `-1` if that bus has none (eg a PV bus).
`reset`(self)	Reset the solver.
`set_config`(self, config)	Restore every scaling/refactor policy type and parameter from a `lightsim2grid.algorithm.AlgoConfig` previously obtained from `get_config()`.
`set_iw_mu_max`(self, value)	Set `get_iw_mu_max()`.
`set_iw_mu_min`(self, value)	Set `get_iw_mu_min()`.
`set_ls_c`(self, value)	Set `get_ls_c()`.
`set_ls_max_iter`(self, value)	Set `get_ls_max_iter()`.
`set_ls_rho`(self, value)	Set `get_ls_rho()`.
`set_max_dVa`(self, value)	Set `get_max_dVa()`.
`set_max_dVm`(self, value)	Set `get_max_dVm()`.
`set_refactor_every_n`(self, value)	Set `get_refactor_every_n()`.
`set_refactor_policy`(self, policy)	Set the Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`).
`set_scaling_policy`(self, policy)	Set the step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`).
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → bool: Returns whether or not the solver has converged or not.

get_J(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → scipy.sparse.csc_matrix[numpy.float64]

Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.

The “jacobian” matrix is only available for some powerflow (the one based on the Newton Raphson algorithm) and we provide it only for the last computed iteration.

Note

It is using the “solver” labelling, as this is accessed from the solvers. Unlike get_Va()/get_Vm(), the Jacobian has no “gridmodel” labelled equivalent on lightsim2grid.network.LSGrid – only lightsim2grid.network.LSGrid.get_J_solver(), which keeps the solver labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_J_solver()

get_V(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_config(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → ls2g::AlgoConfig: Return a lightsim2grid.algorithm.AlgoConfig capturing every scaling/refactor policy type and parameter above, as a single serializable object.

See also

set_config() to restore it; going through a LightSimBackend instead of a raw solver object, see lightsim2grid.lightSimBackend.LightSimBackend.get_ac_algo_config().

get_error(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → float: Maximum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → float: Minimum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → float: Armijo sufficient-decrease constant c for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → int: Maximum number of backtracking iterations for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → float: Backtracking factor rho (in (0, 1)) for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → float: Maximum voltage angle step (radian) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → float: Maximum voltage magnitude step (pu) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_q_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s reactive-power (Q) unknown – currently always -1: no solver in this version stamps a reactive-power unknown as its own Jacobian column.

get_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → int: Refactorize (full factorize(), not the cheaper refactorize()) every N-th iteration, for the EveryN refactor policy. Only read while that policy is active (see set_refactor_policy()).

get_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → lightsim2grid.lightsim2grid_cpp.RefactorPolicyType: Return the current Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType): when the linear solver does a cheaper refactorize() instead of a full factorize().

get_scaling_policy_type(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → lightsim2grid.lightsim2grid_cpp.ScalingPolicyType: Return the current step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType): how the Newton-Raphson step is scaled down before being applied, if at all.

get_theta_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-angle (theta) unknown, or -1 if that bus has none (eg the slack bus, or a PQ-only DC solve). Only valid after a powerflow has been run.

get_timers(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

get_vm_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-magnitude (Vm) unknown, or -1 if that bus has none (eg a PV bus). Only valid after a powerflow has been run.

reset(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

set_config(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, config: ls2g::AlgoConfig) → None: Restore every scaling/refactor policy type and parameter from a lightsim2grid.algorithm.AlgoConfig previously obtained from get_config().

set_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_max().

set_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_min().

set_ls_c(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_c().

set_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, value: SupportsInt | SupportsIndex) → None: Set get_ls_max_iter().

set_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_rho().

set_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVa().

set_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVm().

set_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, value: SupportsInt | SupportsIndex) → None: Set get_refactor_every_n().

set_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, policy: lightsim2grid.lightsim2grid_cpp.RefactorPolicyType) → None: Set the Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType). set_refactor_every_n() is only read by the EveryN policy.

set_scaling_policy(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, policy: lightsim2grid.lightsim2grid_cpp.ScalingPolicyType) → None: Set the step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType). The per-policy parameters below (set_max_dVa()/set_max_dVm(), set_ls_c()/ set_ls_rho()/set_ls_max_iter(), set_iw_mu_min()/set_iw_mu_max()) are only read by their corresponding policy; changing them has no effect while a different policy is active.

solve(self: lightsim2grid.lightsim2grid_cpp.NRSing_SparseLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.NR_CKTSO

This classes implements the Newton Raphson algorithm, allowing for distributed slack and using the faster CKTSO solver available in the CKTSO library for the linear algebra (requires a build from source)

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called NR_CKTSO

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.NR_CKTSO) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.NR_CKTSO) at creation time

Note

CKTSO is available at https://github.com/chenxm1986/cktso

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_J`(self)	Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_config`(self)	Return a `lightsim2grid.algorithm.AlgoConfig` capturing every scaling/refactor policy type and parameter above, as a single serializable object.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_iw_mu_max`(self)	Maximum optimal multiplier for the `Iwamoto` scaling policy.
`get_iw_mu_min`(self)	Minimum optimal multiplier for the `Iwamoto` scaling policy.
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_ls_c`(self)	Armijo sufficient-decrease constant `c` for the `LineSearch` scaling policy.
`get_ls_max_iter`(self)	Maximum number of backtracking iterations for the `LineSearch` scaling policy.
`get_ls_rho`(self)	Backtracking factor `rho` (in `(0, 1)`) for the `LineSearch` scaling policy.
`get_max_dVa`(self)	Maximum voltage angle step (radian) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_max_dVm`(self)	Maximum voltage magnitude step (pu) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_q_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's reactive-power (Q) unknown -- currently always `-1`: no solver in this version stamps a reactive-power unknown as its own Jacobian column.
`get_refactor_every_n`(self)	Refactorize (full `factorize()`, not the cheaper `refactorize()`) every N-th iteration, for the `EveryN` refactor policy.
`get_refactor_policy`(self)	Return the current Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`): when the linear solver does a cheaper `refactorize()` instead of a full `factorize()`.
`get_scaling_policy_type`(self)	Return the current step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`): how the Newton-Raphson step is scaled down before being applied, if at all.
`get_theta_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-angle (theta) unknown, or `-1` if that bus has none (eg the slack bus, or a PQ-only DC solve).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`get_vm_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-magnitude (Vm) unknown, or `-1` if that bus has none (eg a PV bus).
`reset`(self)	Reset the solver.
`set_config`(self, config)	Restore every scaling/refactor policy type and parameter from a `lightsim2grid.algorithm.AlgoConfig` previously obtained from `get_config()`.
`set_iw_mu_max`(self, value)	Set `get_iw_mu_max()`.
`set_iw_mu_min`(self, value)	Set `get_iw_mu_min()`.
`set_ls_c`(self, value)	Set `get_ls_c()`.
`set_ls_max_iter`(self, value)	Set `get_ls_max_iter()`.
`set_ls_rho`(self, value)	Set `get_ls_rho()`.
`set_max_dVa`(self, value)	Set `get_max_dVa()`.
`set_max_dVm`(self, value)	Set `get_max_dVm()`.
`set_refactor_every_n`(self, value)	Set `get_refactor_every_n()`.
`set_refactor_policy`(self, policy)	Set the Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`).
`set_scaling_policy`(self, policy)	Set the step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`).
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → bool: Returns whether or not the solver has converged or not.

get_J(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → scipy.sparse.csc_matrix[numpy.float64]

Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.

The “jacobian” matrix is only available for some powerflow (the one based on the Newton Raphson algorithm) and we provide it only for the last computed iteration.

Note

It is using the “solver” labelling, as this is accessed from the solvers. Unlike get_Va()/get_Vm(), the Jacobian has no “gridmodel” labelled equivalent on lightsim2grid.network.LSGrid – only lightsim2grid.network.LSGrid.get_J_solver(), which keeps the solver labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_J_solver()

get_V(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_config(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → ls2g::AlgoConfig: Return a lightsim2grid.algorithm.AlgoConfig capturing every scaling/refactor policy type and parameter above, as a single serializable object.

See also

set_config() to restore it; going through a LightSimBackend instead of a raw solver object, see lightsim2grid.lightSimBackend.LightSimBackend.get_ac_algo_config().

get_error(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → float: Maximum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → float: Minimum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_ls_c(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → float: Armijo sufficient-decrease constant c for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → int: Maximum number of backtracking iterations for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → float: Backtracking factor rho (in (0, 1)) for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → float: Maximum voltage angle step (radian) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → float: Maximum voltage magnitude step (pu) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_q_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s reactive-power (Q) unknown – currently always -1: no solver in this version stamps a reactive-power unknown as its own Jacobian column.

get_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → int: Refactorize (full factorize(), not the cheaper refactorize()) every N-th iteration, for the EveryN refactor policy. Only read while that policy is active (see set_refactor_policy()).

get_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → lightsim2grid.lightsim2grid_cpp.RefactorPolicyType: Return the current Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType): when the linear solver does a cheaper refactorize() instead of a full factorize().

get_scaling_policy_type(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → lightsim2grid.lightsim2grid_cpp.ScalingPolicyType: Return the current step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType): how the Newton-Raphson step is scaled down before being applied, if at all.

get_theta_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-angle (theta) unknown, or -1 if that bus has none (eg the slack bus, or a PQ-only DC solve). Only valid after a powerflow has been run.

get_timers(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

get_vm_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-magnitude (Vm) unknown, or -1 if that bus has none (eg a PV bus). Only valid after a powerflow has been run.

reset(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

set_config(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, config: ls2g::AlgoConfig) → None: Restore every scaling/refactor policy type and parameter from a lightsim2grid.algorithm.AlgoConfig previously obtained from get_config().

set_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_max().

set_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_min().

set_ls_c(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_ls_c().

set_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, value: SupportsInt | SupportsIndex) → None: Set get_ls_max_iter().

set_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_ls_rho().

set_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVa().

set_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVm().

set_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, value: SupportsInt | SupportsIndex) → None: Set get_refactor_every_n().

set_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, policy: lightsim2grid.lightsim2grid_cpp.RefactorPolicyType) → None: Set the Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType). set_refactor_every_n() is only read by the EveryN policy.

set_scaling_policy(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, policy: lightsim2grid.lightsim2grid_cpp.ScalingPolicyType) → None: Set the step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType). The per-policy parameters below (set_max_dVa()/set_max_dVm(), set_ls_c()/ set_ls_rho()/set_ls_max_iter(), set_iw_mu_min()/set_iw_mu_max()) are only read by their corresponding policy; changing them has no effect while a different policy is active.

solve(self: lightsim2grid.lightsim2grid_cpp.NR_CKTSO, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.NR_KLU

This classes implements the Newton Raphson algorithm, allowing for distributed slack and using the faster KLU solver available in the SuiteSparse library for the linear algebra (can be unavailable if you build lightsim2grid from source). It is usually faster than the lightsim2grid.algorithm.NR_SparseLU.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called NR_KLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.NR_KLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.NR_KLU) at creation time

Note

This is the default solver used when a distributed slack bus is detected (when it’s available, otherwise see lightsim2grid.algorithm.NR_SparseLU).

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_J`(self)	Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_config`(self)	Return a `lightsim2grid.algorithm.AlgoConfig` capturing every scaling/refactor policy type and parameter above, as a single serializable object.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_iw_mu_max`(self)	Maximum optimal multiplier for the `Iwamoto` scaling policy.
`get_iw_mu_min`(self)	Minimum optimal multiplier for the `Iwamoto` scaling policy.
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_ls_c`(self)	Armijo sufficient-decrease constant `c` for the `LineSearch` scaling policy.
`get_ls_max_iter`(self)	Maximum number of backtracking iterations for the `LineSearch` scaling policy.
`get_ls_rho`(self)	Backtracking factor `rho` (in `(0, 1)`) for the `LineSearch` scaling policy.
`get_max_dVa`(self)	Maximum voltage angle step (radian) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_max_dVm`(self)	Maximum voltage magnitude step (pu) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_q_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's reactive-power (Q) unknown -- currently always `-1`: no solver in this version stamps a reactive-power unknown as its own Jacobian column.
`get_refactor_every_n`(self)	Refactorize (full `factorize()`, not the cheaper `refactorize()`) every N-th iteration, for the `EveryN` refactor policy.
`get_refactor_policy`(self)	Return the current Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`): when the linear solver does a cheaper `refactorize()` instead of a full `factorize()`.
`get_scaling_policy_type`(self)	Return the current step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`): how the Newton-Raphson step is scaled down before being applied, if at all.
`get_theta_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-angle (theta) unknown, or `-1` if that bus has none (eg the slack bus, or a PQ-only DC solve).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`get_vm_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-magnitude (Vm) unknown, or `-1` if that bus has none (eg a PV bus).
`reset`(self)	Reset the solver.
`set_config`(self, config)	Restore every scaling/refactor policy type and parameter from a `lightsim2grid.algorithm.AlgoConfig` previously obtained from `get_config()`.
`set_iw_mu_max`(self, value)	Set `get_iw_mu_max()`.
`set_iw_mu_min`(self, value)	Set `get_iw_mu_min()`.
`set_ls_c`(self, value)	Set `get_ls_c()`.
`set_ls_max_iter`(self, value)	Set `get_ls_max_iter()`.
`set_ls_rho`(self, value)	Set `get_ls_rho()`.
`set_max_dVa`(self, value)	Set `get_max_dVa()`.
`set_max_dVm`(self, value)	Set `get_max_dVm()`.
`set_refactor_every_n`(self, value)	Set `get_refactor_every_n()`.
`set_refactor_policy`(self, policy)	Set the Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`).
`set_scaling_policy`(self, policy)	Set the step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`).
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → bool: Returns whether or not the solver has converged or not.

get_J(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → scipy.sparse.csc_matrix[numpy.float64]

Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.

The “jacobian” matrix is only available for some powerflow (the one based on the Newton Raphson algorithm) and we provide it only for the last computed iteration.

Note

It is using the “solver” labelling, as this is accessed from the solvers. Unlike get_Va()/get_Vm(), the Jacobian has no “gridmodel” labelled equivalent on lightsim2grid.network.LSGrid – only lightsim2grid.network.LSGrid.get_J_solver(), which keeps the solver labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_J_solver()

get_V(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_config(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → ls2g::AlgoConfig: Return a lightsim2grid.algorithm.AlgoConfig capturing every scaling/refactor policy type and parameter above, as a single serializable object.

See also

set_config() to restore it; going through a LightSimBackend instead of a raw solver object, see lightsim2grid.lightSimBackend.LightSimBackend.get_ac_algo_config().

get_error(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → float: Maximum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → float: Minimum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_ls_c(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → float: Armijo sufficient-decrease constant c for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → int: Maximum number of backtracking iterations for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → float: Backtracking factor rho (in (0, 1)) for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → float: Maximum voltage angle step (radian) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → float: Maximum voltage magnitude step (pu) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_q_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s reactive-power (Q) unknown – currently always -1: no solver in this version stamps a reactive-power unknown as its own Jacobian column.

get_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → int: Refactorize (full factorize(), not the cheaper refactorize()) every N-th iteration, for the EveryN refactor policy. Only read while that policy is active (see set_refactor_policy()).

get_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → lightsim2grid.lightsim2grid_cpp.RefactorPolicyType: Return the current Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType): when the linear solver does a cheaper refactorize() instead of a full factorize().

get_scaling_policy_type(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → lightsim2grid.lightsim2grid_cpp.ScalingPolicyType: Return the current step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType): how the Newton-Raphson step is scaled down before being applied, if at all.

get_theta_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-angle (theta) unknown, or -1 if that bus has none (eg the slack bus, or a PQ-only DC solve). Only valid after a powerflow has been run.

get_timers(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

get_vm_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-magnitude (Vm) unknown, or -1 if that bus has none (eg a PV bus). Only valid after a powerflow has been run.

reset(self: lightsim2grid.lightsim2grid_cpp.NR_KLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

set_config(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, config: ls2g::AlgoConfig) → None: Restore every scaling/refactor policy type and parameter from a lightsim2grid.algorithm.AlgoConfig previously obtained from get_config().

set_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_max().

set_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_min().

set_ls_c(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_c().

set_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, value: SupportsInt | SupportsIndex) → None: Set get_ls_max_iter().

set_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_rho().

set_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVa().

set_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVm().

set_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, value: SupportsInt | SupportsIndex) → None: Set get_refactor_every_n().

set_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, policy: lightsim2grid.lightsim2grid_cpp.RefactorPolicyType) → None: Set the Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType). set_refactor_every_n() is only read by the EveryN policy.

set_scaling_policy(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, policy: lightsim2grid.lightsim2grid_cpp.ScalingPolicyType) → None: Set the step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType). The per-policy parameters below (set_max_dVa()/set_max_dVm(), set_ls_c()/ set_ls_rho()/set_ls_max_iter(), set_iw_mu_min()/set_iw_mu_max()) are only read by their corresponding policy; changing them has no effect while a different policy is active.

solve(self: lightsim2grid.lightsim2grid_cpp.NR_KLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.NR_NICSLU

This classes implements the Newton Raphson algorithm, allowing for distributed slack and using the faster NICSLU solver available in the NICSLU library for the linear algebra. It is usually faster than the lightsim2grid.algorithm.NR_SparseLU. (requires a build from source)

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called NR_NICSLU

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.NR_NICSLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.NR_NICSLU) at creation time

Warning

Use this solver requires a compilation of lightsim2grid from source (see readme) AND an appropriate license for nicslu.

Note

NICSLU is available at https://github.com/chenxm1986/nicslu

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_J`(self)	Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_config`(self)	Return a `lightsim2grid.algorithm.AlgoConfig` capturing every scaling/refactor policy type and parameter above, as a single serializable object.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_iw_mu_max`(self)	Maximum optimal multiplier for the `Iwamoto` scaling policy.
`get_iw_mu_min`(self)	Minimum optimal multiplier for the `Iwamoto` scaling policy.
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_ls_c`(self)	Armijo sufficient-decrease constant `c` for the `LineSearch` scaling policy.
`get_ls_max_iter`(self)	Maximum number of backtracking iterations for the `LineSearch` scaling policy.
`get_ls_rho`(self)	Backtracking factor `rho` (in `(0, 1)`) for the `LineSearch` scaling policy.
`get_max_dVa`(self)	Maximum voltage angle step (radian) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_max_dVm`(self)	Maximum voltage magnitude step (pu) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_q_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's reactive-power (Q) unknown -- currently always `-1`: no solver in this version stamps a reactive-power unknown as its own Jacobian column.
`get_refactor_every_n`(self)	Refactorize (full `factorize()`, not the cheaper `refactorize()`) every N-th iteration, for the `EveryN` refactor policy.
`get_refactor_policy`(self)	Return the current Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`): when the linear solver does a cheaper `refactorize()` instead of a full `factorize()`.
`get_scaling_policy_type`(self)	Return the current step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`): how the Newton-Raphson step is scaled down before being applied, if at all.
`get_theta_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-angle (theta) unknown, or `-1` if that bus has none (eg the slack bus, or a PQ-only DC solve).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`get_vm_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-magnitude (Vm) unknown, or `-1` if that bus has none (eg a PV bus).
`reset`(self)	Reset the solver.
`set_config`(self, config)	Restore every scaling/refactor policy type and parameter from a `lightsim2grid.algorithm.AlgoConfig` previously obtained from `get_config()`.
`set_iw_mu_max`(self, value)	Set `get_iw_mu_max()`.
`set_iw_mu_min`(self, value)	Set `get_iw_mu_min()`.
`set_ls_c`(self, value)	Set `get_ls_c()`.
`set_ls_max_iter`(self, value)	Set `get_ls_max_iter()`.
`set_ls_rho`(self, value)	Set `get_ls_rho()`.
`set_max_dVa`(self, value)	Set `get_max_dVa()`.
`set_max_dVm`(self, value)	Set `get_max_dVm()`.
`set_refactor_every_n`(self, value)	Set `get_refactor_every_n()`.
`set_refactor_policy`(self, policy)	Set the Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`).
`set_scaling_policy`(self, policy)	Set the step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`).
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → bool: Returns whether or not the solver has converged or not.

get_J(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → scipy.sparse.csc_matrix[numpy.float64]

Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.

The “jacobian” matrix is only available for some powerflow (the one based on the Newton Raphson algorithm) and we provide it only for the last computed iteration.

Note

It is using the “solver” labelling, as this is accessed from the solvers. Unlike get_Va()/get_Vm(), the Jacobian has no “gridmodel” labelled equivalent on lightsim2grid.network.LSGrid – only lightsim2grid.network.LSGrid.get_J_solver(), which keeps the solver labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_J_solver()

get_V(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_config(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → ls2g::AlgoConfig: Return a lightsim2grid.algorithm.AlgoConfig capturing every scaling/refactor policy type and parameter above, as a single serializable object.

See also

set_config() to restore it; going through a LightSimBackend instead of a raw solver object, see lightsim2grid.lightSimBackend.LightSimBackend.get_ac_algo_config().

get_error(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → float: Maximum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → float: Minimum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_ls_c(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → float: Armijo sufficient-decrease constant c for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → int: Maximum number of backtracking iterations for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → float: Backtracking factor rho (in (0, 1)) for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → float: Maximum voltage angle step (radian) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → float: Maximum voltage magnitude step (pu) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_q_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s reactive-power (Q) unknown – currently always -1: no solver in this version stamps a reactive-power unknown as its own Jacobian column.

get_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → int: Refactorize (full factorize(), not the cheaper refactorize()) every N-th iteration, for the EveryN refactor policy. Only read while that policy is active (see set_refactor_policy()).

get_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → lightsim2grid.lightsim2grid_cpp.RefactorPolicyType: Return the current Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType): when the linear solver does a cheaper refactorize() instead of a full factorize().

get_scaling_policy_type(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → lightsim2grid.lightsim2grid_cpp.ScalingPolicyType: Return the current step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType): how the Newton-Raphson step is scaled down before being applied, if at all.

get_theta_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-angle (theta) unknown, or -1 if that bus has none (eg the slack bus, or a PQ-only DC solve). Only valid after a powerflow has been run.

get_timers(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

get_vm_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-magnitude (Vm) unknown, or -1 if that bus has none (eg a PV bus). Only valid after a powerflow has been run.

reset(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

set_config(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, config: ls2g::AlgoConfig) → None: Restore every scaling/refactor policy type and parameter from a lightsim2grid.algorithm.AlgoConfig previously obtained from get_config().

set_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_max().

set_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_min().

set_ls_c(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_c().

set_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, value: SupportsInt | SupportsIndex) → None: Set get_ls_max_iter().

set_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_rho().

set_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVa().

set_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVm().

set_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, value: SupportsInt | SupportsIndex) → None: Set get_refactor_every_n().

set_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, policy: lightsim2grid.lightsim2grid_cpp.RefactorPolicyType) → None: Set the Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType). set_refactor_every_n() is only read by the EveryN policy.

set_scaling_policy(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, policy: lightsim2grid.lightsim2grid_cpp.ScalingPolicyType) → None: Set the step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType). The per-policy parameters below (set_max_dVa()/set_max_dVm(), set_ls_c()/ set_ls_rho()/set_ls_max_iter(), set_iw_mu_min()/set_iw_mu_max()) are only read by their corresponding policy; changing them has no effect while a different policy is active.

solve(self: lightsim2grid.lightsim2grid_cpp.NR_NICSLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.NR_SparseLU

This classes implements the Newton Raphson algorithm, allowing for distributed slack and using the default Eigen sparse solver available in Eigen for the linear algebra.

See Available powerflow algorithms for more information on how to use it.

Note

In the enum lightsim2grid.algorithm.AlgorithmType, it is called NR_SparseLU.

You can use it with:

env_lightsim.backend.set_algo_type(lightsim2grid.algorithm.NR_SparseLU) after creation
LightSimBackend(solver_type=lightsim2grid.algorithm.NR_SparseLU) at creation time

Note

Available on all plateform, this is the default solver used when lightsim2grid.algorithm.NRSing_KLU is not found (when a “single slack” is detected).

Methods:

`compute_pf`(self, arg0, arg1, arg2, arg3, ...)	Function used to perform a powerflow.
`converged`(self)	Returns whether or not the solver has converged or not.
`get_J`(self)	Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.
`get_V`(self)	Returns the complex voltage for each buses as a numpy vector of complex number.
`get_Va`(self)	Returns the voltage angles for each buses as a numpy vector of real number.
`get_Vm`(self)	Returns the voltage magnitude for each buses as a numpy vector of real number.
`get_config`(self)	Return a `lightsim2grid.algorithm.AlgoConfig` capturing every scaling/refactor policy type and parameter above, as a single serializable object.
`get_error`(self)	Returns the error encountered by the solver during the last `compute_pf` / `solve` call, as a `lightsim2grid.algorithm.ErrorType` value (`ErrorType.NoError`, ie 0, when nothing went wrong).
`get_iw_mu_max`(self)	Maximum optimal multiplier for the `Iwamoto` scaling policy.
`get_iw_mu_min`(self)	Minimum optimal multiplier for the `Iwamoto` scaling policy.
`get_linear_solver_stats`(self)	Per-call counters and timings for the underlying linear solver, as a `lightsim2grid.algorithm.LinearSolverStats`.
`get_ls_c`(self)	Armijo sufficient-decrease constant `c` for the `LineSearch` scaling policy.
`get_ls_max_iter`(self)	Maximum number of backtracking iterations for the `LineSearch` scaling policy.
`get_ls_rho`(self)	Backtracking factor `rho` (in `(0, 1)`) for the `LineSearch` scaling policy.
`get_max_dVa`(self)	Maximum voltage angle step (radian) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_max_dVm`(self)	Maximum voltage magnitude step (pu) allowed per iteration, for the `MaxVoltageChange` scaling policy.
`get_nb_iter`(self)	Returns the number of iterations effectively performed by the solver (> 0 integer).
`get_q_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's reactive-power (Q) unknown -- currently always `-1`: no solver in this version stamps a reactive-power unknown as its own Jacobian column.
`get_refactor_every_n`(self)	Refactorize (full `factorize()`, not the cheaper `refactorize()`) every N-th iteration, for the `EveryN` refactor policy.
`get_refactor_policy`(self)	Return the current Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`): when the linear solver does a cheaper `refactorize()` instead of a full `factorize()`.
`get_scaling_policy_type`(self)	Return the current step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`): how the Newton-Raphson step is scaled down before being applied, if at all.
`get_theta_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-angle (theta) unknown, or `-1` if that bus has none (eg the slack bus, or a PQ-only DC solve).
`get_timers`(self)	Returns information about the time taken by some part of the solvers (in seconds)
`get_vm_to_J_col`(self)	`bus_id -> Jacobian column` for that bus's voltage-magnitude (Vm) unknown, or `-1` if that bus has none (eg a PV bus).
`reset`(self)	Reset the solver.
`set_config`(self, config)	Restore every scaling/refactor policy type and parameter from a `lightsim2grid.algorithm.AlgoConfig` previously obtained from `get_config()`.
`set_iw_mu_max`(self, value)	Set `get_iw_mu_max()`.
`set_iw_mu_min`(self, value)	Set `get_iw_mu_min()`.
`set_ls_c`(self, value)	Set `get_ls_c()`.
`set_ls_max_iter`(self, value)	Set `get_ls_max_iter()`.
`set_ls_rho`(self, value)	Set `get_ls_rho()`.
`set_max_dVa`(self, value)	Set `get_max_dVa()`.
`set_max_dVm`(self, value)	Set `get_max_dVm()`.
`set_refactor_every_n`(self, value)	Set `get_refactor_every_n()`.
`set_refactor_policy`(self, policy)	Set the Jacobian refactorization policy (`lightsim2grid.algorithm.RefactorPolicyType`).
`set_scaling_policy`(self, policy)	Set the step-scaling policy (`lightsim2grid.algorithm.ScalingPolicyType`).
`solve`(self, arg0, arg1, arg2, arg3, arg4, ...)	Function used to perform a powerflow.

compute_pf(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

converged(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → bool: Returns whether or not the solver has converged or not.

get_J(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → scipy.sparse.csc_matrix[numpy.float64]

Returns the Jacobian matrix used for solving the powerflow as a scipy sparse CSC matrix matrix of real number.

The “jacobian” matrix is only available for some powerflow (the one based on the Newton Raphson algorithm) and we provide it only for the last computed iteration.

Note

It is using the “solver” labelling, as this is accessed from the solvers. Unlike get_Va()/get_Vm(), the Jacobian has no “gridmodel” labelled equivalent on lightsim2grid.network.LSGrid – only lightsim2grid.network.LSGrid.get_J_solver(), which keeps the solver labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_J_solver()

get_V(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]']: Returns the complex voltage for each buses as a numpy vector of complex number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_V() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_V_solver()

get_Va(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage angles for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Va() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Va_solver()

get_Vm(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]']: Returns the voltage magnitude for each buses as a numpy vector of real number.

Note

It is using the “solver” labelling, as this is accessed from the solvers.

See also

lightsim2grid.network.LSGrid.get_Vm() for the same things, but rather using the “gridmodel” labelling.

See also

This function should be equal to lightsim2grid.network.LSGrid.get_Vm_solver()

get_config(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → ls2g::AlgoConfig: Return a lightsim2grid.algorithm.AlgoConfig capturing every scaling/refactor policy type and parameter above, as a single serializable object.

See also

set_config() to restore it; going through a LightSimBackend instead of a raw solver object, see lightsim2grid.lightSimBackend.LightSimBackend.get_ac_algo_config().

get_error(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → lightsim2grid.lightsim2grid_cpp.ErrorType

Returns the error encountered by the solver during the last compute_pf / solve call, as a lightsim2grid.algorithm.ErrorType value (ErrorType.NoError, ie 0, when nothing went wrong).

Note

Reaching max_iter without meeting the requested tolerance is itself reported as an error here (ErrorType.TooManyIterations), so converged() (which is exactly get_error() == ErrorType.NoError) is False in that case too.

See lightsim2grid.algorithm.ErrorType for the full list of possible values and what each one means.

get_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → float: Maximum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → float: Minimum optimal multiplier for the Iwamoto scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_linear_solver_stats(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → lightsim2grid.lightsim2grid_cpp.LinearSolverStats: Per-call counters and timings for the underlying linear solver, as a lightsim2grid.algorithm.LinearSolverStats.

See also

get_linear_solver_stats_bp() / get_linear_solver_stats_bpp(), the equivalent for the fast-decoupled FDPF_* family, which holds two independent linear solvers (this method does not exist there).

get_ls_c(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → float: Armijo sufficient-decrease constant c for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → int: Maximum number of backtracking iterations for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → float: Backtracking factor rho (in (0, 1)) for the LineSearch scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → float: Maximum voltage angle step (radian) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → float: Maximum voltage magnitude step (pu) allowed per iteration, for the MaxVoltageChange scaling policy. Only read while that policy is active (see set_scaling_policy()).

get_nb_iter(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → int: Returns the number of iterations effectively performed by the solver (> 0 integer).

get_q_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s reactive-power (Q) unknown – currently always -1: no solver in this version stamps a reactive-power unknown as its own Jacobian column.

get_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → int: Refactorize (full factorize(), not the cheaper refactorize()) every N-th iteration, for the EveryN refactor policy. Only read while that policy is active (see set_refactor_policy()).

get_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → lightsim2grid.lightsim2grid_cpp.RefactorPolicyType: Return the current Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType): when the linear solver does a cheaper refactorize() instead of a full factorize().

get_scaling_policy_type(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → lightsim2grid.lightsim2grid_cpp.ScalingPolicyType: Return the current step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType): how the Newton-Raphson step is scaled down before being applied, if at all.

get_theta_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-angle (theta) unknown, or -1 if that bus has none (eg the slack bus, or a PQ-only DC solve). Only valid after a powerflow has been run.

get_timers(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → tuple[float, float, float, float]

Returns information about the time taken by some part of the solvers (in seconds)

Times are measured in seconds using the c++ steady_clock clock.

Note

This is returned as a plain (float, float, float, float) tuple, in the order below (there are no named attributes on it) – for named access to a wider set of timers, see lightsim2grid.algorithm.AlgorithmSelector.get_timers_jacobian() instead, which returns a lightsim2grid.algorithm.TimerJac.

Returns:

timer_Fx_ (float) – Time spent to compute the mismatch at the KCL for each bus (both for active and reactive power)
timer_solve_ (float) – Total time spent in the underlying linear solver
timer_check_ (float) – Time spent in checking whether or not the mismatch of the KCL met the specified tolerance
timer_total_nr_ (float) – Total time spent in the solver

get_vm_to_J_col(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]']: bus_id -> Jacobian column for that bus’s voltage-magnitude (Vm) unknown, or -1 if that bus has none (eg a PV bus). Only valid after a powerflow has been run.

reset(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU) → None: Reset the solver. In this context this will clear all data used by the solver. It is mandatory to do it each time the Ybus matrix (or any of the pv, or pq or ref indices vector are changed).

set_config(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, config: ls2g::AlgoConfig) → None: Restore every scaling/refactor policy type and parameter from a lightsim2grid.algorithm.AlgoConfig previously obtained from get_config().

set_iw_mu_max(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_max().

set_iw_mu_min(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, value: SupportsFloat | SupportsIndex) → None: Set get_iw_mu_min().

set_ls_c(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_c().

set_ls_max_iter(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, value: SupportsInt | SupportsIndex) → None: Set get_ls_max_iter().

set_ls_rho(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, value: SupportsFloat | SupportsIndex) → None: Set get_ls_rho().

set_max_dVa(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVa().

set_max_dVm(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, value: SupportsFloat | SupportsIndex) → None: Set get_max_dVm().

set_refactor_every_n(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, value: SupportsInt | SupportsIndex) → None: Set get_refactor_every_n().

set_refactor_policy(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, policy: lightsim2grid.lightsim2grid_cpp.RefactorPolicyType) → None: Set the Jacobian refactorization policy (lightsim2grid.algorithm.RefactorPolicyType). set_refactor_every_n() is only read by the EveryN policy.

set_scaling_policy(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, policy: lightsim2grid.lightsim2grid_cpp.ScalingPolicyType) → None: Set the step-scaling policy (lightsim2grid.algorithm.ScalingPolicyType). The per-policy parameters below (set_max_dVa()/set_max_dVm(), set_ls_c()/ set_ls_rho()/set_ls_max_iter(), set_iw_mu_min()/set_iw_mu_max()) are only read by their corresponding policy; changing them has no effect while a different policy is active.

solve(self: lightsim2grid.lightsim2grid_cpp.NR_SparseLU, arg0: scipy.sparse.csc_matrix[numpy.complex128], arg1: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg2: Annotated[numpy.typing.NDArray[numpy.complex128], '[m, 1]'], arg3: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg4: Annotated[numpy.typing.NDArray[numpy.float64], '[m, 1]'], arg5: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg6: Annotated[numpy.typing.NDArray[numpy.int32], '[m, 1]'], arg7: SupportsInt | SupportsIndex, arg8: SupportsFloat | SupportsIndex) → bool

Function used to perform a powerflow.

see section Available powerflow algorithms for more information about these.

Note

This python-facing method (also available as solve) validates its inputs before doing anything else: a non-square Ybus, a size mismatch between Ybus / V / Sbus / slack_weights, an out-of-range id in slack_ids / pv / pq, a bus listed in more than one of them, an empty slack_ids, a negative max_iter (0 is accepted: it returns the pre-iteration state, before any Newton-Raphson / Gauss-Seidel step), or a non-finite or non-positive tol all raise a clean RuntimeError (or IndexError for out-of-range ids) instead of touching the underlying solver. This validation is skipped on the internal C++ code path used by lightsim2grid.network.LSGrid and the batch solvers (ContingencyAnalysis, TimeSerie, security analysis), which build these arrays themselves and call the solver many times in a loop: paying this check on every call there would be pure overhead, so it is only performed at this python entry point.

Parameters:

Ybus (scipy.sparse matrix, CSC format) – The admittance matrix of the system
V (numpy.ndarray, vector of complex numbers) – The initial guess (and final result) for the complex angle at each bus (it is modified during the computation :)
Sbus (numpy.ndarray, vector of complex numbers) – Complex power injected at each bus
slack_ids (numpy.ndarray, vector of integers) – Gives all the ids of the buses participating to the distributed slack bus. [might be ignore by some solvers]
slack_weights (numpy.ndarray, vector of real numbers) – For each bus taking part in the distributed slack, it gives its coefficient
pv (numpy.ndarray, vector of integers) – Index of the pv buses
pq (numpy.ndarray, vector of integers) – Index of the pq buses
max_iter (int) – Maximum number of iterations performed by the solver. [might be ignore by some solvers]
tol (float) – Solver tolerance (eg 1e-8) [might be ignore by some solvers]

Examples

Some detailed examples are provided in section Available powerflow algorithms of the documentation.

class lightsim2grid.algorithm.RefactorPolicyType

Jacobian refactorization strategy for the Newton-Raphson loop

Members:

AlwaysRefactor : Rebuild and refactorize J every iteration (default)

EveryN : Refactorize every N iterations; update values only in between

Chord : Build J once on the first iteration; reuse factorization throughout

Attributes:

name

property name

class lightsim2grid.algorithm.ScalingPolicyType

Step-scaling strategy for the Newton-Raphson loop

Members:

NoScaling : Full Newton step (alpha = 1), zero overhead

MaxVoltageChange : Clamp step so max|dVa| <= max_dVa and max|dVm| <= max_dVm

LineSearch : Armijo backtracking line search

Iwamoto : Iwamoto optimal multiplier

Attributes:

name

property name

class lightsim2grid.algorithm.TimerJac

Named timer record returned by get_timers_jacobian(), breaking down the plain (timer_Fx, timer_solve, timer_check, timer_total_nr) tuple of get_timers() into a finer-grained, named set of phases.

All fields default to -1. when not measured by the active solver: only the Newton-Raphson family (NR_*/NRSing_*/NRRefactorRetry_*) fills in every field; Gauss-Seidel and DC solvers only ever set the handful of phases they actually go through (see each field’s own doc for which).

Supports tuple-style iteration, indexing and unpacking, in the field declaration order above.

Attributes:

`timer_Fx`	Time spent computing the KCL mismatch (both active and reactive power) for each bus.
`timer_Va_Vm`	NR-only -- time spent updating the voltage angles / magnitudes from the linear solver's solved increments (`-1.` for Gauss-Seidel and DC solvers).
`timer_check`	Time spent checking whether the KCL mismatch met the convergence tolerance.
`timer_dSbus`	NR-only -- time spent computing the bus-injection sensitivities the Jacobian is built from (`-1.` for Gauss-Seidel and DC solvers).
`timer_factor`	Total time spent in the underlying linear solver's `factorize()` step (same value as `lightsim2grid.algorithm.LinearSolverStats.timer_factor`).
`timer_fillJ`	NR-only -- time spent assembling the Jacobian matrix itself, from the sensitivities measured by `timer_dSbus` (`-1.` for Gauss-Seidel and DC solvers).
`timer_initialize`	Total time spent in the underlying linear solver's `analyze()` (symbolic factorization) step (same value as `lightsim2grid.algorithm.LinearSolverStats.timer_initialize`).
`timer_mismatch`	Time spent (re)computing the mismatch, including any post-processing done once the main loop has finished.
`timer_pre_proc`	Time spent in pre-processing (setup before the main iteration loop starts).
`timer_refactor`	Total time spent in the underlying linear solver's `refactorize()` step (same value as `lightsim2grid.algorithm.LinearSolverStats.timer_refactor`).
`timer_scale`	NR-only -- time spent applying the active step-scaling policy (see `get_scaling_policy_type()`), eg the line-search backtracking of the `LineSearch` policy (`-1.` for Gauss-Seidel and DC solvers).
`timer_solve`	Total time spent in the underlying linear solver's `solve()` step (same value as `lightsim2grid.algorithm.LinearSolverStats.timer_solve` for NR-based solvers).
`timer_total_nr`	Total time spent in the solver (the same value as `get_timers()`'s `timer_total_nr`).

property timer_Fx: Time spent computing the KCL mismatch (both active and reactive power) for each bus.

property timer_Va_Vm: NR-only – time spent updating the voltage angles / magnitudes from the linear solver’s solved increments (-1. for Gauss-Seidel and DC solvers).

property timer_check: Time spent checking whether the KCL mismatch met the convergence tolerance.

property timer_dSbus: NR-only – time spent computing the bus-injection sensitivities the Jacobian is built from (-1. for Gauss-Seidel and DC solvers).

property timer_factor: Total time spent in the underlying linear solver’s factorize() step (same value as lightsim2grid.algorithm.LinearSolverStats.timer_factor). NR-only: -1. for Gauss-Seidel and DC solvers.

property timer_fillJ: NR-only – time spent assembling the Jacobian matrix itself, from the sensitivities measured by timer_dSbus (-1. for Gauss-Seidel and DC solvers).

property timer_initialize: Total time spent in the underlying linear solver’s analyze() (symbolic factorization) step (same value as lightsim2grid.algorithm.LinearSolverStats.timer_initialize). NR-only: -1. for Gauss-Seidel and DC solvers.

property timer_mismatch: Time spent (re)computing the mismatch, including any post-processing done once the main loop has finished.

property timer_pre_proc: Time spent in pre-processing (setup before the main iteration loop starts).

property timer_refactor: Total time spent in the underlying linear solver’s refactorize() step (same value as lightsim2grid.algorithm.LinearSolverStats.timer_refactor). NR-only: -1. for Gauss-Seidel and DC solvers.

property timer_scale: NR-only – time spent applying the active step-scaling policy (see get_scaling_policy_type()), eg the line-search backtracking of the LineSearch policy (-1. for Gauss-Seidel and DC solvers).

property timer_solve: Total time spent in the underlying linear solver’s solve() step (same value as lightsim2grid.algorithm.LinearSolverStats.timer_solve for NR-based solvers).

property timer_total_nr: Total time spent in the solver (the same value as get_timers()’s timer_total_nr).

Available powerflow algorithms

Types of powerflow algorithms

Linear-solver diagnostics: LinearSolverStats

Retrying a failed refactor: NRRefactorRetry_*

Default algorithm selection

Correspondence between class and AlgorithmType enum

Usage

Fine-tuning the Newton-Raphson iteration

Detailed API

Linear-solver diagnostics: `LinearSolverStats`

Retrying a failed refactor: `NRRefactorRetry_*`

Correspondence between class and `AlgorithmType` enum