dolfinx.io#

Tools for file input/output (IO).

Functions

distribute_entity_data(mesh, entity_dim, ...)

Distribute mesh entities and values to owning process.

Classes

VTKFile(comm, filename, mode)

Interface to VTK files.

XDMFFile(comm, filename, file_mode[, encoding])

Interface to manage XDMF files.

VTXMeshPolicy(*values)

VTXWriter(comm, filename, output[, engine, ...])

Writer for VTX files, using ADIOS2 to create the files.
class dolfinx.io.VTKFile(comm: Comm, filename: str | Path, mode: str)[source]#

Bases: object

Interface to VTK files.

VTK supports arbitrary order Lagrange finite elements for the geometry description. XDMF is the preferred format for geometry order <= 2.

Open a VTK file.

Parameters:

  • comm – MPI communicator used when opening the file.

  • filename – Name of the file to open.

  • mode – File opening mode, e.g. "w" for writing.

close()[source]#

Close the VTK file.

write_function(u: list[Function] | Function, t: float = 0.0) → None[source]#

Write a functions to file with a given time.

write_mesh(mesh: Mesh, t: float = 0.0) → None[source]#

Write mesh to file for a given time.

class dolfinx.io.VTXMeshPolicy(*values)#

Bases: Enum

reuse = 1#
update = 0#
class dolfinx.io.VTXWriter(comm: Comm, filename: str | Path, output: Mesh | Function | list[Function] | tuple[Function], engine: str = 'BPFile', mesh_policy: VTXMeshPolicy = VTXMeshPolicy.update)[source]#

Bases: object

Writer for VTX files, using ADIOS2 to create the files.

VTX supports arbitrary order Lagrange finite elements for the geometry description and arbitrary order (discontinuous) Lagrange finite elements for Functions.

The files can be viewed using Paraview.

Initialize a writer for outputting data in the VTX format.

Parameters:

  • comm – The MPI communicator

  • filename – The output filename

  • output – The data to output. Either a mesh, a single (discontinuous) Lagrange Function or list of (discontinuous) Lagrange Functions.

  • engine – ADIOS2 engine to use for output. See ADIOS2 documentation for options.

  • mesh_policy – Controls if the mesh is written to file at the first time step only when a Function is written to file, or is re-written (updated) at each time step. Has an effect only for Function output.

Note

All Functions for output must share the same mesh and have the same element type.

close()[source]#

Close the VTX file.

write(t: float)[source]#

Write data to file for a given time.

class dolfinx.io.XDMFFile(comm: Comm, filename: str | Path, file_mode: str, encoding: Encoding = Encoding.HDF5)[source]#

Bases: object

Interface to manage XDMF files.

Open an XDMF file.

Parameters:

  • comm – MPI communicator used when opening the file.

  • filename – Name of the file to open.

  • file_mode – File opening mode, e.g. "r" for reading or "w" for writing.

  • encoding – File encoding.

class Encoding(*values)#

Bases: Enum

ASCII = 1#
HDF5 = 0#
close()[source]#

Close the XDMF file.

property comm: Comm#

MPI communicator that the file was opened with.

flush() → None[source]#

Flush any buffered data to file.

read_cell_type(name: str = 'mesh', xpath: str = '/Xdmf/Domain') → tuple[CellType, int][source]#

Read the cell type and polynomial degree for a mesh from file.

Parameters:

  • name – Name of the grid node in the xml-scheme in the file.

  • xpath – XPath where the Mesh Grid is stored in the file.

Returns:

Cell type and polynomial degree.

read_geometry_data(name: str = 'mesh', xpath: str = '/Xdmf/Domain') → ndarray[tuple[Any, ...], dtype[float64]][source]#

Read geometry (node coordinates) data for a mesh from file.

Parameters:

  • name – Name of the grid node in the xml-scheme in the file.

  • xpath – XPath where the Mesh Grid is stored in the file.

Returns:

Node coordinates.

