Developer API¶

This page documents the internals of numgeo-ACT — the package layout, the constitutive-model interface, the similarity, weighting, plotting and reporting modules, the runtime helpers and the optimizer back-ends. It is intended for developers extending the tool (for example adding a new constitutive model, a new similarity measure, or a new optimizer back-end). For ordinary calibration use, see the User API.

Package layout¶

ACT/
├── __init__.py
├── globals.py            # setup(): registers the calibration problem
├── DEEM.py               # optimize(): drives the optimization + writes outputs
├── bayesian.py           # surrogate-based optimization back-end
├── models/               # constitutive-model interfaces (one class per model)
│   ├── __init__.py       #   exports all model classes
│   ├── hypoplasticity.py · hypoplasticity_igs.py · hypoplasticity_isa.py · ISA.py
│   ├── hca_sand.py
│   ├── sanisand.py · sanisand2.py · sanisand_f.py · sanisand_msf.py
│   └── ta_ger.py · mod_ta_ger.py
├── numgeo/               # numgeo element-test input writers / runners
│   ├── oedometer.py · isotropic_compression.py
│   ├── triaxial_cd.py · triaxial_cu.py · triaxial_cu_cyclic.py
│   ├── triaxial_cd_cyclic_hca.py · triaxial_cu_cyclic_hca.py
│   ├── simple_shear.py · numgeo.py · common.py
└── utilities/
    ├── excel.py          # the Excel database reader (excel.collect)
    ├── laboratory_tests.py   # in-memory test containers
    ├── distances.py      # similarity / curve-distance measures
    ├── weights.py        # objective weighting (initialize / check)
    ├── plotting.py       # comparison figures (simulation vs experiment)
    ├── reporting.py      # PDF calibration report
    ├── csl.py            # Bauer / Li-Wang critical-state-line fitting
    ├── tools.py          # text-log helpers
    ├── runtime.py        # locate & run the numgeo executable
    ├── timeout.py        # per-test timeouts
    ├── errors.py         # error types
    ├── mealpy.py · scipy.py   # alternative optimizer back-ends
    └── DEEMopt/          # the bundled DEEM / DEEMI optimizer
        ├── DEEM.py · DEEMI.py
        ├── population.py · evaluation.py · sampling.py
        ├── boundary_conditions.py · surrogate.py · toolbox.py · logger.py

The constitutive-model interface¶

Every class in ACT.models implements the same interface, so the optimizer and reporting code treat all models uniformly. To add a new model, implement these methods with identical signatures.

Configuration¶

set(self, <param>=None, ...)          # assign parameter values
set_bounds(self, <param>=None, ...)   # set search interval per parameter ([lo, hi])
update(self, parameter, value)        # set one parameter by name
get_parameter(self, parameter)        # read one parameter by name

set / set_bounds take the model's own parameter names as keyword arguments; each model defines self.name (the numgeo model identifier) and, in __init__, its default parameter values and self.bounds dictionary.

Parameter introspection¶

list_parameter_all(self)                  # every parameter of the model
list_parameter_optimize(self, free_parameter)  # the parameters being optimized
list_parameter_fixed(self, free_parameter)     # the parameters held fixed
parameter_bounds(self, free_parameter)         # bounds of the free parameters

These let globals.setup / DEEM.optimize assemble the search space from the Free_parameter list without knowing model specifics.

numgeo coupling¶

write_numgeo_material(self, parameter, mode)
write_numgeo_initial_state_variables(self, parameter, e0, test_type,
                                     initial_state=False, stress=False)

write_numgeo_material emits the numgeo material definition for the current parameter vector; write_numgeo_initial_state_variables emits the per-test initial state. The element-test drivers in ACT.numgeo call these to build each simulation input.

Reporting hook¶

report_optimization_results(self, filename, error)

Writes the model's optimized parameters and the achieved objective to the log.

Similarity measures — utilities/distances.py¶

The curve-distance functions behind the Similarity / similarity option (see objective function). To add a measure, implement a function with the same calling convention and register its keyword.

least_square(array1, array2)
mod_least_square(array1, array2)
delta_max_value(array1, array2)
discrete_frechet_distance(P1, P2)          # P1, P2: sequences of (x, y) points
hausdorff_distance(array1, array2, distance='euclidean')
moving_average(data, window_width)         # helper used for smoothing

Weighting — utilities/weights.py¶

initialize()
# -> nested dict: weights["global"], weights["triaxCD"], weights["triaxCU"],
#    weights["triaxCUcyc"], weights["triaxCDcycHCA"], weights["triaxCUcycHCA"],
#    weights["USScyc"], weights["scale_max_min"]

check(weighting_factors, triaxCD, triaxCU, triaxCUcyc,
      triaxCDcycHCA, triaxCUcycHCA, USScyc)
