Skip to content

Commit 1a2ecf2

Browse files
committed
docs(readme): add configuration validation section
- Add comprehensive "Configuration Validation" section after Features - Explain the problem of missing/invalid parameters causing silent failures - Show validation summary output for valid configurations - Show detailed error messages for validation failures - Document benefits: prevents wasted time, self-documenting, helpful errors - Add code example for model developers to add validation - Reference tungsten_input.hpp as complete example with 21 parameters - Update features list to include configuration validation
1 parent aa1f3c0 commit 1a2ecf2

File tree

1 file changed

+99
-0
lines changed

1 file changed

+99
-0
lines changed

README.md

Lines changed: 99 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -75,6 +75,105 @@ The project documentation can be found from
7575
- modern c++17 header-only framework, easy to use
7676
- extensible architecture - add custom components without modifying source code
7777
- runtime-switchable FFT backends (CPU/GPU) for optimal performance
78+
- comprehensive configuration validation with helpful error messages
79+
80+
## Configuration Validation
81+
82+
OpenPFC provides **comprehensive parameter validation** to prevent silent failures from missing or invalid configuration parameters. This "fail-fast" approach catches errors immediately at startup rather than hours into a simulation.
83+
84+
### The Problem
85+
86+
Missing or invalid parameters can cause:
87+
- ❌ Silent failures with incorrect physics
88+
- ❌ Hours/days wasted debugging
89+
- ❌ Uninitialized values causing unpredictable behavior
90+
91+
**Example of a dangerous configuration:**
92+
```toml
93+
[model.params]
94+
n0 = -0.10
95+
alpha = 0.50
96+
# Forgot to add lambda! ← Simulation will run with wrong/uninitialized value
97+
```
98+
99+
### The Solution
100+
101+
OpenPFC validates **all parameters before simulation starts**:
102+
103+
```
104+
================================================================================
105+
Configuration Validation Summary - Tungsten PFC Model
106+
================================================================================
107+
Validated 21 parameter(s):
108+
--------------------------------------------------------------------------------
109+
n0 = -0.1 [range: -1, 0]
110+
n_sol = -0.047 [range: -1, 0]
111+
n_vap = -0.464 [range: -1, 0]
112+
T = 3300 [range: 0, 10000]
113+
T0 = 156000 [range: 1, 1e+06]
114+
... (all 21 parameters validated)
115+
================================================================================
116+
```
117+
118+
If validation fails, you get a **clear, actionable error message**:
119+
120+
```
121+
================================================================================
122+
CONFIGURATION VALIDATION FAILED
123+
================================================================================
124+
Found 2 error(s):
125+
126+
1. Required parameter 'lambda' is missing
127+
Parameter: lambda
128+
Description: Strength of meanfield filter (avoid >0.28)
129+
Valid range: [0, 0.5]
130+
Typical value: 0.22
131+
Required: yes
132+
133+
2. Parameter 'stabP' = 2.5 exceeds maximum 1.0
134+
Parameter: stabP
135+
Description: Numerical stability parameter for exponential integrator
136+
Valid range: [0, 1]
137+
Typical value: 0.2
138+
139+
ABORTING: Fix configuration errors before running simulation.
140+
================================================================================
141+
```
142+
143+
### Benefits
144+
145+
-**Prevents wasted time** - Catch errors immediately, not after hours of simulation
146+
-**Self-documenting** - Parameter summary shows exactly what was run (reproducibility)
147+
-**Helpful errors** - Clear messages with valid ranges and typical values
148+
-**Type safety** - Validates parameter types and bounds
149+
150+
### For Model Developers
151+
152+
Add validation to your custom models using the parameter metadata system:
153+
154+
```cpp
155+
#include "openpfc/ui/parameter_validator.hpp"
156+
157+
ParameterValidator validator;
158+
validator.add_metadata(
159+
ParameterMetadata<double>::builder()
160+
.name("temperature")
161+
.description("Effective temperature")
162+
.required(true)
163+
.range(0.0, 10000.0)
164+
.typical(3300.0)
165+
.units("K")
166+
.build()
167+
);
168+
169+
auto result = validator.validate(config);
170+
if (!result.is_valid()) {
171+
std::cerr << result.format_errors() << std::endl;
172+
throw std::invalid_argument("Validation failed");
173+
}
174+
```
175+
176+
See `apps/tungsten/tungsten_input.hpp` for a complete example with 21 validated parameters.
78177

79178
## Extending OpenPFC
80179

0 commit comments

Comments
 (0)