read_information(name: str, xpath: str = '/Xdmf/Domain') → str[source]#

Read information from file.

Parameters:

  • name – Name of the key to read.

  • xpath – XPath where the information is stored in the file.

Returns:

Value associated with name.

read_mesh(ghost_mode=GhostMode.shared_facet, name='mesh', xpath='/Xdmf/Domain', max_facet_to_cell_links: int = 2) → Mesh[source]#

Read mesh data from file.

Note

Changing max_facet_to_cell_links from the default value should only be required when working on branching manifolds. Changing this value on non-branching meshes will only result in a slower mesh partitioning and creation.

Parameters:

  • ghost_mode – Ghost mode to use for the cells in mesh creation.

  • name – Name of the grid node in the xml-scheme in the file

  • xpath – XPath where Mesh Grid is stored in the file.

  • max_facet_to_cell_links – Maximum number of cells that a facet can be linked to.

read_meshtags(mesh: Mesh, name: str, attribute_name: str | None = None, xpath: str = '/Xdmf/Domain') → MeshTags[source]#

Read mesh tags with name given in the XMDF file.

Parameters:

  • mesh – Mesh that the input data is defined on.

  • name – Name of the grid node in the xml-scheme of the XDMF-file.

  • attribute_name – The name of the attribute to read. If attribute_name is empty, reads the first attribute in the file. If attribute_name is not empty but no attributes have the provided name, throws an error. If multiple attributes have the provided name, reads the first one found.

  • xpath – XPath where MeshTags Grid is stored in file.

Returns:

A MeshTags object containing the requested data read from file.

read_topology_data(name: str = 'mesh', xpath: str = '/Xdmf/Domain') → ndarray[tuple[Any, ...], dtype[int64]][source]#

Read topology (cell connectivity) data for a mesh from file.

Parameters:

  • name – Name of the grid node in the xml-scheme in the file.

  • xpath – XPath where the Mesh Grid is stored in the file.

Returns:

Cell connectivity data.

write_function(u: Function, t: float = 0.0, mesh_xpath="/Xdmf/Domain/Grid[@GridType='Uniform'][1]")[source]#

Write function to file for a given time.

Note

Function is interpolated onto the mesh nodes, as a Nth order Lagrange function, where N is the order of the coordinate map. If the Function is a cell-wise constant, it is saved as a cell-wise constant.

Parameters:

  • u – Function to write to file.

  • t – Time associated with Function output.

  • mesh_xpath – Path to mesh associated with the Function in the XDMFFile.

write_geometry(geometry: Geometry, name: str = 'geometry', xpath: str = '/Xdmf/Domain') → None[source]#

Write mesh geometry to file.

Parameters:

  • geometry – Mesh geometry to write.

  • name – Name of the grid node in the xml-scheme in the file.

  • xpath – XPath where the Geometry Grid is stored in the file.

write_information(name: str, value: str, xpath: str = '/Xdmf/Domain') → None[source]#

Write information key-value pair to file.

Parameters:

  • name – Name of the key.

  • value – Value of the key.

  • xpath – XPath where the information is stored in the file.

write_mesh(mesh: Mesh, xpath: str = '/Xdmf/Domain') → None[source]#

Write mesh to file.

write_meshtags(tags: MeshTags, x: Geometry, geometry_xpath: str = '/Xdmf/Domain/Grid/Geometry', xpath: str = '/Xdmf/Domain') → None[source]#

Write mesh tags to file.

dolfinx.io.distribute_entity_data(mesh: Mesh, entity_dim: int, entities: ndarray[tuple[Any, ...], dtype[int64]], values: ndarray) → tuple[ndarray[tuple[Any, ...], dtype[int64]], ndarray][source]#

Distribute mesh entities and values to owning process.

The entities are described by the global vertex indices of the mesh. These entity indices are using the original input ordering.

Returns:

Entities owned by the process (and their local entity-to-vertex indices) and the corresponding values.