From 77b59cb97606eb76f7d48ddc1d82ba7e43e8402a Mon Sep 17 00:00:00 2001 From: Lisa Julia Nebel Date: Wed, 10 Jul 2024 14:06:56 +0200 Subject: [PATCH] Improve documentation for the 'start flow from python' a bit (according to Atgeirrs wishes from last week --- .../{embedded.rst => embedded-python.rst} | 5 +- python/sphinx_docs/docs/flow-in-python.rst | 61 +++++++++++++++++++ python/sphinx_docs/docs/index.rst | 12 ++-- python/sphinx_docs/docs/introduction.rst | 7 --- 4 files changed, 71 insertions(+), 14 deletions(-) rename python/sphinx_docs/docs/{embedded.rst => embedded-python.rst} (95%) 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 95% rename from python/sphinx_docs/docs/embedded.rst rename to python/sphinx_docs/docs/embedded-python.rst index 011c99b..3c74ddc 100644 --- a/python/sphinx_docs/docs/embedded.rst +++ b/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: 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..64b8d16 --- /dev/null +++ b/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. + diff --git a/python/sphinx_docs/docs/index.rst b/python/sphinx_docs/docs/index.rst index b3a1ec4..6ff6e1b 100644 --- a/python/sphinx_docs/docs/index.rst +++ b/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 ================== 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. -