Objective function & similarity¶

The optimizer needs a single number that says how good a parameter set is. In numgeo-ACT that number is the objective value: a weighted combination of how closely each simulated curve matches the corresponding experiment. The optimizer minimizes it.

From curves to a single number¶

For a given parameter set, numgeo-ACT:

simulates every selected laboratory test;
for each test, compares one or more simulated curves against the measured curves (e.g. \(\varepsilon_1\)–\(q\), \(\varepsilon_1\)–\(\varepsilon_v\), the effective stress path, or accumulation-vs-cycles) using a similarity measure;
combines these per-curve distances using the weights you control, into one objective value.

The objective is assembled in three steps. For every test \(t\) of a test family \(f\) (oedometer, drained triaxial, ...), the curve distances are combined with the per-test weights \(w_{f,c}\):

\[ \Phi_t(\mathbf{x}) \;=\; \sum_{c \in \text{curves}(f)} w_{f,c}\, d\big(\text{sim}_{t,c}(\mathbf{x}),\, \text{exp}_{t,c}\big) \]

The tests of one family are then averaged, the families present in the calibration are averaged with equal weight within the monotonic and the cyclic group, and the two groups are combined with the global weights:

\[ \Phi(\mathbf{x}) \;=\; w_{\text{mono}}\, \operatorname{mean}_{f \in \text{monotonic}}\Big(\operatorname{mean}_{t \in f}\Phi_t\Big) \;+\; w_{\text{cyc}}\, \operatorname{mean}_{f \in \text{cyclic}}\Big(\operatorname{mean}_{t \in f}\Phi_t\Big) \]

Here \(\mathbf{x}\) is the vector of free parameters, \(d(\cdot,\cdot)\) is the chosen similarity measure, and the weights are described on the weighting page. Two consequences are worth keeping in mind: every family counts the same regardless of how many tests it contains (one oedometer test weighs as much as five drained triaxial tests), and if only monotonic or only cyclic tests are present the global weights are not applied.

Failed and incomplete simulations¶

A parameter set for which numgeo does not finish every test receives the failure penalty (globals.penalty, 1000) instead of an objective value. This covers simulations that abort or exceed the configured timeout, output files that cannot be read, parameter sets that violate the constraints of the model (for example the Hardening Soil stiffness ratios), and simulations that stop before the end of the experiment: monotonic tests must reach 95 % of the final experimental strain (or stress, for stress-controlled oedometer tests), cyclic tests the compared number of cycles. The penalty is never averaged with valid values, and an unexpected exception inside one evaluation is reported and treated as a failed simulation rather than aborting the calibration.

The population methods (DEEM, CMA-ES) are rank based and unaffected by the size of the penalty. The surrogate-based ACT.SMAC replaces penalised values by the worst successful value before fitting its model, see the optimiser page.

Similarity measures¶

The similarity measure \(d(\cdot,\cdot)\) quantifies the distance between a simulated and a measured curve. Select it once through the Similarity argument of globals.setup. DEEM and the lightweight optimisers all use that setting.

Value	Measure	Idea
`frechet` (default)	discrete Fréchet distance	shape-aware distance between two ordered polylines
`hausdorff`	symmetric Hausdorff distance	largest closest-point distance between two point sets
`least-square`	root-mean-square error	pointwise RMSE after test-specific interpolation and scaling
`mod-least-square`	relative root-mean-square error	pointwise, scale-invariant error relative to non-zero experimental values
`delta-max-value`	maximum absolute deviation	largest pointwise difference after test-specific interpolation and scaling

These are the only supported names. Unsupported values raise ValueError during setup rather than silently selecting another measure. For backwards compatibility, DEEM.optimize(similarity=...) may repeat the configured value; omitting it is clearer, and a conflicting value is rejected.

Long records and the Fréchet distance

The Fréchet distance compares every experimental point with every simulated one. Its cost therefore grows with the product of the two record lengths. Tests recorded with several thousand points, particularly direct simple shear tests, should be thinned once after reading, for example with for test in database.DSS: test.interpolate(200), otherwise every single objective evaluation becomes expensive.

Which measure should I use?

The Fréchet distance (frechet) is the default and a sound general choice: it compares the shape of the curves while respecting their ordering, which suits stress–strain and stress-path data well. Hausdorff is also appropriate for path-based comparisons but does not retain traversal order. Pointwise measures are useful for single-valued monotonic responses sampled on a common independent coordinate. When comparing runs, keep the measure and all weights fixed.

Penalties¶

Some test types add penalty terms to the objective to discourage physically wrong behaviour. For example, it can penalize a simulated undrained cyclic stress path that leaves the convex hull of the measured stress path or that crosses the critical state line, and enforce features such as a stress peak. These appear as dedicated penalty entries in the weights (penalty-hull, penalty-peak-q-eps1, penalty-critical-state-line) and are added on top of the curve distances. All of them are switched off by default (weight 0); a large weight steers the optimizer firmly away from such parameter sets.

Data preparation¶

To compare curves fairly, simulation and experiment must be sampled consistently. numgeo-ACT interpolates the curves onto a common basis before applying the similarity measure, and (for several test types) can scale each compared plane to a common range so that quantities with different magnitudes contribute comparably. Drained-triaxial experimental data after the deviatoric-stress peak are ignored by default (cutoff-triaxCD-expdata-after-max-q in the weights), so that models without softening are not pushed to fit the post-peak branch; the simulation then only has to reach the strain at the peak.

Continue to Weighting of tests to see exactly which curves are compared for each test type and how to rebalance them.

Oedometer loading-unloading-reloading curves¶

For oedometric loading-unloading-reloading data, numgeo-ACT does not evaluate strain as a unique function of stress. That would be wrong because unloading and reloading produce several strains at the same stress level.

Instead, the ordered experimental and numerical paths are compared in the scaled stress-strain plane

\[ \left(\frac{\sigma_v}{\sigma_{v,\max}},\frac{\varepsilon_v}{\varepsilon_{v,\max}}\right) \]

while preserving the row/increment order of the test. With similarity='frechet' this gives a path-consistent distance between the measured and simulated trajectory. The load cycles are therefore still part of the automatic calibration objective and can contribute to the identification of small-strain parameters.

Pointwise measures require a unique value of strain for each stress. If a load reversal is detected, least-square, mod-least-square and delta-max-value therefore raise a clear error. Select frechet or hausdorff for loading-unloading-reloading oedometer paths; ACT does not silently replace the requested measure.