Critical-state-line calibration¶

numgeo-ACT provides a small utility module for fitting critical-state-line (CSL) parameters before or alongside a full element-test calibration. The module is useful when critical void-ratio data are available directly, when the CSL should be inferred from oedometric compression data, or when a first estimate should be generated from \(e_{\max}\), \(e_{\min}\) and Bolton's relative dilatancy parameters.

Supported CSL equations¶

Bauer CSL for hypoplastic models¶

The Bauer form used for the hypoplastic family is

where \(p\) is the mean effective stress, \(e_{c0}\) is the critical void-ratio factor, \(h_s\) is the granulate hardness and \(n\) is the compression exponent. In the ACT Python interface, \(p\) is given in kPa and \(h_s\) is returned in GPa, consistent with the hypoplastic model classes.

Li-Wang CSL for SANISAND-family models¶

The Li-Wang form used by the SANISAND-family models is

where \(e_0\), \(\lambda_c\) and \(\xi\) are fitted parameters and \(p_{atm}\) is the reference pressure, with a default of 100 kPa.

Bolton-generated CSL data¶

When no measured CSL data are available, fit_csl can first generate synthetic CSL points from

and then fit either Bauer or Li-Wang parameters to those points. The pressure unit must be consistent with the selected \(Q\) and \(R\) values. If no pressure vector is supplied, ACT uses a logarithmic default grid from 10 kPa to 1000 kPa.

Input mode 1: direct \(p\)-\(e\) data¶

from ACT.utilities.csl import fit_csl

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

Input mode 2: oedometric compression data¶

For oedometric compression data, ACT converts vertical effective stress to mean effective stress with

K0 may be a scalar or a vector with one value per stress point.

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

Input mode 3: Bolton estimate¶

result = fit_csl(
    model='li-wang',
    emax=0.977,
    emin=0.605,
    Q=9.15,
    R=0.77,
    p_min=10.,
    p_max=1000.,
    n_points=30,
    result_dir='./results/',
)

The returned dictionary contains the fitted parameters, the \(R^2\) value, the input data, the fitted data, the saved figure path and the plain-text report-data path used by the report writer:

print(result['parameters'])
print(result['r2'])
print(result['figure'])

Updating a model instance¶

Pass a model instance through update_model to copy matching fitted CSL parameters directly to the constitutive model object:

from ACT.models import sanisand2
from ACT.utilities.csl import fit_csl

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

For Li-Wang fits, lambdac is written to lambda_c as well when the target model uses the SANISAND naming convention.

Report integration¶

Each call to fit_csl writes a file named csl_fit_*.dat and a corresponding csl_fit_*.png / .pdf figure into the selected result directory. The .dat file is deliberately a small plain-text key-value file, so no JSON parser or additional file-format dependency is required. During DEEM.optimize(...), ACT.utilities.reporting.write_pdf_report looks for these text files and inserts a Critical-state-line calibration page into the ACT report. The page lists the fitted CSL model, input mode, number of data points, \(R^2\) value, fitted parameters and the associated figure.