Improve documentation for the 'start flow from python' a bit (according to Atgeirrs wishes from last 5.7.2024)

Author: Lisa Julia Nebel

python/sphinx_docs/docs/embedded.rst …hon/sphinx_docs/docs/embedded-python.rstpython/sphinx_docs/docs/embedded.rst renamed to python/sphinx_docs/docs/embedded-python.rst python/sphinx_docs/docs/embedded.rst renamed to python/sphinx_docs/docs/embedded-python.rst

@@ -1,7 +1,7 @@
-OPM Embedded Python Documentation
-=================================
+Run Python embedded in OPM Flow
+===============================
 
-The PYACTION keyword is a flow specific keyword which allows for executing embedded Python
+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
@@ -15,7 +15,8 @@ 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.
+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.
+You can also change these settings in the CMakeLists.txt of opm-common.
 
 2. The keyword PYACTION must be added to the SCHEDULE section:
 

python/sphinx_docs/docs/flow-in-python.rst

@@ -0,0 +1,63 @@
+Run OPM Flow from Python
+========================
+
+To run OPM from Python, you need to:
+
+1. Compile Flow with python support:
+
+- Add the cmake flags -DOPM_ENABLE_PYTHON=ON and -DOPM_INSTALL_PYTHON=ON.
+- Optionally add prefix -DCMAKE_INSTALL_PREFIX=/opt/opm to install outside the standard directories.
+- Optionally specify python binary -DPython3_EXECUTABLE=/home/user/miniconda3/envs/rkt/bin/python3 if you don't want to use the system python, e.g. use a python from pyenv or from a conda environment.
+
+Sample compilation on linux:
+
+.. code-block:: bash
+
+		#! /bin/bash
+
+		flags="-DPython3_EXECUTABLE=/home/hakon/miniconda3/envs/rkt/bin/python3 -DOPM_ENABLE_PYTHON=ON -DOPM_INSTALL_PYTHON=ON -DCMAKE_INSTALL_PREFIX=/opt/opm"
+		for repo in opm-common opm-grid opm-models opm-simulators
+		do
+		    cd "$repo"
+		    mkdir -p build
+		    cd build
+		    cmake  $flags ..
+		    make -j8
+		    sudo make install
+		    cd ..
+		    cd ..
+		done
+
+2. Now you should be able to use the module from a Python script.
+
+If you installed in a non-standard directory by specifying -DCMAKE_INSTALL_PREFIX you may need to set the PYTHONPATH environment variable before running your Python script, for example:
+
+.. code-block:: bash
+
+		PYTHONPATH=/opt/opm/lib/python3.11/site-packages python3 spe1case1.py
+
+Here, spe1case1.py could be:
+
+.. code-block:: python
+
+		import os
+		from opm.simulators import BlackOilSimulator
+		from opm.io.parser import Parser
+		from opm.io.ecl_state import EclipseState
+		from opm.io.schedule import Schedule
+		from opm.io.summary import SummaryConfig
+
+		os.chdir("SPE1CASE1")
+		deck  = Parser().parse('SPE1CASE1.DATA')
+		state = EclipseState(deck)
+		schedule = Schedule( deck, state )
+		summary_config = SummaryConfig(deck, state, schedule)
+
+		sim = BlackOilSimulator(deck, state, schedule, summary_config)
+		sim.step_init()
+		sim.step()
+		poro = sim.get_porosity()
+		poro = poro *.95
+		sim.set_porosity(poro)
+		sim.step()
+		sim.step_cleanup()

python/sphinx_docs/docs/index.rst

@@ -2,17 +2,20 @@ Welcome to the Python documentation for OPM Flow!
 =================================================
 
 There are two Python APIs within OPM Flow:
-- running flow from Python code using the Python bindings
-- running a Python script embedded in a simulation
 
+- running Flow from Python code using the Python bindings (see :doc:`flow-in-python`)
+- running a Python script embedded in a simulation (see :doc:`embedded-python`)
+
+
+Contents
+========
 .. toctree::
     :maxdepth: 1
-    :caption: Contents:
 
-    introduction
+    flow-in-python
+    embedded-python
     common
     simulators
-    embedded
 
 Indices and tables
 ==================