Docs for opm common and embedded

cmake/modules/OpmPythonGenerateDocStrings.cmake

@@ -1,15 +1,29 @@
 # Set the path to the input docstrings.json file and the output .hpp file
-set(PYTHON_DOCSTRINGS_FILE "${PROJECT_SOURCE_DIR}/docs/docstrings.json")
-set(DOCSTRINGS_GENERATED_HPP "PyBlackOilSimulatorDoc.hpp")
-set(DOCSTRINGS_GENERATED_HEADER_PATH "${PROJECT_BINARY_DIR}/${TEMP_GEN_DIR}/${DOCSTRINGS_GENERATED_HPP}")
+set(PYBLACKOIL_DOCSTRINGS_FILE "${PROJECT_SOURCE_DIR}/docs/docstrings_simulators.json")
+set(PYBLACKOIL_DOCSTRINGS_GENERATED_HPP "PyBlackOilSimulatorDoc.hpp")
+set(PYBLACKOIL_DOCSTRINGS_GENERATED_HEADER_PATH "${PROJECT_BINARY_DIR}/${TEMP_GEN_DIR}/${PYBLACKOIL_DOCSTRINGS_GENERATED_HPP}")
 
-# Command to run the Python script to generate the .hpp file
+set(COMMON_DOCSTRINGS_FILE "${PROJECT_SOURCE_DIR}/docs/docstrings_common.json")
+set(COMMON_DOCSTRINGS_GENERATED_HPP "OpmCommonPythonDoc.hpp")
+set(COMMON_DOCSTRINGS_GENERATED_HEADER_PATH "${PROJECT_BINARY_DIR}/${TEMP_GEN_DIR}/${COMMON_DOCSTRINGS_GENERATED_HPP}")
+
+# Commands to run the Python script to generate the .hpp file
+
+add_custom_command(
+   OUTPUT ${PYBLACKOIL_DOCSTRINGS_GENERATED_HEADER_PATH}
+   COMMAND ${Python3_EXECUTABLE} ${PROJECT_SOURCE_DIR}/helper_scripts/generate_docstring_hpp.py ${PYBLACKOIL_DOCSTRINGS_FILE} "${PYBLACKOIL_DOCSTRINGS_GENERATED_HEADER_PATH}"
+   PYBLACKOILSIMULATORDOC_HPP "Opm::Pybind::DocStrings"
+   DEPENDS ${PYBLACKOIL_DOCSTRINGS_FILE}
+   COMMENT "Generating ${PYBLACKOIL_DOCSTRINGS_GENERATED_HPP} from JSON file"
+)
 add_custom_command(
-   OUTPUT ${DOCSTRINGS_GENERATED_HEADER_PATH}
-   COMMAND ${Python3_EXECUTABLE} ${PROJECT_SOURCE_DIR}/helper_scripts/generate_docstring_hpp.py ${PYTHON_DOCSTRINGS_FILE} "${DOCSTRINGS_GENERATED_HEADER_PATH}"
-   DEPENDS ${PYTHON_DOCSTRINGS_FILE}
-   COMMENT "Generating ${DOCSTRINGS_GENERATED_HPP} from JSON file"
+   OUTPUT ${COMMON_DOCSTRINGS_GENERATED_HEADER_PATH}
+   COMMAND ${Python3_EXECUTABLE} ${PROJECT_SOURCE_DIR}/helper_scripts/generate_docstring_hpp.py ${COMMON_DOCSTRINGS_FILE} "${COMMON_DOCSTRINGS_GENERATED_HEADER_PATH}"
+   OPMCOMMONPYTHONDOC_HPP "Opm::Common::DocStrings"
+   DEPENDS ${COMMON_DOCSTRINGS_FILE}
+   COMMENT "Generating ${COMMON_DOCSTRINGS_GENERATED_HPP} from JSON file"
 )
 
-# Create a custom target for the generated header file
-add_custom_target(generate_docstring_hpp DEPENDS ${DOCSTRINGS_GENERATED_HEADER_PATH})
+# Create custom targets for the generated header files
+add_custom_target(pyblackoil_generate_docstring_hpp DEPENDS ${PYBLACKOIL_DOCSTRINGS_GENERATED_HEADER_PATH})
+add_custom_target(common_generate_docstring_hpp DEPENDS ${COMMON_DOCSTRINGS_GENERATED_HEADER_PATH})

cmake/modules/OpmPythonSetupOpmSimulatorsBindings.cmake

@@ -13,7 +13,8 @@ function (build_opm_simulators_pybind11_module)
     "${MODULE_VERSION_OBJECT_FILE}"
   )
   # Make sure the module depends on the generated header file
