Functional Inconsistency Index (FII) surrogate-evaluation workflow: code and synthetic demonstration dataset

Abstract

This software implements a controlled, post-hoc workflow for evaluating both the predictive accuracy and the functional behaviour of two-input machine-learning surrogate models. It starts from a normalised analytical table and provides strict input validation, deterministic model fitting, held-out and reconstruction metrics, common-grid response-surface construction, behavioural diagnostics, a deterministic fictional demonstration, automated tests, and release-boundary checks. The archived analytical specification contains five regression families—SVR, decision tree, random forest, extreme gradient boosting, and k-nearest neighbours—and 25 fixed candidate configurations, together with a separate repeated-partition auxiliary analysis. Functional behaviour is summarised using two-directional monotonicity violation rate, normalised roughness, output-range violation, and the Functional Inconsistency Index (FII). FII is a relative, heuristic, and context-dependent post-hoc diagnostic. It is not a measure of physical validity, predictive uncertainty, causal behaviour, or downstream numerical stability. Its values are comparable only when predictor definitions, units, ranges, grid, component definitions, weights, and roughness reference are held constant. The public input contract uses explicit unit-bearing fields: `observation_id`, `material_id`, `lithology`, `water_content_pct`, `bulk_density_mg_m3`, and `thermal_conductivity_w_mk`. Optional dry- and particle-density fields are accepted for consistency checks. The canonical workflow does not silently rename columns, convert units, impute values, or discard malformed records. Frozen analysis settings, candidate definitions, random seed, response grid, reference value, and diagnostic weights are retained in the configuration files. Restricted laboratory observations and source-specific extraction and harmonisation procedures are not distributed. Consequently, exact dataset-specific metrics, model rankings, response surfaces, and FII values cannot be regenerated from the fictional synthetic example alone. The package provides implementation-level reproducibility and transparent configuration; exact retraining of the archived analysis requires authorised access to the restricted canonical dataset. The methodology was applied in the related article *Separating Predictive Accuracy from Functional Behaviour in Machine-Learning Surrogate Models for Geoengineering Applications*, Scientific Reports, https://doi.org/10.1038/s41598-026-65202-3. The software is independently versioned and citable; the article is not required to install, run, or reuse the package.