Add localization keyword documentation

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 <summary_observation>`
@@ -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
@@ -256,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.
+:ref:`LOCALIZATION <localization_keyword>` is defined like a regular
+:ref:`LOCALIZATION keyword <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 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
+BREAKTHROUGH allows the user to define a
+:ref:`BREAKTHROUGH observation <breakthrough_observation>` for the given well.
+BREAKTHROUGH is configured like a regular
+:ref:`BREAKTHROUGH_OBSERVATION <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:
@@ -589,6 +586,139 @@ If a zone is specified but no ZONEMAP is provided, or if the observation locatio
 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
+-----------------------------------------------------------------
+
+A prerequisite for using :ref:`distance based localization <distance_based_localization>`
+is to provide metadata regarding location for the observations.
+
+This can be configured for :ref:`summary observations <summary_observation>` and
+:ref:`breakthrough observations <breakthrough_observation>` 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 <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
 ----------------------
 
@@ -712,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``.

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
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~