Model Calibration and Data Reconciliation
A practical workflow for calibrating NeqSim models against plant historian data
and producing auditable validation output.
When to Use This Skill
- When simulated values do not match measured plant data.
- When building digital twin loops for separators, compressors, or heat exchangers.
- When you need reproducible parameter tuning with physical bounds.
- When a study requires train/validation split and objective fit metrics.
Scope and Non-Goals
This skill focuses on steady-state calibration and data reconciliation.
This skill does not replace dynamic controller tuning. For transient tuning,
load neqsim-dynamic-simulation in addition.
Required Companion Skills
neqsim-plant-data: historian read patterns (PI/IP.21), tag maps, quality flags.
neqsim-input-validation: parameter bounds and physically realistic inputs.
neqsim-troubleshooting: convergence recovery when each case is re-simulated.
Calibration Workflow
- Define objective and acceptance criteria.
- Build a trusted tag map from plant tags to model variables.
- Read, clean, and quality-filter plant data.
- Detect steady-state windows for fitting.
- Choose tunable model parameters with hard physical bounds.
- Run bounded optimization and re-simulate the full NeqSim process each iteration.
- Validate on holdout windows and publish fit diagnostics.
For the replay and validation steps use neqsim.process.operations.replay.ProcessReplay:
it runs a tag-bound time series through the calibrated model with a convergence gate,
records failed rows without aborting, and gives per-window bias/RMS, baseline-standardised
residuals and CUSUM change points (ReplayResult.setBaselineWindow, detectChangePoints),
exportable as CSV/JSON. See docs/process/process_replay.md.
Typical Tunable Parameters
| Equipment |
Parameters to Tune |
Keep Fixed Unless Needed |
| Compressor |
Polytropic efficiency, pressure ratio correction, anti-surge margin |
Driver type, map family |
| Heat exchanger |
UA correction factor, fouling factor |
Duty sign convention, stream topology |
| Separator |
Entrainment assumptions, liquid carry-over tuning factors |
Phase model and EOS |
| Valve/choke |
Cv multiplier, discharge coefficient |
Control architecture |
| Pipeline |
Roughness, overall heat transfer coefficient |
Length and diameter |
Data Reconciliation Quality Gates
Apply these gates before calibration:
- Unit harmonization complete (temperature, pressure, flow basis).
- At least 3 independent steady-state windows.
- Bad-quality tags removed or masked.
- Outlier handling documented.
- Sensor drift flags noted in notes and results.
Python Pattern: Bounded Calibration Loop
import numpy as np
from scipy.optimize import least_squares
# Example: tune compressor efficiency and HX UA multiplier
# x[0] -> compressor efficiency, x[1] -> UA multiplier
LOWER = np.array([0.60, 0.60])
UPPER = np.array([0.90, 1.40])
X0 = np.array([0.75, 1.00])
# Weights for [discharge pressure, discharge temperature, outlet temperature]
W = np.array([1.0, 1.0, 0.8])
def run_model_and_extract_outputs(process, x):
# Example parameter writes using automation addresses
auto = process.getAutomation()
auto.setVariableValue("Main Compressor.polytropicEfficiency", float(x[0]), "")
auto.setVariableValue("Main Cooler.UA_multiplier", float(x[1]), "")
process.run()
p_out = auto.getVariableValue("Main Compressor.outStream.pressure", "bara")
t_out = auto.getVariableValue("Main Compressor.outStream.temperature", "C")
t_cool = auto.getVariableValue("Main Cooler.outStream.temperature", "C")
return np.array([p_out, t_out, t_cool])
def residuals(x, process, y_target):
y_model = run_model_and_extract_outputs(process, x)
return W * (y_model - y_target)
# y_target should come from a selected steady-state time window average
res = least_squares(
fun=residuals,
x0=X0,
bounds=(LOWER, UPPER),
args=(process, y_target),
method="trf",
max_nfev=150,
)
x_opt = res.x
print("Optimized parameters:", x_opt)
print("Cost:", res.cost)
Objective Design Guidance
Use a weighted residual vector with consistent scaling.
A common objective is:
$$
J(\theta) = \sum_{i=1}^{N} w_i\left(\frac{y_i^{model}(\theta) - y_i^{meas}}{s_i}\right)^2
$$
Where:
- $\theta$ is the vector of tunable parameters.
- $w_i$ is the business/engineering importance weight.
- $s_i$ is a scaling term (for example nominal value or sensor sigma).
Train/Validation Split Pattern
- Train on at least two steady windows from different operating regions.
- Validate on one holdout window not used in fitting.
- Report both train and validation metrics.
Recommended minimum metrics:
- RMSE for each calibrated output tag.
- MAPE where denominator is safe and meaningful.
- Mean signed error (bias).
- Max absolute error.
Common Failure Modes and Fixes
| Failure Mode |
Likely Cause |
Corrective Action |
| Excellent train fit, poor validation |
Overfit on narrow operating range |
Add windows across wider throughput and pressure range |
| Non-physical fitted parameters |
Missing bounds |
Enforce hard bounds and pre-check with input validation |
| Optimization stalls |
Flat objective or too many coupled variables |
Reduce parameter count, stage the tuning in phases |
| Noisy residuals |
Sensor spikes and transient periods |
Increase filtering and steady-state screening |
| Unstable run during optimization |
Recycle sensitivity |
Start from converged base case and use troubleshooting recovery patterns |
| Compressor discharge T low even at a plausible efficiency |
Heavy model gas, anti-surge recycle, or a truly low effective efficiency |
Diagnose in order, each with a measurement: (1) gas mole weight / composition, (2) anti-surge valve opening, (3) independent motor or shaft power. If 1 and 2 are clean, fit an effective efficiency to T (compressor.setOutTemperature(T) then compressor.solveEfficiency(T), or the log-ratio update eta*ln(T2m/T1)/ln(T2p/T1) between runs) and check it against the power that was not fitted (Johan Sverdrup stage 3/4: 0.35-0.42 fitted, power within -13 to -27 %). Never widen the efficiency bound before 1-3 |
| Separator gas flow meters disagree with the gas balance by a constant factor on every train |
Meter basis (actual vs standard m3/h) or gas allocation |
Treat as a data question; calibrate gas to the metered platform gas, do not tune GOR to the meter, and report the meter gap |
Compressor.solveEfficiency(T) returns an efficiency of 1.0 (or the lower limit) and the outlet is not at T |
Older NeqSim builds: the unguarded secant step overshoots when the target needs an efficiency far from the start (e.g. wet gas at 134 C from 0.75 start, true value ~0.36). Fixed with a bracketed (safeguarded) secant in Compressor.solveEfficiency, test CompressorSolveEfficiencyTest. A phase-boundary jump can stall one initial guess about 0.1 K off the target; the solve then uses a local secant and interior restarts, still at the 0.01 K tolerance |
Always read back compressor.getOutletStream().getTemperature("C") after the solve and compare with the target; on an older build bisect the efficiency between 0.3 and 0.95 yourself (outlet T usually falls as efficiency rises, but it can chatter across a phase boundary). Report the result as an effective efficiency (it lumps anti-surge recycle heating and composition error) and re-fit it after any change of gas composition or calibration factor |
Reporting Pattern for results.json
Add a calibration block to the task results.json:
{
"calibration": {
"calibrated_parameters": [
{
"name": "Main Compressor.polytropicEfficiency",
"unit": "",
"value": 0.781,
"lower_bound": 0.60,
"upper_bound": 0.90
},
{
"name": "Main Cooler.UA_multiplier",
"unit": "",
"value": 1.12,
"lower_bound": 0.60,
"upper_bound": 1.40
}
],
"fit_metrics": {
"train_rmse": {
"compressor_outlet_pressure_bara": 0.84,
"compressor_outlet_temperature_C": 1.6,
"cooler_outlet_temperature_C": 0.9
},
"train_mape_pct": 1.8,
"train_bias": {
"compressor_outlet_pressure_bara": -0.22,
"compressor_outlet_temperature_C": 0.35,
"cooler_outlet_temperature_C": -0.10
}
},
"validation_metrics": {
"validation_mape_pct": 2.4,
"max_abs_error": {
"compressor_outlet_pressure_bara": 1.7,
"compressor_outlet_temperature_C": 3.1,
"cooler_outlet_temperature_C": 1.8
}
},
"recommended_model_updates": [
"Update base compressor efficiency from 0.75 to 0.78 for this operating period.",
"Retain UA multiplier 1.12 and re-check after next exchanger cleaning campaign."
],
"calibration_risks": [
"Tag TT-402 intermittently flagged suspect quality during two windows.",
"Calibration is validated for 70-90% throughput; extrapolation outside this range is not qualified."
]
}
}
Validation Checklist
References
- ISO 5725 (accuracy and trueness concepts for measurement quality).
- IEC 61511 / ISA-95 practices for validated operational data usage.
- Internal NeqSim patterns in
neqsim-plant-data and neqsim-troubleshooting.
1---2name: neqsim-model-calibration-and-data-reconciliation3description: "Model calibration and data reconciliation workflow for NeqSim digital twins. USE WHEN: reducing model-vs-plant mismatch, tuning process model parameters from historian data, reconciling noisy measurements, or building validation reports for calibrated simulations. Covers tag mapping, data quality gates, steady-state window selection, bounded optimization, residual diagnostics, and results.json reporting."4last_verified: "2026-04-19"5metadata:6 source: https://skillmd.com/skills/equinor/neqsim-model-calibration-and-data-reconciliation7---89# Model Calibration and Data Reconciliation1011A practical workflow for calibrating NeqSim models against plant historian data12and producing auditable validation output.1314## When to Use This Skill1516- When simulated values do not match measured plant data.17- When building digital twin loops for separators, compressors, or heat exchangers.18- When you need reproducible parameter tuning with physical bounds.19- When a study requires train/validation split and objective fit metrics.2021## Scope and Non-Goals2223This skill focuses on steady-state calibration and data reconciliation.2425This skill does not replace dynamic controller tuning. For transient tuning,26load `neqsim-dynamic-simulation` in addition.2728## Required Companion Skills2930- `neqsim-plant-data`: historian read patterns (PI/IP.21), tag maps, quality flags.31- `neqsim-input-validation`: parameter bounds and physically realistic inputs.32- `neqsim-troubleshooting`: convergence recovery when each case is re-simulated.3334## Calibration Workflow35361. Define objective and acceptance criteria.372. Build a trusted tag map from plant tags to model variables.383. Read, clean, and quality-filter plant data.394. Detect steady-state windows for fitting.405. Choose tunable model parameters with hard physical bounds.416. Run bounded optimization and re-simulate the full NeqSim process each iteration.427. Validate on holdout windows and publish fit diagnostics.4344For the replay and validation steps use `neqsim.process.operations.replay.ProcessReplay`:45it runs a tag-bound time series through the calibrated model with a convergence gate,46records failed rows without aborting, and gives per-window bias/RMS, baseline-standardised47residuals and CUSUM change points (`ReplayResult.setBaselineWindow`, `detectChangePoints`),48exportable as CSV/JSON. See `docs/process/process_replay.md`.4950## Typical Tunable Parameters5152| Equipment | Parameters to Tune | Keep Fixed Unless Needed |53|-----------|--------------------|--------------------------|54| Compressor | Polytropic efficiency, pressure ratio correction, anti-surge margin | Driver type, map family |55| Heat exchanger | UA correction factor, fouling factor | Duty sign convention, stream topology |56| Separator | Entrainment assumptions, liquid carry-over tuning factors | Phase model and EOS |57| Valve/choke | Cv multiplier, discharge coefficient | Control architecture |58| Pipeline | Roughness, overall heat transfer coefficient | Length and diameter |5960## Data Reconciliation Quality Gates6162Apply these gates before calibration:6364- Unit harmonization complete (temperature, pressure, flow basis).65- At least 3 independent steady-state windows.66- Bad-quality tags removed or masked.67- Outlier handling documented.68- Sensor drift flags noted in notes and results.6970## Python Pattern: Bounded Calibration Loop7172```python73import numpy as np74from scipy.optimize import least_squares7576# Example: tune compressor efficiency and HX UA multiplier77# x[0] -> compressor efficiency, x[1] -> UA multiplier78LOWER = np.array([0.60, 0.60])79UPPER = np.array([0.90, 1.40])80X0 = np.array([0.75, 1.00])8182# Weights for [discharge pressure, discharge temperature, outlet temperature]83W = np.array([1.0, 1.0, 0.8])8485def run_model_and_extract_outputs(process, x):86 # Example parameter writes using automation addresses87 auto = process.getAutomation()88 auto.setVariableValue("Main Compressor.polytropicEfficiency", float(x[0]), "")89 auto.setVariableValue("Main Cooler.UA_multiplier", float(x[1]), "")9091 process.run()9293 p_out = auto.getVariableValue("Main Compressor.outStream.pressure", "bara")94 t_out = auto.getVariableValue("Main Compressor.outStream.temperature", "C")95 t_cool = auto.getVariableValue("Main Cooler.outStream.temperature", "C")96 return np.array([p_out, t_out, t_cool])979899def residuals(x, process, y_target):100 y_model = run_model_and_extract_outputs(process, x)101 return W * (y_model - y_target)102103104# y_target should come from a selected steady-state time window average105res = least_squares(106 fun=residuals,107 x0=X0,108 bounds=(LOWER, UPPER),109 args=(process, y_target),110 method="trf",111 max_nfev=150,112)113114x_opt = res.x115print("Optimized parameters:", x_opt)116print("Cost:", res.cost)117```118119## Objective Design Guidance120121Use a weighted residual vector with consistent scaling.122123A common objective is:124125$$126J(\theta) = \sum_{i=1}^{N} w_i\left(\frac{y_i^{model}(\theta) - y_i^{meas}}{s_i}\right)^2127$$128129Where:130131- $\theta$ is the vector of tunable parameters.132- $w_i$ is the business/engineering importance weight.133- $s_i$ is a scaling term (for example nominal value or sensor sigma).134135## Train/Validation Split Pattern1361371. Train on at least two steady windows from different operating regions.1382. Validate on one holdout window not used in fitting.1393. Report both train and validation metrics.140141Recommended minimum metrics:142143- RMSE for each calibrated output tag.144- MAPE where denominator is safe and meaningful.145- Mean signed error (bias).146- Max absolute error.147148## Common Failure Modes and Fixes149150| Failure Mode | Likely Cause | Corrective Action |151|--------------|--------------|-------------------|152| Excellent train fit, poor validation | Overfit on narrow operating range | Add windows across wider throughput and pressure range |153| Non-physical fitted parameters | Missing bounds | Enforce hard bounds and pre-check with input validation |154| Optimization stalls | Flat objective or too many coupled variables | Reduce parameter count, stage the tuning in phases |155| Noisy residuals | Sensor spikes and transient periods | Increase filtering and steady-state screening |156| Unstable run during optimization | Recycle sensitivity | Start from converged base case and use troubleshooting recovery patterns |157| Compressor discharge T low even at a plausible efficiency | Heavy model gas, anti-surge recycle, or a truly low effective efficiency | Diagnose in order, each with a measurement: (1) gas mole weight / composition, (2) anti-surge valve opening, (3) independent motor or shaft power. If 1 and 2 are clean, fit an *effective* efficiency to T (`compressor.setOutTemperature(T)` then `compressor.solveEfficiency(T)`, or the log-ratio update `eta*ln(T2m/T1)/ln(T2p/T1)` between runs) and check it against the power that was not fitted (Johan Sverdrup stage 3/4: 0.35-0.42 fitted, power within -13 to -27 %). Never widen the efficiency bound before 1-3 |158| Separator gas flow meters disagree with the gas balance by a constant factor on every train | Meter basis (actual vs standard m3/h) or gas allocation | Treat as a data question; calibrate gas to the metered platform gas, do not tune GOR to the meter, and report the meter gap |159| `Compressor.solveEfficiency(T)` returns an efficiency of 1.0 (or the lower limit) and the outlet is not at T | Older NeqSim builds: the unguarded secant step overshoots when the target needs an efficiency far from the start (e.g. wet gas at 134 C from 0.75 start, true value ~0.36). Fixed with a bracketed (safeguarded) secant in `Compressor.solveEfficiency`, test `CompressorSolveEfficiencyTest`. A phase-boundary jump can stall one initial guess about 0.1 K off the target; the solve then uses a local secant and interior restarts, still at the 0.01 K tolerance | Always read back `compressor.getOutletStream().getTemperature("C")` after the solve and compare with the target; on an older build bisect the efficiency between 0.3 and 0.95 yourself (outlet T usually falls as efficiency rises, but it can chatter across a phase boundary). Report the result as an *effective* efficiency (it lumps anti-surge recycle heating and composition error) and re-fit it after any change of gas composition or calibration factor |160161## Reporting Pattern for results.json162163Add a calibration block to the task `results.json`:164165```json166{167 "calibration": {168 "calibrated_parameters": [169 {170 "name": "Main Compressor.polytropicEfficiency",171 "unit": "",172 "value": 0.781,173 "lower_bound": 0.60,174 "upper_bound": 0.90175 },176 {177 "name": "Main Cooler.UA_multiplier",178 "unit": "",179 "value": 1.12,180 "lower_bound": 0.60,181 "upper_bound": 1.40182 }183 ],184 "fit_metrics": {185 "train_rmse": {186 "compressor_outlet_pressure_bara": 0.84,187 "compressor_outlet_temperature_C": 1.6,188 "cooler_outlet_temperature_C": 0.9189 },190 "train_mape_pct": 1.8,191 "train_bias": {192 "compressor_outlet_pressure_bara": -0.22,193 "compressor_outlet_temperature_C": 0.35,194 "cooler_outlet_temperature_C": -0.10195 }196 },197 "validation_metrics": {198 "validation_mape_pct": 2.4,199 "max_abs_error": {200 "compressor_outlet_pressure_bara": 1.7,201 "compressor_outlet_temperature_C": 3.1,202 "cooler_outlet_temperature_C": 1.8203 }204 },205 "recommended_model_updates": [206 "Update base compressor efficiency from 0.75 to 0.78 for this operating period.",207 "Retain UA multiplier 1.12 and re-check after next exchanger cleaning campaign."208 ],209 "calibration_risks": [210 "Tag TT-402 intermittently flagged suspect quality during two windows.",211 "Calibration is validated for 70-90% throughput; extrapolation outside this range is not qualified."212 ]213 }214}215```216217## Validation Checklist218219- [ ] Parameter bounds are physically meaningful and documented.220- [ ] Calibration windows and validation windows are explicitly listed.221- [ ] Fit metrics are reported for both train and validation sets.222- [ ] Any excluded tags/windows have a documented reason.223- [ ] Final recommendations include applicability range and limitations.224225## References226227- ISO 5725 (accuracy and trueness concepts for measurement quality).228- IEC 61511 / ISA-95 practices for validated operational data usage.229- Internal NeqSim patterns in `neqsim-plant-data` and `neqsim-troubleshooting`.