LightSim2Grid

使用 c++ KLU 和 Eigen 库为 grid2op 提供快速后端。它的主要目标是作为 grid2op 平台的快速后端，主要用作电力系统领域中顺序决策的测试平台。

请参阅免责声明以更详细地了解此软件包是什么以及不是什么。例如，此软件包不应用于详细的电力系统计算或模拟。

• 1 用法
  • 1.1。作为 grid2op 后端（首选方法）
  • 1.2. 替换 pandapower “newtonpf” 方法（高级方法）
• 2 安装（来自pypi官方仓库，推荐）
• 3 安装（来自源代码，适用于更高级的用户）
  • 3.0 重要提示
  • 3.1。检索源
  • （可选，推荐）SuiteSparse 的编译
    • 选项 A. 使用“make”编译 SuiteSparse
    • 选项 B. 使用“cmake”编译 SuiteSparse
  • （可选）包括 NICSLU 线性求解器（实验性）
  • （可选）安装定制
  • 3.2 python包的安装
• 4. 基准
• 5. 理念
• 6. 杂项
  • 6.1 编译的自定义
  • 6.2 剖析代码
  • 6.3 本地测试
  • 6.4 自动执行的测试
  • 5.5 已知问题

用法

安装后（不要忘记，如果您使用了上面的可选虚拟环境，则需要加载它source venv/bin/activate），您可以将其用作任何 python 包。

1.作为grid2op后端（首选方法）

此功能要求您安装 grid2op，版本至少为 0.7.0。你可以安装它

pip install grid2op>=1.6.4

然后你可以通过这种方式使用 LightSimBackend 而不是默认的 PandapowerBackend：

import grid2op
from lightsim2grid import LightSimBackend
env_name = "l2rpn_case14_sandbox"  # or any other name.
env = grid2op.make(env_name, backend=LightSimBackend())

# do regular computation as you would with grid2op

你很高兴。

2.替换pandapower“newtonpf”方法（高级方法）

也可以直接使用 lightsim2grid 的“求解器”部分。

假设你以某种方式得到：

• Ybus您的电力系统的导纳矩阵，例如由 pandapower 给出（将转换为 scipy sparse.csc_matrix）
• V0每条总线上的（复数）电压矢量，例如由 pandapower 给出
• Sbus每条总线的（复杂）功率吸收，例如 pandapower 给出的
• ref松弛总线的 ID（在 0.5.6 版中添加以匹配最近的 pandapower 更改）
• pv光伏客车一览
• pqPQ总线列表
• ppci一个 ppc 内部 pandapower 测试用例（或字典，用于检索与每个松弛总线关联的系数）
• optionspandapower“选项”列表（或带有键max_iteration和的字典tolerance_mva）

您可以使用以下代码定义替换newtonpf函数的功能：pandapower.pandapower.newtonpf

from lightsim2grid.newtonpf import newtonpf
V, converged, iterations, J = newtonpf(Ybus, V, Sbus, ref, weights, pv, pq, ppci, options)

此函数使用 KLU 算法和牛顿求解器的 c++ 实现来提高速度。

安装（来自pypi官方仓库，推荐）

从 0.5.3 版开始，可以像大多数 python 包一样安装 lightsim2grid，调用： python -m pip install lightsim2grid

它包括更快的 grid2op 后端和SuiteSparse更快的KLU求解器，即使在 Windows 上也是如此。这绝对是在您的系统上安装 lightsim2grid 并让它运行而没有太多问题的最简单方法。

请注意，尽管这些软件包已在您使用的平台不同的平台上编译。从您的机器上安装它可能仍然会获得一些好处（在性能方面）。

Pypi 包可用于带有 python 版本的 linux、windows 和 macos：

• 3.7
• 3.8
• 3.9
• 3.10 (lightsim2grid >= 0.6.1)

安装（来自源代码，适用于更高级的用户）

你需要：

• 克隆此存储库并获取 Eigen（编译必需）和 SparseSuite（可选，但推荐）的代码
• （可选，但推荐）编译一段 SparseSuite
• （可选）[实验性] 检索并获得 NICSLU 线性求解器的适当许可证（请参阅https://github.com/chenxm1986/nicslu）
• （可选）指定一些编译标志以使包在您的机器上运行得更快
• 安装软件包

重要的提示

这个包依赖于优秀的pybind11包将c++代码轻松集成到python中。

因此，要安装您需要的 lightsim2gridpybind11及其要求，其中包括一个工作编译器：例如（截至撰写时）gcc（ubuntu 上的默认值，版本 >= 4.8）、clang（MacOS 上的默认值，版本 >= 5.0.0）或 Microsoft视觉工作室（Microsoft Visual Studio 2015 Update 3 或更新版本）。

