Reading a VMAP file#

The most common use case is to get the element nodal stress tensor for a certain geometry 1 and a certain load state STATE-2 out of the vmap file. The vmap interface provides you the nodal geometry (node coordinates), the mesh connectivity index and the field variables.

You can retrieve a DataFrame of the mesh with the desired variables in just one statement.

>>> import pylife.vmap
>>> (pylife.vmap.VMAPImport('demos/plate_with_hole.vmap')
...  .make_mesh('1', 'STATE-2')
...  .join_coordinates()
...  .join_variable('STRESS_CAUCHY')
...  .join_variable('E')
...  .to_frame())
                            x         y    z        S11       S22  S33        S12  S13  S23       E11       E22  E33       E12  E13  E23
element_id node_id
1          1734     14.897208  5.269875  0.0  27.080811  6.927080  0.0 -13.687358  0.0  0.0  0.000119 -0.000006  0.0 -0.000169  0.0  0.0
           1582     14.555333  5.355806  0.0  28.319006  1.178649  0.0 -10.732705  0.0  0.0  0.000133 -0.000035  0.0 -0.000133  0.0  0.0
           1596     14.630658  4.908741  0.0  47.701195  5.512213  0.0 -17.866833  0.0  0.0  0.000219 -0.000042  0.0 -0.000221  0.0  0.0
           4923     14.726271  5.312840  0.0  27.699907  4.052865  0.0 -12.210032  0.0  0.0  0.000126 -0.000020  0.0 -0.000151  0.0  0.0
           4924     14.592996  5.132274  0.0  38.010101  3.345431  0.0 -14.299768  0.0  0.0  0.000176 -0.000038  0.0 -0.000177  0.0  0.0
...                       ...       ...  ...        ...       ...  ...        ...  ...  ...       ...       ...  ...       ...  ...  ...
4770       3812    -13.189782 -5.691876  0.0  36.527439  2.470588  0.0 -14.706686  0.0  0.0  0.000170 -0.000040  0.0 -0.000182  0.0  0.0
           12418   -13.560289 -5.278386  0.0  32.868889  3.320898  0.0 -14.260107  0.0  0.0  0.000152 -0.000031  0.0 -0.000177  0.0  0.0
           14446   -13.673285 -5.569107  0.0  34.291058  3.642457  0.0 -13.836027  0.0  0.0  0.000158 -0.000032  0.0 -0.000171  0.0  0.0
           14614   -13.389065 -5.709927  0.0  36.063541  2.828889  0.0 -13.774759  0.0  0.0  0.000168 -0.000038  0.0 -0.000171  0.0  0.0
           14534   -13.276068 -5.419206  0.0  33.804211  2.829817  0.0 -14.580153  0.0  0.0  0.000157 -0.000035  0.0 -0.000181  0.0  0.0

[37884 rows x 15 columns]

The example is shown as a transcript because it needs the demo VMAP file demos/plate_with_hole.vmap from the pyLife repository.

Supported features#

So far the following data can be read from a vmap file

Geometry#

node positions
node element index

Field variables#

Any field variables can be read and joined to the node element index from the following locations:

element
node
element nodal

In particular, field variables at integration point location cannot cannot be read, as that would require extrapolating them to the node positions. This functionality is not available in pyLife.

The VMAPImport Class#

class pylife.vmap.VMAPImport(filename)[source]#

Read VMAP geometry and result variables into a pandas mesh.

Use this class to bring finite-element results from a .vmap file into pyLife. A VMAP file contains one or more geometries, load states, and variables. A geometry defines node coordinates and element connectivity, a state represents a load step or increment, and variables are result fields such as DISPLACEMENT, STRESS_CAUCHY, or E.

The usual workflow is to open the file, inspect available geometries and states, create a mesh with make_mesh(), add coordinates with join_coordinates(), add one or more variables with join_variable(), and finish with to_frame(). The returned DataFrame is indexed by element_id and node_id where element-nodal data is present and can be used by the pylife.mesh accessors. Coordinate units, stress units, and all other physical units follow the originating finite-element model; pyLife does not convert them during import.

