[Experimental] PGM CLI implementation

.github/conda_pgm_env.yml

@@ -5,7 +5,7 @@
 name: conda-pgm-env
 dependencies:
   # build env
-  - python=3.12
+  - python=3.14
   - pip
   - scikit-build-core
   # build deps
@@ -16,6 +16,7 @@ dependencies:
   - numpy
   - cmake
   - ninja
+  - cli11
   # test deps
   - pytest
   - pytest-cov

.github/workflows/build-test-release.yml

@@ -274,7 +274,12 @@ jobs:
           cmake --install build/
 
       - name: Build python
-        run: python -m pip install . --no-build-isolation --no-deps -C wheel.cmake=false
+        run: | 
+          python conda_build_preparation.py
+          python -m pip install . --no-build-isolation --no-deps -C wheel.cmake=false
 
       - name: Test
-        run: pytest
+        run: |
+          pytest
+          power-grid-model --help
+          power-grid-model --version

.gitignore

@@ -53,6 +53,9 @@ bld/
 # Visual Studio 2017 auto generated files
 Generated\ Files/
 
+# Generated during the Read the Docs build
+/docs/api_reference/cli-help.txt
+
 # MSTest test Results
 [Tt]est[Rr]esult*/
 [Bb]uild[Ll]og.*

.readthedocs.yaml

@@ -34,6 +34,8 @@ build:
       - find power_grid_model_c/power_grid_model_c/include -name *.h -exec sed -i -r "s/ PGM_NOEXCEPT//g" {} \;
       # build doxygen for C header
       - cd docs/doxygen && doxygen && cd ../..
+      # capture CLI help for the reference page
+      - UV_PROJECT_ENVIRONMENT="${READTHEDOCS_VIRTUALENV_PATH}" uv run power-grid-model --help > docs/api_reference/cli-help.txt
 
       # build class and package diagrams
       - pyreverse --no-standalone -o dot src/power_grid_model

CMakeLists.txt

@@ -45,6 +45,7 @@ find_package(Boost REQUIRED)
 find_package(Eigen3 CONFIG REQUIRED)
 find_package(nlohmann_json CONFIG REQUIRED)
 find_package(msgpack-cxx REQUIRED)
+find_package(CLI11 CONFIG REQUIRED)
 
 if(NOT WIN32)
     # thread

conda_build_preparation.py

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+# This script modifies the pyproject.toml file to remove specific sections
+#   [project.entry-points."cmake.root"] and [project.scripts]
+# and deletes the run_pgm_cli.py file from the source directory.
+# It is intended to be run as part of the conda build preparation process.
+# So that conda environment will not be confused with PyPI style Python shim and entry points.
+
+import re
+from pathlib import Path
+
+# Read the root pyproject.toml
+pyproject_path = Path(__file__).parent / "pyproject.toml"
+content = pyproject_path.read_text()
+
+# Remove [project.entry-points."cmake.root"] section
+content = re.sub(r'\n\[project\.entry-points\."cmake\.root"\].*?(?=\n\[|\Z)', "", content, flags=re.DOTALL)
+
+# Remove [project.scripts] section
+content = re.sub(r"\n\[project\.scripts\].*?(?=\n\[|\Z)", "", content, flags=re.DOTALL)
+
+# Write back to pyproject.toml
+pyproject_path.write_text(content)
+
+# Remove run_pgm_cli.py file
+run_pgm_cli_path = (
+    Path(__file__).parent / "src" / "power_grid_model" / "_core" / "power_grid_model_c" / "run_pgm_cli.py"
+)
+run_pgm_cli_path.unlink(missing_ok=True)

docs/_static/css/custom.css

@@ -6,3 +6,8 @@
 .wy-table-responsive table td, .wy-table-responsive table th {
     white-space: inherit;
 }
+
+.cli-help pre {
+    white-space: pre-wrap;
+    overflow-wrap: anywhere;
+}

docs/advanced_documentation/build-guide.md

@@ -16,7 +16,9 @@ In this repository there are three builds:
   * A dynamic library (`.dll` on Windows, `.so` on Linux, or `.dylib` on macOS) with a stable pure C API/ABI which can
     be used by any application (enabled by default).
   * An install target that installs the package containing the dynamic library (enabled by default).
