ert 16.0.9__py3-none-any.whl → 19.0.0rc2__py3-none-any.whl

ert/config/_read_summary.py

@@ -7,20 +7,21 @@ for specification of the file format
 from __future__ import annotations
 
 import fnmatch
-import os
-import os.path
 import re
+import warnings
 from collections.abc import Callable, Sequence
 from datetime import datetime, timedelta
 from enum import Enum, auto
-from typing import Any, TypeVar, assert_never
+from functools import lru_cache
 
 import numpy as np
 import numpy.typing as npt
-import resfo
-from pydantic import PositiveInt
-
-from ert.summary_key_type import SummaryKeyType
+from resfo_utilities import (
+    InvalidSummaryError,
+    InvalidSummaryKeyError,
+    SummaryReader,
+    make_summary_key,
+)
 
 from .response_config import InvalidResponseFile
 
@@ -48,119 +49,27 @@ def read_summary(
     data/CASE.SMSPEC.
 
     """
-    summary, spec = _get_summary_filenames(summary_basename)
+    if summary_basename.lower().endswith(".data"):
+        # For backwards compatability, it is
+        # allowed to give REFCASE and ECLBASE both
+        # with and without .DATA extensions
+        summary_basename = summary_basename[:-5]
+    summary = SummaryReader(case_path=summary_basename)
     try:
         date_index, start_date, date_units, keys, indices = _read_spec(
-            spec, select_keys
+            summary, select_keys
         )
         fetched, time_map = _read_summary(
             summary, start_date, date_units, indices, date_index
         )
-    except resfo.ResfoParsingError as err:
+    except InvalidSummaryError as err:
         raise InvalidResponseFile(
             f"Failed to read summary files {summary_basename}: {err}"
         ) from err
     return (start_date, keys, time_map, fetched)
 
 
-def make_summary_key(
-    keyword: str,
-    number: int | None = None,
-    name: str | None = None,
-    nx: int | None = None,
-    ny: int | None = None,
-    lgr_name: str | None = None,
-    li: int | None = None,
-    lj: int | None = None,
-    lk: int | None = None,
-) -> str:
-    """Converts values found in the smspec file to the summary_key format.
-
-    Ert and some other applications use a colon separated format to specify
-    summary parameters. For instance:
-
-    >>> make_summary_key(keyword="WOPR", name="WELL1")
-    'WOPR:WELL1'
-    >>> make_summary_key(keyword="BOPR", number=4, nx=2, ny=2)
-    'BOPR:2,2,1'
-    """
-    try:
-        sum_type = SummaryKeyType.from_variable(keyword)
-    except Exception as err:
-        raise InvalidResponseFile(
-            f"Could not read summary keyword '{keyword}': {err}"
-        ) from err
-
-    match sum_type:
-        case SummaryKeyType.FIELD | SummaryKeyType.OTHER:
-            return keyword
-        case SummaryKeyType.REGION | SummaryKeyType.AQUIFER:
-            return f"{keyword}:{number}"
-        case SummaryKeyType.BLOCK:
-            nx, ny = _check_if_missing("block", "dimens", nx, ny)
-            (number,) = _check_if_missing("block", "nums", number)
-            i, j, k = _cell_index(number - 1, nx, ny)
-            return f"{keyword}:{i},{j},{k}"
-        case SummaryKeyType.GROUP | SummaryKeyType.WELL:
-            return f"{keyword}:{name}"
-        case SummaryKeyType.SEGMENT:
-            return f"{keyword}:{name}:{number}"
-        case SummaryKeyType.COMPLETION:
-            nx, ny = _check_if_missing("completion", "dimens", nx, ny)
-            (number,) = _check_if_missing("completion", "nums", number)
-            i, j, k = _cell_index(number - 1, nx, ny)
-            return f"{keyword}:{name}:{i},{j},{k}"
-        case SummaryKeyType.INTER_REGION:
-            (number,) = _check_if_missing("inter region", "nums", number)
-            r1 = number % 32768
-            r2 = ((number - r1) // 32768) - 10
-            return f"{keyword}:{r1}-{r2}"
-        case SummaryKeyType.LOCAL_WELL:
-            (name,) = _check_if_missing("local well", "WGNAMES", name)
-            (lgr_name,) = _check_if_missing("local well", "LGRS", lgr_name)
-            return f"{keyword}:{lgr_name}:{name}"
-        case SummaryKeyType.LOCAL_BLOCK:
-            li, lj, lk = _check_if_missing("local block", "NUMLX", li, lj, lk)
-            (lgr_name,) = _check_if_missing("local block", "LGRS", lgr_name)
-            return f"{keyword}:{lgr_name}:{li},{lj},{lk}"
-        case SummaryKeyType.LOCAL_COMPLETION:
-            li, lj, lk = _check_if_missing("local completion", "NUMLX", li, lj, lk)
-            (name,) = _check_if_missing("local completion", "WGNAMES", name)
-            (lgr_name,) = _check_if_missing("local completion", "LGRS", lgr_name)
-            return f"{keyword}:{lgr_name}:{name}:{li},{lj},{lk}"
-        case SummaryKeyType.NETWORK:
-            (name,) = _check_if_missing("network", "WGNAMES", name)
-            return f"{keyword}:{name}"
-        case default:
-            assert_never(default)
-
-
-__all__ = ["make_summary_key", "read_summary"]
-
-
-def _cell_index(
-    array_index: int, nx: PositiveInt, ny: PositiveInt
-) -> tuple[int, int, int]:
-    k = array_index // (nx * ny)
-    array_index -= k * (nx * ny)
-    j = array_index // nx
-    array_index -= j * nx
-
-    return array_index + 1, j + 1, k + 1
-
-
-T = TypeVar("T")
-
-
-def _check_if_missing(
-    keyword_name: str, missing_key: str, *test_vars: T | None
-) -> list[T]:
-    if any(v is None for v in test_vars):
-        raise InvalidResponseFile(
-            f"Found {keyword_name} keyword in summary "
-            f"specification without {missing_key} keyword"
-        )
-    return test_vars  # type: ignore
+__all__ = ["read_summary"]
 
 
 class DateUnit(Enum):
@@ -175,97 +84,30 @@ class DateUnit(Enum):
         raise InvalidResponseFile(f"Unknown date unit {val}")
 
 
-def _is_base_with_extension(base: str, path: str, exts: list[str]) -> bool:
-    """
-    >>> _is_base_with_extension("ECLBASE", "ECLBASE.SMSPEC", ["smspec"])
-    True
-    >>> _is_base_with_extension("ECLBASE", "BASE.SMSPEC", ["smspec"])
-    False
-    >>> _is_base_with_extension("ECLBASE", "BASE.FUNSMRY", ["smspec"])
-    False
-    >>> _is_base_with_extension("ECLBASE", "ECLBASE.smspec", ["smspec"])
-    True
-    >>> _is_base_with_extension("ECLBASE.tar.gz", "ECLBASE.tar.gz.smspec", ["smspec"])
-    True
-    """
-    if "." not in path:
-        return False
-    splitted = path.split(".")
-    return ".".join(splitted[0:-1]) == base and splitted[-1].lower() in exts
-
-
-def _is_unsmry(base: str, path: str) -> bool:
-    return _is_base_with_extension(base, path, ["unsmry", "funsmry"])
-
-
-def _is_smspec(base: str, path: str) -> bool:
-    return _is_base_with_extension(base, path, ["smspec", "fsmspec"])
-
-
-def _find_file_matching(
-    kind: str, case: str, predicate: Callable[[str, str], bool]
-) -> str:
-    directory, base = os.path.split(case)
-    candidates = list(
-        filter(lambda x: predicate(base, x), os.listdir(directory or "."))
-    )
-    if not candidates:
-        raise FileNotFoundError(f"Could not find any {kind} matching case path {case}")
-    if len(candidates) > 1:
-        raise FileNotFoundError(
-            f"Ambiguous reference to {kind} in {case}, could be any of {candidates}"
-        )
-    return os.path.join(directory, candidates[0])
-
-
-def _get_summary_filenames(filepath: str) -> tuple[str, str]:
-    if filepath.lower().endswith(".data"):
-        # For backwards compatability, it is
-        # allowed to give REFCASE and ECLBASE both
-        # with and without .DATA extensions
-        filepath = filepath[:-5]
-    summary = _find_file_matching("unified summary file", filepath, _is_unsmry)
-    spec = _find_file_matching("smspec file", filepath, _is_smspec)
-    return summary, spec
-
-
-def _key2str(key: bytes | str) -> str:
-    ret = key.decode() if isinstance(key, bytes) else key
-    assert isinstance(ret, str)
-    return ret.strip()
-
-
-def _check_vals(
-    kw: str, spec: str, vals: npt.NDArray[Any] | resfo.MESS
-) -> npt.NDArray[Any]:
-    if vals is resfo.MESS or isinstance(vals, resfo.MESS):
-        raise InvalidResponseFile(f"{kw.strip()} in {spec} has incorrect type MESS")
-    return vals
-
-
+@lru_cache
 def _fetch_keys_to_matcher(fetch_keys: Sequence[str]) -> Callable[[str], bool]:
     """
     Transform the list of keys (with * used as repeated wildcard) into
     a matcher.
 
-    >>> match = _fetch_keys_to_matcher([""])
+    >>> match = _fetch_keys_to_matcher(("",))
     >>> match("FOPR")
     False
 
-    >>> match = _fetch_keys_to_matcher(["*"])
+    >>> match = _fetch_keys_to_matcher(("*",))
     >>> match("FOPR"), match("FO*")
     (True, True)
 
 
-    >>> match = _fetch_keys_to_matcher(["F*PR"])
+    >>> match = _fetch_keys_to_matcher(("F*PR",))
     >>> match("WOPR"), match("FOPR"), match("FGPR"), match("SOIL")
     (False, True, True, False)
 
-    >>> match = _fetch_keys_to_matcher(["WGOR:*"])
+    >>> match = _fetch_keys_to_matcher(("WGOR:*",))
     >>> match("FOPR"), match("WGOR:OP1"), match("WGOR:OP2"), match("WGOR")
     (False, True, True, False)
 
-    >>> match = _fetch_keys_to_matcher(["FOPR", "FGPR"])
+    >>> match = _fetch_keys_to_matcher(("FOPR", "FGPR"))
     >>> match("FOPR"), match("FGPR"), match("WGOR:OP2"), match("WGOR")
     (True, True, False, False)
     """
@@ -276,119 +118,52 @@ def _fetch_keys_to_matcher(fetch_keys: Sequence[str]) -> Callable[[str], bool]:
 
 
 def _read_spec(
-    spec: str, fetch_keys: Sequence[str]
+    summary: SummaryReader, fetch_keys: Sequence[str]
 ) -> tuple[int, datetime, DateUnit, list[str], npt.NDArray[np.int64]]:
-    date = None
-    n = None
-    nx = None
-    ny = None
-    wgnames = None
-
-    arrays: dict[str, npt.NDArray[Any] | None] = dict.fromkeys(
-        [
-            "NUMS    ",
-            "KEYWORDS",
-            "NUMLX   ",
-            "NUMLY   ",
-            "NUMLZ   ",
-            "LGRS    ",
-            "UNITS   ",
-        ],
-        None,
-    )
-    if spec.lower().endswith("fsmspec"):
-        mode = "rt"
-        assumed_format = resfo.Format.FORMATTED
+    date = summary.start_date
+    dims = summary.dimensions
+    if dims is not None:
+        nx, ny = dims[0:2]
     else:
-        mode = "rb"
-        assumed_format = resfo.Format.UNFORMATTED
-
-    with open(spec, mode) as fp:
-        for entry in resfo.lazy_read(fp, assumed_format):
-            if all(p is not None for p in [date, n, nx, ny, *arrays.values()]):
-                break
-            kw = entry.read_keyword()
-            if kw in arrays:
-                arrays[kw] = _check_vals(kw, spec, entry.read_array())
-            if kw in {"WGNAMES ", "NAMES   "}:
-                wgnames = _check_vals(kw, spec, entry.read_array())
-            if kw == "DIMENS  ":
-                vals = _check_vals(kw, spec, entry.read_array())
-                size = len(vals)
-                n = vals[0] if size > 0 else None
-                nx = vals[1] if size > 1 else None
-                ny = vals[2] if size > 2 else None
-            if kw == "STARTDAT":
-                vals = _check_vals(kw, spec, entry.read_array())
-                size = len(vals)
-                day = vals[0] if size > 0 else 0
-                month = vals[1] if size > 1 else 0
-                year = vals[2] if size > 2 else 0
-                hour = vals[3] if size > 3 else 0
-                minute = vals[4] if size > 4 else 0
-                microsecond = vals[5] if size > 5 else 0
-                try:
-                    date = datetime(
-                        day=day,
-                        month=month,
-                        year=year,
-                        hour=hour,
-                        minute=minute,
-                        second=microsecond // 10**6,
-                        # Due to https://github.com/equinor/ert/issues/6952
-                        # microseconds have to be ignored to avoid overflow
-                        # in netcdf3 files
-                        # microsecond=self.micro_seconds % 10**6,
-                    )
-                except Exception as err:
-                    raise InvalidResponseFile(
-                        f"SMSPEC {spec} contains invalid STARTDAT: {err}"
-                    ) from err
-    keywords = arrays["KEYWORDS"]
-    nums = arrays["NUMS    "]
-    numlx = arrays["NUMLX   "]
-    numly = arrays["NUMLY   "]
-    numlz = arrays["NUMLZ   "]
-    lgr_names = arrays["LGRS    "]
+        nx, ny = None, None
+
+    keywords = summary.summary_keywords
 
     if date is None:
-        raise InvalidResponseFile(f"Keyword startdat missing in {spec}")
-    if keywords is None:
-        raise InvalidResponseFile(f"Keywords missing in {spec}")
-    if n is None:
-        n = len(keywords)
+        raise InvalidResponseFile(
+            f"Keyword STARTDAT missing in {summary.smspec_filename}"
+        )
 
     indices: list[int] = []
     keys: list[str] = []
     index_mapping: dict[str, int] = {}
     date_index = None
+    date_unit_str = None
+
+    should_load_key = _fetch_keys_to_matcher(tuple(fetch_keys))
+
+    for i, kw in enumerate(keywords):
+        try:
+            key = make_summary_key(
+                kw.summary_variable,
+                kw.number,
+                kw.name,
+                nx,
+                ny,
+                kw.lgr_name,
+                kw.li,
+                kw.lj,
+                kw.lk,
+            )
+            if kw.summary_variable == "TIME":
+                date_index = i
+                date_unit_str = kw.unit
+        except InvalidSummaryKeyError as err:
+            warnings.warn(
+                f"Found {err} in summary specification, key not loaded", stacklevel=2
+            )
+            continue
 
-    should_load_key = _fetch_keys_to_matcher(fetch_keys)
-
-    def optional_get(arr: npt.NDArray[Any] | None, idx: int) -> Any:
-        if arr is None:
-            return None
-        if len(arr) <= idx:
-            return None
-        return arr[idx]
-
-    for i in range(n):
-        keyword = _key2str(keywords[i])
-        if keyword == "TIME":
-            date_index = i
-
-        name = optional_get(wgnames, i)
-        if name is not None:
-            name = _key2str(name)
-        num = optional_get(nums, i)
-        lgr_name = optional_get(lgr_names, i)
-        if lgr_name is not None:
-            lgr_name = _key2str(lgr_name)
-        li = optional_get(numlx, i)
-        lj = optional_get(numly, i)
-        lk = optional_get(numlz, i)
-
-        key = make_summary_key(keyword, num, name, nx, ny, lgr_name, li, lj, lk)
         if should_load_key(key):
             if key in index_mapping:
                 # only keep the index of the last occurrence of a key
@@ -406,19 +181,19 @@ def _read_spec(
 
     indices_array = np.array(indices, dtype=np.int64)[rearranged]
 
-    units = arrays["UNITS   "]
-    if units is None:
-        raise InvalidResponseFile(f"Keyword units missing in {spec}")
     if date_index is None:
-        raise InvalidResponseFile(f"KEYWORDS did not contain TIME in {spec}")
-    if date_index >= len(units):
-        raise InvalidResponseFile(f"Unit missing for TIME in {spec}")
+        raise InvalidResponseFile(
+            f"KEYWORDS did not contain TIME in {summary.smspec_filename}"
+        )
+    if date_unit_str is None:
+        raise InvalidResponseFile(f"Unit missing for TIME in {summary.smspec_filename}")
 
-    unit_key = _key2str(units[date_index])
     try:
-        date_unit = DateUnit[unit_key]
+        date_unit = DateUnit[date_unit_str]
     except KeyError:
-        raise InvalidResponseFile(f"Unknown date unit in {spec}: {unit_key}") from None
+        raise InvalidResponseFile(
+            f"Unknown date unit in {summary.smspec_filename}: {date_unit_str}"
+        ) from None
 
     return (
         date_index,
@@ -443,49 +218,20 @@ def _round_to_seconds(dt: datetime) -> datetime:
 
 
 def _read_summary(
-    summary: str,
+    summary: SummaryReader,
     start_date: datetime,
     unit: DateUnit,
     indices: npt.NDArray[np.int64],
     date_index: int,
 ) -> tuple[npt.NDArray[np.float32], list[datetime]]:
-    if summary.lower().endswith("funsmry"):
-        mode = "rt"
-        assumed_format = resfo.Format.FORMATTED
-    else:
-        mode = "rb"
-        assumed_format = resfo.Format.UNFORMATTED
-
-    last_params = None
     values: list[npt.NDArray[np.float32]] = []
     dates: list[datetime] = []
-
-    def read_params() -> None:
-        nonlocal last_params, values
-        if last_params is not None:
-            vals = _check_vals("PARAMS", summary, last_params.read_array())
-            values.append(vals[indices])
-
+    try:
+        for v in summary.values(report_step_only=True):
+            values.append(v[indices])
             dates.append(
-                _round_to_seconds(
-                    start_date + unit.make_delta(float(vals[date_index]))
-                ),
+                _round_to_seconds(start_date + unit.make_delta(float(v[date_index]))),
             )
-            # Due to https://github.com/equinor/ert/issues/6952
-            # times have to be rounded to whole seconds to avoid overflow
-            # in netcdf3 files
-            # dates.append(start_date + unit.make_delta(float(vals[date_index])))
-            last_params = None
-
-    try:
-        with open(summary, mode) as fp:
-            for entry in resfo.lazy_read(fp, assumed_format):
-                kw = entry.read_keyword()
-                if kw == "PARAMS  ":
-                    last_params = entry
-                if kw == "SEQHDR  ":
-                    read_params()
-            read_params()
+        return np.array(values, dtype=np.float32).T, dates
     except ValueError as e:
         raise InvalidResponseFile(f"Unable to read summary data from {summary}") from e
-    return np.array(values, dtype=np.float32).T, dates

ert/config/design_matrix.py

@@ -25,6 +25,7 @@ class DesignMatrix:
     xls_filename: Path
     design_sheet: str
     default_sheet: str | None
+    priority_source: str = "design_matrix"
 
     def __post_init__(self) -> None:
         try:
@@ -33,6 +34,9 @@ class DesignMatrix:
                 self.design_matrix_df,
                 self.parameter_configurations,
             ) = self.read_and_validate_design_matrix()
+            self.parameter_priority = {
+                cfg.name: self.priority_source for cfg in self.parameter_configurations
+            }
         except (ValueError, AttributeError) as exc:
             raise ConfigValidationError.with_context(
                 f"Error reading design matrix {self.xls_filename}"
@@ -45,8 +49,21 @@ class DesignMatrix:
     def from_config_list(cls, config_list: list[str | dict[str, str]]) -> DesignMatrix:
         filename = Path(cast(str, config_list[0]))
         options = cast(dict[str, str], config_list[1])
+        valid_options = ["DESIGN_SHEET", "DEFAULT_SHEET", "PRIORITY"]
+        option_errors = [
+            ErrorInfo(
+                f"Option {option} is not a valid DESIGN_MATRIX option. "
+                f"Valid options are {', '.join(valid_options)}."
+            ).set_context(config_list)
+            for option in options
+            if option not in valid_options
+        ]
+
+        if option_errors:
+            raise ConfigValidationError.from_collected(option_errors)
         design_sheet = options.get("DESIGN_SHEET", "DesignSheet")
         default_sheet = options.get("DEFAULT_SHEET", None)
+        priority_source = options.get("PRIORITY", DataSource.DESIGN_MATRIX)
         errors = []
         if filename.suffix not in {
             ".xlsx",
@@ -63,6 +80,13 @@ class DesignMatrix:
                     "DESIGN_SHEET and DEFAULT_SHEET can not point to the same sheet."
                 ).set_context(config_list)
             )
+        if priority_source not in {DataSource.DESIGN_MATRIX, DataSource.SAMPLED}:
+            errors.append(
+                ErrorInfo(
+                    f"PRIORITY must be either '{DataSource.DESIGN_MATRIX}'"
+                    f" or '{DataSource.SAMPLED}' priority is '{priority_source}'"
+                ).set_context(config_list)
+            )
         if errors:
             raise ConfigValidationError.from_collected(errors)
         assert design_sheet is not None
@@ -70,6 +94,7 @@ class DesignMatrix:
             xls_filename=filename,
             design_sheet=design_sheet,
             default_sheet=default_sheet,
+            priority_source=priority_source,
         )
 
     def merge_with_other(self, dm_other: DesignMatrix) -> None:
@@ -87,24 +112,17 @@ class DesignMatrix:
         common_keys = set(
             self.design_matrix_df.select(pl.exclude("realization")).columns
         ) & set(dm_other.design_matrix_df.columns)
-        non_identical_cols = set()
         if common_keys:
-            for key in common_keys:
-                if not self.design_matrix_df.select(key).equals(
-                    dm_other.design_matrix_df.select(key)
-                ):
-                    non_identical_cols.add(key)
-            if non_identical_cols:
-                errors.append(
-                    ErrorInfo(
-                        f"Design Matrices '{self.xls_filename.name} "
-                        f"({self.design_sheet} {self.default_sheet or ''})' and "
-                        f"'{dm_other.xls_filename.name} ({dm_other.design_sheet} "
-                        f"{dm_other.default_sheet or ''})' "
-                        "contains non identical columns with the same name: "
-                        f"{non_identical_cols}!"
-                    )
+            errors.append(
+                ErrorInfo(
+                    f"Design Matrices '{self.xls_filename.name} "
+                    f"({self.design_sheet} {self.default_sheet or ''})' and "
+                    f"'{dm_other.xls_filename.name} ({dm_other.design_sheet} "
+                    f"{dm_other.default_sheet or ''})' "
+                    "contains columns with the same name: "
+                    f"{common_keys}!"
                 )
+            )
 
         if errors:
             raise ConfigValidationError.from_collected(errors)
@@ -113,9 +131,7 @@ class DesignMatrix:
             self.design_matrix_df = pl.concat(
                 [
                     self.design_matrix_df,
-                    dm_other.design_matrix_df.select(
-                        pl.exclude([*list(common_keys), "realization"])
-                    ),
+                    dm_other.design_matrix_df.select(pl.exclude(["realization"])),
                 ],
                 how="horizontal",
             )
@@ -133,6 +149,7 @@ class DesignMatrix:
             for cfg in dm_other.parameter_configurations
             if cfg.name not in common_keys
         )
+        self.parameter_priority.update(dm_other.parameter_priority)
 
     def merge_with_existing_parameters(
         self, existing_parameters: list[ParameterConfig]
@@ -154,11 +171,33 @@ class DesignMatrix:
 
         for param_cfg in existing_parameters:
             if isinstance(param_cfg, GenKwConfig) and param_cfg.name in design_cfgs:
-                param_cfg.input_source = DataSource.DESIGN_MATRIX
-                param_cfg.update = False
-                param_cfg.distribution = RawSettings()
                 del design_cfgs[param_cfg.name]
-            new_param_configs += [param_cfg]
+                input_source = DataSource(
+                    self.parameter_priority.get(
+                        param_cfg.name, DataSource.DESIGN_MATRIX.value
+                    )
+                )
+                new_param_configs += [
+                    GenKwConfig(
+                        name=param_cfg.name,
+                        update=(
+                            input_source == DataSource.SAMPLED and param_cfg.update
+                        ),
+                        distribution=(
+                            RawSettings()
+                            if input_source == DataSource.DESIGN_MATRIX
+                            else param_cfg.distribution
+                        ),
+                        group=(
+                            DESIGN_MATRIX_GROUP
+                            if input_source == DataSource.DESIGN_MATRIX
+                            else param_cfg.group
+                        ),
+                        input_source=input_source,
+                    ),
+                ]
+            else:
+                new_param_configs += [param_cfg]
         if design_cfgs.values():
             new_param_configs += list(design_cfgs.values())
         return new_param_configs

ert/config/distribution.py

@@ -17,7 +17,7 @@ class TransSettingsValidation(BaseModel):
     model_config = {"extra": "forbid"}
 
     @classmethod
-    def create(cls: type[T], *args: Any, **kwargs: Any) -> T:
+    def create(cls, *args: Any, **kwargs: Any) -> Self:
         return cls(*args, **kwargs)
 
     @classmethod