4. LS-DYNA solver operations

An LS-DYNA run is driven entirely by a single input deck — a plain-text file conventionally named main.k or job.k — that the solver reads sequentially from top to bottom. Understanding how that deck is structured, how it is assembled from multiple keyword files, how the solver is launched, and how output is controlled is the operational foundation for every crash simulation. This section covers the practical mechanics: deck anatomy, *INCLUDE assembly, the lsdyna execution command line, and the output-control keywords that determine what results you actually get.

Input Deck Anatomy

An LS-DYNA keyword deck is organized into keyword blocks. Each block begins with a keyword line starting with an asterisk (e.g., *CONTROL_TERMINATION), followed by one or more data lines containing fixed-field or comma-delimited values. The solver processes blocks in order, so definition order matters: nodes and elements must exist before parts reference them, and parts must exist before contact or boundary conditions reference them.

A minimal but complete crash deck contains these functional groups:

• Control blocks — *CONTROL_TERMINATION, *CONTROL_TIMESTEP, *CONTROL_ENERGY, *CONTROL_OUTPUT. These govern run duration, time-step scaling, energy tracking, and output frequency.
• Database blocks — *DATABASE_BINARY_D3PLOT, *DATABASE_BINARY_D3THDT, *DATABASE_ASCII_*. These define what is written to disk and how often.
• Geometry — *NODE, *ELEMENT_SHELL, *ELEMENT_SOLID, *ELEMENT_BEAM.
• Parts and materials — *PART, *SECTION_SHELL, *MAT_* (e.g., *MAT_PIECEWISE_LINEAR_PLASTICITY for steel, *MAT_024).
• Connections and conditions — *CONTACT_AUTOMATIC_SINGLE_SURFACE, *BOUNDARY_PRESCRIBED_MOTION_RIGID, *INITIAL_VELOCITY, *CONSTRAINED_*.
• Time history — *DATABASE_HISTORY_NODE, *DATABASE_HISTORY_SHELL for d3plot-adjacent time-history output.

Fixed-field format is the traditional LS-DYNA convention: each field occupies 10 columns, and values must be right-aligned within those columns. Comma-delimited format is more forgiving and is now widely used. Mixing the two within one block is a common source of silent misreads — the solver may parse a value into the wrong field without erroring. Always verify field alignment when hand-editing.

Assembling the Deck with *INCLUDE

Real crash models are never a single monolithic file. They are assembled from sub-files: a mesh file per subsystem (BIW, closures, powertrain, dummy), a materials file, a contacts file, and a control file. The *INCLUDE keyword pulls these together at solve time:

*INCLUDE
biw_mesh.k
closures_mesh.k
dummy_positioned.k
materials.k
contacts.k
control_output.k

Paths in *INCLUDE are relative to the directory where the solver is launched, not to the including file. This is a frequent operational trap: a deck that runs from the project root fails when launched from a subdirectory. Use consistent relative paths or absolute paths, and keep the working directory fixed. Nested includes are allowed, but circular includes will cause the solver to abort during input processing.

Execution Commands

The solver is launched from the command line. The canonical form on Linux is:

lsdyna i=main.k ncpu=8 memory=2000m

Key command-line parameters:

For MPP (massively parallel) builds, the launch differs — typically via mpirun or a scheduler:

mpirun -np 32 lsdyna_mpp i=main.k memory=4000m

The choice between SMP and MPP affects memory behavior and scalability. SMP shares memory across threads and is simpler for single-node runs; MPP distributes memory across ranks and scales better on clusters but requires decomposition and can introduce contact-related differences. For crash models with large contact surfaces, MPP decomposition quality directly affects both runtime and result consistency.

Output Control

Output is governed by two families of keywords: binary database controls and ASCII controls. The most important is *DATABASE_BINARY_D3PLOT, which writes the state database used by post-processors (LS-PrePost, Animator) for contour plots and animations:

*DATABASE_BINARY_D3PLOT
     0.002       0         0         0

The first field is the output interval in seconds. For a 100 ms crash event, 0.002 yields 50 states — usually sufficient for animation and peak-value extraction. Setting it too fine (e.g., 0.0001) produces 1000 states and can generate tens of gigabytes, slowing both solve and post-processing. Setting it too coarse misses peak deformation and force spikes.

Time-history output is controlled separately. *DATABASE_BINARY_D3THDT writes the d3thdt file at a specified interval, and *DATABASE_HISTORY_NODE / *DATABASE_HISTORY_SHELL select which entities are tracked. These are the curves you use for occupant acceleration, intrusion, and force-displacement checks:

*DATABASE_HISTORY_NODE
$#    id1       id2       id3       id4
      1001      1002      1003      1004

ASCII output blocks such as *DATABASE_ASCII_GLSTAT (global energy), *DATABASE_ASCII_MATSUM (material energy summary), and *DATABASE_ASCII_RCFORC (contact forces) are essential for debugging. GLSTAT and MATSUM together let you verify energy balance — a critical sanity check. If hourglass energy exceeds roughly 5% of internal energy, or if total energy drifts significantly, the model has a numerical problem that must be resolved before trusting any result.

Reading the Run: What to Watch

During execution, LS-DYNA writes a d3hsp file containing the input echo, mass/energy summary, and time-step information, plus a messag file with progress and warnings. The first thing to check after launch is the initial time step reported in d3hsp. A very small initial step (e.g., below 1e-7 s) usually indicates a tiny or badly shaped element, and the run will be prohibitively slow. The messag file reports the current cycle, time, and estimated remaining time; monitoring it lets you catch a stalled or diverging run early.

At termination, verify three things: the run reached the intended end time (not an error termination), the energy balance is acceptable, and the d3plot file contains the expected number of states. Only then should results be interpreted.

Practical Checklist for a Reproducible Run

The following sequence reflects a disciplined operational workflow. It is not a rigid template but a set of checkpoints that prevent the most common failures:

1. Assemble the deck with *INCLUDE using paths relative to the launch directory.
2. Run a keyword-check pass and resolve all parse errors and undefined references.
3. Confirm *CONTROL_TERMINATION end time matches the intended event duration.
4. Set *DATABASE_BINARY_D3PLOT interval to balance resolution against disk usage.
5. Enable GLSTAT and MATSUM for energy diagnostics.
6. Launch with appropriate ncpu and memory; monitor messag for the first few hundred cycles.
7. After termination, check end time, energy balance, and d3plot state count before interpreting results.

Mastering these mechanics turns the solver from a black box into a controllable tool. The deck structure determines what the solver sees, the execution command determines how it runs, and the output controls determine what evidence you have to judge the result. Get these three right, and the simulation becomes reproducible and debuggable rather than a one-shot gamble.