-  add_dependencies(simulators generate_docstring_hpp)
+  add_dependencies(simulators pyblackoil_generate_docstring_hpp)
+  add_dependencies(simulators common_generate_docstring_hpp)
 
   set_target_properties(
            simulators PROPERTIES
@@ -26,4 +27,4 @@ function (build_opm_simulators_pybind11_module)
   target_include_directories(simulators PRIVATE "${PROJECT_BINARY_DIR}/${TEMP_GEN_DIR}")
 endfunction()
 
-build_opm_simulators_pybind11_module()
+build_opm_simulators_pybind11_module()

docs/docs/common.rst

@@ -0,0 +1,4 @@
+OPM Common Python Documentation
+===============================
+
+.. opm_common_docstrings::

docs/docs/conf.py

@@ -1,6 +1,6 @@
 # Configuration file for the Sphinx documentation builder.
 
-project = "opm"
+project = "OPM Python Documentation"
 copyright = "2024 Equinor ASA"
 author = "Håkon Hægland"
 
@@ -37,7 +37,8 @@ def extract_opm_python_release():
 # Our sphinx extension that will use the docstrings.json file to generate documentation
 extensions = ["opm_python_docs.sphinx_ext_docstrings"]
 # Path to docstrings.json
-opm_python_docstrings_path = os.path.abspath('../docstrings.json')
+opm_simulators_docstrings_path = os.path.abspath('../docstrings_simulators.json')
+opm_common_docstrings_path = os.path.abspath('../docstrings_common.json')
 
 templates_path = ["_templates"]
 exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]

docs/docs/embedded.rst

@@ -0,0 +1,52 @@
+OPM Embedded Python Documentation
+=================================
+
+The PYACTION keyword is a flow specific keyword which allows for executing embedded Python
+code in the SCHEDULE section. The embedded Python code will then be executed at the end of each successful timestep.
+
+The PYACTION keyword is inspired
+by the ACTIONX keyword, but instead of a .DATA formatted condition you
+are allowed to implement the condition with a general Python script. The
+ACTIONX keywords are very clearly separated in a condition part and an
+action part in the form of a list of keywords which are effectively injected in
+the SCHEDULE section when the condition evaluates to true.
+This is not so for PYACTION where there is one Python script in which both
+conditions can be evaluated and changes applied.
+
+In order to enable the PYACTION keyword:
+
+1. OPM flow must be compiled with the cmake switches -DOPM ENABLE EMBEDDED PYTHON=ON and -DOPM ENABLE PYTHON=ON, the default is to build with these switches set to OFF.
+
+2. The keyword PYACTION must be added to the SCHEDULE section:
+
+.. code-block:: python
+
+	<PYACTION\_NAME>  <SINGLE/UNLIMITED> /
+	<pythonscript> /
+
+3. You need to provide the Python script.
+
+
+To interact with the simulator in the embedded Python code, you can access four variables from the simulator:
+
+.. code-block:: python
+
+	# Python module opm_embedded
+	import opm_embedded
+	# The current EclipseState
+	ecl_state = opm_embedded.current_ecl_state
+	# The current Schedule
+	schedule = opm_embedded.current_schedule
+	# The current SummaryState
+	summary_state = opm_embedded.current_summary_state
+	# The current report step
+	report_step = opm_embedded.current_report_step 
+
+
+- current_ecl_state: An instance of the `EclipseState <common.html#opm.io.ecl_state.EclipseState>`_ class - this is a representation of all static properties in the model, ranging from porosity to relperm tables. The content of the ecl state is immutable - you are not allowed to change the static properties at runtime.
+
+- current_schedule: An instance of the `Schedule <common.html#opm.io.schedule.Schedule>`_ class - this is a representation of all the content from the SCHEDULE section, notably all well and group information and the timestepping.
+
+- current_report_step: This is an integer for the report step we are currently working on. Observe that the PYACTION is called for every simulator timestep, i.e. it will typically be called multiple times with the same value for the report step argument.
+
+- current_summary_state: An instance of the `SummaryState <common.html#opm.io.sim.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.

docs/docs/index.rst

@@ -1,13 +1,15 @@
-Welcome to the Python documentation for opm-simulators!
-=======================================================
+Welcome to the Python documentation for OPM Flow!
+=================================================
 
 .. toctree::
     :maxdepth: 1
     :caption: Contents:
 
     introduction
-    python
-
+    common
+    simulators
+    embedded
+
 Indices and tables
 ==================
 

docs/docs/introduction.rst

@@ -1,4 +1,4 @@
 Introduction
 ============
 
-Documentation for the ``opm.simulators`` Python module.
+Documentation for the OPM Python interfaces.

docs/docs/simulators.rst

@@ -0,0 +1,5 @@
+OPM Simulators Python Documentation
+===================================
+
+.. opm_simulators_docstrings::
+