The calibration workflow¶

This page explains each stage of a numgeo-ACT calibration and documents the two central entry points — globals.setup(...) and DEEM.optimize(...) — in full.

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[DEEM.optimize<br/>run the optimizer]
    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.
Optimize. DEEM.optimize(...) runs the global optimizer, evaluating candidate parameter sets by simulating every test with numgeo and scoring the fit, until it converges.

`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=[],
    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.
`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`	reader instance	`None`	The `excel` reader holding the parsed data.

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
HCA (drained/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",
    similarity="frechet",
    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`	`'frechet'`	Similarity measure (see Objective function).
`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.

Alternative optimizers¶

DEEM is the default and recommended optimizer. numgeo-ACT also provides other back-ends for experimentation:

mealpy — a large collection of metaheuristic optimizers (ACT.utilities.mealpy).
scipy — gradient-free and gradient-based optimizers from SciPy (ACT.utilities.scipy).
Bayesian optimization — a surrogate-model-based interface (ACT.bayesian).

For the rationale behind DEEM and how the objective function is constructed, see Optimization.