From ed242810edbf53aa31f6260a6f924196277d9bb7 Mon Sep 17 00:00:00 2001 From: Lisa Julia Nebel Date: Wed, 10 Jul 2024 19:08:59 +0200 Subject: [PATCH] Improve documentation for the 'start flow from python' a bit (according to Atgeirrs wishes from last 5.7.2024) --- .../{embedded.rst => embedded-python.rst} | 9 +-- python/sphinx_docs/docs/flow-in-python.rst | 63 +++++++++++++++++++ python/sphinx_docs/docs/index.rst | 13 ++-- python/sphinx_docs/docs/introduction.rst | 7 --- 4 files changed, 76 insertions(+), 16 deletions(-) rename python/sphinx_docs/docs/{embedded.rst => embedded-python.rst} (91%) create mode 100644 python/sphinx_docs/docs/flow-in-python.rst delete mode 100644 python/sphinx_docs/docs/introduction.rst diff --git a/python/sphinx_docs/docs/embedded.rst b/python/sphinx_docs/docs/embedded-python.rst similarity index 91% rename from python/sphinx_docs/docs/embedded.rst rename to python/sphinx_docs/docs/embedded-python.rst index 011c99b..398252c 100644 --- a/python/sphinx_docs/docs/embedded.rst +++ b/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: diff --git a/python/sphinx_docs/docs/flow-in-python.rst b/python/sphinx_docs/docs/flow-in-python.rst new file mode 100644 index 0000000..de6be73 --- /dev/null +++ b/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() diff --git a/python/sphinx_docs/docs/index.rst b/python/sphinx_docs/docs/index.rst index b3a1ec4..0df9ea5 100644 --- a/python/sphinx_docs/docs/index.rst +++ b/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 ================== diff --git a/python/sphinx_docs/docs/introduction.rst b/python/sphinx_docs/docs/introduction.rst deleted file mode 100644 index 5b8bb5c..0000000 --- a/python/sphinx_docs/docs/introduction.rst +++ /dev/null @@ -1,7 +0,0 @@ -Introduction -============ - -Documentation for the OPM Python interfaces. - -#TODO: expand on the introduction, add information about installation and requirements for example. Some example code would also be nice. -