Parameters:: filename (str) – Path to the VMAP file to read.
Raises:: Exception – Raised by h5py when the file cannot be opened or read.

See also

pylife.vmap.VMAPExport: Write pyLife mesh data and variables to VMAP.

Examples

import pylife.vmap as vmap

mesh = (
    vmap.VMAPImport("demos/plate_with_hole.vmap")
    .make_mesh("1", "STATE-2")
    .join_coordinates()
    .join_variable("STRESS_CAUCHY")
    .to_frame()
)

element_sets(geometry)[source]#

List element set names for a geometry.

Parameters:: geometry (str) – Name of the VMAP geometry whose element sets are requested.
Returns:: View of element set names defined for geometry. Use these names with filter_element_set() to restrict the current mesh to selected elements.
Return type:: dict_keys
Raises:: KeyError – Raised when geometry is not present or the VMAP geometry set data is malformed.

filter_element_set(element_set)[source]#

Restrict the working mesh to an element set.

Parameters:

element_set (str) – Name of the VMAP element set in the current geometry.

Returns:

The importer itself to allow fluent method chaining.

Return type:

VMAPImport

Raises:

APIUseError – Raised when make_mesh() has not been called before filtering.
KeyError – Raised when element_set is not defined for the current geometry.

filter_node_set(node_set)[source]#

Restrict the working mesh to a node set.

Parameters:

node_set (str) – Name of the VMAP node set in the current geometry.

Returns:

The importer itself to allow fluent method chaining.

Return type:

VMAPImport

Raises:

APIUseError – Raised when make_mesh() has not been called before filtering.
KeyError – Raised when node_set is not defined for the current geometry.

geometries()[source]#

List geometry names stored in the VMAP file.

Returns:: View of the VMAP geometry names. Pass one of these names to make_mesh(), nodes(), node_sets(), or element_sets().
Return type:: KeysView

join_coordinates()[source]#

Join node coordinates to the working mesh.

The added columns are x, y, and z. Values use the length unit of the source finite-element model, commonly millimetres.

Returns:

The importer itself to allow fluent method chaining.

Return type:

VMAPImport

Raises:

APIUseError – Raised when make_mesh() has not been called before joining coordinates.
KeyError – Raised when the current geometry does not contain the expected coordinate datasets.

Examples

mesh = (
    VMAPImport("demos/plate_with_hole.vmap")
    .make_mesh("1")
    .join_coordinates()
    .to_frame()
)

join_variable(var_name, state=None, column_names=None)[source]#

Join a VMAP result variable to the working mesh.

Variables are result fields stored for a geometry and state. Typical VMAP variables are DISPLACEMENT for nodal displacement, STRESS_CAUCHY for Cauchy stress, and E for strain. Their numeric units follow the source finite-element model; stresses are commonly stored in MPa.

Parameters:

var_name (str) – Name of the VMAP variable to join.
state (str, optional) – Name of the state from which to read var_name. If omitted, the state set by make_mesh() or by the previous join_variable() call is used. Default is None.
column_names (list of str, optional) – Column names to use in the returned DataFrame. The list length must match the VMAP variable dimension. If omitted, pyLife uses predefined names for known variables. Default is None.

Returns:

The importer itself to allow fluent method chaining.

Return type:

VMAPImport

Raises:

APIUseError – Raised when make_mesh() has not been called or no state is known.
KeyError – Raised when the geometry, state, or variable is not present, or when no predefined column names exist for var_name and column_names is not supplied.
ValueError – Raised when column_names does not match the variable dimension.
FeatureNotSupportedError – Raised when the VMAP variable location is not node, element, or element- nodal data.

Notes

When column_names is omitted, pyLife uses these predefined names:

DISPLACEMENT: dx, dy, dz.
STRESS_CAUCHY: S11, S22, S33, S12, S13, S23.
E: E11, E22, E33, E12, E13, E23.

Todo

Move the central definition of pyLife VMAP column names into user documentation.

Examples

mesh = (
    VMAPImport("demos/plate_with_hole.vmap")
    .make_mesh("1")
    .join_variable("DISPLACEMENT", "STATE-1")
    .join_variable("STRESS_CAUCHY", "STATE-2")
    .join_variable("E")
    .to_frame()
)

