Add allowed keywords to forward model steps

Author: larsevj

docs/ert/getting_started/howto/plugin_system.rst

@@ -58,6 +58,8 @@ To install forward model steps that you want to have available in ERT you can us
             super().__init__(
                 name="MY_FORWARD_MODEL",
                 command=["my_executable", "<parameter1>", "<parameter2>"],
+                required_keywords=["<parameter1>"],
+                allowed_keywords=["<parameter2>"],
             )
 
         def validate_pre_realization_run(
@@ -94,6 +96,14 @@ forward model step is invalid (which ert then handles gracefully and presents ni
 to the user). If you want to show a warning in cases where the configuration cannot be
 validated pre-experiment, you can use the ``ForwardModelStepWarning.warn(...)`` method.
 
+Use ``required_keywords`` to declare named arguments that the user must provide. Use
+``allowed_keywords`` to reject named arguments not supported by the forward model
+step. The allowed-keyword check is opt-in: omitting ``allowed_keywords`` preserves the
+default of accepting any named argument. Required keywords and keywords with a
+``default_mapping`` are implicitly allowed. Setting ``allowed_keywords`` to an empty
+list rejects all other named arguments. These declarations validate argument names
+only; use the validation methods for constraints on argument values.
+
 .. code-block:: python
 
    import ert

src/ert/config/ert_config.py

@@ -701,10 +701,17 @@ def create_list_of_forward_model_steps_to_run(
 
         user_positional_args_by_step[id(fm_step)] = user_positional_args
 
-        try:
-            fm_step.check_required_keywords()
-        except ConfigValidationError as err:
-            errors.append(err)
+        keyword_errors: list[ConfigValidationError] = []
+        for check_keywords in (
+            fm_step.check_allowed_keywords,
+            fm_step.check_required_keywords,
+        ):
+            try:
+                check_keywords()
+            except ConfigValidationError as err:
+                keyword_errors.append(err)
+        if keyword_errors:
+            errors.extend(keyword_errors)
             continue
         fm_steps.append(fm_step)
 

src/ert/config/forward_model_step.py

@@ -96,6 +96,7 @@ class ForwardModelStepOptions(TypedDict, total=False):
     environment: NotRequired[dict[str, str]]
     default_mapping: NotRequired[dict[str, str]]
     required_keywords: NotRequired[list[str]]
+    allowed_keywords: NotRequired[list[str] | None]
 
 
 def _get_source_package() -> str:
@@ -157,6 +158,9 @@ class ForwardModelStep(BaseModelWithContextSupport):
         max_arg: The maximum number of arguments
         arglist: The arglist with which the executable is invoked
         required_keywords: Keywords that are required to be supplied by the user
+        allowed_keywords: Keywords that may be supplied by the user. If ``None``,
+            any keyword is allowed; an empty list allows only required keywords and
+            keywords with default values.
         arg_types: Types of user-provided arguments, this list must have indices
             corresponding to the number of args that are user specified
             and thus also subject to substitution.
@@ -182,6 +186,7 @@ class ForwardModelStep(BaseModelWithContextSupport):
     max_arg: int | None = None
     arglist: list[str] = Field(default_factory=list)
     required_keywords: list[str] = Field(default_factory=list)
+    allowed_keywords: list[str] | None = None
     arg_types: list[SchemaItemType] = Field(default_factory=list)
     environment: dict[str, str] = Field(default_factory=dict)
     default_mapping: dict[str, str] = Field(default_factory=dict)
@@ -223,6 +228,27 @@ def check_required_keywords(self) -> None:
                 self.name,
             )
 
+    def check_allowed_keywords(self) -> None:
+        if self.allowed_keywords is None:
+            return
+
+        accepted_keywords = (
+            set(self.allowed_keywords)
+            | set(self.required_keywords)
+            | set(self.default_mapping)
+        )
+        unexpected_keywords = set(self.private_args).difference(accepted_keywords)
+        if unexpected_keywords:
+            plural = "s" if len(unexpected_keywords) > 1 else ""
+            verb = "are" if plural else "is"
+            allowed_keywords_message = ", ".join(sorted(accepted_keywords)) or "none"
+            raise ConfigValidationError.with_context(
+                f"Keyword{plural} {', '.join(sorted(unexpected_keywords))} "
+                f"{verb} not allowed for forward model step {self.name}. "
+                f"Allowed keywords: {allowed_keywords_message}",
+                self.name,
+            )
+
     @model_validator(mode="after")
     def set_default_env(self) -> Self:
         self.environment.update(ForwardModelStep.default_env)
@@ -344,6 +370,7 @@ def __init__(
         environment = kwargs.get("environment", {}) or {}
         default_mapping = kwargs.get("default_mapping", {}) or {}
         required_keywords = kwargs.get("required_keywords", []) or []
+        allowed_keywords = kwargs.get("allowed_keywords")
 
         super().__init__(
             name=name,
@@ -359,6 +386,7 @@ def __init__(
             min_arg=0,
             max_arg=0,
             required_keywords=required_keywords,
+            allowed_keywords=allowed_keywords,
             arg_types=[],
             environment=environment,
             default_mapping=default_mapping,

src/ert/plugins/hook_implementations/forward_model_steps.py

@@ -9,7 +9,6 @@
     ForwardModelStepJSON,
     ForwardModelStepPlugin,
     ForwardModelStepValidationError,
-    ForwardModelStepWarning,
     plugin,
 )
 
@@ -216,6 +215,7 @@ def __init__(self) -> None:
                 "<OPTS>",
             ],
             default_mapping={"<NUM_CPU>": "1", "<OPTS>": ""},
+            allowed_keywords=["<VERSION>", "<NUM_CPU>", "<OPTS>", "<ECLBASE>"],
         )
 
     def validate_pre_experiment(self, fm_json: ForwardModelStepJSON) -> None:
@@ -281,6 +281,7 @@ def __init__(self) -> None:
                 "<OPTS>",
             ],
             default_mapping={"<NUM_CPU>": "1", "<OPTS>": "", "<VERSION>": "version"},
