[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,7 +16,9 @@ dependencies:
   - numpy
   - cmake
   - ninja
+  - cli11
   # test deps
   - pytest
   - pytest-cov
   - msgpack-python
+  - dynamic-metadata

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

@@ -273,8 +273,18 @@ jobs:
           cmake --build build/ --verbose -j1
           cmake --install build/
 
-      - name: Build python
-        run: python -m pip install . --no-build-isolation --no-deps -C wheel.cmake=false
+      - name: Build python (Linux)
+        if: matrix.os == 'ubuntu'
+        run: CONDA_BUILD=1 python -m pip install . --no-build-isolation --no-deps -C wheel.cmake=false
 
+      - name: Build python (Windows)
+        if: matrix.os == 'windows'
+        run: |
+          $env:CONDA_BUILD = "1"
+          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

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):
@@ -301,6 +307,7 @@ Install from source in develop mode and run the tests:
 ```shell
 uv sync
 uv run pytest
+uv run power-grid-model -h
 ```
 
 ### Build CMake Project
@@ -357,7 +364,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
@@ -389,6 +396,7 @@ Go to the repository folder in your powershell, build project from source and ru
 ```powershell
 uv sync
 uv run pytest
+uv run power-grid-model -h
 ```
 
 #### Build Python Library from Source with Native Debug Symbols
@@ -435,7 +443,7 @@ In this section, an example is given for setup in macOS Tahoe and the project's
 The recommended way to get the [C++ packages](#c) and `uv` is via [Homebrew](https://brew.sh):
 
 ```shell
-brew install ninja cmake boost eigen nlohmann-json msgpack-cxx doctest uv
+brew install ninja cmake boost eigen nlohmann-json msgpack-cxx doctest uv cli11
 ```
 
 ### Environment variables
@@ -462,6 +470,7 @@ Install from source in develop mode and run the tests:
 ```shell
 uv sync
 uv run pytest
+uv run power-grid-model -h
 ```
 
 ### Build CMake Project

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

@@ -105,6 +105,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](example_notebooks/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.

extra_project_metadata.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: Contributors to the Power Grid Model project <powergridmodel@lfenergy.org>
+#
+# SPDX-License-Identifier: MPL-2.0
+
+"""Provide Python package entry points outside Conda builds.
+
+Regular builds expose the CMake root entry point and Python CLI shim through
+package metadata. Conda builds use the native CLI executable directly, so provide empty tables for
+these fields to avoid installing a Python shim that could conflict with it.
+"""
+
+import os
+from collections.abc import Mapping
+from typing import Any
+
+
+def dynamic_metadata(_settings: Mapping[str, Any], _project: Mapping[str, Any]) -> dict[str, Any]:
+    if "CONDA_BUILD" in os.environ:
+        return {"entry-points": {}, "scripts": {}}
+
+    return {
+        "entry-points": {"cmake.root": {"power_grid_model": "power_grid_model._core.power_grid_model_c"}},
+        "scripts": {"power-grid-model": "power_grid_model._core.power_grid_model_c.run_pgm_cli:main"},
+    }

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,25 @@
+# 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_target_properties(
+    power_grid_model_cli
+    PROPERTIES
+        INSTALL_RPATH_USE_LINK_PATH FALSE
+        OUTPUT_NAME "power-grid-model"
+)
+if(APPLE)
+  set_target_properties(power_grid_model_cli PROPERTIES INSTALL_RPATH "@loader_path/../${CMAKE_INSTALL_LIBDIR}")
+elseif(UNIX) # Linux, BSD (not Windows/macOS)
+  set_target_properties(power_grid_model_cli PROPERTIES 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_target_properties(power_grid_model_cli_backend PROPERTIES INSTALL_RPATH_USE_LINK_PATH FALSE)
+if(APPLE)
+    set_target_properties(power_grid_model_cli_backend PROPERTIES INSTALL_RPATH "@loader_path")
+elseif(UNIX) # Linux, BSD (not Windows/macOS)
+    set_target_properties(power_grid_model_cli_backend PROPERTIES 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