From f0420d3187211d7a53aea3e55daf19db4a32d40d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5vard=20Berland?= Date: Fri, 28 Aug 2026 14:59:51 +0200 Subject: [PATCH 1/3] Update documentation on reservoir simulators Explicitly state how NUM_CPU should be handled for Eclipse and Flow. Fix backslash rendering bug for multiline Ert config examples Fix erroneous example on supplying multiple options to Eclipse 100. Curly braces do not work. --- .../forward_model_steps.py | 68 ++++++++++++------- 1 file changed, 45 insertions(+), 23 deletions(-) diff --git a/src/ert/plugins/hook_implementations/forward_model_steps.py b/src/ert/plugins/hook_implementations/forward_model_steps.py index 780ab524e4c..9c9f9d48ab8 100644 --- a/src/ert/plugins/hook_implementations/forward_model_steps.py +++ b/src/ert/plugins/hook_implementations/forward_model_steps.py @@ -237,26 +237,33 @@ def validate_pre_experiment(self, fm_json: ForwardModelStepJSON) -> None: @staticmethod def documentation() -> ForwardModelStepDocumentation | None: return ForwardModelStepDocumentation( - description="The Eclipse 100 black-oil reservoir simulator from SLB", + description="""The Eclipse 100 black-oil reservoir simulator from SLB. + +Ert will parse the DATA-file for the :code:`PARALLEL` keyword and set up the +correct number of CPUs. If the :code:`PARALLEL` keyword is set up/computed +during the forward model, then :code:`NUM_CPU` must be set in the Ert config +for correct configuration of CPU usage. + """, category="simulators.reservoir", examples=""" -The version, number of cpu, and whether or not to ignore errors and whether -or not to produce `YOUR_CASE_NAME.h5` output files can be configured in the -configuration file when adding the job, as such: +The version, whether or not to ignore errors and whether or not to produce +:code:`YOUR_CASE_NAME.h5` output files can be configured in the configuration +file when adding the job, as such: .. code-block:: bash - FORWARD_MODEL ECLIPSE100(, =xxxx, \ - ={"--ignore-errors", "--summary-conversion"}) + FORWARD_MODEL ECLIPSE100(, =xxxx, \\ + ="--ignore-errors --summary-conversion") The :code:`OPTS` argument is optional and can be removed, fully or partially. In absence of :code:`--ignore-errors` eclipse will fail on errors. Adding the flag :code:`--ignore-errors` will result in eclipse ignoring errors. -And in absence of :code:`--summary-conversions` eclipse will run without producing -`YOUR_CASE_NAME.h5` output files. Add flag :code:`--summary-conversions` to produce -`YOUR_CASE_NAME.h5` output files. +And in absence of :code:`--summary-conversions` eclipse will run without +producing :code:`YOUR_CASE_NAME.h5` output files. Add flag +:code:`--summary-conversion` to produce :code:`YOUR_CASE_NAME.h5` output +files. """, ) @@ -305,18 +312,24 @@ def validate_pre_experiment( @staticmethod def documentation() -> ForwardModelStepDocumentation | None: return ForwardModelStepDocumentation( - description="The Eclipse 300 compositional reservoir simulator from SLB", + description="""The Eclipse 300 compositional reservoir simulator from SLB. + +Ert will parse the DATA-file for the :code:`PARALLEL` keyword and set up the +correct number of CPUs. If the :code:`PARALLEL` keyword is set up/computed +during the forward model, then :code:`NUM_CPU` must be set in the Ert config +for correct configuration of CPU usage. +""", category="simulators.reservoir", examples=""" -The version, number of cpu and whether or not to ignore errors can -be configured in the configuration file when adding the job, as such: +The version and whether or not to ignore errors can be configured in the +configuration file when adding the step, as such: .. code-block:: bash FORWARD_MODEL ECLIPSE300(, =xxxx, ="--ignore-errors") The :code:`OPTS` argument is optional and can be removed, thus running eclipse -without ignoring errors +without ignoring errors. """, ) @@ -368,15 +381,11 @@ def validate_pre_experiment(self, fm_json: ForwardModelStepJSON) -> None: @staticmethod def documentation() -> ForwardModelStepDocumentation | None: return ForwardModelStepDocumentation( - category="simulators.reservoir", - examples=""" -.. code-block:: bash - - FORWARD_MODEL FLOW(, =xxx, ="--ignore-errors") + description="""Forward model for OPM Flow simulator. -The :code:`OPTS` argument is optional and can be skipped. :code:`ECLBASE` can -also be defaulted. Multiple options in :code:`OPTS` can be supplied by -separating them with a space. +Flow will be run with the number of CPUs defined either through +the keyword :code:`NUM_CPU` or parsed from the :code:`PARALLEL` keyword +in the DATA file if :code:`NUM_CPU` is not set. ERT will be able to run the flow simulator if there is an executable named :code:`flow` or :code:`flowrun` found in the user's :code:`$PATH` environment @@ -385,9 +394,22 @@ def documentation() -> ForwardModelStepDocumentation | None: If :code:`flowrun` is found, it will take precedence, and then it will be possible to select the version of flow to use by setting :code:``. Available versions are verified towards what :code:`flowrun --report-versions` -returns. +returns. An appropriate setting for the threads parameter (per CPU core) +will automatically be selected if :code:`flowrun` is found. + +Any options that should be forwarded to the simulator should be included +in the :code:`` argument, multiple arguments can be supplied by +separating them with a space. +""", + category="simulators.reservoir", + examples=""" +.. code-block:: bash + + FORWARD_MODEL FLOW(, =rc46, ="--ignore-errors") + +The :code:`OPTS` argument is optional and can be skipped. :code:`ECLBASE` can +also be defaulted. """, - description="""Forward model for OPM Flow simulator""", ) From 924949d965155684f97e1ef062e5c31f0b6224ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5vard=20Berland?= Date: Tue, 1 Sep 2026 09:54:19 +0200 Subject: [PATCH 2/3] dontmerge: try ref --- src/ert/plugins/hook_implementations/forward_model_steps.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/ert/plugins/hook_implementations/forward_model_steps.py b/src/ert/plugins/hook_implementations/forward_model_steps.py index 9c9f9d48ab8..c242dfaeeb2 100644 --- a/src/ert/plugins/hook_implementations/forward_model_steps.py +++ b/src/ert/plugins/hook_implementations/forward_model_steps.py @@ -239,7 +239,7 @@ def documentation() -> ForwardModelStepDocumentation | None: return ForwardModelStepDocumentation( description="""The Eclipse 100 black-oil reservoir simulator from SLB. -Ert will parse the DATA-file for the :code:`PARALLEL` keyword and set up the +:ref:`DATA_FILE ` Ert will parse the DATA-file for the :code:`PARALLEL` keyword and set up the correct number of CPUs. If the :code:`PARALLEL` keyword is set up/computed during the forward model, then :code:`NUM_CPU` must be set in the Ert config for correct configuration of CPU usage. From b5e20c01ff207a37d188fb5836720773c08ec66d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?H=C3=A5vard=20Berland?= Date: Tue, 1 Sep 2026 10:40:19 +0200 Subject: [PATCH 3/3] \!fixup add link to DATA_FILE --- .../forward_model_steps.py | 25 +++++++++++-------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/src/ert/plugins/hook_implementations/forward_model_steps.py b/src/ert/plugins/hook_implementations/forward_model_steps.py index c242dfaeeb2..19936af7478 100644 --- a/src/ert/plugins/hook_implementations/forward_model_steps.py +++ b/src/ert/plugins/hook_implementations/forward_model_steps.py @@ -239,10 +239,11 @@ def documentation() -> ForwardModelStepDocumentation | None: return ForwardModelStepDocumentation( description="""The Eclipse 100 black-oil reservoir simulator from SLB. -:ref:`DATA_FILE ` Ert will parse the DATA-file for the :code:`PARALLEL` keyword and set up the -correct number of CPUs. If the :code:`PARALLEL` keyword is set up/computed -during the forward model, then :code:`NUM_CPU` must be set in the Ert config -for correct configuration of CPU usage. +If you have used the :ref:`DATA_FILE ` keyword Ert will parse the +DATA-file for the :code:`PARALLEL` keyword and set up the correct number of +CPUs. If the :code:`PARALLEL` keyword is set up/computed during the forward +model, then :code:`NUM_CPU` must be set in the Ert config for correct +configuration of CPU usage. """, category="simulators.reservoir", examples=""" @@ -314,10 +315,11 @@ def documentation() -> ForwardModelStepDocumentation | None: return ForwardModelStepDocumentation( description="""The Eclipse 300 compositional reservoir simulator from SLB. -Ert will parse the DATA-file for the :code:`PARALLEL` keyword and set up the -correct number of CPUs. If the :code:`PARALLEL` keyword is set up/computed -during the forward model, then :code:`NUM_CPU` must be set in the Ert config -for correct configuration of CPU usage. +If you have used the :ref:`DATA_FILE ` keyword Ert will parse the +DATA-file for the :code:`PARALLEL` keyword and set up the correct number of +CPUs. If the :code:`PARALLEL` keyword is set up/computed during the forward +model, then :code:`NUM_CPU` must be set in the Ert config for correct +configuration of CPU usage. """, category="simulators.reservoir", examples=""" @@ -383,9 +385,10 @@ def documentation() -> ForwardModelStepDocumentation | None: return ForwardModelStepDocumentation( description="""Forward model for OPM Flow simulator. -Flow will be run with the number of CPUs defined either through -the keyword :code:`NUM_CPU` or parsed from the :code:`PARALLEL` keyword -in the DATA file if :code:`NUM_CPU` is not set. +Flow will be run with the number of CPUs defined either through the keyword +:code:`NUM_CPU` or parsed from the :code:`PARALLEL` keyword in the DATA file +(requires usage of the :ref:`DATA_FILE ` keyword) if :code:`NUM_CPU` +is not set. ERT will be able to run the flow simulator if there is an executable named :code:`flow` or :code:`flowrun` found in the user's :code:`$PATH` environment