本自述文件不包括此类编译器的安装。更多信息请参考 pybind11的文档。如果您在安装此类编译器时遇到问题，请不要犹豫写 github 问题（在 Windows 上nb您必须安装 Visual Studio，在 MacO 的 linux 上您可能已经安装了工作编译器）。

1. 检索来源

首先，您可以使用 git 下载它：

git clone https://github.com/BDonnot/lightsim2grid.git
cd lightsim2grid
# it is recommended to do a python virtual environment
python -m virtualenv venv  # optional
source venv/bin/activate  # optional

# retrieve the code of SparseSuite and Eigen (dependencies, mandatory)
git submodule init
git submodule update

（可选，推荐）SuiteSparse 的编译

SuiteSparse 带有更快的 KLU 线性求解器。

自 0.3.0 版起，此要求已被删除。这意味着在 linux / macos 上，您仍然可以从更快的 KLU 求解器中受益。您仍然可以从 lightsim 的加速（与默认的 PandaPowerBackend 相比）中受益，但这种加速将低于您设法编译 SuiteSparse（有关更多信息，请参阅基准小节）。

NB在这两种情况下计算功率流的算法是完全相同的。它是一种基于 Newton-Raphson 的方法。但是要执行这种算法，需要求解一些线性方程组。两个版本（有和没有 KLU）的唯一区别是线性方程求解器不同。直到双浮点精度，两个结果（有和没有 KLU）都应该匹配。

有两种方法可以安装此软件包。要么使用“make”（Linux / unix 上的首选方法——包括 MacOS），要么使用“cmake”，它适用于所有平台，但需要更多时间且自动化程度较低（主要是因为 SuiteSparse 不能直接使用“cmake”构建所以我们需要额外的步骤来实现它。）

（可选）选项 A. 使用“make”编译 SuiteSparse

这是在您的系统上编译 SuiteSparse 的最简单方法，但不幸的是，它仅适用于“make”可用的操作系统（例如Linux 或 MacOS），但这不适用于 Windows……Windows 上的编译将在下一段中介绍 （可选）选项 B. 使用“cmake”编译 SuiteSparse

无论如何，在这种情况下，这非常容易。做就是了：

# compile static libraries of SparseSuite
make

你很高兴。而已。

（可选）选项 B. 使用“cmake”编译 SuiteSparse

这适用于大多数平台，包括 MacOS、Linux 和 Windows。

它需要安装免费cmake程序并比其他系统做更多的工作。这就是为什么我们只建议在 Windows 上使用它。

主要步骤（对于windows，somme命令需要在linux/macos上适配）是：

1. cd build_cmake
2. py generate_c_files.py
3. mkdir build和 cd 那里：cd build
4. cmake -DCMAKE_INSTALL_PREFIX=..\built -DCMAKE_BUILD_TYPE=Release ..
5. cmake --build . --config Release
6. cmake --build . --config Release --target install

如需更多信息，请随时阅读专用的自述文件。

（可选）包括 NICSLU 线性求解器（实验性）

另一个可以与 lighsim2grid 一起使用的线性求解器是“NICSLU”线性求解器，在某些情况下，它可能比 KLU 线性求解器更快。如果使用 lightsim2grid，这可以提高速度。

要使用它，您需要：

1. 从https://github.com/chenxm1986/nicslu检索源代码（仅作为免费软件提供）并将其保存在您的计算机上。假设您将这个 github 存储库克隆到NICSLU_GIT （例如NICSLU_GIT="/home/user/Documents/nicslu/"）。另请注意，您需要检查您的使用是否符合他们的许可证！
2. 在编译lightsim2grid之前定义“PATH_NICSLU”环境变量，在linux上你可以这样做 export PATH_NICSLU=NICSLU_GIT/nicsluDATE （例如export PATH_NICSLU=/home/user/Documents/nicslu/nicslu202103，如果你克隆存储库作为示例step 1)并使用作者在2021年3月编译的nicslu版本[在编写自述文件时分发的版本])

就是这样。Lightsim 将能够使用此线性求解器。

不过要小心，您需要许可证文件才能使用它。到目前为止，最好的方法是将许可证文件复制粘贴到与您执行 python 的位置相同的位置（即您每次都需要复制粘贴它）。

（可选）安装定制

如果您费心从源代码编译包，您可能还想从一些额外的加速中受益。

这可以通过指定__O3_OPTIM和__COMPILE_MARCHNATIVE环境变量来实现。

第一个将使用-O3编译器标志（/O2在 Windows 上）编译包，这将告诉编译器进一步优化代码以提高速度。

