User API¶

This page is the concise reference for the functions an end user calls to run a calibration: reading the database, choosing and configuring a model, describing the problem, and launching the optimizer. For a narrated walk-through see the calibration workflow; for the full per-model parameter bounds see Constitutive models.

A complete calibration uses four objects:

from ACT.utilities.excel import excel   # 1. read experimental data
from ACT.models import hypoplasticity_isa  # 2. pick a constitutive model
from ACT import globals, DEEM           # 3. configure  +  4. optimize

1 · Reading data — `excel`¶

from ACT.utilities.excel import excel

Reads an Excel database (one sheet per test) into Python. The reader works by cell position; the required layout is documented on the Excel sheet reference.

Constructor¶

excel()

Takes no arguments. Create one instance, then call collect on it.

`collect()`¶

collect(filename)

Reads filename and populates the reader instance in place (it mutates the object and returns None). After calling it, the parsed tests are available as list attributes:

Attribute	Test type (sheet)
`.oedometer`	oedometric compression (`OED-#`)
`.isotropic_compression_test`	isotropic compression (`IC-#`)
`.triax_CD`	drained triaxial (`CD-#`)
`.triax_CU`	undrained triaxial (`CU-#`)
`.triax_CUcyc`	undrained cyclic triaxial (`CUCYC-#`)
`.triax_CDcyc_HCA`	drained HCA triaxial (`CDCYC_HCA-#`)
`.triax_CUcyc_HCA`	undrained HCA triaxial (`CUCYC_HCA-#`)
`.USScyc`	undrained cyclic simple shear (`USScyc-#`)

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

print(len(database.triax_CD))   # how many drained triaxial tests were read

Call it on a variable

collect returns None and stores the data on the instance. Use db = excel(); db.collect(path) — not tests = excel().collect(path).

2 · Choosing a model¶

from ACT.models import hypoplasticity_isa   # or any other model class

Every model is a class with the same interface. Import the class, construct it, and (optionally) set initial values and search bounds. The full list of classes, their name strings, default parameters and default bounds is on the Constitutive models pages.

Constructor¶

Model(out_dir="./results/", out_dir2="./run_tmp/", out_dir3="./run_final/")

Argument	Default	Description
`out_dir`	`"./results/"`	final results, report and plots
`out_dir2`	`"./run_tmp/"`	temporary per-evaluation run files
`out_dir3`	`"./run_final/"`	files of the final (best) run

Configuring parameters¶

Method	Purpose
`set(<param>=<value>, ...)`	assign initial / fixed parameter values
`set_bounds(<param>=[lo, hi], ...)`	override the search interval of individual parameters
`update(parameter, value)`	set a single parameter by name
`get_parameter(parameter)`	read a single parameter by name

model = hypoplasticity_isa()                  # defaults + default bounds pre-set
model.set(hs=4.0e6, n=0.27, ed=0.55, ec=0.95) # initial / fixed values
model.set_bounds(n=[0.20, 0.35], ec=[0.85, 1.05])  # narrow some intervals
model.update("alpha", 0.12)
print(model.get_parameter("alpha"))

The per-model set / set_bounds argument names are exactly the model's parameters — see each model page.

Optional · Fitting critical-state-line parameters¶

The CSL helper is imported from the utilities package:

from ACT.utilities.csl import fit_csl

fit_csl(...) returns a dictionary. The fitted parameters are stored by name, not by position. For the Bauer CSL this means:

result = fit_csl(
    model='bauer',
    p=[25., 50., 100., 200., 400.],
    e=[0.91, 0.88, 0.85, 0.82, 0.79],
    result_dir=model.out_dir,
)

params = result['parameters']

ec0 = params['ec0']
hs  = params['hs']
n   = params['n']

print(result['r2'])

For oedometric compression data, do not pass the vertical stress as p. Pass it as vertical_stress or sigma_v, and provide K0 and void_ratio:

result = fit_csl(
    model='bauer',
    vertical_stress=[25., 50., 100., 200., 400.],
    K0=0.45,
    void_ratio=[0.91, 0.88, 0.85, 0.82, 0.79],
    result_dir=model.out_dir,
)

ACT then converts the data internally with \(p=\sigma_v(1+2K_0)/3\). If p and e are provided directly, K0 is ignored because ACT assumes that p is already the mean effective stress.

For ACT oedometer sheets with stress-strain data, pass the measured strain and initial void ratio. Several collected ACT oedometer tests can be passed with fit_csl_oedometer_tests(db.oedometer, ...); see the full utility page for the complete example. For a single test, pass arrays directly. For loading-unloading-reloading curves the default evaluation='auto' uses the virgin loading envelope:

result = fit_csl(
    model='bauer',
    vertical_stress=sigma_v,
    K0=K0,
    strain=eps_ax,
    e_initial=e0,
    evaluation='auto',
    result_dir=model.out_dir,
)