# validates that, for each active test type, the per-quantity weights sum to ~1

initialize() returns the default weight structure (documented in full on the weighting page); check() is called before a run and aborts with a message if any active test's weights are inconsistent (sum outside 0.98–1.0). A custom dictionary is passed through globals.setup(Weights=...).

Plotting — utilities/plotting.py¶

simulation_vs_experiment(model, parameter, oedometer_exp, triax_CD, triax_CU,
                         triax_CUcyc, triaxCDcycHCA, triaxCUcycHCA, USScyc,
                         iso_comp_exp, directory, weights, name)
save_result_figure(fig, filename)     # saves BOTH <name>.pdf and <name>.png
create_figure_with_subplots(nrows, ncols)
set_matplotlib_defaults()

simulation_vs_experiment produces the per-test comparison figures; every figure is written as both PDF and PNG via save_result_figure. set_matplotlib_defaults applies the consistent figure style used throughout the reports.

Critical-state-line fitting — utilities/csl.py¶

bauer_csl(p, ec0, hs, n)
li_wang_csl(p, e0, lambdac, xi, patm=100.)
bolton_csl(p, emax, emin, Q, R)
fit_csl_oedometer_tests(tests, model='bauer', K0=None, result_dir='./results/', **kwargs)
fit_csl(model='bauer', p=None, e=None, sigma_v=None, vertical_stress=None,
        K0=None, void_ratio=None, strain=None, axial_strain=None,
        e_initial=None, initial_void_ratio=None,
        emax=None, emin=None, Q=None, R=None,
        patm=100., p_min=10., p_max=1000., n_points=30,
        evaluation='auto', envelope_bins=40, stress_tolerance=0.005,
        x0=None, bounds=None, result_dir='./results/', filename=None,
        show=False, update_model=None)

The user-facing documentation is available under Utilities → CSL calibration. fit_csl is a standalone pre-calibration helper. It returns a dictionary, prints the fitted parameters and \(R^2\), saves a PNG/PDF comparison figure and writes a compact plain-text csl_fit_*.dat report-data file into the result directory. For non-monotonic oedometric loading-unloading-reloading data, evaluation='auto' fits the virgin loading envelope instead of all path points. reporting.write_pdf_report reads these text files and inserts a compact CSL page with settings and figure into the ACT report.

Reporting — utilities/reporting.py¶

create_report_paths(directory=None)   # -> (log_file, report_file)
write_pdf_report(filename, model, free_parameter, weights, algorithm_settings,
                 initial_parameter, final_parameter,
                 oedometer, triaxCD, triaxCU, triaxCUcyc,
                 triaxCDcycHCA, triaxCUcycHCA, USScyc, iso_comp,
                 result_directory, error=None, experimental_database='-')

write_pdf_report assembles the multi-page numgeo-ACT calibration report (title page with logo, initial/final parameter tables, per-test figures, page footers). create_report_paths returns the log- and report-file paths for a run.

Text logging — utilities/tools.py¶

print_header_to_file(file, free_parameter, weights, method=None, similarity=None,
                     maxiter=None, popsize=None, experimental_database=None)
print_algorithm_settings_to_file(file, settings)
print_parameter_table_to_file(file, model, free_parameter, parameter,
                              title='Parameter table')
print_closing_to_file(file, start, end)

These build the plain-text log that accompanies the PDF report (header, settings, initial/final parameter tables, timing).

Runtime — utilities/runtime.py¶

get_numgeo_command()   # locate the numgeo executable (must be on PATH)
run_numgeo(...)        # run a numgeo element-test simulation
is_windows()           # platform check
make_executable(path)  # chmod +x on POSIX
remove_tree(path) · handle_readonly(...)   # robust temp-dir cleanup

numgeo-ACT shells out to the numgeo solver for every element-test simulation; get_numgeo_command resolves the executable in a platform-independent way (numgeo must be installed and on the PATH — see installation).

Optimizer back-ends¶

DEEM is the default and is bundled with numgeo-ACT under ACT.utilities.DEEMopt (the same algorithm documented at the DEEM site · GitHub), including the improved DEEMI variant, population handling, sampling, boundary conditions and an optional surrogate. Alternative back-ends are exposed for experimentation:

The optimizer is selected through the method argument of DEEM.optimize; method='no_optimization' performs a single simulation pass without optimizing.

numgeo element-test writers — ACT.numgeo¶

The ACT.numgeo subpackage builds and runs the numgeo input for each element test. There is one module per test type (oedometer, isotropic_compression, triaxial_cd, triaxial_cu, triaxial_cu_cyclic, triaxial_cd_cyclic_hca, triaxial_cu_cyclic_hca, simple_shear), each consuming the model's write_numgeo_material / write_numgeo_initial_state_variables output. To support a new test type, add a corresponding driver here and a reader branch in ACT.utilities.excel.