+            allowed_keywords=["<VERSION>", "<NUM_CPU>", "<OPTS>", "<ECLBASE>"],
         )
 
     def validate_pre_experiment(
@@ -344,10 +345,10 @@ def __init__(self) -> None:
                 "<NUM_CPU>": "1",
                 "<OPTS>": "",
             },
+            allowed_keywords=["<VERSION>", "<NUM_CPU>", "<OPTS>", "<ECLBASE>"],
         )
 
     def validate_pre_experiment(self, fm_json: ForwardModelStepJSON) -> None:
-        allowed_args = {"<VERSION>", "<NUM_CPU>", "<OPTS>", "<ECLBASE>"}
         if "--np" in self.private_args.get("<OPTS>", ""):
             raise ForwardModelStepValidationError(
                 "Do not supply --np as an option to FLOW, "
@@ -359,10 +360,6 @@ def validate_pre_experiment(self, fm_json: ForwardModelStepJSON) -> None:
                 "set NUM_CPU in the Ert config instead."
             )
 
-        if unknowns := set(self.private_args) - allowed_args:
-            raise ForwardModelStepWarning(
-                f"Unknown option(s) supplied to Flow: {sorted(unknowns)}"
-            )
         available_versions = _available_flow_versions(
             env_vars=fm_json["environment"] or {}
         )

tests/ert/unit_tests/config/test_forward_model.py

@@ -609,10 +609,16 @@ def test_that_flow_fm_gives_error_on_threads_in_opts(plugins_ert_config):
         )
 
 
