MPCO Recorder and HDF5 Format

This page is a work in progress as of April 25, 2026.

The MPCORecorder in OpenSees saves model and analysis information in HDF5 format. However, unless I’m missing something, documentation for the MPCORecorder is pretty limited. So here are some easy examples and explanations of the recorded data.

Requirements

As of version 3.8.0.0 of openseespy, the HDF5 libraries and MPCORecorder are not included in the pip package. Compiling locally on Linux is not terribly difficult.

The libhdf5-dev package has the libraries to which the MPCORecorder (and a couple other recorders) will link. The hdf5-tools package has useful command line tools for inspecting HDF5 files, but is not necessary for compiling.

sudo apt install libhdf5-dev hdf5-tools

I use Makefiles, not CMake. Modify your Makefile.def to define _HDF5 and to use paths for HDF5_INCLUDE and HDF5_LIBRARY in the same manner as other packages, such as Tcl.

# Add to C++FLAGS
HDF5_FLAG = -D_HDF5

# Add to MACHINE_NUMERICAL_LIBS
HDF5_LIBRARY = /usr/lib/x86_64-linux-gnu/hdf5/serial/libhdf5.so

# Add to INCLUDES
HDF5_INCLUDES = -I/usr/include/hdf5/serial

The h5py package is useful for working with HDF5 files in Python.

python3 -m pip install h5py

Minimal Example

Before moving on to beams, fiber sections, and solid elements, a one-dimensional model with one zero length element will highlight some of the basic information saved in HDF5 format.

import openseespy.opensees as ops
import h5py

ops.wipe()
ops.model('basic','-ndm',1,'-ndf',1)

ops.node(1,0); ops.fix(1,1)
ops.node(2,0)

ops.uniaxialMaterial('Elastic',1,500)

ops.element('zeroLength',1,1,2,'-mat',1,'-dir',1)

# Will create an HDF5 file zl.mpco
ops.recorder('mpco','zl','-N','displacement','-E','material.stress')

ops.timeSeries('Linear',1)
ops.pattern('Plain',1,1)
ops.load(2,100)

ops.analysis('Static','-noWarnings')
ops.analyze(2)

# To close recorder file for subsequent reading
ops.wipe() 

This analysis will record results to a file named zl.mpco. The file format is binary, but we can view the file contents using h5dump.

h5dump -n zl.mpco

The file contains several datasets and groups of datasets.

In Python, we can see the contents using the visit() function from h5py.

data = h5py.File('zl.mpco', 'r')

print(data.visit(print))

You should see the same keys as produced by the h5dump command, but without the additional information of group vs. dataset.

For this example, there are two high level groups: INFO and MODEL_STAGE[1]. The INFO group contains information about the OpenSees version used and the spatial dimension of the model.

print(data['INFO']['SOLVER_NAME']) # OpenSees
print(data['INFO']['SOLVER_VERSION']) # 3.8.0
print(data['INFO']['SPATIAL_DIM']) # 1 (for this MWE)

The MODEL_STAGE[1] group contains information on the nodes and elements of the model along with analysis results.

NODES

The MODEL_STAGE[1]/MODEL/NODES/ID and MODEL_STAGE[1]/MODEL/NODES/COORDINATES datasets contain the node tags and coordinates, respectively.

The number of nodes in the model is obtained from the shape of the ID dataset.

NodeData = data['MODEL_STAGE[1]']['MODEL']['NODES']
Nnodes = NodeData['ID'].shape[0]

We can then loop through the ID and COORDINATES datasets to get the node tags and coordinates.

for i in range(Nnodes):
    tag = NodeData['ID'][i]
    coords = NodeData['COORDINATES'][i]

ELEMENTS

The MODEL_STAGE[1]/MODEL/ELEMENTS group contains information about the type of elements in the model along with each element’s tag and connected nodes.

ElementData = data['MODEL_STAGE[1]']['MODEL']['ELEMENTS']
for key, value in ElementData.items():
    n = value.shape[0]
    print(f"{n} elements of type {key}")
    for j in range(n):
        tag = value[j,0]
        print(f"Element tag: {tag}")
        nodes = value[j,1:]
        print(f"Connected nodes: {nodes}")

For this example, the element key 19-ZeroLength[1:0] is a mashup of three items.

The element class tag defined in SRC/classTags.h, in this case 19.
The class name of the element returned by getClassType(), in this case ZeroLength.
Information about the element integration rule in brackets, in this case [1:0]. This information is important for beam-column and solid elements but can be safely ignored for zero-length elements.

NODE RESULTS

ELEMENT RESULTS

I work on problems related to modeling and nonlinear structural analysis. If these problems are relevant to a current professional project, feel free to reach out.

OpenSees Cloud

OpenSees AMI