binout

MATLAB functions to work with LS-DYNA binout files:

• The function get_binout_data(), called the binout reader, reads result (or state) data from the binout file.
• The function get_d3plot_d3thdt_control_data() is a helper function and is called (internally) from within the binout reader function to retrieve important control data from the root d3plot file (if available)
• The function struct2graph() is a standalone function and can be used (for convenience) to graphically display the content and hierarchy of a nested MATALB struct.

The MATLAB source files of the functions are in the src folder. Additionally, sample LS-DYNA files are provided in the LS-DYNA-sample folder. You can download these files (note: the provided sample binout file is about 78 MB) and use the MATLAB script test1.m in the src folder to get started.

The binout Reader Function

What It Does?

The function get_binout_data() takes the path to an LS-DYNA binout file and returns a MATLAB struct variable containing all the data in the binout file. You can immediately work with the data in MATLAB.

What Is a binout?

A binout is a binary file generated by LS-DYNA after running an LS-DYNA model, and it contains various result databases, such as "matsum" (for material summary, like energy and rigid body velocities' data), "nodout" (for nodal data, like displacements and velocities), "elout" (for element data, like stresses, stress-resultants, and strains), and so on. See how to get a binout file? for detail.

Usage

The formal syntax is

[binin] = get_binout_data(binout_filename)

Input:

Argument	Type	Description	Required?
binout_filename	[char|string]	(relative or absolute) path of the root binout file	Yes

*There is only 1 input argument.

The root binout file is the first if there are more than one binout file. The function is configured to auto-detect and read all files sequentially. Data from these files will be joined.

Output:

Argument	Type	Description	Required?
binin	scalar MATLAB struct	A MATLAB structure containing all result data in the binout file(s)	-

*There is only 1 output argument.

This is a scalar but highly nested structure. Use the "." (dot) indexing method in MATLAB to traverse the binin structure to arrive at a data of interest. The returned binin structure will have n root fields, where (n-1) is the number of databases contained in the binout file(s), such as "matsum", "nodout", etc. The last n^th field (when available) is called "control".

Further Details:

On the Interpretation of Data in the binin

Every directory (and sub-directory) in the original binout becomes a field (and sub-field) in the returned binin. All fields of the main binin structure are scalar structures themselves. In general, each of these structures contains exactly two fields: "data" and "metadata", each of which is also a structure. The fields of the "data" structure are the actual result (or state) data of interest. Among the fields of the "metadata" structure is a field called "ids" that stores the IDs of the model entities, e.g. nodes, parts, etc. However, some fields of the binin have intermediate structures under them, and the "data" and "metadata" are fields of those intermediate structures.

For example, the "binin.matsum" structure will have the fields metadata and data as its immediate fields. On the other hand, the "binin.elout" structure will contain intermediate fields like "shell", "solid", etc. In this case, the "metadata" and "data" structures are fields of "binin.elout.shell", "binin.elout.solid", and so on. See the figs/graphs folder, for the content and organisation of a sample binin struct.

The root field "control" under the binin structure contains supplementary control data retrieved from the root d3plot file, which is provided by (internally) calling the get_d3plot_d3thdt_control_data() helper function. The binout reader function will auto-detect the root d3plot file. Among the control data retrieved are the element-node connectivity arrays and some others (like the initial geometry and useful info about the model).

The values associated with the fields of the data structure are, in general, 2D arrays except "time" (which is always a column vector). Rows of the 2D arrays correspond to time instants (so that the number of rows equals the number of entries of the time vector). The columns of the 2D arrays correspond to the IDs of the entities (like parts, nodes, etc), which (again) are generally found in the "metadata" structure. However, the IDs of elements and contacts are stored directly in the "data" structure itself. The columns of the 2D arrays in the "data" structure in the sub-fields of the "elout" (say "elout.shell") correspond to elements IDs (stored in "ids") and their integration points (the number of which is stored in a field called "nip").

In general, fields' names in "data" and "metadata" are explicit and self-explanatory (e.g. "kinetic_energy", "time", "x_velocity", "x_displacement", etc). Although, a few fields in the "data" structure for the substructures of "elout" are abbreviated. Stresses are abbreviated by "sig_xx", "sig_xy", etc ("sig" for "sigma"), and, strains are abbreviated by "eps_xx" and so on ("eps" for "epsilon").

Lastly, the structuring and naming of fields are directly borrowed from the binout file. So, if one is already familiar with opening binout files in LS-PrePost, then there is no need to make further explanation as, in this case, the binin structure should be very familiar too.

The figs/graphs folder contains several example contents (as visual graphs) of a sample binin structure and its children.

Optional Feature

If needed, one can use the standalone function struct2graph() to visually display the hierarchy map of the binin structure. The function accepts a scalar (possibly highly nested) MATLAB structure as the first input argument, and it produces the figures and returns their handles as output. The sample graphs in the figs/graphs folder were generated by this function.

How to Get a binout File?

To make LS-DYNA write the results of your interest to one (or more) binout file(s), follow the following steps:

1. In the input keyword file, add one or more database keywords of the form *database_<option>, where <option> is the database type, e.g. matsum, nodout, etc.
   • In each database keyword, set the value of BINARY (second field of first card) to 2, to tell LS-DYNA to add this database to the binout file.
2. For certain kinds of database types, you need to add some additional database keywords to activate those database types. See lsdyna_database for more details.
3. Run your model, and LS-DYNA should generate one (or more) binout files.

The first of these files is named as binout, which is called the root file. The number of generated binout files, by default, is about ceil(overallSize/1), where overallSize is the total size of requested data in gigabytes (GB).

Note

We would like to explain choosing the word "binin": it is meant to be read as BIN-ary output of ls-dyna IN matlab. That is, binin contains the output (or results) from LS-DYNA.

Motivation

The work is shared to:

• Help engineers and researchers ❤️ to easily work with LS-DYNA results. So, please let us know (in issues or discussions) if you encounter any problem or if you need additional clarifications.
• Enrich MATLAB by affording a tool to import real-world data from world-class FE solver (LS-DYNA).
• Extend LS-DYNA by allowing users to make use of the powerful tools in MATLAB to perform additional post-processing calculations and generate graphics with publication-quality to share with others.

We hope the work will be useful and will take a little leap to advance the post-processing.

Contributions

This work is part of a PhD study at The Blast and Impact Dynamics Research Group, at The University of Sheffield (2024).

The source code of the MATLAB functions, included in this repo, are also published in The University of Sheffield's online research data (ORDA) repository and are publicly available at: https://doi.org/10.15131/shef.data.26018836

Supervised by:

• Prof. Andrew Tyas ([email protected])
• Dr. Samuel E. Rigby ([email protected]; @Dr_SamRigby)
• Dr. Maurizio Guadagnini ([email protected])

Developed by:

• Dr. Samuel E. Rigby ([email protected];@Dr_SamRigby)
• Saud A. E. Alotaibi ([email protected]; [email protected]; @saudbinayed), sponsored by Qassim University, Saudi Arabia, and the Saudi Arabian Cultural Bureau in London, the United Kingdom.

Sponsors: