Config Validation¶
How TANGO validates a configuration file before any simulation runs: which errors are raised for missing keys, wrong types and unsupported values, and where each check lives. Status: available; open questions are listed at the end.
Principle¶
Every setting a simulation needs must raise an error if it is missing or mis-entered in the config file. Settings that are optional, or valid but unusual, produce a warning instead. Validation finishes before the first timestep, so a bad config never fails halfway through a run.
graph TD
File[Config file .yml] --> ReadFile(Workflow.from_file)
File --> NoFile[File does not exist]
ReadFile --> ConfigError[
Error:
- missing or extra keys
- wrong type, out-of-range value
- non-existent option, e.g. 9SPOT
- NotImplementedError for an option not yet supported, e.g. AGS_DOUBLET
]
ReadFile --> ConfigWarning[Warning:
- optional block missing
]
ConfigWarning --> Workflow_init[Workflow.__init__]
Workflow_init --> InitError[Error:
-CoolPropError]
Workflow_init --> InitWarning[Warning:]
InitWarning --> Workflow_run[Workflow.run]
Where the checks live¶
Most checks are pydantic validators in src/tango_core/core/specs.py.
@field_validator checks one field; @model_validator checks rules that
span several fields. A validator raises ValueError for a value that cannot
be right and logs a warning for a value that is plausible but unusual.
Every pydantic ValidationError is caught in Workflow.__init__
(src/tango_core/workflows/workflow.py) and re-raised as ConfigError, so
ConfigError is the single error type for a bad config file. tango_core
maps it to exit code 1.
Example: a single field¶
surface_temperature is in kelvin.
| Range | Result |
|---|---|
| Outside 204–330 K (−69.15 to 56.85 °C) | ValueError; almost certainly a unit mistake (°C entered as K) or a typo |
| Above 315 K (41.85 °C) or below 278 K (4.85 °C) | Warning; plausible but unusual for a geothermal site |
| Otherwise | Accepted |
class Common(BaseModel):
...
surface_temperature: float
...
@field_validator("surface_temperature")
@classmethod
def check_surface_temperature(cls, te: float) -> float:
if not (204 <= te <= 330):
raise ValueError(...) # outside the plausible range
elif te > 315:
logger.warning(...) # quite high
elif te < 278:
logger.warning(...) # quite low
return te
Example: rules across fields¶
SimConfig.check_injection_mode_requirements is a @model_validator,
because injection_mode decides which other fields are required:
injection_mode |
bc_checkpoint_idx |
mass_rate |
|---|---|---|
absent (SystemDirect) |
not used | as given |
manual, manual-fracking-check |
required | required |
class SimConfig(BaseModel):
...
injection_mode: InjectionPolicy | None = None
mass_rate: float | None = None
bc_checkpoint_idx: int | None = None
...
@model_validator(mode="after")
def check_injection_mode_requirements(self) -> SimConfig:
if self.injection_mode is None:
return self
if self.bc_checkpoint_idx is None:
raise ValueError(...)
if self.mass_rate is None:
raise ValueError(...)
return self
Example: an optional block¶
The economic block is optional. Workflow.__init__ builds it with
_build_economic_component and, if the block is absent, logs a warning and
runs without economic outputs:
try:
self._economic = _build_economic_component(config["economic"])
except KeyError:
logger.warning("No economic component found, this simulation will run without economic outputs")
self._economic = None
Tests¶
tests/regtest/test_config_validation.py loads deliberately broken configs
with Workflow.from_file() and checks that each raises the expected error:
ConfigError for a missing block or a wrong value, NotImplementedError
for an option that is recognized but not implemented. It also checks that
a missing optional block or an unusual value logs a warning while the
Workflow is still built. Problems that only appear once Workflow.run()
starts are out of scope for that file.
Open questions¶
- Validators live in the same module as the schema they validate. Whether larger components should move their validators into separate modules is undecided.
- Every config problem surfaces as
ConfigErrorrather thanKeyErrororValueError. The message names the field, but callers cannot branch on the kind of problem. - Each custom field validator is code to maintain. Where a pydantic
constraint (
gt=0,Literal[...]) expresses the same rule, it is the cheaper option.