第二个将使用-march=native标志编译包（在 macOS 和 linux 上）

在基于 linux 的机器上做这些事情的例子是：

export __O3_OPTIM=1
export __COMPILE_MARCHNATIVE=1

如果要禁用它们，只需将它们各自的值设置为 0。

2.python包的安装

现在您只需要以这种方式安装 lightsim2grid 包，就像任何 python 包一样：

# install the dependency
pip install -U pybind11
# compile and install the python package
pip install -U .

你完成了:-)

基准

当与 grid2op 一起用于各种环境大小时，Lightsim2grid 比 pandapower 快得多。

首先在基于 IEEE case14 网格的环境中：

然后在基于 IEEE 案例 118 的环境中：

有关更多信息（包括重现这些结果的确切方法，以及使用的计算机），您可以查阅文档上的专用基准页面。

哲学

Lightsim2grid 旨在提供针对 grid2op 平台的某种高效（在计算速度方面）的后端。

它提供了一个与 grid2op 兼容的 c++ api，能够计算来自给定电网的流量（以及电压和无功功率）。这个网格可以根据grid2op机制进行修改（更多信息见grid2Op官方文档）。

该代码的目的不是在性能方面提供最先进的求解器，也不是在电力系统元素（例如负载、发电机、电力线、变压器等）建模的真实性方面。

Lightsim2grid 代码库被“组织”成 4 个不同的部分：

1. 修改元素（例如断开电源线或更改发电机的电压幅度设定值，或 grid2op 可能执行的任何其他操作）
2. 从电网的状态生成Ybus（稀疏）复数导纳矩阵和Sbus复数注入向量（例如，每个元件的物理特性，哪些元件在使用中，每个发电机产生的功率和每个负载消耗的功率，什么是电网拓扑ETC。）
3. 求解具有“标准”“功率流约束”的方程的复杂电压V（和部分Sbus矢量） （例如，在给定组件处设置的电压幅度，在其他方面，它是 的虚部）V.(Ybus.V)* = SbusVSbus
4. 计算有功功率、无功功率、电力线上的流量等，根据在步骤 3) 计算的V和Sbus复矢量。

步骤 1、2 和 4 在GridModel类中完成。

第 3 步的执行得益于“潮流求解器”。

使用自定义潮流求解器

目前，一些基本的“求解器”（例如执行上述点的程序3.）是可用的，基于 Gauss Seidel 或 Newton-Raphson 方法来执行“功率流”。

没有什么可以阻止任何其他“求解器”与 lightsim2grid 一起使用，从而与 grid2op 一起使用。为此，您只需要在 C++ 中实现一个“lightsim2grid 求解器”，主要包括定义一个函数：

bool compute_pf(const Eigen::SparseMatrix<cplx_type> & Ybus,  // the admittance matrix
                CplxVect & V,  // store the results of the powerflow and the Vinit !
                const CplxVect & Sbus,  // the injection vector
                const Eigen::VectorXi & ref,  // bus id participating to the distributed slack
                const RealVect & slack_weights,  // slack weights for each bus
                const Eigen::VectorXi & pv,  // (might be ignored) index of the components of Sbus should be computed
                const Eigen::VectorXi & pq,  // (might be ignored) index of the components of |V| should be computed
                int max_iter,  // maximum number of iteration (might be ignored)
                real_type tol  // solver tolerance 
                );

使用的类型有：

• real_type: double => 表示实数的类型
• cplx_type: std::complex<real_type> => 表示复数的类型
• CplxVect: Eigen::Matrix<cplx_type, Eigen::Dynamic, 1> => 表示复数向量的类型
• RealVect: Eigen::Matrix<real_type, Eigen::Dynamic, 1> => 表示实数向量的类型
• Eigen::VectorXi=> 表示一个整数向量
• Eigen::SparseMatrix<cplx_type>=> 表示稀疏矩阵

例如，参见BaseNRSolver以了解 Newton Raphson 求解器的实现（它需要一些“线性求解器”，有关这些的更多详细信息在下面的部分中给出）

在这方面的任何贡献都非常受欢迎。

注意目前“求解器”仅使用上述信息来执行功率流。如果需要实施更“深入”的解决方案，请通过 github 问题告知我们。例如，提议的“求解器”使用有关电网元素（电力线、拓扑等）的直接信息来执行一些电力流可能完全没问题。

NB在 lightsim2grid 中“嵌入”求解器的所有代码不是强制性的。由于不同的定制，只有在满足某些条件时才完全有可能安装给定的“lightsim求解器”。例如，在基于 Windows 的机器上，SuiteSparse 库无法轻松编译，因此 KLUSolver 不可用。

