Quickstart¶

This example calibrates Hypo-ISA against monotonic and cyclic tests. Adapt the workbook path, parameter values and test selection to your data.

Complete driver script¶

Save this as run_calibration.py in the repository root:

from pathlib import Path

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


def run_calibration():
    database_path = Path("database-kfs-monotonic-cyclic.xlsx").resolve()
    workdir = Path("calibration").resolve()
    workdir.mkdir(parents=True, exist_ok=True)

    database = excel()
    database.collect(str(database_path))

    model = hypoplasticity_isa(
        out_dir=str(workdir / "results"),
        out_dir2=str(workdir / "temporary"),
        out_dir3=str(workdir / "final"),
    )
    model.set(
        phic=30.0,
        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,
    )
    model.set_bounds(
        hs=[1.0, 10.0],
        n=[0.20, 0.40],
        ed=[0.50, 0.75],
        ec=[0.90, 1.20],
    )

    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=str(workdir),
        Experimental_database=database_path,
    )

    DEEM.optimize(maxiter=200, n_cpu=8)


if __name__ == "__main__":
    run_calibration()

The if __name__ == "__main__": guard is required whenever an optimiser uses n_cpu > 1. IPOP-CMA-ES, SMAC-style search and local search use spawned workers on every platform. DEEM uses the platform default, including spawn on Windows. Use the guard for every calibration driver, including drivers that currently run with n_cpu=1, so a later CPU count or operating system change remains safe. Keep model construction, globals.setup(...) and the optimiser call inside the guarded function, as above. A spawned import must not repeat model setup or prepare the same output directories.

The script resolves one workdir before constructing the model and puts the temporary, final and report directories below it. This prevents outputs from being split between the caller's current directory and the path registered by globals.setup(...).

What each stage does¶

1. Read the database¶

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

collect() populates the reader instance and returns None. The parsed lists are available as follows:

Do not write database = excel().collect(...), because that assigns None to database.

2. Configure the model¶

set(...) assigns the starting parameter set. Parameters not listed in Free_parameter remain fixed. set_bounds(...) optionally narrows the search interval of parameters supported by that model. The model pages document units, defaults, dependencies and model-specific interface differences.

3. Register the calibration¶

globals.setup(...) is the source of truth for the tests, weights, timeouts and similarity measure. The five supported values of Similarity are documented on the objective-function page.

Only lists passed to setup contribute to the objective. This makes it safe to keep more tests in the workbook than are used by a particular calibration.

4. Run an optimiser¶

The example uses DEEM:

DEEM.optimize(maxiter=200, n_cpu=8)

For expensive calibrations, the included SMAC-style search normally needs fewer real evaluations:

from ACT import SMAC

SMAC.optimize(max_evaluations=240, n_cpu=8, random_state=0)

For a rugged continuous problem, use CMA-ES. It only uses the ranking of the candidates, so failed simulations do not distort the search:

from ACT import CMAES

CMAES.optimize(max_evaluations=600, n_cpu=8, population_size=16, random_state=0)

For refinement near a credible parameter set, use the deterministic local pattern search:

from ACT import local

local.optimize(max_evaluations=100, n_cpu=8, initial_step=0.2)

DEEM's maxiter counts generations, whereas the other three backends expose an explicit max_evaluations budget. Compare their costs on the optimisation page before interpreting run time.

Run a simulation-only check¶

Before a long optimisation, replace the optimiser call temporarily with:

DEEM.optimize(method="no_optimization")

This evaluates every selected test once with the initial parameters and writes the comparison output without searching. Check that:

• every intended test appears;
• numgeo completes without timeouts;
• units, signs and initial states are credible;
• the simulated and experimental axes cover comparable ranges.

Then restore the selected optimiser call and start the calibration. See Output and reporting for the generated files and Troubleshooting for common failures.