Output & reporting¶

Every calibration run documents itself. When DEEM.optimize(...), CMAES.optimize(...), SMAC.optimize(...) or local.optimize(...) finishes, numgeo-ACT writes a PDF report, a text log, and a set of comparison plots to the configured run locations. The timestamped PDF and text log are written directly under globals.setup(path=...). CMA-ES, SMAC and local search also write a run-specific terminal transcript there; full DEEM optimisation writes terminal_out.txt, while DEEM.optimize(method="no_optimization") writes no transcript. The three lightweight backends place comparison data, plots and a run-specific <report-stem>-optimization-history.csv in <model.out_dir>/<report-stem>/. The exact raw input and output of their final numgeo evaluation are kept in the matching <model.out_dir3>/<report-stem>/ directory.

PDF calibration report¶

The headline artifact is a multi-page numgeo-ACT calibration report (PDF). It collects, in one document:

a title page with the numgeo-ACT logo, the generation date, the calibrated model, the optimization method and similarity measure, the final objective (error) value, and the result directory;
parameter tables listing the initial and final (optimized) parameter sets;
comparison figures for every honoured test, showing the simulation against the experiment;
an optional Critical-state-line calibration page when ACT.utilities.csl.fit_csl report-data files are present in the result directory;
a footer on each page identifying the model and page number.

This single PDF is usually all you need to review or archive a calibration.

Text log¶

Alongside the PDF, a plain-text log file records the run in detail:

a header with the free parameters, the weights, the method, the similarity measure, the iteration limit and population settings, and the experimental database used;
the algorithm settings;
the initial and final parameter tables;
the achieved objective value and timing information (start, end, duration).

CMA-ES, SMAC-style and local runs write a run-specific <report-stem>-terminal-out.txt, record every evaluated parameter vector and objective value in <report-stem>-optimization-history.csv, and return these paths through their CalibrationResult object. Full DEEM optimisation uses the fixed name terminal_out.txt; its simulation-only no_optimization mode does not start a terminal transcript.

For CMA-ES, SMAC-style and local runs, the history CSV is created before the first objective evaluation and synchronised after every completed batch. If the optimiser, native solver or report finalisation raises an exception, the rows already written remain in <model.out_dir>/<report-stem>/ for diagnosis. A successful run atomically replaces this live checkpoint with the optimiser's canonical ordered history. Checkpoints are an audit and recovery aid only; automatic resume from a partial history is not currently supported.

Dependent parameters

Some model classes may define dependent parameters. For Hypo-IGS, if mR is optimized while mT is not part of Free_parameter, ACT uses mT = 0.7*mR. In this case the log file and the PDF report mark mT as dependent instead of fixed, and the shown value is the effective value used in the numgeo calculations.

Critical-state-line output¶

The CSL utility ACT.utilities.csl.fit_csl(...) writes a compact plain-text csl_fit_*.dat report-data file and a matching csl_fit_*.png / .pdf figure into the selected result directory. When the calibration report is generated, this text file is picked up automatically and inserted as a dedicated CSL page with the fitted Bauer or Li-Wang parameters and the \(R^2\) value.

Comparison plots¶

For each test type, numgeo-ACT produces a simulation-vs-experiment figure, saved as both PDF and PNG:

File	Content
`oedometer.pdf` / `.png`	oedometer stress–strain
`triaxCD.pdf` / `.png`	drained triaxial: \(\varepsilon_1\)–\(q\) and \(\varepsilon_1\)–\(\varepsilon_v\)
`triaxCU.pdf` / `.png`	undrained triaxial: stress–strain and effective stress path
`triaxCUcyc.*`	undrained cyclic triaxial: stress path, pore-pressure build-up
HCA / `USScyc` figures	accumulation-vs-cycles and cyclic-simple-shear responses
`DSS.pdf` / `.png`	drained direct simple shear: \(\gamma\)–\(\tau\) and \(\gamma\)–\(\varepsilon_v\)

In these plots the simulation is drawn against your experimental curves (as in the home-page animation), making it easy to see at a glance how well the optimized parameters reproduce each test and where they differ.

Where the files go¶

The output locations are set by the three directories passed to the model constructor (with defaults):

model = hypoplasticity_isa(
    out_dir="./results/",     # comparison data, plots and histories
    out_dir2="./run_tmp/",    # temporary run files during optimization
    out_dir3="./run_final/",  # raw files of the final (best) numgeo run
)

Constructors normalise the three inputs to absolute paths immediately. A relative input is anchored to the process working directory at model construction time. Prefer explicit paths below one resolved calibration directory, as in the Quickstart, especially when globals.setup(path=...) points elsewhere.

The working path given to globals.setup holds the timestamped PDF and log. It also holds the run-specific CMA-ES, SMAC or local transcript or the fixed DEEM terminal_out.txt when a full optimisation is run. Temporary per-evaluation files live under out_dir2; comparison data, plots and lightweight history live under out_dir; and the best-fit raw numgeo run is preserved under out_dir3. For the lightweight backends, CalibrationResult.result_directory points to the comparison-data/plot folder and CalibrationResult.final_directory points to the raw final-run folder.

Use dedicated ACT-only directories

The model manages and cleans all three output directories. out_dir2 is recursively reset; direct files and symbolic links in out_dir are removed; and non-report subdirectories in out_dir3 are removed. Configure three separate directories used only by ACT. Never use a general project, data or home directory. ACT rejects broad roots, overlapping paths, links and other unsafe configurations, but cannot identify every ordinary folder selected by mistake.

Reviewing a run

Start with the PDF report for the overview, then open the per-test PNG/PDF plots to judge the fit of individual tests, and consult the text log for the precise parameter values and run settings.

Critical-state-line summary page¶

When a CSL fit generated by ACT.utilities.csl.fit_csl is present in the result directory, the PDF report adds a compact CSL summary page. The page contains the input source, number of fitted points, \(R^2\), fitted parameters and the CSL comparison figure on the same page. The corresponding csl_fit_*.png file is not repeated again in the normal result-figure section.