completor 0.1.2__py3-none-any.whl

completor/create_wells.py

@@ -0,0 +1,314 @@
+"""Module for creating completion structure."""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from completor import completion
+from completor.constants import Headers, Method
+from completor.logger import logger
+from completor.read_casefile import ReadCasefile
+from completor.read_schedule import fix_compsegs_by_priority
+
+try:
+    import numpy.typing as npt
+except ImportError:
+    pass
+
+
+class CreateWells:
+    """Class for creating well completion structure.
+
+    Args:
+        case: ReadCasefile class.
+
+    Attributes:
+        active_wells: Active wells defined in the case file.
+        method: Method for segment creation.
+        well_name: Well name (in loop).
+        laterals: List of lateral number of the well in loop.
+        df_completion: Completion data frame in loop.
+        df_reservoir: COMPDAT and COMPSEGS data frame fusion in loop.
+        df_welsegs_header: WELSEGS first record.
+        df_welsegs_content: WELSEGS second record.
+        df_mdtvd: Data frame of MD and TVD relationship.
+        df_tubing_segments: Tubing segment data frame.
+        df_well: Data frame after completion.
+        df_well_all: Data frame (df_well) for all laterals after completion.
+        df_reservoir_all: df_reservoir for all laterals.
+    """
+
+    def __init__(self, case: ReadCasefile):
+        """Initialize CreateWells."""
+        self.well_name: str | None = None
+        self.df_reservoir = pd.DataFrame()
+        self.df_mdtvd = pd.DataFrame()
+        self.df_completion = pd.DataFrame()
+        self.df_tubing_segments = pd.DataFrame()
+        self.df_well = pd.DataFrame()
+        self.df_compdat = pd.DataFrame()
+        self.df_well_all = pd.DataFrame()
+        self.df_reservoir_all = pd.DataFrame()
+        self.df_welsegs_header = pd.DataFrame()
+        self.df_welsegs_content = pd.DataFrame()
+        self.laterals: list[int] = []
+
+        self.case: ReadCasefile = case
+        self.active_wells = self._active_wells()
+        self.method = self._method()
+
+    def update(self, well_name: str, schedule: completion.WellSchedule) -> None:
+        """Update class variables in CreateWells.
+
+        Args:
+            well_name: Well name.
+            schedule: ReadSchedule object.
+        """
+        self.well_name = well_name
+        self._active_laterals()
+        for lateral in self.laterals:
+            self.select_well(schedule, lateral)
+            self.well_trajectory()
+            self.define_annulus_zone()
+            self.create_tubing_segments()
+            self.insert_missing_segments()
+            self.complete_the_well()
+            self.get_devices()
+            self.correct_annulus_zone()
+            self.connect_cells_to_segments()
+            self.add_well_lateral_column(lateral)
+            self.combine_df(lateral)
+
+    def _active_wells(self) -> npt.NDArray[np.unicode_]:
+        """Get a list of active wells specified by users.
+
+        If the well has annulus content with gravel pack and the well is perforated,
+        Completor will not add a device layer.
+        Completor does nothing to gravel-packed perforated wells by default.
+        This behavior can be changed by setting the GP_PERF_DEVICELAYER keyword in the case file to true.
+
+        Returns:
+            Active wells.
+        """
+        # Need to check completion of all wells in completion table to remove GP-PERF type wells
+        active_wells = list(set(self.case.completion_table[Headers.WELL]))
+        # We cannot update a list while iterating of it
+        for well_name in active_wells.copy():
+            # Annulus content of each well
+            ann_series = self.case.completion_table[self.case.completion_table[Headers.WELL] == well_name][
+                Headers.ANNULUS
+            ]
+            type_series = self.case.completion_table[self.case.completion_table[Headers.WELL] == well_name][
+                Headers.DEVICE_TYPE
+            ]
+            gp_check = not ann_series.isin(["OA"]).any()
+            perf_check = not type_series.isin(["AICD", "AICV", "DAR", "ICD", "VALVE", "ICV"]).any()
+            if gp_check and perf_check and not self.case.gp_perf_devicelayer:
+                # De-activate wells with GP_PERF if instructed to do so:
+                active_wells.remove(well_name)
+            if not active_wells:
+                logger.warning(
+                    "There are no active wells for Completor to work on. E.g. all wells are defined with Gravel Pack "
+                    "(GP) and valve type PERF. If you want these wells to be active set GP_PERF_DEVICELAYER to TRUE."
+                )
+                return np.array([])
+        return np.array(active_wells)
+
+    def _method(self) -> Method:
+        """Define how the user wants to create segments.
+
+        Returns:
+            Creation method enum.
+
+        Raises:
+            ValueError: If method is not one of the defined methods.
+        """
+        if isinstance(self.case.segment_length, float):
+            if float(self.case.segment_length) > 0.0:
+                return Method.FIX
+            if float(self.case.segment_length) == 0.0:
+                return Method.CELLS
+            if self.case.segment_length < 0.0:
+                return Method.USER
+            else:
+                raise ValueError(
+                    f"Unrecognized method '{self.case.segment_length}' in SEGMENTLENGTH keyword. "
+                    "The value should be one of: 'WELSEGS', 'CELLS', 'USER', or a number: -1 for 'USER', "
+                    "0 for 'CELLS', or a positive number for 'FIX'."
+                )
+
+        elif isinstance(self.case.segment_length, str):
+            if "welsegs" in self.case.segment_length.lower() or "infill" in self.case.segment_length.lower():
+                return Method.WELSEGS
+            if "cell" in self.case.segment_length.lower():
+                return Method.CELLS
+            if "user" in self.case.segment_length.lower():
+                return Method.USER
+            else:
+                raise ValueError(
+                    f"Unrecognized method '{self.case.segment_length}' in SEGMENTLENGTH keyword. "
+                    "The value should be one of: "
+                    "'WELSEGS', 'CELLS', 'USER', or a number: -1 for 'USER', 0 for 'CELLS', positive number for 'FIX'."
+                )
+        else:
+            raise ValueError(
+                f"Unrecognized type of '{self.case.segment_length}' in SEGMENTLENGTH keyword. "
+                "The keyword must either be float or string."
+            )
+
+    def _active_laterals(self) -> None:
+        """Get a list of lateral numbers for the well.
+
+        ``get_active_laterals`` uses the case class DataFrame property
+        ``completion_table`` with a format as shown in the function
+        ``read_casefile.ReadCasefile.read_completion``.
+        """
+        self.laterals = list(
+            self.case.completion_table[self.case.completion_table[Headers.WELL] == self.well_name][
+                Headers.BRANCH
+            ].unique()
+        )
+
+    def select_well(self, schedule: completion.WellSchedule, lateral: int) -> None:
+        """Filter all the required DataFrames for this well and its laterals."""
+        if self.well_name is None:
+            raise ValueError("No well name given")
+
+        self.df_completion = self.case.get_completion(self.well_name, lateral)
+        self.df_welsegs_header, self.df_welsegs_content = schedule.get_well_segments(self.well_name, lateral)
+        df_compsegs = schedule.get_compsegs(self.well_name, lateral)
+        df_compdat = schedule.get_compdat(self.well_name)
+        self.df_reservoir = pd.merge(df_compsegs, df_compdat, how="inner", on=[Headers.I, Headers.J, Headers.K])
+
+        # Remove WELL column in the df_reservoir.
+        self.df_reservoir.drop([Headers.WELL], inplace=True, axis=1)
+        # If multiple occurrences of same IJK in compdat/compsegs --> keep the last one.
+        self.df_reservoir.drop_duplicates(subset=Headers.START_MEASURED_DEPTH, keep="last", inplace=True)
+        self.df_reservoir.reset_index(inplace=True)
+
+    def well_trajectory(self) -> None:
+        """Create trajectory DataFrame relations between measured depth and true vertical depth."""
+        self.df_mdtvd = completion.well_trajectory(self.df_welsegs_header, self.df_welsegs_content)
+
+    def define_annulus_zone(self) -> None:
+        """Define an annulus zone if specified."""
+        self.df_completion = completion.define_annulus_zone(self.df_completion)
+
+    def create_tubing_segments(self) -> None:
+        """Create tubing segments as the basis.
+
+        The function creates a class property DataFrame df_tubing_segments
+        from the class property DataFrames df_reservoir, df_completion, and df_mdtvd.
+
+        The behavior of the df_tubing_segments will vary depending on the existence of the ICV keyword.
+        When the ICV keyword is present, it always creates a lumped tubing segment on its interval,
+        whereas other types of devices follow the default input.
+        If there is a combination of an ICV and other devices (with devicetype >1),
+        this results in a combination of ICV segment length with segment lumping,
+        and default segment length on other devices.
+        """
+        df_tubing_cells = completion.create_tubing_segments(
+            self.df_reservoir,
+            self.df_completion,
+            self.df_mdtvd,
+            self.method,
+            self.case.segment_length,
+            self.case.minimum_segment_length,
+        )
+
+        df_tubing_user = completion.create_tubing_segments(
+            self.df_reservoir,
+            self.df_completion,
+            self.df_mdtvd,
+            Method.USER,
+            self.case.segment_length,
+            self.case.minimum_segment_length,
+        )
+
+        if (len(self.df_completion[Headers.DEVICE_TYPE].unique()) > 1) & (
+            (self.df_completion[Headers.DEVICE_TYPE] == "ICV") & (self.df_completion[Headers.VALVES_PER_JOINT] > 0)
+        ).any():
+            self.df_tubing_segments = fix_compsegs_by_priority(self.df_completion, df_tubing_cells, df_tubing_user)
+
+        # If all the devices are ICVs, lump the segments.
+        elif (self.df_completion[Headers.DEVICE_TYPE] == "ICV").all():
+            self.df_tubing_segments = df_tubing_user
+        # If none of the devices are ICVs use defined method.
+        else:
+            self.df_tubing_segments = df_tubing_cells
+
+    def insert_missing_segments(self) -> None:
+        """Create a placeholder segment for inactive cells."""
+        self.df_tubing_segments = completion.insert_missing_segments(self.df_tubing_segments, self.well_name)
+
+    def complete_the_well(self) -> None:
+        """Complete the well with users' completion design."""
+        self.df_well = completion.complete_the_well(self.df_tubing_segments, self.df_completion, self.case.joint_length)
+        self.df_well[Headers.ROUGHNESS] = self.df_well[Headers.ROUGHNESS].apply(lambda x: f"{x:.3E}")
+
+    def get_devices(self) -> None:
+        """Complete the well with the device information.
+
+        Updates the class property DataFrame df_well described in ``complete_the_well``.
+        """
+        if not self.case.completion_icv_tubing.empty:
+            active_devices = pd.concat(
+                [self.df_completion[Headers.DEVICE_TYPE], self.case.completion_icv_tubing[Headers.DEVICE_TYPE]]
+            ).unique()
+        else:
+            active_devices = self.df_completion[Headers.DEVICE_TYPE].unique()
+        if "VALVE" in active_devices:
+            self.df_well = completion.get_device(self.df_well, self.case.wsegvalv_table, "VALVE")
+        if "ICD" in active_devices:
+            self.df_well = completion.get_device(self.df_well, self.case.wsegsicd_table, "ICD")
+        if "AICD" in active_devices:
+            self.df_well = completion.get_device(self.df_well, self.case.wsegaicd_table, "AICD")
+        if "DAR" in active_devices:
+            self.df_well = completion.get_device(self.df_well, self.case.wsegdar_table, "DAR")
+        if "AICV" in active_devices:
+            self.df_well = completion.get_device(self.df_well, self.case.wsegaicv_table, "AICV")
+        if "ICV" in active_devices:
+            self.df_well = completion.get_device(self.df_well, self.case.wsegicv_table, "ICV")
+
+    def correct_annulus_zone(self) -> None:
+        """Remove the annulus zone if there is no connection to the tubing."""
+        self.df_well = completion.correct_annulus_zone(self.df_well)
+
+    def connect_cells_to_segments(self) -> None:
+        """Connect cells to the well.
+
+        We only need the following columns from the well DataFrame: MD, NDEVICES, DEVICETYPE, and ANNULUS_ZONE.
+
+        ICV placement forces different methods in segment creation as USER defined.
+        """
+        # drop BRANCH column, not needed
+        self.df_reservoir.drop([Headers.BRANCH], axis=1, inplace=True)
+        icv_device = (
+            self.df_well[Headers.DEVICE_TYPE].nunique() > 1
+            and (self.df_well[Headers.DEVICE_TYPE] == "ICV").any()
+            and not self.df_well[Headers.NUMBER_OF_DEVICES].empty
+        )
+        method = Method.USER if icv_device else self.method
+        self.df_reservoir = completion.connect_cells_to_segments(
+            self.df_well[[Headers.TUB_MD, Headers.NUMBER_OF_DEVICES, Headers.DEVICE_TYPE, Headers.ANNULUS_ZONE]],
+            self.df_reservoir,
+            self.df_tubing_segments,
+            method,
+        )
+
+    def add_well_lateral_column(self, lateral: int) -> None:
+        """Add well and lateral column in df_well and df_compsegs."""
+        self.df_well[Headers.WELL] = self.well_name
+        self.df_reservoir[Headers.WELL] = self.well_name
+        self.df_well[Headers.LATERAL] = lateral
+        self.df_reservoir[Headers.LATERAL] = lateral
+
+    def combine_df(self, lateral: int) -> None:
+        """Combine all DataFrames for this well."""
+        if lateral == self.laterals[0]:
+            self.df_well_all = self.df_well.copy(deep=True)
+            self.df_reservoir_all = self.df_reservoir.copy(deep=True)
+        else:
+            self.df_well_all = pd.concat([self.df_well_all, self.df_well], sort=False)
+            self.df_reservoir_all = pd.concat([self.df_reservoir_all, self.df_reservoir], sort=False)

completor/exceptions/__init__.py

@@ -0,0 +1,4 @@
+from completor.exceptions.clean_exceptions import CompletorError
+from completor.exceptions.exceptions import CaseReaderFormatError
+
+__all__ = ["CompletorError", "CaseReaderFormatError"]

completor/exceptions/clean_exceptions.py

@@ -0,0 +1,10 @@
+"""Separate file for exceptions that don't need parser, this is needed to avoid circular imports from parser.py"""
+
+
+class CompletorError(Exception):
+    """Custom error for completor, if anything goes critically wrong in completor this error will be raised.
+
+    This error is caught in main initiating the abort function and will terminate the program.
+    """
+
+    pass

completor/exceptions/exceptions.py

@@ -0,0 +1,134 @@
+from __future__ import annotations
+
+from completor import parse
+
+
+class _BaseCaseException(Exception):
+    """Base for custom case exceptions."""
+
+    def __init__(
+        self, message: str, lines: list[str] | None = None, error_line: int | None = None, window_size: int = 5
+    ):
+        """Initialize the error message."""
+        if lines is None or error_line is None:
+            super().__init__(message)
+        else:
+            message = self._format_error_message(message, lines, error_line, window_size)
+            super().__init__(message)
+
+    def _format_error_message(self, message: str, original_lines: list[str], error_line: int, windows_size: int) -> str:
+        """Format error message to show lines where the error occurred.
+
+        The error is displayed with line numbers and ">" to indicate
+        the line the error happened at. Then add the error message.
+
+        Format example:
+            Error at line 7:
+            Could not parse "KEYWORD".
+                5: KEYWORD
+                6: -- Some comment
+              > 7: data data something wrong /
+                8: data data /
+                9: /
+
+        Args:
+            message: Error message appended to the formatted error.
+            original_lines: Lines in the original file the error happened at.
+            error_line: What line the error occurred at.
+            windows_size: How many lines from the file around the error should be
+                displayed. (3=error_line-3:error_line+3).
+
+        Returns:
+            Error message formatted with lines from file where error occurred,
+            arrow pointing at error line and error message.
+        """
+        # From 0 indexed to 1 indexed (like the actual file)
+        start = self._clamp((error_line - windows_size), 0, len(original_lines))
+        end = self._clamp((error_line + windows_size), 0, len(original_lines))
+
+        lines = original_lines[start:end].copy()
+        new_lines = []
+        error_line += 1
+        for i, line in enumerate(lines):
+            shifted_index = i + start + 1
+            if shifted_index == error_line:
+                new_lines.append(f"> {str(shifted_index).rjust(len(str(end)))}: {line}")
+            else:
+                new_lines.append(f"  {str(shifted_index).rjust(len(str(end)))}: {line}")
+
+        string = "\n".join(new_lines)
+        return f"\n{string}\n\nError at line {error_line} in case file:\n{message}"
+
+    @staticmethod
+    def _clamp(n, minn, maxn):
+        """Method for preventing index out of bounds."""
+        return max(min(maxn, n), minn)
+
+
+class CaseReaderFormatError(_BaseCaseException):
+    """Used for keywords with faulty data/format."""
+
+    error_index: int | None = None
+
+    def __init__(
+        self,
+        message: str | None = None,
+        lines: list[str] | None = None,
+        header: list[str] | None = None,
+        keyword: str | None = None,
+        error_index: int | None = None,
+        window_size: int = 5,
+    ):
+        if message is None:
+            message = "Something went wrong while reading the casefile! "
+
+        if lines is None or header is None:
+            super().__init__(message)
+            return
+
+        extra_info = "few/many"
+        if error_index is None:
+            if keyword is None:
+                super().__init__(message)
+                return
+            try:
+                error_index, is_larger = CaseReaderFormatError.find_error_line(keyword, lines, header)
+                extra_info = "many" if is_larger else "few"
+            except Exception:  # pylint: disable=broad-exception-caught
+                super().__init__(message)
+
+        message += (
+            f"Too {extra_info} entries in data for keyword '{keyword}', "
+            f"expected {len(header)} entries: {header}!\n"
+            "Please check the documentation for this keyword or "
+            "contact the team directly if you believe this to be a mistake."
+        )
+        super().__init__(message, lines, error_index, window_size)
+
+    @staticmethod
+    def find_error_line(keyword: str, lines: list[str], header: list[str]):
+        """Find line where error occurs.
+
+        Args:
+            keyword: Current keyword in case-file.
+            lines: The (preferably) original case-file lines.
+            header: The expected headers for this keyword.
+
+        Raises:
+            ValueError: If the line could not be found.
+
+        Returns:
+            Line number and whether there are too many/few data entries vs header.
+        """
+        stripped_content = [x.strip() for x in lines]
+        start, end = parse.locate_keyword(stripped_content, keyword)
+
+        line_content = {
+            i + start + 1: line for i, line in enumerate(lines[start + 1 : end]) if line and not line.startswith("--")
+        }
+
+        for line, content in line_content.items():
+            if len(content.strip().split()) != len(header):
+                return line, len(header) < len(content.strip().split())
+
+        raise ValueError("Could not find the erroneous line.")