For Li-Wang CSL parameters, use:

result = fit_csl(model='li-wang', p=p_data, e=e_data, result_dir=model.out_dir)

params = result['parameters']
e0       = params['e0']
lambdac  = params['lambdac']
xi       = params['xi']

For the full utility reference, including Bolton-generated CSL points and update_model, see Utilities → CSL calibration.

3 · Describing the problem — `globals.setup`¶

from ACT import globals

setup registers the calibration problem: the model, which parameters are free, which tests to honour, and the objective settings.

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,
)

Model & parameters

Argument	Default	Description
`Model`	`None`	the constitutive-model instance to calibrate
`Free_parameter`	`[]`	list of parameter names to optimize; the rest stay fixed unless the selected model defines a dependency

Model-dependent parameters

Free_parameter can activate model-specific dependencies. For Hypo-IGS, if mR is listed but mT is not listed, ACT uses the dependent value mT = 0.7*mR during the numgeo back-calculations and in the generated reports. To optimize mT independently, include both mR and mT in Free_parameter.

Tests to honour — pass the matching reader attributes from step 1.

Argument	Reader attribute	Test
`oedometer`	`database.oedometer`	oedometric compression
`iso_comp`	`database.isotropic_compression_test`	isotropic compression
`triaxCD`	`database.triax_CD`	drained triaxial
`triaxCU`	`database.triax_CU`	undrained triaxial
`triaxCUcyc`	`database.triax_CUcyc`	undrained cyclic triaxial
`triaxCDcycHCA`	`database.triax_CDcyc_HCA`	drained HCA
`triaxCUcycHCA`	`database.triax_CUcyc_HCA`	undrained HCA
`USScyc`	`database.USScyc`	cyclic simple shear

Objective & run settings

Argument	Default	Description
`Similarity`	`'frechet'`	curve-distance measure (see objective function)
`Weights`	`None`	custom weight dictionary; `None` uses the defaults
`path`	`None`	working directory for the calibration
`Timeout`	`None`	per-test simulation timeouts (see timeouts)
`Experimental_database`	`None`	the reader instance, passed through for reporting

globals.setup(
    Model=model,
    Free_parameter=["hs", "n", "ed", "ec", "alpha", "beta"],
    oedometer=database.oedometer,
    triaxCD=database.triax_CD,
    triaxCU=database.triax_CU,
    path="./calibration/",
    Experimental_database=database,
)

4 · Running the optimizer — `DEEM.optimize`¶

from ACT import DEEM

Runs the global optimization defined by setup. Writes the outputs (PDF report, log, comparison plots) when finished.

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',
)

Budget & parallelism

Argument	Default	Description
`maxiter`	`200`	maximum number of iterations (generations)
`n_cpu`	`1`	parallel workers; set to the number of available cores

Population

Argument	Default	Description
`nparticles_max`	`100`	maximum population size
`nparticles_min`	`100`	minimum population size (set `< max` to shrink over time)
`npop_max`	`4`	maximum number of sub-populations
`npop_min`	`4`	minimum number of sub-populations

Termination & sampling

Argument	Default	Description
`termination`	`'tolerance'`	`'tolerance'` stops early on convergence; `'iterations'` runs the full `maxiter`
`tolerance`	`1e-4`	early-termination tolerance
`exit_iter`	`100`	iterations below the tolerance before stopping
`sampling`	`'LHS'`	initial sampling (Latin Hypercube by default)
`similarity`	`'frechet'`	similarity measure (kept consistent with `setup`)
`method`	`'DEEM'`	optimizer; `'no_optimization'` runs the initial parameters once

Dry run first

DEEM.optimize(method='no_optimization') simulates every test once with the initial parameter set — no optimization — so you can confirm the database and starting values produce sensible results before committing to a full run.

Full minimal example¶

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

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

model = hypoplasticity_isa()

globals.setup(
    Model=model,
    Free_parameter=["hs", "n", "ed", "ec", "alpha", "beta"],
    oedometer=database.oedometer,
    triaxCD=database.triax_CD,
    triaxCU=database.triax_CU,
    path="./calibration/",
    Experimental_database=database,
)

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

For the internals — the model interface, the similarity-measure functions, the weighting and reporting modules, and how to add a new model — see the Developer API.

User API¶

1 · Reading data — excel¶

Constructor¶

collect()¶

2 · Choosing a model¶

Constructor¶

Configuring parameters¶

Optional · Fitting critical-state-line parameters¶

3 · Describing the problem — globals.setup¶

4 · Running the optimizer — DEEM.optimize¶

Full minimal example¶

1 · Reading data — `excel`¶

`collect()`¶

3 · Describing the problem — `globals.setup`¶

4 · Running the optimizer — `DEEM.optimize`¶