Merge pull request #4018 from lisajulia/feature/pyAction-add-document…

…ation Add documentation for PyAction
OPM · Jun 26, 2024 · ae5bef9 · ae5bef9
2 parents d8279b2 + 73cc234
commit ae5bef9
Show file tree

Hide file tree

Showing 11 changed files with 326 additions and 111 deletions.
diff --git a/.github/workflows/dispatch_opm_simulators.yml b/.github/workflows/dispatch_opm_simulators.yml
@@ -0,0 +1,29 @@
+name: Dispatch to opm-simulators
+
+on:
+  push:
+    branches: master
+    paths:
+      - 'python/docstrings_common.json'
+  pull_request:
+    branches: master
+    paths:
+      - 'python/docstrings_common.json'
+
+jobs:
+  dispatch:
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v4
+
+    - name: Send dispatch to opm-simulators
+      env:
+        PERSONAL_ACCESS_TOKEN: ${{ secrets.PERSONAL_ACCESS_TOKEN }}
+      run: |
+        curl -X POST \
+          -H "Accept: application/vnd.github+json" \
+          -H "Authorization: token ${{ secrets.PERSONAL_ACCESS_TOKEN }}" \
+          https://api.github.com/repos/lisajulia/opm-simulators/dispatches \
+          -d '{"event_type":"docstrings_common_updated"}'
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -149,6 +149,21 @@ macro (sources_hook)
   endif()
   set_source_files_properties(src/opm/input/eclipse/Python/Python.cpp
                               PROPERTIES COMPILE_FLAGS -Wno-shadow)
+  if (OPM_ENABLE_PYTHON)
+    # Set the path to the input docstrings.json file and the output .hpp file
+    set(PYTHON_DOCSTRINGS_FILE "${PROJECT_SOURCE_DIR}/python/docstrings_common.json")
+    set(PYTHON_DOCSTRINGS_GENERATED_HPP "${PROJECT_BINARY_DIR}/python/cxx/OpmCommonPythonDoc.hpp")
+    # Command to run the Python script
+    add_custom_command(
+        OUTPUT ${PYTHON_DOCSTRINGS_GENERATED_HPP}
+        COMMAND ${PYTHON_EXECUTABLE} ${PROJECT_SOURCE_DIR}/python/generate_docstring_hpp.py
+                ${PYTHON_DOCSTRINGS_FILE} ${PYTHON_DOCSTRINGS_GENERATED_HPP} OPMCOMMONPYTHONDOC_HPP "Opm::Common::DocStrings"
+        DEPENDS ${PYTHON_DOCSTRINGS_FILE}
+        COMMENT "Generating OpmCommonPythonDoc.hpp from JSON file"
+    )
+    list(INSERT opm-common_SOURCES 0 ${PYTHON_DOCSTRINGS_GENERATED_HPP})
+  endif()
+
   if(QuadMath_FOUND)
     get_target_property(qm_defs QuadMath::QuadMath INTERFACE_COMPILE_DEFINITIONS)
     get_target_property(qm_options QuadMath::QuadMath INTERFACE_COMPILE_OPTIONS)
@@ -157,7 +172,6 @@ macro (sources_hook)
                                 PROPERTIES COMPILE_DEFINITIONS "${qm_defs}"
                                 COMPILE_OPTIONS "${qm_options}")
   endif()
-
 endmacro (sources_hook)
 
 macro (fortran_hook)
@@ -456,6 +470,13 @@ if (OPM_ENABLE_PYTHON)
       install( PROGRAMS "python/install.py" DESTINATION "${OPM_PYTHON_COMMON_DIR}" )
   endif()
 
+  if (OPM_ENABLE_PYTHON OR OPM_INSTALL_PYTHON) # if OPM_ENABLE_EMBEDDED_PYTHON is true, then OPM_ENABLE_PYTHON is also automatically true
+    ## Need to install this Python script such that it can be used by opm-simulators when building against an installed
+    ##  opm-common
+    install( PROGRAMS "python/generate_docstring_hpp.py" DESTINATION "${OPM_PYTHON_COMMON_DIR}" )
+    install( FILES "python/docstrings_common.json" DESTINATION "${OPM_PYTHON_COMMON_DIR}" )
+  endif()
+
   # Observe that if the opmcommon library has been built as a shared library the
   # python library opmcommon_python will in general not find it runtime while
   # testing.