completor/hook_implementations/jobs.py

@@ -0,0 +1,63 @@
+from pathlib import Path
+
+from pkg_resources import resource_filename
+
+from completor.logger import logger
+
+SKIP_TESTS = False
+try:
+    from ert.shared.plugins.plugin_manager import hook_implementation  # type: ignore
+    from ert.shared.plugins.plugin_response import plugin_response  # type: ignore
+
+except ModuleNotFoundError:
+    logger.warning("Cannot import ERT, did you install Completor with ert option enabled?")
+    pass
+
+
+@hook_implementation
+@plugin_response(plugin_name="completor")  # type: ignore
+def installable_jobs():
+    config_file = Path(resource_filename("completor", "config_jobs/run_completor"))
+    return {config_file.name: config_file}
+
+
+@hook_implementation
+@plugin_response(plugin_name="completor")  # type: ignore  # pylint: disable=no-value-for-parameter
+def job_documentation(job_name):
+    if job_name != "run_completor":
+        return None
+
+    description = """Completor is a script for modelling
+wells with advanced completion.
+It generates a well schedule to be included in reservoir simulator,
+by combining the multi-segment tubing definition (from pre-processor reservoir modelling tools)
+with a user defined file specifying the completion design.
+The resulting well schedule comprises all keywords and parameters required by
+reservoir simulator. See the Completor documentation for details.
+
+Required:
+---------
+-i   : followed by name of file specifying completion design (e.g. completion.case).
+-s   : followed by name of schedule file with multi-segment tubing definition,
+       including COMPDAT, COMPSEGS and WELSEGS (required if not specified in case file).
+
+Optional:
+---------
+--help   : how to run completor.
+--about  : about completor.
+-o       : followed by name of completor output file.
+--figure  : generates a pdf file with a schematics of the well segment structure.
+
+"""
+
+    examples = """.. code-block:: console
+  FORWARD_MODEL run_completor(
+    <CASE>=path/to/completion.case,
+    <INPUT_SCH>=path/to/input.sch,
+    <OUTPUT_SCH>path/to/output.sch
+)
+"""
+
+    category = "modelling.reservoir"
+
+    return {"description": description, "examples": examples, "category": category}