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
├── SMAC.py               # SMAC-style optimiser with an evaluation budget
├── local.py              # bounded local pattern search
├── _calibration_optimizer.py  # shared lightweight-backend/report adapter
├── 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
    ├── optimizers.py      # dependency-light SMBO and pattern-search kernels
    └── 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 runtime contract used by the optimisers and reporting code. To add a new model, implement the operations below with semantics matching an existing production model. Keyword signatures for model parameters remain model-specific.

Configuration¶

set(self, <param>=None, ...)          # assign parameter values
update(self, parameter, value)        # set one parameter by name
get_parameter(self, parameter)        # read one parameter by name

Most models additionally implement set_bounds(self, <param>=None, ...) for user overrides. The base sanisand class is a deliberate legacy exception: it computes 16 built-in bounds in parameter_bounds(...) and has neither a set_bounds method nor a self.bounds dictionary. Do not make generic code depend on either convenience attribute. Every model defines self.name, the numgeo material identifier.

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

The public registry is ACT.globals.SUPPORTED_SIMILARITY_MEASURES and contains exactly these five keywords. globals.setup(Similarity=...) validates and stores the selected value. Every test-specific error entry point validates against the same registry; adding a function to distances.py alone does not make it supported.

Weighting: utilities/weights.py¶

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

check(weighting_factors, triaxCD, triaxCU, triaxCUcyc,
      triaxCDcycHCA, triaxCUcycHCA, USScyc, DSS=[])
# 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, DSS,
                         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, DSS, 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(..., diagnostic_file=None)  # run a numgeo element-test simulation
is_windows()           # platform check
make_executable(path)  # chmod +x on POSIX
remove_tree(path) · handle_readonly(...)   # temporary-directory 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). Pass diagnostic_file to run_numgeo to retain the native process output and a concise timeout, launch or exit-status message; normal calibration runs remain quiet by default.

Optimiser backends¶

DEEM is the default and is bundled under ACT.utilities.DEEMopt (the same algorithm documented at the DEEM site · GitHub), including the improved DEEMI variant, population handling, sampling and boundary conditions. Three public, dependency-light backends reuse DEEM.optimization_objective through the shared _calibration_optimizer.run_calibration adapter:

| Backend | Public module | Numerical kernel | Budget | |----------|--------|-------| | DEEM / DEEMI | ACT.DEEM | ACT.utilities.DEEMopt | generations | | IPOP-CMA-ES | ACT.CMAES | optimizers.cma_es_minimize | strict objective evaluations | | SMAC-style SMBO | ACT.SMAC (ACT.SMAC3 alias) | optimizers.smac_minimize | strict objective evaluations | | Local pattern search | ACT.local | optimizers.pattern_search_minimize | strict objective evaluations |

CalibrationBatchEvaluator owns a persistent spawn-based worker pool and gives each real evaluation a private temporary directory. CalibrationResult carries the numerical history, transcript and generated log/report/history paths, including separate comparison-data and raw-final-run directories. The PDF, text log and transcript remain directly under globals.setup(path=...); a result_directory is therefore not a self-contained archive. None of these backends downloads packages. CMA-ES uses the bundled NumPy implementation. SMAC-style surrogate='auto' tries an already installed scikit-learn Extra-Trees backend and otherwise uses the bundled NumPy Gaussian process.

The three model output paths are destructive managed workspaces, not arbitrary storage locations. Construction validates that they are distinct canonical absolute paths and rejects broad roots, overlaps, links and mount points. Cleanup semantics are intentional: out_dir2 is recursively reset, direct files/symlinks in out_dir are removed, and non-report subdirectories in out_dir3 are removed. Examples and integrations must allocate three dedicated ACT-only directories and must never reuse a general project or data directory.

ACT.bayesian remains as a deprecated compatibility wrapper that translates its historical evaluation budget to ACT.SMAC; it no longer imports the third-party bayesian-optimization package or maintains a separate objective. The older ACT.utilities.mealpy and ACT.utilities.scipy modules are retained for reference only. They are unsupported, are not compatible with the current runtime contract, and may not work. They are not part of the ACT 0.1.0 optimiser API.

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.