Do not expose the environment related functions in the Python bindings but automatically handle it during module import and cleanup. NO user action required anymore.

Author: breyerml

README.md

@@ -805,9 +805,6 @@ Roughly the same can be achieved using our Python bindings with the following Py
 import plssvm
 from sklearn.metrics import classification_report
 
-# correctly initialize and finalize environments
-environment_guard = plssvm.environment.ScopeGuard()
-
 try:
     # create a new C-SVM parameter set, explicitly overriding the default kernel function
     params = plssvm.Parameter(kernel_type=plssvm.KernelFunctionType.POLYNOMIAL)

bindings/Python/CMakeLists.txt

@@ -41,7 +41,6 @@ set(PLSSVM_PYTHON_BINDINGS_SOURCES
     ${CMAKE_CURRENT_LIST_DIR}/classification_types.cpp
     ${CMAKE_CURRENT_LIST_DIR}/csvm.cpp
     ${CMAKE_CURRENT_LIST_DIR}/data_set.cpp
-    ${CMAKE_CURRENT_LIST_DIR}/environment.cpp
     ${CMAKE_CURRENT_LIST_DIR}/file_format_types.cpp
     ${CMAKE_CURRENT_LIST_DIR}/gamma.cpp
     ${CMAKE_CURRENT_LIST_DIR}/kernel_function_types.cpp

bindings/Python/README.md

@@ -13,7 +13,6 @@
         - [plssvm.openmp.CSVM, plssvm.hpx.CSVM, plssvm.stdpar.CSVM, plssvm.cuda.CSVM, plssvm.hip.CSVM, plssvm.opencl.CSVM, plssvm.sycl.CSVM, plssvm.dpcpp.CSVM, plssvm.adaptivecpp.CSVM, plssvm.kokkos.CSVM](#plssvmopenmpcsvm-plssvmhpxcsvm-plssvmcudacsvm-plssvmhipcsvm-plssvmopenclcsvm-plssvmsyclcsvm-plssvmdpcppcsvm-plssvmadaptivecppcsvm-plssvmkokkoscsvm)
         - [plssvm.Model](#plssvmmodel)
         - [plssvm.Version](#plssvmversion)
-        - [plssvm.environment.ScopeGuard](#plssvmenvironmentscopeguard)
         - [plssvm.detail.tracking.PerformanceTracker](#plssvmdetailtrackingperformancetracker)
         - [plssvm.detail.tracking.Events](#plssvmdetailtrackingevent-plssvmdetailtrackingevents)
     - [Free functions](#free-functions)
@@ -198,7 +197,6 @@ The following table lists all PLSSVM enumerations exposed on the Python side:
 | `ClassificationType`   | `OAA`, `OAO`                                                            | The different supported multi-class classification strategies (default: `LIBSVM`).                                                                                                                                                                          |
 | `BackendType`          | `AUTOMATIC`, `OPENMP`, `HPX`, `CUDA`, `HIP`, `OPENCL`, `SYCL`, `KOKKOS` | The different supported backends (default: `AUTOMATIC`). If `AUTOMATIC` is provided, the selected backend depends on the used target platform.                                                                                                              |
 | `VerbosityLevel`       | `QUIET`, `LIBSVM`, `TIMING`, `FULL`                                     | The different supported log levels (default: `FULL`). `QUIET` means no output, `LIBSVM` output that is as conformant as possible with LIBSVM's output, `TIMING` all timing related outputs, and `FULL` everything. Can be combined via bit-wise operations. |
-| `Status`               | `UNINITIALIZED`, `INITIALIZED`, `FINALIZED`, `UNNECESSARY`              | The different environment status values. **Note**: located in the `plssvm.environment` module.                                                                                                                                                              |                                                                                                                                                                                                                   |
 
 If a SYCL implementation is available, additional enumerations are available:
 
@@ -343,9 +341,8 @@ If the most performant backend should be used, it is sufficient to use `plssvm.C
 `sycl_implementation_type` to choose between DPC++ and AdaptiveCpp as SYCL implementations
 and `sycl_kernel_invocation_type` to choose between the two different SYCL kernel invocation types.
 
-**Note**: if the backend type is `plssvm.BackendType.HPX` it is necessary to initialize and finalize the HPX runtime.
-The runtime can be manually managed using `plssvm.environment.initialize()` and `plssvm.environment.finalize()`.
-We recommend utilizing `plssvm.environment.ScopeGuard()` to manage the lifetime of the HPX runtime automatically.
+**Note**: if the backend type is `plssvm.BackendType.HPX` or `plssvm.BackendType.Kokkos` special initialization and finalization functions must be called. 
+However, this is **automatically** handled by our Python bindings on the module import and cleanup.
 
 | methods                                                                                                                                      | description                                                                                                                                                                                                         |
 |----------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -443,19 +440,6 @@ A class encapsulating the version information of the used PLSSVM installation.
 | `minor : int`      | The minor PLSSVM version.                 |
 | `patch : int`      | The patch PLSSVM version.                 |
 
-#### `plssvm.environment.ScopeGuard`
-
-The environmental scope guard can be used to automatically finalize all necessary backend environments when it goes out of scope.
-
-| constructors                            | description                                                                                                                                                                             |
-|-----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `ScopeGuard([backends={}])`             | Create a new scope guard initializing all available backend environments. If a list of backends is provided, only initializes these backends.                                           |
-| `ScopeGuard(argc, argv, [backends={}])` | Create a new scope guard initializing all available backend environments using the provided command line arguments. If a list of backends is provided, only initializes these backends. |
-
-| methods      | description                                                                                                                       |
-|--------------|-----------------------------------------------------------------------------------------------------------------------------------|
-| `backends()` | Return all initialized backends. All backends returned by this function will be finalized when the scope guard goes out of scope. |
-
 #### `plssvm.detail.tracking.PerformanceTracker`
 
 A submodule used to track various performance statistics like runtimes, but also the used setup and hyperparameters.
@@ -549,15 +533,6 @@ If a stdpar implementation is available, additional free functions are available
 |-------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------|
 | `list_available_stdpar_implementations()` | List all available stdpar implementations (determined during PLSSVM's build step; currently always guaranteed to be only one implementation). |
 
-Additional free functions are available under `plssvm.environment.`.
-
-| function                                | description                                                                                                                                                  |
-|-----------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `get_backend_status(backend)`           | Return the current environment status of the provided backend.                                                                                               |
-| `initialize([backends={}])`             | Initialize all available backend environments. If a list of backends is provided, only initializes these backends.                                           |
-| `initialize(argc, argv, [backends={}])` | Initialize all available backend environments using the provided command line arguments. If a list of backends is provided, only initializes these backends. |
-| `finalize([backends={}])`               | Finalize all available backend environments. If a list of backends is provided, only finalizes these backends.                                               |
-
 ### Exceptions
 
 The PLSSVM Python3 bindings define a few new exception types:
@@ -576,6 +551,5 @@ The PLSSVM Python3 bindings define a few new exception types:
 | `MatrixError`                | If something went wrong in the internal matrix class. **Note**: shouldn't occur in user code.                          |
 | `KernelLaunchResourcesError` | If something went wrong during a kernel launch due to insufficient ressources.                                         |
 | `ClassificationReportError`  | If something in the classification report went wrong. **Note**: shouldn't occur in user code.                          |
-| `EnvironmentError`           | If something during environment initialization or finalization went wrong.                                             |
 
 Depending on the available backends, additional `BackendError`s are also available (e.g., `plssvm.cuda.BackendError`).

bindings/Python/environment.cpp

@@ -7,6 +7,7 @@
  *          See the LICENSE.md file in the project root for full license information.
  */
 
+#include "plssvm/environment.hpp"            // plssvm::environment::{initialize, finalize}
 #include "plssvm/exceptions/exceptions.hpp"  // plssvm::exception
 
 #include "pybind11/pybind11.h"  // PYBIND11_MODULE, py::module_, py::exception, py::register_exception_translator
@@ -32,7 +33,6 @@ void init_parameter(py::module_ &);
 void init_model(py::module_ &);
 void init_data_set(py::module_ &);
 void init_version(py::module_ &);
-void init_environment(py::module_ &);
 void init_exceptions(py::module_ &, const py::exception<plssvm::exception> &);
 void init_csvm(py::module_ &);
 void init_openmp_csvm(py::module_ &, const py::exception<plssvm::exception> &);
@@ -48,6 +48,14 @@ void init_sklearn(py::module_ &);
 PYBIND11_MODULE(plssvm, m) {
     m.doc() = "Parallel Least Squares Support Vector Machine";
 
+    // automatically initialize the environments
+    plssvm::environment::initialize();
+
+    // automatically finalize the environments
+    m.add_object("_cleanup", py::capsule([]() {
+                     plssvm::environment::finalize();
+                 }));
+
     // register PLSSVM base exception
     static py::exception<plssvm::exception> base_exception(m, "PLSSVMError");
     py::register_exception_translator([](std::exception_ptr p) {
@@ -81,7 +89,6 @@ PYBIND11_MODULE(plssvm, m) {
     init_model(m);
     init_data_set(m);
     init_version(m);
-    init_environment(m);
     init_exceptions(m, base_exception);
     init_csvm(m);
 

bindings/Python/main.cpp

@@ -1,9 +1,6 @@
 import plssvm
 from sklearn.metrics import classification_report
 
-# correctly initialize and finalize environments
-environment_guard = plssvm.environment.ScopeGuard()
-
 try:
     # create a new C-SVM parameter set, explicitly overriding the default kernel function
     params = plssvm.Parameter(kernel_type=plssvm.KernelFunctionType.POLYNOMIAL)

examples/python/main.py

@@ -1,9 +1,6 @@
 from sklearn.datasets import make_classification
 import plssvm
 
-# correctly initialize and finalize environments
-environment_guard = plssvm.environment.ScopeGuard()
-
 num_samples = 2**8
 num_features = 2**6