Skip to main content
Version: v2.0.2

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, copy the original config and edit its existing [sim] section:

[sim]
modelname = result-r
is_restarting = yes
restarting_from_modelname = result
restarting_from_frame = 10

Replace result and 10 with the original model prefix and an output frame that has both save and checkpoint files. Run the executable with this edited config, retaining the original physical controls and allowing enough steps or time to continue. Frame numbers are output-frame indices, not necessarily physical step numbers. Both restart-selection parameters are required; rerunning an unchanged fresh config does not automatically select a checkpoint.

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.

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:

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

Errors in the configuration file stop the run with 10 or 11 and a message naming the problem. 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)