The calibration workflow¶

This workflow shows each stage of a numgeo-ACT calibration, explains globals.setup(...) and shows how to launch each supported optimiser.

Overview¶

flowchart TD
    A[Prepare Excel database] --> B[excel.collect]
    B --> C[Instantiate model<br/>set parameters and bounds]
    C --> D[globals.setup<br/>register the problem]
    D --> E[Choose an optimiser<br/>run the calibration]
    E --> F[Optimized parameters<br/>report, logs, plots]

A calibration always follows the same four stages:

Provide the data. The experimental database is read from an Excel workbook with excel().collect(...). See Experimental data.
Define the model. Instantiate one of the supported constitutive models, give it initial parameter values with set(...), and optionally narrow the search intervals with set_bounds(...).
Register the problem. globals.setup(...) ties everything together: the model, the free parameters, the tests to honour, the similarity measure and the weighting.
Optimise. Run DEEM, IPOP-CMA-ES, SMAC-style Bayesian optimisation or local pattern search. Each backend evaluates candidate parameter sets by simulating every selected test with numgeo and scoring the fit.

`globals.setup`¶

setup registers the calibration problem. It validates the inputs and raises an error if the model, the free parameters or the working path are missing, or if no test lists are provided.

from ACT import globals

globals.setup(
    Model=None,
    Free_parameter=[],
    oedometer=[],
    triaxCD=[],
    triaxCU=[],
    triaxCUcyc=[],
    triaxCDcycHCA=[],
    triaxCUcycHCA=[],
    USScyc=[],
    DSS=[],
    iso_comp=[],
    Similarity="frechet",
    Weights=None,
    path=None,
    Timeout=None,
    Experimental_database=None,
)

Argument	Type	Default	Description
`Model`	model instance	`None`	The constitutive model to calibrate. Required.
`Free_parameter`	list of str	`[]`	Names of the parameters to optimize. Required (at least one).
`oedometer`	list	`[]`	Oedometric compression tests (from the database).
`triaxCD`	list	`[]`	Drained monotonic triaxial tests.
`triaxCU`	list	`[]`	Undrained monotonic triaxial tests.
`triaxCUcyc`	list	`[]`	Undrained cyclic triaxial tests.
`triaxCDcycHCA`	list	`[]`	Drained cyclic triaxial tests for the HCA model.
`triaxCUcycHCA`	list	`[]`	Undrained cyclic triaxial tests for the HCA model.
`USScyc`	list	`[]`	Undrained cyclic simple shear tests.
`DSS`	list	`[]`	Drained monotonic direct simple shear tests.
`iso_comp`	list	`[]`	Isotropic compression tests.
`Similarity`	str	`'frechet'`	Similarity measure used to score the fit (see Objective function).
`Weights`	dict	`None`	Per-test / per-quantity weighting; defaults are used if `None` (see Weighting).
`path`	str	`None`	Working directory for the calibration. Required.
`Timeout`	dict	`None`	Per-test maximum simulation runtimes; sensible defaults are used if `None`.
`Experimental_database`	path-like or str	`None`	Workbook path/name recorded in the report; when omitted, ACT uses the source file stored on the first selected test where available.

At least one test list is required

setup raises an error if all of the test lists are empty. There must be something to calibrate against.

Timeouts¶

Each test type has a default maximum runtime so that a pathological parameter set cannot stall the optimizer indefinitely. The defaults (in seconds) are:

Test	Default timeout
Oedometer	10
Isotropic compression	10
Drained triaxial (CD)	15
Undrained triaxial (CU)	20
Undrained cyclic triaxial (per cycle)	3
Undrained cyclic triaxial (total)	1000
Cyclic simple shear (per cycle)	2
Cyclic simple shear (total)	1000
Drained direct simple shear (DSS)	20
HCA, drained or undrained (per cycle)	2
HCA (total)	600

You can override them by passing a Timeout dictionary in the same structure.

Strain-based early termination (undrained cyclic triaxial)

In addition to the time limits above, the undrained cyclic triaxial test has a strain-based early-termination criterion: the numgeo simulation stops automatically once the axial strain reaches ±20 %. This avoids spending time on the runaway, unphysical strains some models produce after liquefaction, which would not contribute to the calibration. See Undrained cyclic triaxial for details.

`DEEM.optimize`¶

optimize runs the optimization. By default it uses the DEEM algorithm.

from ACT import DEEM

DEEM.optimize(
    maxiter=200,
    n_cpu=1,
    nparticles_max=100,
    nparticles_min=100,
    npop_max=4,
    npop_min=4,
    exit_iter=100,
    tolerance=1e-4,
    sampling="LHS",
    method="DEEM",
    termination="tolerance",
)

Argument	Default	Description
`maxiter`	`200`	Maximum number of optimizer iterations (generations).
`n_cpu`	`1`	Number of CPU cores used to run simulations in parallel.
`nparticles_max`	`100`	Maximum population size (number of candidate parameter sets).
`nparticles_min`	`100`	Minimum population size.
`npop_max`	`4`	Maximum number of sub-populations (DEEM multi-population scheme).
`npop_min`	`4`	Minimum number of sub-populations.
`exit_iter`	`100`	Stop if no improvement is found within this many iterations.
`tolerance`	`1e-4`	Convergence tolerance on the objective function.
`sampling`	`'LHS'`	Initial sampling strategy (Latin Hypercube Sampling).
`similarity`	`None`	Legacy compatibility argument; omit it. If supplied, it must equal the value from `globals.setup(Similarity=...)`.
`method`	`'DEEM'`	Optimizer to use. `'no_optimization'` simulates the initial parameters once without optimizing.
`termination`	`'tolerance'`	Termination criterion.

Parallelization

The optimizer evaluates many candidate parameter sets per iteration, each requiring a set of numgeo simulations. Increasing n_cpu to match the number of available cores is the single most effective way to reduce wall-clock time.

Lightweight optimisers¶

Two dependency-light backends use the same registered calibration problem and reporting pipeline:

from ACT import SMAC, local

# Global search with a strict evaluation budget.
SMAC.optimize(max_evaluations=240, n_cpu=4, random_state=0)

# Deterministic local refinement from the current model parameters.
local.optimize(max_evaluations=100, n_cpu=4, initial_step=0.2)

Do not run both calls sequentially in one driver unless the first result is intended to become the starting point of the second. The optimisation guide documents algorithm choice, budgets, dependencies and every public argument.