Overview¶

simml is a lightweight surrogate modeling framework built on top of scikit-learn.

It is designed for engineering studies, numerical simulations, parametric sweeps, and batch computation workflows where large simulation datasets are generated and later approximated with fast predictive models.

The library focuses on:

• simple dataset-driven workflows
• reproducible surrogate training
• automated model evaluation
• sklearn compatibility
• lightweight deployment through joblib

Core Idea¶

A simulation workflow generates a CSV dataset:

input parameters  →  simulation  →  output quantities

simml then trains surrogate models that learn:

f(inputs) → outputs

allowing predictions to be evaluated in milliseconds instead of rerunning expensive simulations.

Typical Workflow¶

Batch simulations
        ↓
CSV dataset generation
        ↓
Train surrogate models
        ↓
Cross-validation & model selection
        ↓
Save trained pipelines
        ↓
Fast inference / optimization / exploration

Dataset Structure¶

simml operates directly on CSV datasets.

A dataset contains:

• feature columns (inputs)
• target columns (outputs)

Example:

Where:

• length, width, angle are features
• lift, drag are prediction targets

Available Training Modes¶

Single-Output Training¶

Implemented with:

SurrogateTrainer

A separate pipeline is trained for each target variable.

For:

• 3 targets
• 3 model types

the trainer produces:

9 independent models

Advantages¶

• independent optimization per target
• simpler debugging
• robust behavior
• easier interpretation

Typical Use Cases¶

• unrelated target variables
• small datasets
• highly heterogeneous outputs

Multi-Output Training¶

Implemented with:

MultiOutputSurrogateTrainer

A single pipeline predicts all targets simultaneously.

For:

• 3 targets
• 3 model types

the trainer produces:

3 multi-output models

Advantages¶

• captures correlations between targets
• fewer saved models
• cleaner deployment
• potentially better global consistency

Typical Use Cases¶

• correlated physical quantities
• coupled simulation outputs
• reduced deployment complexity

Supported Models¶

Linear Regression¶

Fast and interpretable baseline model.

Best suited for:

• approximately linear systems
• low-noise datasets
• quick benchmarking

Gaussian Process Regression¶

Probabilistic non-linear regression model.

Best suited for:

• smooth physical systems
• small to medium datasets
• high-accuracy interpolation

Characteristics:

• excellent predictive quality
• expensive on large datasets
• naturally smooth predictions

Neural Network (MLP)¶

Multi-layer perceptron regressor using sklearn.

Best suited for:

• larger datasets
• strongly non-linear systems
• high-dimensional inputs

Characteristics:

• flexible
• scalable
• sensitive to hyperparameters

Validation Strategy¶

simml automatically evaluates models using cross-validation.

K-Fold Cross Validation¶

Used to estimate generalization performance.

Metrics include:

• R²
• MAE
• RMSE

Leave-One-Out Cross Validation (LOOCV)¶

Used to compute predictive robustness metrics.

Metrics include:

• Q²
• PRESS
• LOOCV RMSE

This is particularly useful in engineering surrogate modeling workflows.

Saved Models¶

All trained models are saved as sklearn pipelines using joblib.

Each pipeline contains:

StandardScaler
        +
trained estimator

This guarantees identical preprocessing during inference.

sklearn Compatibility¶

simml is intentionally built around sklearn primitives:

• Pipeline
• StandardScaler
• LinearRegression
• GaussianProcessRegressor
• MLPRegressor

This makes the framework:

• easy to extend
• easy to debug
• interoperable with sklearn tooling

Design Philosophy¶

simml intentionally avoids:

• proprietary binary formats
• hidden preprocessing
• complex training orchestration
• framework lock-in

Instead, it favors:

• explicit configuration
• plain CSV datasets
• sklearn-native pipelines
• reproducible workflows

What simml does Not Do¶

simml does not:

• generate simulation datasets
• manage simulation campaigns
• orchestrate HPC workloads
• perform Bayesian optimization
• provide deep learning frameworks

Its role begins once a dataset already exists.

Intended Use Cases¶

Typical applications include:

• CFD surrogate models
• FEM approximation
• parametric engineering studies
• design space exploration
• optimization acceleration
• uncertainty studies
• reduced-order modeling
• fast digital twins

Minimal Training Example¶

See:

minimal_example.md

for a runnable example using both:

• SurrogateTrainer
• MultiOutputSurrogateTrainer