Troubleshooting¶

Start with the two installation smoke tests and a simulation-only pass. The messages below cover the most common failures.

numgeo was not found in PATH¶

ACT intentionally resolves the solver through the system PATH.

where.exe numgeo
.venv\Scripts\python -c "from ACT.utilities.runtime import get_numgeo_command; print(get_numgeo_command())"

command -v numgeo
.venv/bin/python -c "from ACT.utilities.runtime import get_numgeo_command; print(get_numgeo_command())"

If the first command fails, add the directory containing the executable to PATH, not the executable filename itself. Open a new terminal after editing the Windows environment. On Linux, also check the executable bit with ls -l /path/to/numgeo.

numgeo exits immediately with 0xC0000135 on Windows¶

0xC0000135 is Windows STATUS_DLL_NOT_FOUND. It occurs while Windows loads the process, before numgeo parses the input generated by ACT. For the pinned Windows blob, clean CI identifies six direct Intel runtime imports listed on the installation page. They are not bundled, so reinstalling Python/ACT or changing PATH cannot fix this release artifact.

Retain numgeo-process.log and numgeo-linkage.log when diagnosing the failure. Use only the verified replacement executable or authorised complete runtime bundle supplied by the release owner; do not obtain individual DLLs from unofficial download sites.

ModuleNotFoundError: No module named 'ACT'¶

Use the intended virtual environment and run from the repository root. Put a custom driver in that directory, or launch a bundled example with python -m, as shown on the examples page. Do not run a nested example by double-clicking it.

If a dependency is missing, install the complete supported stack from the installation page. On a restricted computer, use a platform-matched offline wheel directory.

Worker processes start the script repeatedly¶

The driver is missing the multiprocessing guard. CMA-ES, SMAC-style and local search use spawned workers on all platforms; DEEM also uses spawn on Windows. Put model construction, globals.setup(...) and the optimiser call in a function and call it only as follows:

def run_calibration():
    # read data, configure ACT, then call the optimiser
    ...


if __name__ == "__main__":
    run_calibration()

The complete pattern is in the Quickstart.

A numgeo evaluation fails or times out¶

ACT assigns a penalty to failed parameter sets so that a global search can continue. Frequent failures usually indicate one of the following:

• bounds include physically inadmissible or numerically unstable combinations;
• units or stress/strain sign conventions do not match the sheet definition;
• the initial state is incompatible with the model;
• the per-test timeout is too short for an otherwise valid calculation;
• the ACT and numgeo executables come from different releases.

First run the initial parameter set only. If it fails, inspect the retained numgeo input/output before increasing the timeout. If it succeeds, narrow the offending parameter bounds or add the relevant model constraint. Increase a timeout through the dictionary passed as globals.setup(Timeout=...); do not raise every timeout indiscriminately.

Bounds or parameter names are rejected¶

Parameter names are case-sensitive. Copy them from the selected model page or from its class in ACT.models. Ensure every bound is finite, has two entries and satisfies lower <= upper. A fixed parameter should normally be omitted from Free_parameter, rather than represented by an artificial zero-width search interval.

The base sanisand class is an exception to the usual convenience interface: it provides built-in bounds through parameter_bounds(...) but does not expose a public set_bounds(...) method. Select a supported built-in bound or edit the model implementation; do not call an undocumented method.

The Excel reader returns None¶

This is expected: collect() changes the reader instance in place.

database = excel()
database.collect("tests.xlsx")

Do not assign the return value of collect().

Excel data are missing or shifted¶

ACT uses sheet names and defined cell positions. Check the sheet reference and, in particular:

• the exact sheet prefix and sequential number;
• units and required metadata cells;
• blank rows inside a data block;
• numbers stored as text;
• formulas whose cached result was not saved by the spreadsheet application.

Open and save formula-based workbooks once in Excel or LibreOffice before reading them on a headless computer. Compare a problematic sheet with the template.

Similarity measure is rejected¶

globals.setup(Similarity=...) accepts exactly frechet, least-square, mod-least-square, hausdorff and delta-max-value. All optimisers use this setting. Do not pass a conflicting legacy similarity value to an optimiser.

Oedometric loading-unloading-reloading paths are not single-valued functions of stress. Use frechet or hausdorff for those paths; pointwise measures are rejected rather than silently changing the requested metric.

The calibration is too expensive¶

Use the following sequence:

1. interpolate very dense experimental records to the resolution justified by the measurements;
2. run a simulation-only pass;
3. reduce the initial free-parameter set to identifiable parameters;
4. try SMAC-style search when the evaluation budget is strict;
5. try IPOP-CMA-ES when the response is rugged or contains broad penalty regions;
6. use local pattern search only to refine a credible parameter set;
7. increase n_cpu only within the available memory and numgeo licence/runtime constraints.

See Choosing an optimiser for the algorithm trade-offs.

Outputs cannot be written¶

Use a new, writable calibration directory and close PDF or spreadsheet files that another program has locked. Avoid synchronised/network folders for the temporary evaluation directory; they can add substantial file-system latency. The final report can be copied to such a folder after the run.

CMA-ES, SMAC and local search also prevent two processes from using the same globals.setup(path=...) directory simultaneously. Wait for the active run to finish or give each concurrent calibration a different working path.

If the problem persists, retain the terminal output, ACT log, driver, workbook and one failed numgeo run when reporting the issue. Remove confidential test data before sharing files externally.