-  * Native C++ unit tests.
+  * A shared library that provides the command-line interface backend.
+  * A command-line interface executable.
+  * Native C++ unit tests, including tests for the command-line interface.
   * C API tests.
   * A performance benchmark program.
   * An example C program to call the shared library.
@@ -111,6 +113,7 @@ Manual installation is only required for standalone CMake builds.
 | [eigen3](https://eigen.tuxfamily.org/)                              | Installed automatically              | CMake needs to be able find `eigen3`        | header-only | [Mozilla Public License, version 2.0](https://www.mozilla.org/en-US/MPL/2.0/)                                |
 | [nlohmann-json](https://github.com/nlohmann/json)                   | Installed automatically              | CMake needs to be able find `nlohmann_json` | header-only | [MIT](https://github.com/nlohmann/json/blob/develop/LICENSE.MIT)                                             |
 | [msgpack-cxx](https://github.com/msgpack/msgpack-c/tree/cpp_master) | Installed automatically              | CMake needs to be able find `msgpack-cxx`   | header-only | [Boost Software License - Version 1.0](https://github.com/msgpack/msgpack-c/blob/cpp_master/LICENSE_1_0.txt) |
+| [CLI11](https://github.com/CLIUtils/CLI11)                          | Installed automatically              | CMake needs to be able find `CLI11`         | header-only | [BSD 3-Clause](https://github.com/CLIUtils/CLI11/blob/main/LICENSE)                                         |
 | [doctest](https://github.com/doctest/doctest)                       | None                                 | CMake needs to be able find `doctest`       | header-only | [MIT](https://github.com/doctest/doctest/blob/master/LICENSE.txt)                                            |
 <!-- pyml enable line-length-->
 
@@ -209,8 +212,11 @@ In the developer build the following build targets (directories) are enabled:
 
 * `power_grid_model_c`: a dynamic library (`.so` on Linux, `.dylib` on macOS, `.dll` on Windows) with stable pure
   C API/ABI which can be used by any application.
+* `power_grid_model_cli_backend`: a shared library that provides the command-line interface backend.
+* `power_grid_model_cli`: the command-line interface executable (`power-grid-model`).
 * `tests/cpp_unit_tests_*`: (including subdirectories) the different unit test targets for the C++ core using the
   `doctest` framework.
+* `tests/cpp_cli_tests`: the command-line interface test target using the `doctest` framework.
 * `tests/cpp_validation_tests`: the validation test target using the `doctest` framework.
 * `tests/native_api_tests`: the C API test target using the `doctest` framework.
 * `tests/benchmark_cpp`: the C++ benchmark target for performance measure.
@@ -275,7 +281,7 @@ The recommended way to get the [C++ packages](#c) and `uv` is via [Homebrew](htt
 ```shell
 brew install \
     gdb gcovr lcov lld cmake ninja \
-    boost eigen nlohmann-json msgpack-cxx doctest uv
+  boost eigen nlohmann-json msgpack-cxx cli11 doctest uv
 ```
 
 Append the following lines into the file `${HOME}/.bashrc` (required for `scikit-build` for the Python installation):
@@ -357,7 +363,7 @@ powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | ie
 The recommended way to get [C++ packages](#c) is via `conda`. Open a miniforge console.
 
 ```shell
-conda create --yes -p C:\conda_envs\cpp_pkgs -c conda-forge libboost-headers eigen nlohmann_json msgpack-cxx doctest
+conda create --yes -p C:\conda_envs\cpp_pkgs -c conda-forge libboost-headers eigen nlohmann_json msgpack-cxx cli11 doctest
 ```
 
 ### Environment variables

docs/api_reference/cli-reference.md

@@ -0,0 +1,19 @@
+<!--
+SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+
+SPDX-License-Identifier: MPL-2.0
+-->
+
+# Power Grid Model CLI Reference
+
+This is the CLI reference for the `power-grid-model`.
+
+**The Power Grid Model CLI is still experimental. We offer no guarantee on stability of CLI arguments!**
+
+See below the CLI Reference, you can also run `power-grid-model --help` to get them:
+
+```{literalinclude} cli-help.txt
+:language: text
+:class: cli-help
+```
+

docs/index.md

@@ -100,6 +100,7 @@ user_manual/serialization
 :maxdepth: 2
 api_reference/python-api-reference
 api_reference/power-grid-model-c-api-reference
+api_reference/cli-reference
 ```
 
 ```{toctree}

docs/quickstart.md

@@ -162,3 +162,7 @@ This is what makes Power Grid Model a powerful calculation engine.
 You need to create a batch update dataset and put it in the `update_data` argument of `calculate_power_flow`.
 Please refer to [Power Flow Example](examples/Power%20Flow%20Example.ipynb) for a detailed tutorial about how to execute
 batch calculations.
+
+## Power Grid Model Command Line Interface (CLI)
+
+Power Grid Model also provides an experimental CLI. See [CLI API Reference](api_reference/cli-reference.md) for more details.

power_grid_model_c/CMakeLists.txt

@@ -5,3 +5,5 @@
 add_subdirectory("power_grid_model")
 add_subdirectory("power_grid_model_c")
 add_subdirectory("power_grid_model_cpp")
+add_subdirectory("power_grid_model_cli_backend")
+add_subdirectory("power_grid_model_cli")

power_grid_model_c/power_grid_model_cli/CMakeLists.txt

@@ -0,0 +1,21 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+add_executable(power_grid_model_cli main.cpp)
+
+target_link_libraries(power_grid_model_cli PRIVATE power_grid_model_cli_backend)
+
+set_property(TARGET power_grid_model_cli PROPERTY INSTALL_RPATH_USE_LINK_PATH FALSE)
+set_property(TARGET power_grid_model_cli PROPERTY OUTPUT_NAME "power-grid-model")
+if(APPLE)
+  set_property(TARGET power_grid_model_cli PROPERTY INSTALL_RPATH "@loader_path/../${CMAKE_INSTALL_LIBDIR}")
+elseif(UNIX) # Linux, BSD (not Windows/macOS)
+  set_property(TARGET power_grid_model_cli PROPERTY INSTALL_RPATH "$ORIGIN/../${CMAKE_INSTALL_LIBDIR}")
+endif()
+
+install(
+    TARGETS power_grid_model_cli
+    EXPORT power_grid_modelTargets
+    COMPONENT power_grid_model
+)

power_grid_model_c/power_grid_model_cli/main.cpp

@@ -0,0 +1,7 @@
+// SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+//
+// SPDX-License-Identifier: MPL-2.0
+
+#include <power_grid_model_cli_backend/cli_main.h>
+
+int main(int argc, char** argv) { return PGM_cli_main(argc, argv, nullptr, nullptr, nullptr); }

power_grid_model_c/power_grid_model_cli_backend/CMakeLists.txt

@@ -0,0 +1,73 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+add_library(
+    power_grid_model_cli_backend
+    SHARED
+    "src/cli_main.cpp"
+    "src/cli_options.cpp"
+    "src/pgm_calculation.cpp"
+)
+
+target_include_directories(
+    power_grid_model_cli_backend
+    PUBLIC
+        $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+        $<INSTALL_INTERFACE:include>
+    PRIVATE
+        ${CMAKE_CURRENT_SOURCE_DIR}/src
+)
+
+file(
+    GLOB_RECURSE pgm_cli_backend_public_headers
+    "${CMAKE_CURRENT_SOURCE_DIR}/include/*.h"
+)
+
+target_link_libraries(power_grid_model_cli_backend PRIVATE power_grid_model_c)
+target_link_libraries(power_grid_model_cli_backend PRIVATE power_grid_model_cpp)
+target_link_libraries(power_grid_model_cli_backend PRIVATE CLI11::CLI11)
+
+target_compile_definitions(
+    power_grid_model_cli_backend
+    PRIVATE
+        PGM_CLI_BACKEND_EXPORTS
+        PGM_ENABLE_EXPERIMENTAL
+)
+
+target_sources(
+    power_grid_model_cli_backend
+    PUBLIC
+        FILE_SET pgm_cli_backend_public_headers
+            TYPE HEADERS
+            BASE_DIRS "${CMAKE_CURRENT_SOURCE_DIR}/include/"
+            FILES "${pgm_cli_backend_public_headers}"
+)
+
+set_target_properties(
+    power_grid_model_cli_backend
+    PROPERTIES VERSION ${PGM_VERSION} SOVERSION ${PGM_VERSION_MAJOR}
+)
+
+set_property(TARGET power_grid_model_cli_backend PROPERTY INSTALL_RPATH_USE_LINK_PATH FALSE)
+if(APPLE)
+    set_property(TARGET power_grid_model_cli_backend PROPERTY INSTALL_RPATH "@loader_path")
+elseif(UNIX) # Linux, BSD (not Windows/macOS)
+    set_property(TARGET power_grid_model_cli_backend PROPERTY INSTALL_RPATH "$ORIGIN")
+endif()
+
+if(NOT PGM_MSVC_REPRODUCIBLE_BUILD)
+    set_target_properties(
+        power_grid_model_cli_backend
+        PROPERTIES
+            INTERPROCEDURAL_OPTIMIZATION_RELEASE TRUE
+            INTERPROCEDURAL_OPTIMIZATION_RELWITHDEBINFO TRUE
+    )
+endif()
+
+install(
+    TARGETS power_grid_model_cli_backend
+    EXPORT power_grid_modelTargets
+    COMPONENT power_grid_model
+    FILE_SET pgm_cli_backend_public_headers
+)

power_grid_model_c/power_grid_model_cli_backend/include/power_grid_model_cli_backend/cli_main.h

@@ -0,0 +1,62 @@
+// SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+//
+// SPDX-License-Identifier: MPL-2.0
+
+#pragma once
+#ifndef POWER_GRID_MODEL_CLI_BACKEND_CLI_MAIN_H
+#define POWER_GRID_MODEL_CLI_BACKEND_CLI_MAIN_H
+
+#ifdef _WIN32
+#define PGM_CLI_HELPER_DLL_IMPORT __declspec(dllimport)
+#define PGM_CLI_HELPER_DLL_EXPORT __declspec(dllexport)
+#define PGM_CLI_HELPER_DLL_LOCAL
+#else
+#if __GNUC__ >= 4
+#define PGM_CLI_HELPER_DLL_IMPORT __attribute__((visibility("default")))
+#define PGM_CLI_HELPER_DLL_EXPORT __attribute__((visibility("default")))
+#define PGM_CLI_HELPER_DLL_LOCAL __attribute__((visibility("hidden")))
+#else
+#define PGM_CLI_HELPER_DLL_IMPORT
+#define PGM_CLI_HELPER_DLL_EXPORT
+#define PGM_CLI_HELPER_DLL_LOCAL
+#endif
+#endif
+
+#ifdef PGM_CLI_BACKEND_EXPORTS
+#define PGM_CLI_API PGM_CLI_HELPER_DLL_EXPORT
+#else
+#define PGM_CLI_API PGM_CLI_HELPER_DLL_IMPORT
+#endif
+#define PGM_CLI_LOCAL PGM_CLI_HELPER_DLL_LOCAL
+
+#ifdef __cplusplus
+#define PGM_CLI_NOEXCEPT noexcept
+#else
+#define PGM_CLI_NOEXCEPT
+#endif
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// NOLINTNEXTLINE(modernize-use-using)
+typedef void (*PGM_CLIMessageCallback)(char const* msg, void* user_data);
+
+/**
+ * @brief CLI entry point for the Power Grid Model command line interface.
+ *
+ * @param argc Number of command line arguments.
+ * @param argv Command line arguments.
+ * @param cout_callback Callback used for standard output. When null, std::cout is used.
+ * @param cerr_callback Callback used for standard error. When null, std::cerr is used.
+ * @param user_data Opaque user data forwarded to the callbacks.
+ * @return Process exit code.
+ */
+PGM_CLI_API int PGM_cli_main(int argc, char** argv, PGM_CLIMessageCallback cout_callback,
+                             PGM_CLIMessageCallback cerr_callback, void* user_data) PGM_CLI_NOEXCEPT;
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif // POWER_GRID_MODEL_CLI_BACKEND_CLI_MAIN_H