-def test_that_flow_fm_gives_config_warning_on_unknown_options(plugins_ert_config):
-    with pytest.warns(ConfigWarning, match=r".*Unknown option.*Flow: .*DUMMY.*"):
+@pytest.mark.parametrize("fm_step_name", ["ECLIPSE100", "ECLIPSE300", "FLOW"])
+def test_that_reservoir_simulator_fm_rejects_unknown_keyword(
+    plugins_ert_config, fm_step_name
+):
+    with pytest.raises(
+        ConfigValidationError,
+        match=rf"Keyword <DUMMY> is not allowed for forward model step {fm_step_name}",
+    ):
         plugins_ert_config.from_file_contents(
-            "NUM_REALIZATIONS 1\nFORWARD_MODEL FLOW(<DUMMY>=moredummy)\n"
+            f"NUM_REALIZATIONS 1\nFORWARD_MODEL {fm_step_name}(<DUMMY>=moredummy)\n"
         )
 
 
@@ -1126,6 +1132,120 @@ def __init__(self) -> None:
     )
 
 
+def _load_forward_model_with_keyword_contract(
+    invocation: str,
+    *,
+    allowed_keywords: list[str] | None,
+    required_keywords: list[str] | None = None,
+    default_mapping: dict[str, str] | None = None,
+    command: list[str] | None = None,
+) -> ErtConfig:
+    class FMWithKeywordContract(ForwardModelStepPlugin):
+        def __init__(self) -> None:
+            super().__init__(
+                name="FMWithKeywordContract",
+                command=command or ["echo"],
+                required_keywords=required_keywords or [],
+                allowed_keywords=allowed_keywords,
+                default_mapping=default_mapping or {},
+            )
+
+    return ErtConfig.with_plugins(
+        ErtRuntimePlugins(
+            installed_forward_model_steps={
+                "FMWithKeywordContract": FMWithKeywordContract(),
+            }
+        )
+    ).from_file_contents(
+        f"""
+        NUM_REALIZATIONS 1
+        FORWARD_MODEL FMWithKeywordContract{invocation}
+        """
+    )
+
+
+def test_that_plugin_fm_step_rejects_keyword_not_in_allowed_keywords():
+    with pytest.raises(
+        ConfigValidationError,
+        match=(
+            r"Keyword <C> is not allowed for forward model step "
+            r"FMWithKeywordContract\. Allowed keywords: <A>, <B>"
+        ),
+    ):
+        _load_forward_model_with_keyword_contract(
+            "(<A>=one,<C>=three)",
+            allowed_keywords=["<A>", "<B>"],
+            command=["echo", "<A>", "<B>"],
+        )
+
+
+def test_that_plugin_fm_step_without_allowed_keywords_accepts_unknown_keywords():
+    _load_forward_model_with_keyword_contract(
+        "(<UNKNOWN>=value)",
+        allowed_keywords=None,
+    )
+
+
+def test_that_plugin_fm_step_with_empty_allowed_keywords_rejects_named_argument():
+    with pytest.raises(
+        ConfigValidationError,
+        match=(
+            r"Keyword <A> is not allowed for forward model step "
+            r"FMWithKeywordContract\. Allowed keywords: none"
+        ),
+    ):
+        _load_forward_model_with_keyword_contract(
+            "(<A>=one)",
+            allowed_keywords=[],
+        )
+
+
+def test_that_allowed_keywords_do_not_restrict_keyword_values():
+    ert_config = _load_forward_model_with_keyword_contract(
+        '(<OPTIONS>="--foo --bar=baz")',
+        allowed_keywords=["<OPTIONS>"],
+        command=["echo", "<OPTIONS>"],
+    )
+
+    assert ert_config.forward_model_steps[0].private_args == {
+        "<OPTIONS>": "--foo --bar=baz"
+    }
+
+
+def test_that_required_keywords_are_implicitly_allowed():
+    _load_forward_model_with_keyword_contract(
+        "(<REQUIRED>=value)",
+        allowed_keywords=[],
+        required_keywords=["<REQUIRED>"],
+        command=["echo", "<REQUIRED>"],
+    )
+
+
+def test_that_defaulted_keyword_is_implicitly_allowed():
+    ert_config = _load_forward_model_with_keyword_contract(
+        "(<DEFAULTED>=override)",
+        allowed_keywords=[],
+        default_mapping={"<DEFAULTED>": "default"},
+        command=["echo", "<DEFAULTED>"],
+    )
+
+    assert ert_config.forward_model_steps[0].private_args == {"<DEFAULTED>": "override"}
+
+
+def test_that_required_keyword_typo_reports_unknown_and_missing_keywords():
+    with pytest.raises(ConfigValidationError) as exc_info:
+        _load_forward_model_with_keyword_contract(
+            "(<REQURIED>=value)",
+            allowed_keywords=[],
+            required_keywords=["<REQUIRED>"],
+            command=["echo", "<REQUIRED>"],
+        )
+
+    error = str(exc_info.value)
+    assert "Keyword <REQURIED> is not allowed" in error
+    assert "Required keyword <REQUIRED> not found" in error
+
+
 @pytest.mark.usefixtures("use_tmpdir")
 def test_that_one_required_keyword_in_forward_model_is_validated():
     Path("step").write_text("EXECUTABLE echo\nREQUIRED MESSAGE", encoding="utf-8")

