3. LS-DYNA energy database

Energy balance in LS-DYNA is not a single number but a family of related time histories distributed across several ASCII output files. Each file answers a different question: GLSTAT gives the global energy ledger, MATSUM decomposes that ledger part by part, SLEOUT isolates the contact and friction contribution, and RCFORC reports the interface forces that generate sliding energy in the first place. Reading them together is what turns a raw glstat curve into a defensible statement about model quality. This chapter explains what each database contains, how to request it, and how to extract and cross-check the time histories so that hourglass energy, sliding energy, and external work can be judged against consistent references.

What each database actually stores

All four files are written by the ASCII output subsystem and are controlled through *DATABASE_ASCII_* keywords. The relevant cards are *DATABASE_ASCII_GLSTAT, *DATABASE_ASCII_MATSUM, *DATABASE_ASCII_SLEOUT, and *DATABASE_ASCII_RCFORC. Each card carries a DT field (output interval) and, for MATSUM and SLEOUT, a PSETID or part-set selector that limits output to the parts of interest. A typical request for a crash or impact model looks like this:

*DATABASE_ASCII_GLSTAT
$#    dt    binary      lcur       ioopt
   1.0E-4         0         0         1
*DATABASE_ASCII_MATSUM
$#    dt    binary     lcur       ioopt
   1.0E-4         0        0         1
*DATABASE_ASCII_SLEOUT
$#    dt    binary     lcur       ioopt
   1.0E-4         0        0         1
*DATABASE_ASCII_RCFORC
$#    dt    binary     lcur       ioopt
   1.0E-4         0        0         1

With DT = 1.0E-4 and a termination time of 20 ms, each file receives roughly 200 samples, which is dense enough to resolve the peak of an impact event without producing unwieldy files. Setting DT far larger than the physical event duration is a common mistake: the peak hourglass energy or the contact force spike can fall entirely between two samples and never appear in the output.

GLSTAT is the global energy summary. Each row contains total kinetic energy, internal energy, total energy, hourglass energy, sliding (contact) energy, external work, damping energy, and the system damping and mass-scaling contributions, together with the global x, y, z momenta. It is the primary file for the energy-ratio checks that govern whether a solution is trustworthy.

MATSUM repeats the energy decomposition per part or per part set: kinetic, internal, hourglass, and (where applicable) sliding energy, plus the part mass and the current time step. This is where you localize a global anomaly — a model whose total hourglass energy is 4% may be perfectly acceptable if that energy is concentrated in one poorly meshed bracket and negligible everywhere else.

SLEOUT reports sliding energy split by contact definition, with separate columns for the slave side, master side, and the friction contribution. Because sliding energy is the term most often confused with physical dissipation, SLEOUT is the file that lets you decide whether a large sliding-energy value reflects genuine frictional work or numerical penalty oscillation.

RCFORC stores the resultant contact forces at each interface, resolved into global x, y, z components and reported per contact surface. It is the force-side counterpart to SLEOUT's energy-side view: integrating the RCFORC force over the contact displacement should reproduce the sliding energy, so the two files provide an independent consistency check.

Extracting the time histories

The ASCII files are plain text with a header line per block and one row per output time. A robust extraction workflow reads them into a small script rather than eyeballing the columns, because the column order differs between LS-DYNA versions and between solver builds. The following Python fragment parses glstat by locating the header row and mapping column names, which keeps the script portable across versions:

import numpy as np

def read_glstat(path):
    with open(path) as f:
        lines = f.readlines()
    # find the header line that names the columns
    hdr_idx = next(i for i, l in enumerate(lines) if "time" in l.lower() and "kinetic" in l.lower())
    names = lines[hdr_idx].split()
    data = np.loadtxt(lines[hdr_idx + 1:], ndmin=2)
    return {n: data[:, k] for k, n in enumerate(names)}

g = read_glstat("glstat")
t = g["time"]
ratio = g["hourglass_energy"] / np.maximum(g["total_energy"], 1e-12)
print("peak hourglass ratio:", ratio.max(), "at t =", t[ratio.argmax()])

For MATSUM the file contains one block per part, each preceded by a part ID line; the parser must split on those markers and return a dictionary keyed by part ID. SLEOUT is organized per contact definition, and RCFORC per surface, so the same block-splitting logic applies. Once parsed, the four datasets should be resampled onto a common time vector — LS-DYNA writes them at the same DT only if the cards share that value, and in practice they often do not.

Interpreting the curves

The first check is the global energy ratio. Plot total energy, kinetic energy, internal energy, hourglass energy, and sliding energy on one axis against time. In a well-behaved explicit run, total energy is conserved to within a few percent after the initial transient, kinetic energy rises during loading and decays as deformation proceeds, and internal energy rises correspondingly. Hourglass energy should stay below roughly 5% of total energy; sustained values above 10% indicate that the hourglass control is too weak for the element formulation, or that the mesh is under-integrated in a region carrying bending.

The second check localizes the problem. Sum the MATSUM hourglass column across all parts and compare it with the GLSTAT hourglass curve. If the sums agree, the global value is trustworthy and the per-part breakdown identifies the offending component. A frequent pattern in shell-dominated automotive models is a single thin bracket contributing 60–70% of total hourglass energy while every other part sits below 1%; the fix is usually a local mesh refinement or a switch from reduced to fully integrated shells in that region, not a global change of hourglass coefficient.

The third check concerns sliding energy. SLEOUT separates the friction contribution from the penalty contribution. If the friction term grows smoothly and tracks the relative sliding distance, the energy is physical. If the total sliding energy grows in a staircase pattern while the friction term stays flat, the penalty stiffness is generating spurious work as contact nodes oscillate between penetration and release. Reducing the penalty scale factor or switching to a soft constraint formulation typically removes the staircase. The RCFORC integral provides the independent confirmation: integrate the resultant contact force over the relative displacement of the contacting surfaces and compare with the SLEOUT sliding energy at the same time. Agreement within a few percent validates both files; a large discrepancy points to a contact definition that is not actually active, or to output written at a different interval than assumed.

A worked interpretation example

Consider a 20 ms drop test of a simplified electronics enclosure: an aluminum housing modeled with reduced-integration shells, a PCB modeled with solid elements, and a rigid floor. The GLSTAT curve shows total energy rising to 42 J during the impact and settling at 40 J, with hourglass energy peaking at 3.1 J (7.4% of total) at 6 ms and decaying to 1.2 J by 20 ms. MATSUM attributes 2.4 J of the peak to the housing's side walls, which carry the bending. SLEOUT reports 5.8 J of sliding energy, of which 4.9 J is friction and 0.9 J is penalty work; the RCFORC integral over the contact displacement gives 5.6 J, consistent within 4%. The interpretation is that the model is acceptable but marginal on hourglass: the side walls should be refined or switched to fully integrated shells before the result is used for design decisions, while the sliding energy is predominantly physical friction and needs no corrective action.

This example illustrates the working principle of the energy database: no single file is conclusive. GLSTAT flags the magnitude, MATSUM locates it, SLEOUT classifies it, and RCFORC corroborates it. When the four agree, the energy balance is defensible; when they disagree, the disagreement itself identifies where to look next.