xtgeo 4.14.0__cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

xtgeo/grid3d/_grdecl_format.py

@@ -0,0 +1,309 @@
+from __future__ import annotations
+
+import warnings
+from contextlib import contextmanager
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from xtgeo.common import null_logger
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+    from io import TextIOWrapper
+
+    from xtgeo.common.types import FileLike
+
+logger = null_logger(__name__)
+
+
+def run_length_encoding(arr: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Perform run-length encoding on a 1D NumPy array.
+
+    Run-length encoding is a data compression technique that represents
+    consecutive  repeated values as a single value and its count.
+
+    Args:
+        arr (np.ndarray): A 1D NumPy array to be encoded.
+
+    Returns:
+        tuple[np.ndarray, np.ndarray]: A tuple containing two 1D NumPy arrays:
+            - counts (np.ndarray): An array of counts representing the number
+              of consecutive occurrences of each unique value.
+            - values (np.ndarray): An array of the unique values corresponding to
+              the counts.
+
+    Examples:
+        >>> import numpy as np
+        >>> arr = np.array([1, 1, 2, 2, 2, 3, 3, 1, 1, 1])
+        >>> counts, values = run_length_encoding(arr)
+        >>> print(counts)
+        [2 3 2 3]
+        >>> print(values)
+        [1 2 3 1]
+
+        >>> arr = np.array([5, 5, 5, 5, 5])
+        >>> counts, values = run_length_encoding(arr)
+        >>> print(counts)
+        [5]
+        >>> print(values)
+        [5]
+
+    """
+    change_indices = np.where(~np.isclose(arr[:-1], arr[1:]))[0] + 1
+    counts = np.diff(np.concatenate(([0], change_indices, [len(arr)])))
+    values = arr[np.concatenate(([0], change_indices))]
+
+    return counts, values
+
+
+def split_line(line: str) -> Generator[str, None, None]:
+    """
+    split a keyword line inside a grdecl file. This splits the values of a
+    'simple' keyword into tokens. ie.
+
+    >>> list(split_line("3 1.0 3*4 PORO 3*INC 'HELLO WORLD  ' 3*'NAME'"))
+    ['3', '1.0', '3*4', 'PORO', '3*INC', "'HELLO WORLD  '", "3*'NAME'"]
+
+    note that we do not require string literals to have delimiting space at the
+    end, but at the start. This is to be permissive at the end (as there is no
+    formal requirement for spaces at end of string literals), but no space at
+    the start of a string literal might indicate a repeating count.
+
+    >>> list(split_line("3'hello world'4"))
+    ["3'hello world'", '4']
+
+    """
+    value = ""
+    inside_str = False
+    for char in line:
+        if char == "'":
+            # Either the start or
+            # the end of a string literal
+            if inside_str:
+                yield value + char
+                value = ""
+                inside_str = False
+            else:
+                inside_str = True
+                value += char
+        elif inside_str:
+            # inside a string literal
+            value += char
+        elif value and value[-1] == "-" and char == "-":
+            # a comment
+            value = value[0:-1]
+            break
+        elif char.isspace():
+            # delimiting space
+            if value:
+                yield value
+                value = ""
+        else:
+            value += char
+    if value:
+        yield value
+
+
+def split_line_no_string(line: str) -> Generator[str, None, None]:
+    """
+    Same as split_line, but does not handle string literals, instead
+    its quite a bit faster.
+    """
+    for w in line.split():
+        if w.startswith("--"):
+            return
+        yield w
+
+
+def match_keyword(kw1: str, kw2: str) -> bool:
+    """
+    Perhaps surprisingly, the eclipse input format considers keywords
+    as 8 character strings with space denoting end. So PORO, 'PORO ', and
+    'PORO    ' are all considered the same keyword.
+
+    Note that spaces may also occur inside e.g. tracer keywords, hence 'G1 F' vs 'G1 S'
+    are different keywords.
+
+    >>> match_keyword("PORO", "PORO ")
+    True
+    >>> match_keyword("PORO", "PERM")
+    False
+    >>> match_keyword("MORETHAN8LETTERS1)", "MORETHAN8LETTER2")
+    True
+    >>> match_keyword("G1 F", "G1 S")
+    False
+
+    """
+    return kw1[0:8].rstrip() == kw2[0:8].rstrip()
+
+
+def interpret_token(val: str) -> list[str]:
+    """
+    Interpret a eclipse token, tries to interpret the
+    value in the following order:
+    * string literal
+    * keyword
+    * repreated keyword
+    * number
+
+    If the token cannot be matched, we default to returning
+    the uninterpreted token.
+
+    >>> interpret_token("3")
+    ['3']
+    >>> interpret_token("1.0")
+    ['1.0']
+    >>> interpret_token("'hello'")
+    ['hello']
+    >>> interpret_token("PORO")
+    ['PORO']
+    >>> interpret_token("3PORO")
+    ['3PORO']
+    >>> interpret_token("3*PORO")
+    ['PORO', 'PORO', 'PORO']
+    >>> interpret_token("3*'PORO '")
+    ['PORO ', 'PORO ', 'PORO ']
+    >>> interpret_token("3'PORO '")
+    ["3'PORO '"]
+
+    """
+    if val[0] == "'" and val[-1] == "'":
+        # A string literal
+        return [val[1:-1]]
+    if val[0].isalpha():
+        # A keyword
+        return [val]
+    if "*" in val:
+        multiplicand, value = val.split("*")
+        return interpret_token(value) * int(multiplicand)
+    return [val]
+
+
+IGNORE_ALL = None
+
+
+@contextmanager
+def open_grdecl(
+    grdecl_file: FileLike,
+    keywords: list[str],
+    simple_keywords: list[str] | None = None,
+    max_len: int | None = None,
+    ignore: list[str] | None = IGNORE_ALL,
+    strict: bool = True,
+) -> Generator[Generator[tuple[str, list[str]], None, None], None, None]:
+    """Generates tuples of keyword and values in records of a grdecl file.
+
+    The format of the file must be that of the GRID section of a eclipse input
+    DATA file.
+
+    The records looked for must be "simple" ie.  start with the keyword, be
+    followed by single word values and ended by a slash ('/').
+
+    .. code-block:: none
+
+        KEYWORD
+        value value value /
+
+    reading the above file with :code:`open_grdecl("filename.grdecl",
+    keywords="KEYWORD")` will generate :code:`[("KEYWORD", ["value", "value",
+    "value"])]`
+
+    open_grdecl does not follow includes, obey skips, parse MESSAGE commands or
+    make exception for groups and subrecords.
+
+    Raises:
+        ValueError: when end of file is reached without terminating a keyword,
+            or the file contains an unrecognized (or ignored) keyword.
+
+    Args:
+        keywords (List[str]): Which keywords to look for, these are expected to
+        be at the start of a line in the file  and the respective values
+        following on subsequent lines separated by whitespace. Reading of a
+        keyword is completed by a final '\'. See example above.
+
+        simple_keywords (List[str]): Similar to keywords, but faster and
+        cannot contain any string literals, such as the GRIDUNIT keyword
+        which can be followed by the string literal 'METRES '.
+
+        max_len (int): The maximum significant length of a keyword (Eclipse
+        uses 8) ignore (List[str]): Keywords that have no associated data, and
+        should be ignored, e.g. ECHO. Defaults to ignore all keywords that are
+        not part of the results.
+
+        ignore (List[str]): list of unmatched keywords to ignore, defaults to
+        ignoring all unmatched keywords. Any keyword not ignored and not in
+        the list of keywords looked for will give an error unless strict=False.
+        Although a keyword is ignored, if it has trailing values on new lines
+        those are interpreted as keywords, in order to ignore keywords with
+        trailing values, use strict=False and filter warnings. Alternatively,
+        add it to the list of expected keywords.
+
+        strict (boolean): Whether unmatched keywords should raise an error or
+        a warning.
+    """
+
+    if simple_keywords is None:
+        simple_keywords = []
+
+    def read_grdecl(
+        grdecl_stream: TextIOWrapper,
+    ) -> Generator[tuple[str, list[str]], None, None]:
+        words: list[str] = []
+        keyword = None
+        line_splitter = split_line
+
+        line_no = 1
+        line = grdecl_stream.readline()
+
+        while line:
+            if line is None:
+                break
+
+            if keyword is None:
+                snubbed = line[0 : min(max_len, len(line))] if max_len else line
+                simple_matched_keywords = [
+                    kw for kw in simple_keywords if match_keyword(kw, snubbed)
+                ]
+                matched_keywords = [kw for kw in keywords if match_keyword(kw, snubbed)]
+                if matched_keywords or simple_matched_keywords:
+                    if matched_keywords:
+                        keyword = matched_keywords[0]
+                        line_splitter = split_line
+                    else:
+                        keyword = simple_matched_keywords[0]
+                        line_splitter = split_line_no_string
+                    logger.debug("Keyword %s found on line %d", keyword, line_no)
+                elif (
+                    list(split_line(line))  # Not an empty line
+                    and ignore is not IGNORE_ALL  # Not ignoring all
+                    and not any(
+                        match_keyword(snubbed, i) for i in ignore
+                    )  # Not ignoring this
+                ):
+                    if strict:
+                        raise ValueError(
+                            f"Unrecognized keyword {repr(line)} on line {line_no}"
+                        )
+                    else:
+                        warnings.warn(
+                            f"Unrecognized keyword {repr(line)} on line {line_no}"
+                        )
+
+            else:
+                for word in line_splitter(line):
+                    if word == "/":
+                        yield (keyword, words)
+                        keyword = None
+                        words = []
+                        break
+                    words += interpret_token(word)
+            line = grdecl_stream.readline()
+            line_no += 1
+
+        if keyword is not None:
+            raise ValueError(f"Reached end of stream while reading {keyword}")
+
+    with open(grdecl_file, "r") as stream:
+        yield read_grdecl(stream)

xtgeo/grid3d/_grdecl_grid.py

@@ -0,0 +1,400 @@
+"""
+Datastructure for the contents of grdecl files.
+
+The grdecl file format is not specified in a strict manner
+but in the most general sense it is a file that can be included
+into the GRID section of a eclipse input file.
+
+However, it is nearly impossible to support such a file format completely,
+instead we narrow it down to the following subset of keywords:
+
+    * COORD
+    * ZCORN
+    * ACTNUM
+    * MAPAXES
+    * GRIDUNIT
+    * SPECGRID
+    * GDORIENT
+
+And ignore ECHO and NOECHO keywords. see _grid_format for the details
+of how these keywords are layed out in a text file, and see GrdeclGrid
+for how the grid geometry is interpreted from these keywords.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+import numpy as np
+import resfo
+
+from xtgeo.common.types import Dimensions
+from xtgeo.io._file import FileFormat
+
+from ._ecl_grid import (
+    CoordinateType,
+    EclGrid,
+    GdOrient,
+    GrdeclKeyword,
+    GridRelative,
+    GridUnit,
+    MapAxes,
+    Units,
+)
+from ._grdecl_format import IGNORE_ALL, open_grdecl, run_length_encoding
+
+
+@dataclass
+class SpecGrid(GrdeclKeyword):
+    """The SPECGRID keyword gives the size of the grid.
+
+    The 3 first values is the number of cells in each dimension
+    of the grid. The next is the number of reservoirs in the file and
+    the last is the type of coordinates, see CoordinateType.
+
+    example:
+        "SPECGRID 10 10 10 1 T /" meaning 10x10x10 grid with 1 reservoir
+        and cylindrical coordinates.
+
+    """
+
+    ndivix: int = 1
+    ndiviy: int = 1
+    ndiviz: int = 1
+    numres: int = 1
+    coordinate_type: CoordinateType = CoordinateType.CARTESIAN
+
+    def to_grdecl(self):
+        return [
+            self.ndivix,
+            self.ndiviy,
+            self.ndiviz,
+            self.numres,
+            self.coordinate_type.to_grdecl(),
+        ]
+
+    def to_bgrdecl(self):
+        return np.array(
+            [
+                self.ndivix,
+                self.ndiviy,
+                self.ndiviz,
+                self.numres,
+                self.coordinate_type.to_bgrdecl(),
+            ],
+            dtype=np.int32,
+        )
+
+    @classmethod
+    def from_bgrdecl(cls, values):
+        ivalues = [int(v) for v in values[:4]]
+        if len(values) < 5:
+            return cls(*ivalues)
+        if len(values) == 5:
+            return cls(*ivalues, CoordinateType.from_bgrdecl(values[-1]))
+        raise ValueError("SPECGRID should have at most 5 values")
+
+    @classmethod
+    def from_grdecl(cls, values):
+        ivalues = [int(v) for v in values[:4]]
+        if len(values) < 5:
+            return cls(*ivalues)
+        if len(values) == 5:
+            return cls(*ivalues, CoordinateType.from_grdecl(values[-1]))
+        raise ValueError("SPECGRID should have at most 5 values")
+
+
+class GrdeclGrid(EclGrid):
+    """
+    The main keywords that describe a grdecl grid is COORD, ZCORN and ACTNUM
+    and are described in xtgeo.grid3d._ecl_grid.
+    The remaining fields (SPECGRID, MAPAXES, MAPUNITS, GRIDUNIT, GDORIENT)
+    describe units, orientation and dimensions, see corresponding dataclasses.
+    The number of cells in each direction is described in the SPECGRID keyword.
+    """
+
+    def __init__(
+        self,
+        coord: np.ndarray,
+        zcorn: np.ndarray,
+        specgrid: SpecGrid,
+        actnum: np.ndarray | None = None,
+        mapaxes: MapAxes | None = None,
+        mapunits: Units | None = None,
+        gridunit: GridUnit | None = None,
+        gdorient: GdOrient | None = None,
+    ):
+        self._coord = coord
+        self._zcorn = zcorn
+        self.specgrid = specgrid
+        self._actnum = actnum
+        self._mapaxes = mapaxes
+        self.mapunits = mapunits
+        self.gridunit = gridunit
+        self.gdorient = gdorient
+
+    def __str__(self):
+        return (
+            "GrdeclGrid("
+            f"coord={self._coord}, "
+            f"zcorn={self._zcorn}, "
+            f"specgrid={self.specgrid}, "
+            f"actnum={self._actnum}, "
+            f"mapaxes={self._mapaxes}, "
+            f"mapunits={self.mapunits}, "
+            f"gridunit={self.gridunit}, "
+            f"gdorient={self.gdorient})"
+        )
+
+    def __repr__(self):
+        return str(self)
+
+    @property
+    def mapaxes(self) -> MapAxes | None:
+        return self._mapaxes
+
+    @mapaxes.setter
+    def mapaxes(self, value):
+        self._mapaxes = value
+
+    @property
+    def coord(self) -> np.ndarray:
+        return self._coord
+
+    @coord.setter
+    def coord(self, value):
+        self._coord = value
+
+    @property
+    def zcorn(self) -> np.ndarray:
+        return self._zcorn
+
+    @zcorn.setter
+    def zcorn(self, value):
+        self._zcorn = value
+
+    @property
+    def actnum(self) -> np.ndarray | None:
+        return self._actnum
+
+    @classmethod
+    def default_settings_grid(
+        cls,
+        coord: np.ndarray,
+        zcorn: np.ndarray,
+        actnum: np.ndarray | None,
+        size: tuple[int, int, int],
+    ):
+        return cls(coord, zcorn, SpecGrid(*size), actnum)
+
+    def __eq__(self, other):
+        if not isinstance(other, GrdeclGrid):
+            return False
+        return (
+            self.specgrid == other.specgrid
+            and self.mapaxes == other.mapaxes
+            and self.mapunits == other.mapunits
+            and self.gridunit == other.gridunit
+            and self.gdorient == other.gdorient
+            and np.array_equal(self.actnum, other.actnum)
+            and np.array_equal(self.coord, other.coord)
+            and np.array_equal(self.zcorn, other.zcorn)
+        )
+
+    @property
+    def dimensions(self) -> Dimensions:
+        """Dimensions NamedTuple: The grid dimensions (read only)."""
+        return Dimensions(
+            self.specgrid.ndivix, self.specgrid.ndiviy, self.specgrid.ndiviz
+        )
+
+    @property
+    def is_map_relative(self) -> bool:
+        return (
+            self.gridunit is not None
+            and self.gridunit.grid_relative == GridRelative.MAP
+        )
+
+    @property
+    def map_axis_units(self):
+        if self.mapunits is None:
+            return Units.METRES
+        return self.mapunits
+
+    @map_axis_units.setter
+    def map_axis_units(self, value):
+        self.mapunits = value
+
+    @property
+    def grid_units(self):
+        if self.gridunit is None:
+            return Units.METRES
+        return self.gridunit.unit
+
+    @grid_units.setter
+    def grid_units(self, value):
+        if self.gridunit is None and value != Units.METRES:
+            self.gridunit = GridUnit(unit=value)
+        elif self.gridunit is not None:
+            self.gridunit.unit = value
+
+    @classmethod
+    def from_file(cls, filename, fileformat: FileFormat = FileFormat.GRDECL):
+        """
+        write the grdeclgrid to a file.
+        :param filename: path to file to write.
+        :param fileformat: Either "grdecl" or "bgrdecl" to
+            indicate binary or ascii format.
+        """
+        if fileformat == FileFormat.GRDECL:
+            return cls._from_grdecl_file(filename)
+        if fileformat == FileFormat.BGRDECL:
+            return cls._from_bgrdecl_file(filename)
+        raise ValueError(b"Unknown grdecl file format {fileformat}")
+
+    @classmethod
+    def _from_bgrdecl_file(cls, filename, fileformat=None):
+        keyword_factories = {
+            "COORD": lambda x: np.array(x, dtype=np.float32),
+            "ZCORN": lambda x: np.array(x, dtype=np.float32),
+            "ACTNUM": lambda x: np.array(x, dtype=np.int32),
+            "MAPAXES": MapAxes.from_bgrdecl,
+            "MAPUNITS": lambda x: Units.from_bgrdecl(x[0]),
+            "GRIDUNIT": GridUnit.from_bgrdecl,
+            "SPECGRID": SpecGrid.from_bgrdecl,
+            "GDORIENT": GdOrient.from_bgrdecl,
+        }
+        results = {}
+        for entry in resfo.lazy_read(filename, fileformat=fileformat):
+            if len(results) == len(keyword_factories):
+                break
+            kw = entry.read_keyword().rstrip()
+            if kw in results:
+                raise ValueError(f"Duplicate keyword {kw} in {filename}")
+            try:
+                factory = keyword_factories[kw]
+            except KeyError as e:
+                raise ValueError(f"Unknown grdecl keyword {kw}") from e
+            results[kw.lower()] = factory(entry.read_array())
+        return cls(**results)
+
+    @classmethod
+    def _from_grdecl_file(cls, filename):
+        keyword_factories = {
+            "COORD": lambda x: np.array(x, dtype=np.float32),
+            "ZCORN": lambda x: np.array(x, dtype=np.float32),
+            "ACTNUM": lambda x: np.array(x, dtype=np.int32),
+            "MAPAXES": MapAxes.from_grdecl,
+            "MAPUNITS": lambda x: Units.from_grdecl(x[0]),
+            "GRIDUNIT": GridUnit.from_grdecl,
+            "SPECGRID": SpecGrid.from_grdecl,
+            "GDORIENT": GdOrient.from_grdecl,
+        }
+        results = {}
+        with open_grdecl(
+            filename,
+            keywords=["MAPAXES", "MAPUNITS", "GRIDUNIT", "SPECGRID", "GDORIENT"],
+            simple_keywords=["COORD", "ZCORN", "ACTNUM"],
+            max_len=None,
+            ignore=IGNORE_ALL,
+            strict=False,
+        ) as keyword_generator:
+            for kw, values in keyword_generator:
+                if len(results) == len(keyword_factories):
+                    break
+                if kw in results:
+                    raise ValueError(f"Duplicate keyword {kw} in {filename}")
+                try:
+                    factory = keyword_factories[kw]
+                except KeyError as e:
+                    raise ValueError(f"Unknown grdecl keyword {kw}") from e
+                results[kw.lower()] = factory(values)
+        return cls(**results)
+
+    def to_file(self, filename, fileformat="grdecl", rle: bool = False):
+        """
+        write the grdeclgrid to a file.
+        :param filename: path to file to write.
+        :param fileformat: Either "grdecl" or "bgrdecl" to
+            indicate binary or ascii format.
+        :param rle: Boolean flag indicating whether to use Run-Length Encoding (RLE)
+                    compression when writing the file (only for grdecl).
+        """
+        if fileformat == "grdecl":
+            return self._to_grdecl_file(filename, rle)
+        if fileformat == "bgrdecl":
+            return self._to_bgrdecl_file(filename)
+        raise ValueError(b"Unknown grdecl file format {fileformat}")
+
+    def _to_grdecl_file(self, filename, rle):
+        with open(filename, "w") as filestream:
+            keywords = [
+                ("SPECGRID", self.specgrid.to_grdecl()),
+                ("MAPAXES", self.mapaxes.to_grdecl() if self.mapaxes else None),
+                ("MAPUNITS", [self.mapunits.to_grdecl()] if self.mapunits else None),
+                ("GRIDUNIT", self.gridunit.to_grdecl() if self.gridunit else None),
+                ("GDORIENT", self.gdorient.to_grdecl() if self.gdorient else None),
+                ("COORD", self.coord),
+                ("ZCORN", self.zcorn),
+                ("ACTNUM", self.actnum),
+            ]
+            for kw, values in keywords:
+                if values is None:
+                    continue
+                filestream.write(f"{kw}\n")
+                if rle and (kw == "ACTNUM"):
+                    counts, unique_values = run_length_encoding(values)
+                    for i, (count, unique_value) in enumerate(
+                        zip(counts, unique_values)
+                    ):
+                        filestream.write(
+                            f" {count}*{unique_value}"
+                            if count > 1
+                            else f" {unique_value}"
+                        )
+                        if i % 6 == 5:
+                            filestream.write("\n")
+                else:
+                    for i, value in enumerate(values):
+                        filestream.write(f" {value}")
+
+                        if i % 6 == 5:  # 6 should ensure < 128 character width total
+                            filestream.write("\n")
+
+                filestream.write("\n /\n")
+
+    def _to_bgrdecl_file(self, filename, fileformat=resfo.Format.UNFORMATTED):
+        contents = filter(
+            lambda x: x[1] is not None,
+            [
+                ("SPECGRID", self.specgrid.to_bgrdecl()),
+                ("MAPAXES ", self.mapaxes.to_bgrdecl() if self.mapaxes else None),
+                ("MAPUNITS", [self.mapunits.to_bgrdecl()] if self.mapunits else None),
+                ("GRIDUNIT", self.gridunit.to_bgrdecl() if self.gridunit else None),
+                ("GDORIENT", self.gdorient.to_bgrdecl() if self.gdorient else None),
+                ("COORD   ", self.coord.astype(np.float32)),
+                ("ZCORN   ", self.zcorn.astype(np.float32)),
+                (
+                    "ACTNUM  ",
+                    self.actnum.astype(np.int32) if self.actnum is not None else None,
+                ),
+            ],
+        )
+        resfo.write(
+            filename,
+            contents,
+        )
+
+    def _check_xtgeo_compatible(self):
+        if self.specgrid.coordinate_type == CoordinateType.CYLINDRICAL:
+            raise NotImplementedError(
+                "Xtgeo does not currently support cylindrical coordinate systems"
+            )
+        if self.specgrid.numres != 1:
+            raise NotImplementedError(
+                "Xtgeo does not currently support multiple reservoirs"
+            )
+        if self.gridunit and self.gridunit.grid_relative == GridRelative.MAP:
+            raise NotImplementedError(
+                "Xtgeo does not currently support conversion of map relative grid units"
+            )