From 8f4c9dbfbf3773f00c4ad7f4a6a3e65c2c294863 Mon Sep 17 00:00:00 2001 From: eq-sandkav Date: Thu, 2 Jul 2026 15:52:19 +0200 Subject: [PATCH 1/5] Delete hanging section in observations docs It is unclear what this was trying to describe, but it's obvious that it has lost its example and has therefore lost its purpose. --- docs/ert/reference/configuration/observations.rst | 4 ---- 1 file changed, 4 deletions(-) diff --git a/docs/ert/reference/configuration/observations.rst b/docs/ert/reference/configuration/observations.rst index d5f6a4042d0..2caaf6946c6 100644 --- a/docs/ert/reference/configuration/observations.rst +++ b/docs/ert/reference/configuration/observations.rst @@ -209,10 +209,6 @@ keyword ERROR_MIN: This error mode is also relevant for observations that may be zero, for example water production rates. -Note that the configuration parser does not treat carriage return -different from space. Thus, the following statement is equivalent to -the previous: - .. _bulk_configuration_of_summary_observations: Bulk configuration of summary observations From ba5dfb3a1df886a3e961b110e2b9a79891a710e8 Mon Sep 17 00:00:00 2001 From: eq-sandkav Date: Thu, 2 Jul 2026 23:11:26 +0200 Subject: [PATCH 2/5] Add documentation for LOCALIZATION keyword The LOCALIZATION keyword is already referenced in the documentation for the bulk config without existing, so its time to add some documentation for this keyword. --- .../reference/configuration/observations.rst | 54 +++++++++++++++++++ ...entle_introduction_to_history_matching.rst | 2 + 2 files changed, 56 insertions(+) diff --git a/docs/ert/reference/configuration/observations.rst b/docs/ert/reference/configuration/observations.rst index 2caaf6946c6..a860aaec6d6 100644 --- a/docs/ert/reference/configuration/observations.rst +++ b/docs/ert/reference/configuration/observations.rst @@ -584,6 +584,60 @@ are correctly associated with reservoir zones. If a zone is specified but no ZONEMAP is provided, or if the observation location doesn't match the expected zone, the observation will be deactivated with a warning during the simulation. +The LOCALIZATION keyword - Configuring observations with location +----------------------------------------------------------------- + +A prerequisite for using :ref:`distance based localization ` +is to provide metadata regarding location for the observations. + +This can be configured for :ref:`summary observations ` and +:ref:`breakthrough observations ` by inserting a `LOCALIZATION` +keyword into their declarations. + +The `LOCALIZATION` object has two required fields: `NORTH` and `EAST`. Additionally, +`RADIUS` can be configured here, but will be defaulted to 3000m if absent. + +The `LOCALIZATION` object can be defined as follows: + +.. code-block:: none + + LOCALIZATION { + EAST=70; + NORTH=80; + RADIUS=2500; + }; + +And inserted into a summary observation like so: + +.. code-block:: none + + SUMMARY_OBSERVATION WOPR_OP1_141 { + KEY = WOPR; + VALUE = 1e6; + ERROR = 3e4; + DATE = 2012-02-13; + LOCALIZATION { + EAST = 70; + NORTH = 80; + RADIUS = 2500; + }; + }; + +And similarily into a :ref:`breakthrough observation ` + +The RFT observations already contains the keywords `NORTH` and `EAST` in its´ regular +configuration. These observations are therefore already correctly configured for distance +based localization. + +The radius for RFTs will be the default radius value of 3000m, but can be overwritten by +providing a `LOCALIZATION` object containing just the `RADIUS` key, e.g. + +.. code-block:: + + LOCALIZATION { + RADIUS=2500; + }; + Observation converters ---------------------- diff --git a/docs/ert/theory/gentle_introduction_to_history_matching.rst b/docs/ert/theory/gentle_introduction_to_history_matching.rst index 1c0f645c1bd..be57ed436bf 100644 --- a/docs/ert/theory/gentle_introduction_to_history_matching.rst +++ b/docs/ert/theory/gentle_introduction_to_history_matching.rst @@ -520,6 +520,8 @@ That said, adaptive localization has some practical benefits. It is relatively easy to understand, and it can be enabled with minimal configuration. In practice, the only tunable input is the correlation threshold. +.. _distance_based_localization: + Distance based localization ~~~~~~~~~~~~~~~~~~~~~~~~~~~ From 86c3f913080ba85135823f601d36a83b25120e30 Mon Sep 17 00:00:00 2001 From: eq-sandkav Date: Wed, 19 Aug 2026 16:05:08 +0200 Subject: [PATCH 3/5] Add references in bulk summary config This will link to the BREAKTHROUGH observation section and the LOCALIZATION keyword section in the places where they are referenced from the bulk configuration documentation. --- .../reference/configuration/observations.rst | 21 +++++++++++-------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/docs/ert/reference/configuration/observations.rst b/docs/ert/reference/configuration/observations.rst index a860aaec6d6..cb7c40de742 100644 --- a/docs/ert/reference/configuration/observations.rst +++ b/docs/ert/reference/configuration/observations.rst @@ -252,15 +252,16 @@ a well. The WELL keyword can contain two types of configuration: LOCALIZATION and BREAKTHROUGH. -LOCALIZATION contains two required fields: NORTH and EAST, and optionally -RADIUS. These localization attributes will be applied to all observations -sharing the same well name as the WELL configuration. - -BREAKTHROUGH allows the user to define a BREAKTHROUGH observation for -the given well. BREAKTHROUGH is configured like a regular -BREAKTHROUGH_OBSERVATION - which requires the fields KEY, THRESHOLD, DATE -and ERROR. BREAKTHROUGH will also inherit the LOCALIZATION values should -they be defined for the well. Only one occurrence of BREAKTHROUGH can +:ref:`LOCALIZATION ` is defined like a regular +:ref:`LOCALIZATION keyword ` but will be applied to all observations +in the csv file sharing the same well name as the WELL configuration. + +BREAKTHROUGH allows the user to define a +:ref:`BREAKTHROUGH observation ` for the given well. +BREAKTHROUGH is configured like a regular +:ref:`BREAKTHROUGH_OBSERVATION ` - which requires the fields +KEY, THRESHOLD, DATE and ERROR. BREAKTHROUGH will also inherit the LOCALIZATION values +should they be defined for the well. Only one occurrence of BREAKTHROUGH can be configured per WELL. A SUMMARY configuration containing all of these elements may look like: @@ -584,6 +585,8 @@ are correctly associated with reservoir zones. If a zone is specified but no ZONEMAP is provided, or if the observation location doesn't match the expected zone, the observation will be deactivated with a warning during the simulation. +.. _localization_keyword: + The LOCALIZATION keyword - Configuring observations with location ----------------------------------------------------------------- From 23cac216aaf8ffbd1a5a605f71f6946dbaffa430 Mon Sep 17 00:00:00 2001 From: eq-sandkav Date: Wed, 19 Aug 2026 16:08:37 +0200 Subject: [PATCH 4/5] Move Seismic documentation to other obs types It's nice to have all the observation types gathered in one place. --- .../reference/configuration/observations.rst | 154 +++++++++--------- 1 file changed, 77 insertions(+), 77 deletions(-) diff --git a/docs/ert/reference/configuration/observations.rst b/docs/ert/reference/configuration/observations.rst index cb7c40de742..6e346259192 100644 --- a/docs/ert/reference/configuration/observations.rst +++ b/docs/ert/reference/configuration/observations.rst @@ -585,6 +585,83 @@ are correctly associated with reservoir zones. If a zone is specified but no ZONEMAP is provided, or if the observation location doesn't match the expected zone, the observation will be deactivated with a warning during the simulation. + +.. _seismic_observation: + +SEISMIC_OBSERVATION keyword +--------------------------- + +The keyword ``SEISMIC_OBSERVATION`` is used to condition on spatially +distributed observations along a horizon, such as 4D seismic attributes +(amplitude, time-shift, impedance change, etc.). Each observation +represents a single measurement at a specific horizontal location, and a +single ``SEISMIC_OBSERVATION`` declaration typically defines many +individual measurements loaded from an external file. + +A minimal seismic observation is created as follows: + +.. code-block:: none + + SEISMIC_OBSERVATION OBS_MEAN_2025 { + OBS_FILE = path/to/observations.csv; + }; + +The name (``OBS_MEAN_2025`` above) is used as a label for the observation +within ERT and must be unique. If the name is omitted, the stem of the +observation file will be used. + +Observations are read from either a CSV file or a Parquet file. The file +type is determined from the file extension (``.csv`` or ``.parquet``). +Parquet is the preferred format for seismic observations as it is a typed, +compressed binary format that is significantly smaller and faster to load +than CSV. The file must contain one row per observation with the following +required columns: + +- ``X_UTME``: Easting coordinate of the measurement location. +- ``Y_UTMN``: Northing coordinate of the measurement location. +- ``OBS``: The observed value at that location. +- ``OBS_ERROR``: The observation error (absolute standard deviation). + +.. note:: + The ``CSV`` key is a deprecated alias for ``OBS_FILE``. + Existing configurations using ``CSV = path/to/observations.csv;`` will + continue to work but emit a deprecation warning; new configurations should + use ``OBS_FILE``. ``OBS_FILE`` and ``CSV`` cannot be combined in the same + declaration. + +An example of such a CSV could look like this: + +.. code-block:: none + + X_UTME,Y_UTMN,OBS,OBS_ERROR + 463401.665023891,6929758.90312445,0.008602961,0.005 + 463312.374851203,6929712.58234601,-0.007062605,0.005 + 463245.488743621,6929689.04095157,0.009096828,0.005 + 463198.920134567,6929645.33178924,-0.007231411,0.005 + +All observation coordinates within a single ``SEISMIC_OBSERVATION`` +declaration must be at least 0.2 m apart. Overlapping or duplicate +coordinates will cause ERT to raise a configuration error. + +Limiting observations with a boundary polygon +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +An optional ``BOUNDARY`` file may be provided to restrict which +observations are used during the update step. Observations located +outside the polygon are deactivated. The boundary file must contain a +closed polygon, given as ``X Y Z`` triplets, with the polygon terminated +by a line containing ``999.0 999.0 999.0``: + +.. code-block:: none + + SEISMIC_OBSERVATION OBS_MIN_2025 { + OBS_FILE = path/to/observations.csv; + BOUNDARY = path/to/boundary.pol; + }; + +The boundary file is resolved relative to the directory containing the +observation configuration file, the same as ``OBS_FILE``. + .. _localization_keyword: The LOCALIZATION keyword - Configuring observations with location @@ -765,80 +842,3 @@ is ``summary``. Valid formats are: - date: '2015-03-15' value: 0.015 error: 0.01 - - -.. _seismic_observation: - -SEISMIC_OBSERVATION keyword ---------------------------- - -The keyword ``SEISMIC_OBSERVATION`` is used to condition on spatially -distributed observations along a horizon, such as 4D seismic attributes -(amplitude, time-shift, impedance change, etc.). Each observation -represents a single measurement at a specific horizontal location, and a -single ``SEISMIC_OBSERVATION`` declaration typically defines many -individual measurements loaded from an external file. - -A minimal seismic observation is created as follows: - -.. code-block:: none - - SEISMIC_OBSERVATION OBS_MEAN_2025 { - OBS_FILE = path/to/observations.csv; - }; - -The name (``OBS_MEAN_2025`` above) is used as a label for the observation -within ERT and must be unique. If the name is omitted, the stem of the -observation file will be used. - -Observations are read from either a CSV file or a Parquet file. The file -type is determined from the file extension (``.csv`` or ``.parquet``). -Parquet is the preferred format for seismic observations as it is a typed, -compressed binary format that is significantly smaller and faster to load -than CSV. The file must contain one row per observation with the following -required columns: - -- ``X_UTME``: Easting coordinate of the measurement location. -- ``Y_UTMN``: Northing coordinate of the measurement location. -- ``OBS``: The observed value at that location. -- ``OBS_ERROR``: The observation error (absolute standard deviation). - -.. note:: - The ``CSV`` key is a deprecated alias for ``OBS_FILE``. - Existing configurations using ``CSV = path/to/observations.csv;`` will - continue to work but emit a deprecation warning; new configurations should - use ``OBS_FILE``. ``OBS_FILE`` and ``CSV`` cannot be combined in the same - declaration. - -An example of such a CSV could look like this: - -.. code-block:: none - - X_UTME,Y_UTMN,OBS,OBS_ERROR - 463401.665023891,6929758.90312445,0.008602961,0.005 - 463312.374851203,6929712.58234601,-0.007062605,0.005 - 463245.488743621,6929689.04095157,0.009096828,0.005 - 463198.920134567,6929645.33178924,-0.007231411,0.005 - -All observation coordinates within a single ``SEISMIC_OBSERVATION`` -declaration must be at least 0.2 m apart. Overlapping or duplicate -coordinates will cause ERT to raise a configuration error. - -Limiting observations with a boundary polygon -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -An optional ``BOUNDARY`` file may be provided to restrict which -observations are used during the update step. Observations located -outside the polygon are deactivated. The boundary file must contain a -closed polygon, given as ``X Y Z`` triplets, with the polygon terminated -by a line containing ``999.0 999.0 999.0``: - -.. code-block:: none - - SEISMIC_OBSERVATION OBS_MIN_2025 { - OBS_FILE = path/to/observations.csv; - BOUNDARY = path/to/boundary.pol; - }; - -The boundary file is resolved relative to the directory containing the -observation configuration file, the same as ``OBS_FILE``. From ca82eb81add228d18a4502c63aba31c0f712e612 Mon Sep 17 00:00:00 2001 From: eq-sandkav Date: Wed, 19 Aug 2026 16:10:55 +0200 Subject: [PATCH 5/5] Make error modes a subsection of summary Sections which are appending information to an existing section looks nice in the table of contents on the sidebar. They appear indented under the main section, in this case summary observations. --- docs/ert/reference/configuration/observations.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/ert/reference/configuration/observations.rst b/docs/ert/reference/configuration/observations.rst index 6e346259192..b4ba2d48f15 100644 --- a/docs/ert/reference/configuration/observations.rst +++ b/docs/ert/reference/configuration/observations.rst @@ -132,7 +132,7 @@ Here are two examples: .. _error_modes: Error modes for summary observations ------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The item ERROR_MODE can take three different values: ABS, REL or RELMIN. The default error mode for the :ref:`SUMMARY_OBSERVATION `