diff --git a/python/cxx/eclipse_state.cpp b/python/cxx/eclipse_state.cpp
@@ -5,6 +5,7 @@
 
 #include "export.hpp"
 
+#include <python/cxx/OpmCommonPythonDoc.hpp>
 
 namespace {
 
@@ -96,29 +97,28 @@ namespace {
 
 void python::common::export_EclipseState(py::module& module) {
 
+    using namespace Opm::Common::DocStrings;
+
     // Note: In the below class we std::shared_ptr as the holder type, see:
     //
     //  https://pybind11.readthedocs.io/en/stable/advanced/smart_ptrs.html
     //
     // this makes it possible to share the returned object with e.g. and
     //   opm.simulators.BlackOilSimulator Python object
     //
-    py::class_< EclipseState, std::shared_ptr<EclipseState> >( module, "EclipseState", R"pbdoc(
-            The Opm::EclipseState class - this is a representation of all static properties in the model,
-            ranging from porosity to relperm tables. The content of the EclipseState is immutable and may not
-            be changed at runtime.)pbdoc")
+    py::class_< EclipseState, std::shared_ptr<EclipseState> >( module, "EclipseState", EclipseStateClass_docstring)
         .def(py::init<const Deck&>())
         .def_property_readonly( "title", &EclipseState::getTitle )
         .def( "field_props",    &get_field_props, ref_internal)
         .def( "grid",           &EclipseState::getInputGrid, ref_internal)
         .def( "config",         &EclipseState::cfg, ref_internal)
         .def( "tables",         &EclipseState::getTableManager, ref_internal)
         .def( "has_input_nnc",  &EclipseState::hasInputNNC )
-        .def( "simulation",     &EclipseState::getSimulationConfig, ref_internal)
-        .def( "input_nnc",      &getNNC )
-        .def( "faultNames",     &faultNames )
-        .def( "faultFaces",     &faultFaces, py::arg("fault_name"))
-        .def( "jfunc",          &jfunc )
+        .def( "simulation",     &EclipseState::getSimulationConfig, ref_internal, EclipseState_simulation_docstring)
+        .def( "input_nnc",      &getNNC, EclipseState_input_nnc_docstring)
+        .def( "faultNames",     &faultNames, EclipseState_faultNames_docstring)
+        .def( "faultFaces",     &faultFaces, py::arg("fault_name"), EclipseState_faultFaces_docstring)
+        .def( "jfunc",          &jfunc, EclipseState_jfunc_docstring)
         ;
 
 }
diff --git a/python/cxx/group.cpp b/python/cxx/group.cpp
@@ -2,6 +2,7 @@
 #include <pybind11/stl.h>
 #include "export.hpp"
 
+#include <python/cxx/OpmCommonPythonDoc.hpp>
 
 namespace {
 
@@ -12,9 +13,11 @@ namespace {
 
 void python::common::export_Group(py::module& module) {
 
-  py::class_< Group >( module, "Group")
-    .def_property_readonly( "name", &Group::name)
-    .def_property_readonly( "num_wells", &Group::numWells)
-    .def_property_readonly( "well_names", &wellnames );
+  using namespace Opm::Common::DocStrings;
+
+  py::class_< Group >( module, "Group", GroupClass_docstring)
+    .def_property_readonly( "name", &Group::name, Group_name_docstring)
+    .def_property_readonly( "num_wells", &Group::numWells, Group_num_wells_docstring)
+    .def_property_readonly( "well_names", &wellnames, Group_well_names_docstring);
 
 }
diff --git a/python/cxx/schedule.cpp b/python/cxx/schedule.cpp
@@ -16,6 +16,7 @@
 #include <pybind11/chrono.h>
 #include "export.hpp"
 
+#include <python/cxx/OpmCommonPythonDoc.hpp>
 
 namespace {
 
@@ -192,95 +193,34 @@ namespace {
 
 void python::common::export_Schedule(py::module& module) {
 
+    using namespace Opm::Common::DocStrings;
+
     // Note: In the below class we use std::shared_ptr as the holder type, see:
     //
     //  https://pybind11.readthedocs.io/en/stable/advanced/smart_ptrs.html
     //
     // this makes it possible to share the returned object with e.g. and
     //   opm.simulators.BlackOilSimulator Python object
     //
-    py::class_< Schedule, std::shared_ptr<Schedule> >( module, "Schedule", R"pbdoc(
-        The Opm::Schedule class - this is a representation of all the content from
-        the SCHEDULE section, notably all well and group information and the timestepping.
-    )pbdoc")
+    py::class_< Schedule, std::shared_ptr<Schedule> >( module, "Schedule", ScheduleClass_docstring)
     .def(py::init<const Deck&, const EclipseState& >(), py::arg("deck"), py::arg("eclipse_state"))
-    .def("_groups", &get_groups, py::arg("report_step"))
+    .def("_groups", &get_groups, py::arg("report_step"), Schedule_groups_docstring)
     .def_property_readonly( "start",  &get_start_time )
     .def_property_readonly( "end",    &get_end_time )
     .def_property_readonly( "timesteps", &get_timesteps )
     .def("__len__", &Schedule::size)
-    .def("__getitem__", &getitem)
-    .def("shut_well", py::overload_cast<const std::string&, std::size_t>(&Schedule::shut_well), py::arg("well_name"), py::arg("step"), R"(
-    Shut down a well at a given report step.
-
-    Args:
-        well_name (str): The name of the well to shut down.
-        report_step (int): The report step at which to shut down the well.
-
-    Raises:
-        ValueError: If the report step is in the past or exceeds the duration of the simulation.
-
-    Returns:
-        None
-    )")
-    .def("shut_well", py::overload_cast<const std::string&>(&Schedule::shut_well), py::arg("well_name"), R"(
-    Shut down a well at the current report step.
-
-    Args:
-        well_name (str): The name of the well to shut down.
-
-    Returns:
-        None
-    )")
-    .def("open_well", py::overload_cast<const std::string&, std::size_t>(&Schedule::open_well), py::arg("well_name"), py::arg("step"), R"(
-    Open a well at a given report step.
-
-    Args:
-        well_name (str): The name of the well to open.
-        report_step (int): The report step at which to open the well.
-
-    Raises:
-        ValueError: If the report step is in the past or exceeds the duration of the simulation.
-
-    Returns:
-        None
-    )")
-    .def("open_well", py::overload_cast<const std::string&>(&Schedule::open_well), py::arg("well_name"), R"(
-    Open a well at the current report step.
-
-    Args:
-        well_name (str): The name of the well to open.
-
-    Returns:
-        None
-    )")
-    .def("stop_well", py::overload_cast<const std::string&, std::size_t>(&Schedule::stop_well), py::arg("well_name"), py::arg("step"), R"(
-    Stop a well at a given report step.
-
-    Args:
-        well_name (str): The name of the well to stop.
-        report_step (int): The report step at which to stop the well.
-
-    Raises:
-        ValueError: If the report step is in the past or exceeds the duration of the simulation.
-
-    Returns:
-        None
-    )")
-    .def("stop_well", py::overload_cast<const std::string&>(&Schedule::stop_well), py::arg("well_name"), R"(
-    Stop a well at the current report step.
-
-    Args:
-        well_name (str): The name of the well to stop.
-
-    Returns:
-        None
-    )")
-    .def( "get_wells", &Schedule::getWells, py::arg("well_name_pattern"))
-    .def( "get_injection_properties", &get_injection_properties, py::arg("well_name"), py::arg("report_step"))
-    .def( "get_production_properties", &get_production_properties, py::arg("well_name"), py::arg("report_step"))
+    .def("__getitem__", &getitem, py::arg("report_step"), Schedule_getitem_docstring)
+    .def("shut_well", py::overload_cast<const std::string&, std::size_t>(&Schedule::shut_well), py::arg("well_name"), py::arg("step"), Schedule_shut_well_well_name_step_docstring)
+    .def("shut_well", py::overload_cast<const std::string&>(&Schedule::shut_well), py::arg("well_name"), Schedule_shut_well_well_name_docstring)
+    .def("open_well", py::overload_cast<const std::string&, std::size_t>(&Schedule::open_well), py::arg("well_name"), py::arg("step"), Schedule_open_well_well_name_step_docstring)
+    .def("open_well", py::overload_cast<const std::string&>(&Schedule::open_well), py::arg("well_name"), Schedule_open_well_well_name_docstring)
+    .def("stop_well", py::overload_cast<const std::string&, std::size_t>(&Schedule::stop_well), py::arg("well_name"), py::arg("step"), Schedule_stop_well_well_name_step_docstring)
+    .def("stop_well", py::overload_cast<const std::string&>(&Schedule::stop_well), py::arg("well_name"), Schedule_stop_well_well_name_docstring)
+    .def( "get_wells", &Schedule::getWells, py::arg("well_name_pattern"), Schedule_get_wells_docstring)
+    .def( "get_injection_properties", &get_injection_properties, py::arg("well_name"), py::arg("report_step"), Schedule_get_injection_properties_docstring)
+    .def( "get_production_properties", &get_production_properties, py::arg("well_name"), py::arg("report_step"), Schedule_get_production_properties_docstring)
     .def("well_names", py::overload_cast<const std::string&>(&Schedule::wellNames, py::const_), py::arg("well_name_pattern"))
-    .def( "get_well", &get_well, py::arg("well_name"), py::arg("report_step"))
+    .def( "get_well", &get_well, py::arg("well_name"), py::arg("report_step"), Schedule_get_well_docstring)
     .def( "insert_keywords", py::overload_cast<Schedule&, py::list&, std::size_t>(&insert_keywords), py::arg("keywords"), py::arg("step"))
     .def( "insert_keywords", py::overload_cast<Schedule&, const std::string&, std::size_t, const UnitSystem&>(&insert_keywords), py::arg("data"), py::arg("step"), py::arg("unit_system"))
     .def( "insert_keywords", py::overload_cast<Schedule&, const std::string&, std::size_t>(&insert_keywords), py::arg("data"), py::arg("step"))

diff --git a/python/cxx/schedule_state.cpp b/python/cxx/schedule_state.cpp
@@ -2,6 +2,8 @@
 
 #include "export.hpp"
 
+#include <python/cxx/OpmCommonPythonDoc.hpp>
+
 namespace {
         const Group& get_group(const ScheduleState& st, const std::string& group_name) {
         return st.groups.get(group_name);
@@ -18,8 +20,10 @@ namespace {
  */
 void python::common::export_ScheduleState(py::module& module) {
 
-    py::class_<ScheduleState>(module, "ScheduleState")
-        .def_property_readonly("nupcol", py::overload_cast<>(&ScheduleState::nupcol, py::const_))
-        .def("group", &get_group, ref_internal, py::arg("group_name"))
+    using namespace Opm::Common::DocStrings;
+
+    py::class_<ScheduleState>(module, "ScheduleState", ScheduleStateClass_docstring)
+        .def_property_readonly("nupcol", py::overload_cast<>(&ScheduleState::nupcol, py::const_), ScheduleState_nupcol_docstring)
+        .def("group", &get_group, ref_internal, py::arg("group_name"), ScheduleState_get_group_docstring)
         ;
 }
diff --git a/python/cxx/summary_state.cpp b/python/cxx/summary_state.cpp
@@ -25,6 +25,8 @@
 #include <pybind11/chrono.h>
 #include "export.hpp"
 
+#include <python/cxx/OpmCommonPythonDoc.hpp>
+
 namespace {
 
 
@@ -42,22 +44,21 @@ std::vector<std::string> wells(const SummaryState * st) {
 
 void python::common::export_SummaryState(py::module& module) {
 
-    py::class_<SummaryState, std::shared_ptr<SummaryState>>(module, "SummaryState", R"pbdoc(
-            The Opm::SummaryState class - this is where the current summary results of the simulator are stored.
-            The SummaryState class has methods to get hold of well, group and general variables.
-        )pbdoc")
+    using namespace Opm::Common::DocStrings;
+
+    py::class_<SummaryState, std::shared_ptr<SummaryState>>(module, "SummaryState", SummaryStateClass_docstring)
         .def(py::init<std::time_t>())
         .def("update", &SummaryState::update)
-        .def("update_well_var", &SummaryState::update_well_var, py::arg("well_name"), py::arg("variable_name"), py::arg("new_value"))
-        .def("update_group_var", &SummaryState::update_group_var, py::arg("group_name"), py::arg("variable_name"), py::arg("new_value"))
-        .def("well_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::get_well_var, py::const_), py::arg("well_name"), py::arg("variable_name"))
-        .def("group_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::get_group_var, py::const_), py::arg("group_name"), py::arg("variable_name"))
-        .def("elapsed", &SummaryState::get_elapsed)
-        .def_property_readonly("groups", groups)
-        .def_property_readonly("wells", wells)
+        .def("update_well_var", &SummaryState::update_well_var, py::arg("well_name"), py::arg("variable_name"), py::arg("new_value"), SummaryState_update_well_var_docstring)
+        .def("update_group_var", &SummaryState::update_group_var, py::arg("group_name"), py::arg("variable_name"), py::arg("new_value"), SummaryState_update_group_var_docstring)
+        .def("well_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::get_well_var, py::const_), py::arg("well_name"), py::arg("variable_name"), SummaryState_well_var_docstring)
+        .def("group_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::get_group_var, py::const_), py::arg("group_name"), py::arg("variable_name"), SummaryState_group_var_docstring)
+        .def("elapsed", &SummaryState::get_elapsed, SummaryState_elapsed_docstring)
+        .def_property_readonly("groups", groups, SummaryState_groups_docstring)
+        .def_property_readonly("wells", wells, SummaryState_wells_docstring)
         .def("__contains__", &SummaryState::has)
-        .def("has_well_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::has_well_var, py::const_), py::arg("well_name"), py::arg("variable_name"))
-        .def("has_group_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::has_group_var, py::const_), py::arg("group_name"), py::arg("variable_name"))
+        .def("has_well_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::has_well_var, py::const_), py::arg("well_name"), py::arg("variable_name"), SummaryState_has_well_var_docstring)
+        .def("has_group_var", py::overload_cast<const std::string&, const std::string&>(&SummaryState::has_group_var, py::const_), py::arg("group_name"), py::arg("variable_name"), SummaryState_has_group_var_docstring)
         .def("__setitem__", &SummaryState::set)
         .def("__getitem__", py::overload_cast<const std::string&>(&SummaryState::get, py::const_))
         ;

diff --git a/python/cxx/well.cpp b/python/cxx/well.cpp
@@ -5,6 +5,7 @@
 #include <pybind11/stl.h>
 #include "export.hpp"
 
+#include <python/cxx/OpmCommonPythonDoc.hpp>
 
 namespace {
 
@@ -34,17 +35,19 @@ namespace {
 
 void python::common::export_Well(py::module& module) {
 
+    using namespace Opm::Common::DocStrings;
+
     py::class_< Well >( module, "Well")
         .def_property_readonly( "name", &Well::name )
         .def_property_readonly( "preferred_phase", &preferred_phase )
-        .def( "pos",             &get_pos )
+        .def( "pos",             &get_pos, Well_pos_docstring)
         .def( "status",          &status )
-        .def( "isdefined",       &Well::hasBeenDefined )
+        .def( "isdefined",       &Well::hasBeenDefined, Well_isdefined_docstring)
         .def( "isinjector",      &Well::isInjector )
         .def( "isproducer",      &Well::isProducer )
         .def( "group",           &Well::groupName )
         .def( "guide_rate",      &Well::getGuideRate )
-        .def( "available_gctrl", &Well::isAvailableForGroupControl )
-        .def( "connections",     &connections );
+        .def( "available_gctrl", &Well::isAvailableForGroupControl, Well_available_gctrl_docstring)
+        .def( "connections",     &connections, Well_connections_docstring);
 
 }