Lithology-specific thermal-conductivity response surfaces and RSCI diagnostics

Abstract

This software release provides the computational workflow developed for lithology-specific reconstruction and evaluation of thermal-conductivity response surfaces in mineral soils. Thermal conductivity is represented as a function of gravimetric water content on a dry-mass basis and measured wet bulk density. These variables are treated as mathematically coupled but nonredundant descriptors of achieved material state. Four lithological groups are analysed separately: sand, silt, clayey soil, and clay. The software implements Support Vector Regression, Generalised Additive Models, Random Forests, and Extreme Gradient Boosting, together with the controlled BASE, SMOOTH, INTERMEDIATE, and TUNED candidate configurations. Measurements mapped to the same material state are aggregated to a single state-level target. Predictive reliability is evaluated using five-fold cross-validation grouped by parent-material group. For TUNED candidates, hyperparameters are selected exclusively within each outer-training subset using three-fold grouped inner cross-validation with RMSE as the optimisation criterion. All fit-dependent preprocessing is restricted to the applicable training folds. After grouped predictive validation, the candidate models are refitted to all available material states of the corresponding lithology for response-surface reconstruction. These full-data fits are used only for surface geometry, model-agreement diagnostics, and response-profile extraction; their predictions do not enter the grouped predictive metrics. Surface interpretation is restricted to the lithology-specific convex hull of the observed material-state domain. Response profiles are extracted as mathematical cross-sections of the fitted surfaces at state-level quartiles. A central component of the release is the Response-Surface Consistency Index (RSCI), a post-hoc, within-lithology relative diagnostic of response-surface geometry. It combines boundedness, smoothness, local extrema, gradient variation, and gradient-sign fragmentation. RSCI complements grouped predictive metrics—R², RMSE, MAE, and MBE—but is not a physical-validity score, an uncertainty measure, or a tuning objective. Its derivative-based components are defined under the adopted physical-coordinate convention and should be interpreted together with predictive performance, observational support, cross-family agreement, and geological–geotechnical reasoning. The archive includes deterministic synthetic demonstration data, input-schema documentation, automated tests, model and tuning configurations, aggregate reference outputs, selected response grids, response-profile data, and frozen publication figures. The final aggregate checkpoints correspond to 2,242 source observations, 703 unique material states, and 235 parent-material groups. Restricted record-level experimental and harmonised datasets, institutional identifiers, parent-material mappings, fold assignments, record-level group-withheld predictions, detailed inner-fold records, and manuscript-trained estimators are not distributed. The archive therefore supports inspection, testing, and execution of the documented workflow on schema-compliant data, but not exact retraining of the reported models without authorised access to the original analysis dataset. Version: 1.1.0Software author: Mateusz ŻeruńCopyright holder: Polish Geological Institute – National Research Institute (PGI-NRI)Licence: MIT