Skip to content

Quickstart

This page walks through a complete calibration from start to finish. The example calibrates the Hypo-ISA model against a database of monotonic and cyclic tests on Karlsruhe fine sand — the same model and material shown in the animation on the home page.

Before you start

Make sure the numgeo executable is on your PATH and the Python dependencies are installed (see Installation). You also need an Excel database formatted for the reader — download and adapt the template, or use your own workbook.

The full script

from ACT.utilities.excel import excel
from ACT import globals, DEEM
from ACT.models import hypoplasticity_isa

# ---------------------------------------------------------------------------
# 1) Read the experimental database
#    collect() populates the reader instance in place (it returns None).
# ---------------------------------------------------------------------------
database = excel()
database.collect("database-kfs-monotonic-cyclic.xlsx")

# ---------------------------------------------------------------------------
# 2) Instantiate the model and provide a full set of initial parameters.
#    Parameters not listed as "free" later are held fixed at these values;
#    the free ones use these as a starting point.
#    (The values below are illustrative starting values, not final results.)
# ---------------------------------------------------------------------------
model = hypoplasticity_isa()
model.set(
    phic=0.5236, fei=1.10, ec=1.054, ed=0.677, hs=4.0, n=0.27,
    alpha=0.14, beta=2.5, R=1.4e-4, mR=5.0, beta_h0=0.3,
    beta_hmax=2.0, chi0=5.0, chi_max=20.0, eps_acc=0.02, cz=600.0,
)

# ---------------------------------------------------------------------------
# 3) Optionally narrow the search bounds of the free parameters.
#    Each bound is given as [lower, upper]. Parameters you do not pass keep
#    the model's built-in default bounds.
# ---------------------------------------------------------------------------
model.set_bounds(
    hs=[1.0, 10.0],
    n=[0.20, 0.40],
    ed=[0.50, 0.75],
    ec=[0.90, 1.20],
)

# ---------------------------------------------------------------------------
# 4) Describe the calibration problem: which model, which parameters are free,
#    and which tests to honour.
# ---------------------------------------------------------------------------
globals.setup(
    Model=model,
    Free_parameter=["hs", "n", "ed", "ec", "alpha", "beta"],
    oedometer=database.oedometer,
    triaxCD=database.triax_CD,
    triaxCU=database.triax_CU,
    triaxCUcyc=database.triax_CUcyc,
    Similarity="frechet",
    path="./calibration/",
    Experimental_database=database,
)

# ---------------------------------------------------------------------------
# 5) Run the optimization. Results, plots and a PDF report are written to the
#    output directories.
# ---------------------------------------------------------------------------
DEEM.optimize(maxiter=200, n_cpu=8, similarity="frechet")

Step by step

1. Read the database

database = excel()
database.collect("database-kfs-monotonic-cyclic.xlsx")

excel().collect(...) parses the workbook and fills the reader instance with one list per test type — database.oedometer, database.triax_CD, database.triax_CU, database.triax_CUcyc, database.triax_CDcyc_HCA, database.triax_CUcyc_HCA, database.isotropic_compression_test and database.USScyc. Each entry is one test, with its initial void ratio, boundary conditions and measured curves already extracted.

Tip

collect() modifies the instance and returns None, so call it on a variable — do not write database = excel().collect(...).

See Experimental data for exactly how each sheet must be laid out.

2. Choose the model and set parameters

model = hypoplasticity_isa()
model.set(phic=0.5236, ..., cz=600.0)

Every model is a class in ACT.models. Instantiating it gives default parameter values and default search bounds. set(...) assigns a full set of parameter values; these act as the starting point for the optimization and as fixed values for any parameter you do not mark as free.

The available models, their parameters, defaults, bounds and the exact arguments of set/set_bounds are documented under Constitutive models.

3. Set the search bounds

model.set_bounds(hs=[1.0, 10.0], n=[0.20, 0.40], ...)

set_bounds(...) overrides the lower/upper search interval for individual parameters. Each value is a two-element list [lower, upper]. Parameters you omit keep their built-in defaults, so you only need to pass the ones you want to change.

4. Describe the problem with setup

globals.setup(Model=model, Free_parameter=[...], oedometer=..., ...)

globals.setup(...) registers the calibration problem. Its most important arguments are:

Argument Meaning
Model the model instance to calibrate
Free_parameter list of parameter names to optimize
oedometer, triaxCD, triaxCU, triaxCUcyc, triaxCDcycHCA, triaxCUcycHCA, USScyc, iso_comp the test lists to honour (from the database)
Similarity similarity measure (default 'frechet')
Weights optional per-test weighting (see Weighting)
path working directory for the calibration
Experimental_database the reader instance

The full argument list is documented under The calibration workflow. setup raises an error if the model, the free parameters or the path are missing, or if no tests are supplied.

5. Run the optimizer

DEEM.optimize(maxiter=200, n_cpu=8, similarity="frechet")

DEEM.optimize(...) runs the DEEM global optimizer. Use n_cpu to parallelize the simulations across CPU cores and maxiter to cap the number of iterations. When it finishes, the optimized parameters, comparison plots and a PDF report are written to the output directories — see Output & reporting.

Dry run without optimizing

To simulate the tests once with the initial parameters (no optimization), call DEEM.optimize(method="no_optimization"). This is a fast way to check that your database and parameters produce sensible simulations before launching a full calibration.