Running DES3D

dynearthsol2d input.cfg

or

dynearthsol3d input.cfg

• Several example input files are provided under examples/ directory. The format of the input file is described in examples/defaults.cfg.
• Benchmark cases with analytical solution can be found under benchmarks/ directory.
• Execute the executable with -h flag to see the available input parameters and their descriptions.

Progress reporting

The sim.info_display_step_interval parameter controls how often DES3D prints a status line to the screen:

info_display_step_interval = 10   # print progress every 10 simulation steps

This parameter replaced the older info_display_interval (which was wall-clock seconds) as of 2026. The value must be a positive multiple of mesh.quality_check_step_interval; DES3D will round it up automatically and notify you if an adjustment is made.

Checkpointing and restart

DES3D writes checkpoint files at regular intervals so that a simulation can be resumed after interruption. As of 2026, restarts are deterministic: a restarted run produces bit-for-bit identical output to one that never stopped. The following state is now fully persisted in the checkpoint:

• dt and dt_PT (time step)
• max_global_vel_mag
• reference_frame_time
• info_display_next_step
• dhacc (surface marker correction)
• strain_rate, viscosity, volume_old
• plastic strain-rate (delta_plstrain), so a restarted run's diagnostic output matches a continuous one

To restart from a checkpoint, run the executable with the same config file. DES3D detects the most recent checkpoint automatically.

Checkpoint/output format revision 4

The checkpoint and frame file format was bumped from revision 3 to 4. A revision (or dimensionality) mismatch between the file and the running binary is now a hard error with a diagnostic naming the expected and actual values — previously it was accepted silently and could be misread. This means checkpoint and frame files written before this change cannot be restarted or read by a newer DES3D binary. Finish or discard runs on the old binary before upgrading.

Frame files (HDF5 and plain binary) now also embed the full .info row (steps, time, dt, walltime, node/element/segment counts). If a run's .info file is lost, utils/recreate_info.py rebuilds it from the frame files alone; restart() also falls back to this embedded metadata automatically when .info is missing.

Provenance

Every build, run and frame records where it came from:

What	Where
The build	in the executable, as a build.snapshot block: strings <exe> | grep '^build\.snapshot\.'
The run	in <modelname>.manifest, beside the model's output
Each frame or checkpoint	a /provenance group (HDF5) or a provenance record (des-binary) in the file itself

The manifest uses the cfg format: [runtime.model], [runtime.host], [runtime.device], [runtime.threads] and [runtime.env] first, then the build's own [build.*] sections, closed by [runtime.end] once the time loop ends (a record without it died, was killed, or is still running). Its first fields, end_time, stopped_by and wall_time, are enough to see how every run of a sweep ended:

grep -A3 '^[runtime.end]' */*.manifest

A restart appends its record rather than starting the file over. The same sections print to the screen once at run start, one line each as [build][...] then [runtime][...]; set sim.has_runtime_info_display = no to silence them:

[sim]
has_runtime_info_display = no

make snapshot_diff=1 (off by default) also embeds the working-tree diff in the executable, so build.code-changes in the manifest is more than a note that it wasn't captured.

A GPU build that finds no device exits 52 (see Exit codes) after appending its manifest record, so the attempt is on record even though the run never started.

The full field-by-field reference is doc/provenance.md in the DynEarthSol repository.

Run-time warnings

• While running, DES3D might print warnings on screen. An example is the warning about the potential race condition: e.g.,

****************************************************************
*    Warning: egroup-0 and egroup-2 might share common nodes.
*             There is some risk of racing conditions.
*             Please either increase the resolution or
*             decrease the number OpenMP threads.
****************************************************************

• Please do pay attention and follow given suggestions if any.

Exit codes

DES3D exits with a two-digit code that is printed together with its category. The first digit is the category (1x is yours to fix, 2x the environment, 3x–6x the code itself) and the second the specific cause:

Code	Meaning
0	Normal exit
10 / 11	Config error / bad value or unknown option
12	Malformed .poly or .exo file
20 / 21 / 22	Cannot open file / read or write failed (HDF5) / restart mismatch
30 / 31	Unsupported in this NDIMS / library not built in
40 / 41 / 42	Triangle or TetGen / MMG / mesh quality or topology
50 / 51 / 52	NaN or non-finite value / marker or geometry lookup / resource exhausted
60 / 61	Assertion violated / unreachable branch

Errors in the configuration file stop the run with 10 or 11 and a message naming the problem. For example, every mattype_* index is checked against num_materials at startup, and an out-of-range one exits with 11 naming the parameter.

A NaN velocity stops the run with 50 instead of continuing to write frames. The run prints a single line summarizing the affected fields, their counts and the first bad element and node. A GPU build that finds no device at startup exits 52, after appending its manifest record — see Provenance. Scripts that test for specific exit statuses need updating: earlier builds used 1, 2, 10, 11 and 12 with different meanings.

Initial stress

By default (initial_stress_option = 0) the historical initialization is used. For zero-gravity models, set initial_stress_option = 1 in the [ic] section to prescribe a homogeneous absolute stress tensor with initial_stress:

[ic]
initial_stress_option = 1
# 2-D: [sxx, szz, sxz]    3-D: [sxx, syy, szz, sxy, sxz, syz]
initial_stress = [sxx, szz, sxz]   # replace with your values (Pa)