tests/ert/unit_tests/run_models/snapshots/test_experiment_serialization/test_that_dumped_enif_matches_snapshot/heat_equationconfig.ert/config.json

@@ -48,6 +48,7 @@
         "<ARG1>"
       ],
       "required_keywords": [],
+      "allowed_keywords": null,
       "arg_types": [],
       "environment": {
         "_ERT_ITERATION_NUMBER": "<ITER>",

tests/ert/unit_tests/run_models/snapshots/test_experiment_serialization/test_that_dumped_enif_matches_snapshot/poly_examplepoly.ert/poly.json

@@ -41,6 +41,7 @@
       "max_arg": null,
       "arglist": [],
       "required_keywords": [],
+      "allowed_keywords": null,
       "arg_types": [],
       "environment": {
         "_ERT_ITERATION_NUMBER": "<ITER>",

tests/ert/unit_tests/run_models/snapshots/test_experiment_serialization/test_that_dumped_enif_matches_snapshot/snake_oilsnake_oil.ert/snake_oil.json

@@ -41,6 +41,7 @@
       "max_arg": null,
       "arglist": [],
       "required_keywords": [],
+      "allowed_keywords": null,
       "arg_types": [],
       "environment": {
         "_ERT_ITERATION_NUMBER": "<ITER>",
@@ -65,6 +66,7 @@
       "max_arg": null,
       "arglist": [],
       "required_keywords": [],
+      "allowed_keywords": null,
       "arg_types": [],
       "environment": {
         "_ERT_ITERATION_NUMBER": "<ITER>",
@@ -89,6 +91,7 @@
       "max_arg": null,
       "arglist": [],
       "required_keywords": [],
+      "allowed_keywords": null,
       "arg_types": [],
       "environment": {
         "_ERT_ITERATION_NUMBER": "<ITER>",

tests/ert/unit_tests/run_models/snapshots/test_experiment_serialization/test_that_dumped_ensemble_experiment_matches_snapshot/heat_equationconfig.ert/config.json

@@ -48,6 +48,7 @@
         "<ARG1>"
       ],
       "required_keywords": [],
+      "allowed_keywords": null,
       "arg_types": [],
       "environment": {
         "_ERT_ITERATION_NUMBER": "<ITER>",

tests/ert/unit_tests/run_models/snapshots/test_experiment_serialization/test_that_dumped_ensemble_experiment_matches_snapshot/poly_examplepoly.ert/poly.json

@@ -41,6 +41,7 @@
       "max_arg": null,
       "arglist": [],
       "required_keywords": [],
+      "allowed_keywords": null,
       "arg_types": [],
       "environment": {
         "_ERT_ITERATION_NUMBER": "<ITER>",