Improve documentation for the 'start flow from python' a bit (accordi…

…ng to Atgeirrs wishes from last week

python/sphinx_docs/docs/embedded.rst → python/sphinx_docs/docs/embedded-python.rst

@@ -1,5 +1,5 @@
-OPM Embedded Python Documentation
-=================================
+Run embedded Python code in OPM flow
+====================================
 
 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.
@@ -16,6 +16,7 @@ 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.
+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,61 @@
+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 distro 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:: python
+		#! /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:: python
+		$ PYTHONPATH=/opt/opm/lib/python3.11/site-packages python3 spe1case1.py
+
+	where 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()
+
+#TODO: expand on the introduction, add information about installation and requirements for example. Some example code would also be nice.
+

python/sphinx_docs/docs/index.rst

@@ -2,17 +2,19 @@ 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 :ref:`flow-in-python`)
+- running a Python script embedded in a simulation (see :ref:`embedded-python`)
 
+
+Contents
+========
 .. toctree::
     :maxdepth: 1
-    :caption: Contents:
 
-    introduction
+    flow-in-python
+    embedded-python
     common
     simulators
-    embedded
 
 Indices and tables
 ==================