Common Conventions¶

Writers for simple VTK datasets use the same conventions for data associations, names, handles, and collective calls. Mesh-specific array shapes and mesh-writing requirements are described in the corresponding reference chapters.

The caller is responsible for supplying all required mesh and data writes, including complete coverage of datasets written in regions. Closing a file releases resources and finalizes any open time step; it does not certify that the output is complete.

Data Associations and Components¶

Point data supplies one tuple per mesh point.
Cell data supplies one tuple per mesh cell.
Field data supplies values associated with the VTK dataset as a whole, independently of mesh points and cells. See Field Data.

A tuple contains one or more numeric components. Scalar data has one component per tuple; multicomponent data may represent vectors, tensors, or other grouped values. For multicomponent Fortran arrays, the first dimension indexes the components. The remaining dimensions index tuples, using a mesh-dependent layout for point and cell data.

The optional attribute argument to point and cell data creation or registration designates a VTK role, such as Scalars, Vectors, Tensors, or GlobalIds. This is separate from the array’s component count. Blank values are ignored. See the VTK dataset chapters for supported shapes and the VTKHDF specification for the full set of attribute roles. These designations are supported by VTK 9.7.0 and later and ParaView 6.2.0 and later; earlier versions ignore them.

Names and Handles¶

Point, cell, and field data have separate namespaces within each VTK dataset. Names are trimmed; blank names are replaced by a default. The characters /, ., and space are replaced by underscores. Duplicate names, including names that become identical after these substitutions, are made unique by appending a suffix such as _1. The resulting name is what VTK and ParaView see. The original name is written as the Name attribute on the HDF5 dataset for user reference.

Each write by name or temporal registration creates a new dataset. Repeating a name does not select an existing dataset. Where subsequent writes are supported, they identify the dataset by an opaque handle: vtkhdf_cell_data_handle, vtkhdf_point_data_handle, or vtkhdf_field_data_handle. These types are exported by the file-type modules. Store the returned handle and use it only with its owning file.

Collective Calls¶

In MPI builds, all writer methods are collective over the communicator passed to create. All ranks must call the same methods in the same order. Non-distributed arguments, including filenames, modes, names, and attribute designations, must have identical values on all ranks. Distributed arrays and placement arguments may differ as specified by the writer interface. For start_time_step, only rank zero’s time value is used.

Field data has a distinct rule: all ranks supply arguments with matching type, kind, and shape, but only rank zero contributes values.

In serial builds, the same methods are used with the communicator argument omitted from create. Always call close explicitly; automatic Fortran finalization cannot perform collective cleanup.

Writer Modes and Time Stepping¶

Each file-type module exports the mode constants supported by its writer.

Mode	Behavior
`VTKHDF_STATIC`	Fixed mesh and static data; no time stepping. This is the default.
`VTKHDF_FIXED_MESH`	Fixed mesh and static or temporal data.
`VTKHDF_MOVING_MESH`	Fixed topology and temporal geometry; data may be static or temporal as supported by the writer.
`VTKHDF_DYNAMIC_MESH`	Temporal topology, geometry, and point/cell data.

ImageData supports VTKHDF_STATIC and VTKHDF_FIXED_MESH. RectilinearGrid and StructuredGrid additionally support VTKHDF_MOVING_MESH. UnstructuredGrid supports all four modes. In moving-mesh mode, the structured writers also allow static point/cell data; UnstructuredGrid requires temporal point/cell data. Static field data is supported in every writer mode.

Temporal data must be registered before the first start_time_step call. Writes by handle then supply data for the current step. A step is completed by finalize_time_step; starting another step or closing the file also finalizes an open step. Rules for required writes and reuse of omitted values depend on the data association and VTK dataset type and are specified in their reference chapters.