Writing a VMAP file#

The VMAPExport Class#

class pylife.vmap.VMAPExport(file_name)[source]#

Write pyLife mesh data and variables to a VMAP file.

Use this class to export a pandas mesh from pyLife to the HDF5-based VMAP format. A geometry stores node coordinates and element connectivity, optional node and element sets describe named subsets, and variables store result fields inside VMAP states for later post-processing in CAE tools.

The input mesh is a DataFrame indexed by element_id and node_id. Coordinate columns x and y are required for two-dimensional meshes; z is used when present for three-dimensional meshes. Variables are read from mesh columns such as dx, dy, dz for DISPLACEMENT or S11 through S23 for STRESS_CAUCHY. Numeric values are written as provided, so units follow the pyLife data and the originating finite-element model.

Parameters:

file_name (str) – Path to the VMAP file to create. Existing files are overwritten by h5py in write mode.

Raises:

OSError – Raised when the VMAP file cannot be created. A partially created file is removed before the exception is re-raised.

See also

pylife.vmap.VMAPImport

Read VMAP geometry and variables into pandas.

Examples

exporter = VMAPExport("results.vmap")
(
    exporter
    .add_geometry("1", mesh)
    .add_variable("STATE-1", "1", "DISPLACEMENT", mesh)
    .add_variable("STATE-1", "1", "STRESS_CAUCHY", mesh)
)
add_element_set(geometry_name, indices, mesh, name=None)[source]#

Add a named element set to an existing geometry.

Parameters:

  • geometry_name (str) – Name of the VMAP geometry that receives the set.

  • indices (pandas.Index) – Element ids to include in the set. Every id must be present in mesh.

  • mesh (pandas.DataFrame) – Mesh whose element_id index level defines the valid element ids.

  • name (str, optional) – User-visible value of the VMAP MYSETNAME attribute. If omitted, an empty string is written. Default is None.

Returns:

The exporter itself to allow fluent method chaining.

Return type:

VMAPExport

Raises:

  • KeyError – Raised when an id in indices is not present in mesh or the geometry does not exist.

  • TypeError – Raised when name is not a string.

  • VMAPExportError – Raised when writing the VMAP geometry set fails.

add_geometry(geometry_name, mesh)[source]#

Add a geometry from a pyLife mesh to the VMAP file.

The geometry contains node coordinates and element connectivity. The mesh must be indexed by element_id and node_id and must contain coordinate columns x and y; column z is written when present.

Parameters:

  • geometry_name (str) – Name of the VMAP geometry to create.

  • mesh (pandas.DataFrame) – Mesh to export. The frame must contain one row per element-node pair and coordinate columns in the length unit used by the model.

Returns:

The exporter itself to allow fluent method chaining.

Return type:

VMAPExport

Raises:

  • KeyError – Raised when geometry_name already exists.

  • VMAPExportError – Raised when geometry creation fails. The partially created geometry is removed before the exception is re-raised.

add_integration_types(content)[source]#

Add VMAP integration type definitions to the system group.

Parameters:

content (dict) – Mapping of integration type keys to constructor arguments for VMAPIntegrationType.

Returns:

The exporter itself to allow fluent method chaining.

Return type:

VMAPExport

Raises:

  • KeyError – Raised when the VMAP integration type dataset already exists.

  • VMAPExportError – Raised when writing the system dataset fails.

add_node_set(geometry_name, indices, mesh, name=None)[source]#

Add a named node set to an existing geometry.

Parameters:

  • geometry_name (str) – Name of the VMAP geometry that receives the set.

  • indices (pandas.Index) – Node ids to include in the set. Every id must be present in mesh.

  • mesh (pandas.DataFrame) – Mesh whose node_id index level defines the valid node ids.

  • name (str, optional) – User-visible value of the VMAP MYSETNAME attribute. If omitted, an empty string is written. Default is None.

Returns:

The exporter itself to allow fluent method chaining.

Return type:

VMAPExport

Raises:

  • KeyError – Raised when an id in indices is not present in mesh or the geometry does not exist.

  • TypeError – Raised when name is not a string.

  • VMAPExportError – Raised when writing the VMAP geometry set fails.

add_variable(state_name, geometry_name, variable_name, mesh, column_names=None, location=None)[source]#

Add a result variable to a state and geometry.

The variable values are taken from columns in mesh and written below the VMAP VARIABLES group. When the state or state-specific geometry group does not yet exist, it is created automatically. Known pyLife variables use predefined column names and VMAP locations; custom variables require explicit column_names and may require an explicit location.

Parameters:

  • state_name (str) – Name of the VMAP state, usually a load step or increment such as STATE-1.

  • geometry_name (str) – Name of the VMAP geometry that owns the variable.

  • variable_name (str) – Name of the VMAP variable to create, for example DISPLACEMENT or STRESS_CAUCHY.

  • mesh (pandas.DataFrame) – Mesh containing the columns to export. For nodal variables one value per node_id is written; for element-nodal variables the values are written for the mesh rows.

  • column_names (list of str, optional) – Mesh columns to export for variable_name. If omitted, predefined pyLife column names are used for known variables. Default is None.

  • location (enum.Enum, optional) – VMAP variable location. Use VariableLocations.NODE for nodal data or VariableLocations.ELEMENT_NODAL for element-nodal data. If omitted, the predefined location for a known variable is used. Default is None.

Returns:

The exporter itself to allow fluent method chaining.

Return type:

VMAPExport

Raises:

  • KeyError – Raised when geometry_name does not exist, the variable already exists, or no predefined column names are available.

  • APIUseError – Raised when location is missing for an unknown variable or is not a VariableLocations value.

  • VMAPExportError – Raised when writing the variable fails. The partially created variable is removed before the exception is re-raised.

Notes

Only nodal and element-nodal variables are supported by the current export implementation. Values are written without unit conversion.

property file_name#

Return the path of the VMAP file being written.

Returns:

Path passed to VMAPExport during construction.

Return type:

str

set_group_attribute(object_path, key, value)[source]#

Set an attribute on an existing VMAP HDF5 object.

Parameters:

  • object_path (str) – Absolute path of the VMAP group or dataset whose attribute is written.

  • key (str) – Name of the attribute to create.

  • value (numpy.dtype) – Attribute value to store. The value must be accepted by h5py.AttributeManager.create().

Raises:

KeyError – Raised when object_path does not exist in the VMAP file.

variable_column_names(parameter_name)[source]#

Return pyLife column names for a VMAP variable.

Parameters:

parameter_name (str) – VMAP variable name, for example DISPLACEMENT or STRESS_CAUCHY.

Returns:

Column names expected in the mesh for parameter_name.

Return type:

list of str

Raises:

KeyError – Raised when parameter_name is not a predefined VMAP variable in pyLife.

Examples

>>> from pylife.vmap import VMAPExport
>>> VMAPExport.variable_column_names(None, "DISPLACEMENT")
['dx', 'dy', 'dz']

In practice the method is called on an export object, e.g. export.variable_column_names("STRESS_CAUCHY").

variable_location(parameter_name)[source]#

Return the predefined VMAP location for a variable.

Parameters:

parameter_name (str) – VMAP variable name, for example DISPLACEMENT or STRESS_CAUCHY.

Returns:

VMAP location used by pyLife for the variable, such as nodal or element-nodal data.

Return type:

enum.Enum

Raises:

KeyError – Raised when parameter_name is not a predefined VMAP variable in pyLife.