---

Corrai: A Framework for Modeling, Sampling, Optimization and Surrogates

Corrai is a Python library for scientific exploration of complex systems.
It provides a unified framework for model definition, parameterization, sampling, optimization, sensitivity analysis, and surrogate modeling.

While originally motivated by building energy research, Corrai is domain-independent and can be applied to any problem requiring model calibration, uncertainty quantification, or reduced-order modeling.

---

Main Features

• Sampling methods

  • Generate experimental designs using built-in samplers: Sobol, Latin Hypercube, FAST, Morris, random, or custom samplers (Sample and Sampler).
  • Easily connect samples with model parameters to prepare sensitivity or optimization studies.

• Sensitivity & uncertainty analysis

  • Built-in analyzers for variance-based (Sobol), screening (Morris), and FAST methods (sensitivity.py).(SAlib).
  • Quantify the influence of each parameter on model outputs.

• Optimization and calibration

  • Single and multi-objective parameter identification and model calibration (optimize.py).
  • Integrated with evolutionary and gradient-based optimizers (pymoo).

• Surrogate modeling

  • Train ML-based surrogates (linear, polynomial, SVR, random forest, MLP, …).
  • Grid-search hyperparameter tuning (sklearn).
  • Evaluate accuracy with statistical metrics (nmbe, cv_rmse).

• Visualization support

  • Plotting utilities to inspect results, sensitivity indices, surrogate accuracy, etc.

• Model abstraction

  • Define analytical, external simulator, numerical, or FMU-driven models (classes Model and ModelicaFmuModel).
  • Associate parameters with model properties such as domain, initial values, continuity (class Parameter)

---

Getting started

Installation

Corrai requires Python 3.10 or above. The recommended way to install corrai is via pip:

pip install corrai

This will install python-tide and all its dependencies.

Quick example

    import pandas as pd

from corrai.base.parameter import Parameter
from corrai.sensitivity import SobolSanalysis, MorrisSanalysis
from corrai.base.model import IshigamiDynamic

SIMULATION_OPTIONS = {
    "start": "2009-01-01 00:00:00",
    "end": "2009-01-01 05:00:00",
    "timestep": "h",
}

PARAMETER_LIST = [
    Parameter("par_x1", (-3.14159265359, 3.14159265359), model_property="x1"),
    Parameter("par_x2", (-3.14159265359, 3.14159265359), model_property="x2"),
    Parameter("par_x3", (-3.14159265359, 3.14159265359), model_property="x3"),
]

# Configure a Sobol sensitivity analysis
sobol = SobolSanalysis(
    parameters=PARAMETER_LIST,
    model=IshigamiDynamic(),
    simulation_options=SIMULATION_OPTIONS,
)

# Draw sample, and run simulations
sobol.add_sample(15 ** 2, simulate=True, n_cpu=1, calc_second_order=True)

# Corrai works for models that returns time series
# Ishigami model here will return the same value for the given parameters
# from START to END at 1h timestep
sobol.analyze('res', method="mean")["mean_res"]

# Default aggregation method is mean value of the timeseries
sobol.plot_bar('res')

# Display 2nd order matrix for parameters interaction
sobol.plot_s2_matrix('res')

# Display mean output values of the sample as hist
sobol.sampler.sample.plot_hist('res')

# Compute dynamic sensitivity analisys at plot
# Obviously, in this example indexes value do not vary
sobol.plot_dynamic_metric('res', sensitivity_metric="ST", freq="h")

Sponsors

The development of this library has been supported by METABUILDING LABS Project, which has received funding from the European Union’s Horizon 2020 Research and Innovation Programme under Grant Agreement No. 953193. The sole responsibility for the content of this library lies entirely with the author’s view. The European Commission is not responsible for any use that may be made of the information it contains.