Naming conventions: “solver” vs “algorithm”

This page explains how the terms solver and algorithm are used in LightSim2Grid, and how to read and build the names of the AlgorithmType enum values and the corresponding Python classes.

Three distinct meanings of “solver”

The word solver appears in three different contexts in LightSim2Grid, and they should not be confused:

The linear solver — a numerical library that solves a sparse linear system $Ax = b$ eg at each Newton-Raphson iteration. Examples: SparseLULinearSolver (Eigen built-in), KLU (SuiteSparse), NICSLU, CKTSO. These names end in LinearSolver in C++.
The powerflow algorithm — the outer numerical method used to solve the power-flow equations. Examples: Newton-Raphson (NR), DC approximation, Fast-Decoupled Power Flow (FDPF), Gauss-Seidel. Each algorithm can use one linear solver internally (where applicable). This is what AlgorithmType enumerates, and what AlgorithmSelector dispatches.
Solver bus numbering — the compact internal bus index used by the sparse matrices, which only includes connected buses (not disconnected ones). Methods like get_Ybus_solver(), get_pv_solver(), id_me_to_ac_solver() etc. use “solver” in this third sense. These are low-level diagnostic accessors; the naming is intentionally kept for clarity.

How `AlgorithmType` enum names are built

Each enum value encodes both the outer powerflow algorithm and the linear solver library used for its internal linear algebra. The naming pattern is:

{Algorithm}_{LinearSolver}

Where the algorithm prefix is:

Prefix	Meaning
`NR_`	Newton-Raphson with distributed (multi-) slack
`NRSing_`	Newton-Raphson with single slack (slightly faster when only one slack bus exists)
`DC_`	DC approximation (linearised power flow)
`FDPF_XB_`	Fast-Decoupled Power Flow, XB variant (`fdxb` in pypower / pandapower)
`FDPF_BX_`	Fast-Decoupled Power Flow, BX variant (`fdbx` in pypower / pandapower)

And the linear-solver suffix is:

Suffix	Library
`_SparseLU`	Eigen’s built-in sparse LU — always available, no extra dependency
`_KLU`	SuiteSparse KLU — available when lightsim2grid is compiled with KLU support
`_NICSLU`	NICSLU — requires a license and a source build
`_CKTSO`	CKTSO — requires a license and a source build

Special cases (no linear solver choice):

GaussSeidelAlgo — the Gauss-Seidel iterative method. No sparse factorisation is involved.
GaussSeidelSynchAlgo — synchronous (all-buses-at-once) Gauss-Seidel variant.

Complete table

`AlgorithmType` value	Python class	Description
`NR_SparseLU`	`NR_SparseLU`	NR multi-slack + SparseLU (default when KLU unavailable)
`NRSing_SparseLU`	`NRSing_SparseLU`	NR single-slack + SparseLU
`DC_SparseLU`	`DC_SparseLU`	DC + SparseLU
`FDPF_XB_SparseLU`	`FDPF_XB_SparseLU`	Fast-Decoupled XB + SparseLU
`FDPF_BX_SparseLU`	`FDPF_BX_SparseLU`	Fast-Decoupled BX + SparseLU
`NR_KLU`	`NR_KLU`	NR multi-slack + KLU (default when KLU available)
`NRSing_KLU`	`NRSing_KLU`	NR single-slack + KLU
`DC_KLU`	`DC_KLU`	DC + KLU
`FDPF_XB_KLU`	`FDPF_XB_KLU`	Fast-Decoupled XB + KLU
`FDPF_BX_KLU`	`FDPF_BX_KLU`	Fast-Decoupled BX + KLU
`NR_NICSLU`	`NR_NICSLU`	NR multi-slack + NICSLU (requires license)
`NRSing_NICSLU`	`NRSing_NICSLU`	NR single-slack + NICSLU (requires license)
`DC_NICSLU`	`DC_NICSLU`	DC + NICSLU (requires license)
`FDPF_XB_NICSLU`	`FDPF_XB_NICSLU`	Fast-Decoupled XB + NICSLU
`FDPF_BX_NICSLU`	`FDPF_BX_NICSLU`	Fast-Decoupled BX + NICSLU
`NR_CKTSO`	`NR_CKTSO`	NR multi-slack + CKTSO (requires license)
`NRSing_CKTSO`	`NRSing_CKTSO`	NR single-slack + CKTSO (requires license)
`DC_CKTSO`	`DC_CKTSO`	DC + CKTSO (requires license)
`FDPF_XB_CKTSO`	`FDPF_XB_CKTSO`	Fast-Decoupled XB + CKTSO
`FDPF_BX_CKTSO`	`FDPF_BX_CKTSO`	Fast-Decoupled BX + CKTSO
`GaussSeidel`	`GaussSeidelAlgo`	Gauss-Seidel iterative (no sparse factorisation)
`GaussSeidelSynch`	`GaussSeidelSynchAlgo`	Synchronous Gauss-Seidel iterative

Usage example

import lightsim2grid
from lightsim2grid.algorithm import AlgorithmType

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

# switch to NR with KLU (if available)
env.backend.set_algo_type(AlgorithmType.NR_KLU)

# inspect what algorithm is currently active
print(env.backend.get_algo_types())
# >>> (<AlgorithmType.NRSing_KLU: 7>, <AlgorithmType.DC_KLU: 9>)

# list all algorithms available in this build
env.backend._grid.available_algorithm_names()

Note

The method is called change_algorithm(type) in the C++ LSGrid Python binding (env.backend._grid.change_algorithm(AlgorithmType.NR_KLU)), consistent with pandapower’s algorithm= parameter and MATPOWER’s pf.alg option.

Migration from old names

Before version 0.14, the enum values and class names used shorter names that did not make the algorithm component explicit (KLU, SparseLU, DC, etc.). These old names are kept as deprecated aliases in the Python enum so that existing code continues to work, but they will be removed in a future release:

Old name (deprecated)	New canonical name
`AlgorithmType.SparseLU`	`AlgorithmType.NR_SparseLU`
`AlgorithmType.SparseLUSingleSlack`	`AlgorithmType.NRSing_SparseLU`
`AlgorithmType.DC`	`AlgorithmType.DC_SparseLU`
`AlgorithmType.KLU`	`AlgorithmType.NR_KLU`
`AlgorithmType.KLUSingleSlack`	`AlgorithmType.NRSing_KLU`
`AlgorithmType.KLUDC`	`AlgorithmType.DC_KLU`
`AlgorithmType.NICSLU`	`AlgorithmType.NR_NICSLU`
`AlgorithmType.NICSLUSingleSlack`	`AlgorithmType.NRSing_NICSLU`
`AlgorithmType.NICSLUDC`	`AlgorithmType.DC_NICSLU`
`AlgorithmType.CKTSO`	`AlgorithmType.NR_CKTSO`
`AlgorithmType.CKTSOSingleSlack`	`AlgorithmType.NRSing_CKTSO`
`AlgorithmType.CKTSODC`	`AlgorithmType.DC_CKTSO`