make_mesh(geometry, state=None)[source]#

Create the working mesh for a geometry and optional state.

The working mesh contains the element-to-node connectivity as a pandas MultiIndex with levels element_id and node_id. Subsequent calls to filter_node_set(), filter_element_set(), join_coordinates(), and join_variable() operate on this mesh until to_frame() returns it and resets the importer.

Parameters:

geometry (str) – Name of the VMAP geometry to use.
state (str, optional) – Name of the VMAP state to use for following join_variable() calls. If omitted, pass a state to the first join_variable() call. Default is None.

Returns:

The importer itself to allow fluent method chaining.

Return type:

VMAPImport

Raises:

KeyError – Raised when geometry is not present or the VMAP connectivity data is malformed.

See also

pylife.vmap.VMAPImport.join_coordinates: Add node coordinates to the mesh.
pylife.vmap.VMAPImport.join_variable: Add a VMAP result variable to the mesh.
pylife.vmap.VMAPImport.to_frame: Return the finished pandas mesh.

Examples

mesh = (
    VMAPImport("demos/plate_with_hole.vmap")
    .make_mesh("1", "STATE-2")
    .join_coordinates()
    .join_variable("STRESS_CAUCHY")
    .to_frame()
)

node_sets(geometry)[source]#

List node set names for a geometry.

Parameters:: geometry (str) – Name of the VMAP geometry whose node sets are requested.
Returns:: View of node set names defined for geometry. Use these names with filter_node_set() to restrict the current mesh to selected nodes.
Return type:: dict_keys
Raises:: KeyError – Raised when geometry is not present or the VMAP geometry set data is malformed.

nodes(geometry)[source]#

Retrieve the node positions.

Parameters:: geometry (str) – Name of the VMAP geometry whose node coordinates are requested.
Returns:: Node coordinate table indexed by node_id with columns x, y, and z. Coordinate values use the length unit of the source finite- element model, commonly millimetres.
Return type:: pandas.DataFrame
Raises:: KeyError – Raised when geometry is not present or the VMAP file does not contain the expected coordinate datasets.

states()[source]#

List state names stored in the VMAP file.

Returns:: View of the VMAP state names. A state represents a load step or increment and can be passed to make_mesh(), variables(), or join_variable().
Return type:: KeysView

to_frame()[source]#

Return the completed mesh and reset the importer.

Returns:: Mesh data joined so far. The frame is usually indexed by element_id and node_id and contains any coordinates or variable columns added to the working mesh.
Return type:: pandas.DataFrame
Raises:: APIUseError – Raised when make_mesh() has not been called or the working mesh has already been returned.

Notes

Calling this method clears the working mesh. Call make_mesh() again to start importing another geometry, state, or filtered subset.

try_get_geometry_set(geometry_name, geometry_set_name)[source]#

Read a geometry set without raising if it is absent.

Parameters:

geometry_name (str) – Name of the geometry the set belongs to.
geometry_set_name (str) – Name of the geometry set to read.

Returns:

The node or element IDs of the geometry set, or None if the set does not exist in the VMAP file.

Return type:

pandas.Index or None

See also

try_get_vmap_object: Read an arbitrary VMAP group without raising.

try_get_vmap_object(group_full_path)[source]#

Read a VMAP group or dataset without raising if it is absent.

Parameters:: group_full_path (str) – Full path of the group inside the VMAP file, e.g. '/VMAP/GEOMETRY/1'.
Returns:: The requested HDF5 object, or None if the path does not exist.
Return type:: h5py.Group or h5py.Dataset or None

See also

try_get_geometry_set: Read a geometry set without raising.

variables(geometry, state)[source]#

List variable names for a geometry and state.

Parameters:

geometry (str) – Name of the VMAP geometry to inspect.
state (str) – Name of the VMAP state to inspect.

Returns:

Names of result variables available for the geometry and state combination, for example DISPLACEMENT or STRESS_CAUCHY.

Return type:

list of str

Raises:

KeyError – Raised when geometry or state is unknown, or when the state does not contain data for the geometry.