注意如果某些“lightsim2grid”求解器仅在机器上安装了某些软件包时可用，那将完全没问题。

使用自定义线性求解器求解功率流

在 lightsim2grid（c++ 部分）中，由于使用“模板元编程”而不重新编码 Newton Raphson 算法（或 DC 潮流算法）并利用线性求解器，它也是可能的。

“线性求解器”是可以实现 3 个基本功能的任何东西：

• initialize(const Eigen::SparseMatrix<real_type> & J)：初始化求解器并准备求解线性系统J.x = b（通常每个能流调用一次）
• ErrorType solve(const Eigen::SparseMatrix<real_type> & J, RealVect & b, bool has_just_been_inialized): 有效解决J.x = b（通常每个能流调用多次）
• ErrorType reset()：清除求解器的状态（通常在能流结束时执行以将状态重置为“空白”/“好像刚刚初始化”状态）

在 c++ 代码“KLUSolver.h”、“SparLUSolver.h”和“NICSLU.h”中给出了一些示例

这种用法通常需要大约 20 / 30 行 c++ 代码（不包括注释，例如用于异常处理的锅炉代码）。

引用

如果您在您的一项工作中使用此软件包，请引用：

@misc{lightsim2grid,
    author = {B. Donnot},
    title = {{Lightsim2grid - A c++ backend targeting the Grid2Op platform. }},
    year = {2020},
    publisher = {GitHub},
    journal = {GitHub repository},
    howpublished = {\url{https://GitHub.com/bdonnot/lightsim2grid}},
}

各种各样的

编译的自定义

启用 NICSLU

为此，您需要声明PATH_NICSLU指向 NICSLU 包的有效安装的环境变量（请参阅https://github.com/chenxm1986/nicslu）。例如：export PATH_NICSLU=/home/user/Documents/nicslu/nicslu202103

启用03优化

默认情况下，至少在 ubuntu 上，仅使用“-O2”编译器标志。使用O3优化标志，需要指定__COMPLILE_O3环境变量：set __COMPLILE_O3=1编译前（so before python3 setup.py buildor python -m pip install -e .）

这个编译参数会增加编译时间，但会使包更快。

启用“-march=native”优化

默认情况下，为了可移植性，我们不使用-march=native标志进行编译。这会导致某些平台上的一些错误。如果你想进一步提高性能。

您可以set __COMPILE_MARCHNATIVE=1在编译之前启用它（所以在 python3 setup.py buildor之前python -m pip install -e .）

分析代码

这是目前正在进行的工作。它远非完美，可能只适用于linux。

有关更多详细信息，请参阅https://github.com/xflash96/pybind11_package_example/blob/main/tutorial.md#perf。

cd benchmarks
perf record ./test_profile.py
perf report

本地测试

还有一些官方测试，以确保求解器返回与 pandapower 相同的结果，在“lightsim2grid/tests”中执行

cd lightsim2grid/tests
python -m unittest discover

该测试确保该模拟器给出的结果与 pandapower 在使用 Newton-Raphson 算法时给出的结果一致，使用单个松弛总线，不对发电机执行 q 限制等。

注意要运行这些测试，您需要从源代码安装 grid2op，否则 LightSim2gridBackend 的所有测试都将失败。为此，您可以执行以下操作：

git clone https://github.com/rte-france/Grid2Op.git
cd Grid2Op
pip3 install -U -e .
cd ..

自动执行的测试

每次在 lightsim2grid 代码中进行修改时，都会在标准平台上自动执行一些测试。

目前，这些测试包括在 gcc（版本 8、10、11 和 12）和 clang（版本 10、13 和 14）上的编译。

注意clang 和 gcc 的中间版本（例如gcc 9 或 clang 12）没有定期测试，但 lightsim2grid 曾经在这些版本上工作。我们假设如果它适用于例如clang 10 和 clang 14 那么它也可以在所有中间版本上编译。

NB包可能在这些编译器的早期版本上工作（我们从未测试过）。lightsim2grid 的唯一“真正”要求是有一个支持 c++11 的编译器（至少）。

已知的问题

存储单元

存储单元的处理存在差异，当不要求在 pandapower 和 lightsim2grid 之间生产/消耗任何东西（设定点为 0）时，仅在存储单元单独在其总线上的情况下。

Pandapower 没有检测到它，情节可以继续。另一方面，lightsim2grid 检测到它并引发错误，因为在这种情况下，网格不再连接（这是所需的行为）。

编译问题

在 clang 编译器（MacOS 计算机上的默认编译器）上，有时需要将 pybind11 版本降级到 2.6.2 才能安装软件包。

您可以使用以下命令降级 pybind11：python -m pip install -U pybind11==2.6.2