cashocs.io.mesh#

Mesh input and output.

Functions

check_mesh_compatibility(mesh, ...)

Checks, whether the supplied mesh file is compatible with the mesh used.

cli_convert([argv])

Converts a Gmsh .msh file to a .xdmf mesh file.

convert(input_file[, output_file, mode, quiet])

Converts the input mesh file to a xdmf mesh file for cashocs to work with.

create_point_representation(dim, points, ...)

Creates the representation of the mesh coordinates for gmsh .msh file.

export_mesh(mesh, mesh_file[, subdomains, ...])

Exports a mesh (together with its subdomains and boundaries).

extract_mesh_from_xdmf(xdmffile[, ...])

Extracts a Gmsh mesh file from an XDMF state file.

gather_coordinates(mesh)

Gathers the mesh coordinates on process 0 to write out the mesh to a Gmsh file.

import_mesh(mesh_file[, comm])

Imports a mesh file for use with cashocs / FEniCS.

parse_file(original_msh_file, out_msh_file, ...)

Parses the mesh file and writes a new, corresponding one.

read_mesh_from_xdmf(filename[, step, comm])

Reads a mesh from a .xdmf file containing a checkpointed function.

write_out_mesh(mesh, original_msh_file, ...)

Writes out mesh as Gmsh .msh file.

Classes

NamedMeasure(*args, **kwargs)

A named integration measure, which can use strings for defining subdomains.

cashocs.io.mesh.check_mesh_compatibility(mesh, original_mesh_file)[source]#

Checks, whether the supplied mesh file is compatible with the mesh used.

This function returns None if they are compatible and raises an exception otherwise.

Parameters:
  • mesh (fenics.Mesh) – The mesh that is currently used.

  • original_mesh_file (str) – The path to the mesh file.

Return type:

None

cashocs.io.mesh.convert(input_file, output_file=None, mode='physical', quiet=False)[source]#

Converts the input mesh file to a xdmf mesh file for cashocs to work with.

Parameters:
  • input_file (str) – A gmsh .msh file.

  • output_file (str | None) – The name of the output .xdmf file or None. If this is None, then a file name.msh will be converted to name.xdmf, i.e., the name of the input file stays the same

  • quiet (bool) – A boolean flag which silences the output.

  • mode (str) – The mode which is used to define the subdomains and boundaries. Should be one of ‘physical’ (the default), ‘geometrical’, or ‘none’.

Return type:

None

cashocs.io.mesh.create_point_representation(dim, points, idcs, subwrite_counter)[source]#

Creates the representation of the mesh coordinates for gmsh .msh file.

Parameters:
  • dim (int) – Dimension of the mesh.

  • points (ndarray) – The array of the mesh coordinates.

  • idcs (ndarray) – The list of indices of the points for the current element.

  • subwrite_counter (int) – A counter for looping over the indices.

Returns:

A string representation of the mesh coordinates.

Return type:

str

cashocs.io.mesh.export_mesh(mesh, mesh_file, subdomains=None, boundaries=None, comm=None)[source]#

Exports a mesh (together with its subdomains and boundaries).

This is useful so that the mesh can be reimported later on again. This is used for checkpointing in cashocs, but also has other use cases, e.g., storing a function on hard disk and later reimporting it to perform a post-processing.

Parameters:
  • mesh (fenics.Mesh) – The fenics mesh which shall be exported.

  • mesh_file (str) – Filename / path to the exported mesh. Has to end in .xdmf. Boundaries and subdomains will be named accordingly.

  • subdomains (Optional[fenics.MeshFunction]) – The subdomains meshfunction corresponding to the mesh. Optional, default is None, so that no subdomain information is used.

  • boundaries (Optional[fenics.MeshFunction]) – The boundaries meshfunction corresponding to the mesh. Optional, default is None, so that no boundary information is used.

  • comm (Optional[MPI.Comm]) – The MPI communicator used. Optional, default is None, so that the fenics.MPI.comm_world is used.

Return type:

None

cashocs.io.mesh.extract_mesh_from_xdmf(xdmffile, iteration=0, outputfile=None, original_gmsh_file=None, quiet=False)[source]#

Extracts a Gmsh mesh file from an XDMF state file.

Parameters:
  • xdmffile (str) – The path to the XDMF state file.

  • iteration (int) – The iteration of interest (for a time series saved in the XDMF file), default is 0.

  • outputfile (str | None) – The path to the output Gmsh file. The default is None in which case the output is saved in the same directory as the XDMF state file.

  • original_gmsh_file (str | None) – The original gmsh .msh file used to create the mesh. This can be used to generate output files which preserve, e.g., physical tags and only updates the nodal positions. This will not work if the geometry has been remeshed. The default is None, which uses a more robust (but less detailed) approach.

  • quiet (bool) – When this is set to True, verbose output is disabled. Default is False.

Return type:

None

cashocs.io.mesh.gather_coordinates(mesh)[source]#

Gathers the mesh coordinates on process 0 to write out the mesh to a Gmsh file.

Parameters:

mesh (fenics.Mesh) – The corresponding mesh.

Returns:

A numpy array which contains the vertex coordinates of the mesh

Return type:

ndarray

cashocs.io.mesh.import_mesh(mesh_file, comm=None)[source]#

Imports a mesh file for use with cashocs / FEniCS.

This function imports a mesh file. The mesh file can either be a Gmsh mesh file or an xdmf mesh file that was generated by GMSH and converted to .xdmf with the function cashocs.convert(). If there are Physical quantities specified in the GMSH file, these are imported to the subdomains and boundaries output of this function and can also be directly accessed via the measures, e.g., with dx(1), ds(1), etc.

Parameters:
  • mesh_file (str) – The location of the mesh file in .xdmf or .msh file format.

  • comm (Optional[MPI.Comm]) – MPI communicator that is to be used for creating the mesh.

Returns:

A tuple (mesh, subdomains, boundaries, dx, ds, dS), where mesh is the imported FEM mesh, subdomains is a mesh function for the subdomains, boundaries is a mesh function for the boundaries, dx is a volume measure, ds is a surface measure, and dS is a measure for the interior facets.

Return type:

_typing.MeshTuple

Notes

In case the boundaries in the Gmsh .msh file are not only marked with numbers (as physical groups), but also with names (i.e. strings), these strings can be used with the integration measures dx and ds returned by this method. E.g., if one specified the following in a 2D Gmsh .geo file

Physical Surface("domain", 1) = {i,j,k};

where i,j,k are representative for some integers, then this can be used in the measure dx (as we are 2D) as follows. The command

dx(1)

is completely equivalent to

dx("domain")

and both can be used interchangeably.

cashocs.io.mesh.parse_file(original_msh_file, out_msh_file, points, dim)[source]#

Parses the mesh file and writes a new, corresponding one.

Parameters:
  • original_msh_file (str) – Path to the original GMSH mesh file of the mesh object, has to end with .msh.

  • out_msh_file (str) – Path to the output mesh file, has to end with .msh.

  • points (ndarray) – The mesh coordinates gathered on process 0

  • dim (int) – The dimensionality of the mesh

Return type:

None

cashocs.io.mesh.read_mesh_from_xdmf(filename, step=0, comm=None)[source]#

Reads a mesh from a .xdmf file containing a checkpointed function.

Parameters:
  • filename (str) – The filename to the .xdmf file.

  • step (int) – The checkpoint number. Default is 0.

  • comm (Optional[MPI.Comm]) – MPI communicator that is to be used for creating the mesh.

Returns:

The corresponding mesh for the checkpoint number.

Return type:

fenics.Mesh

cashocs.io.mesh.write_out_mesh(mesh, original_msh_file, out_msh_file)[source]#

Writes out mesh as Gmsh .msh file.

This method updates the vertex positions in the original_gmsh_file, the topology of the mesh and its connections are the same. The original GMSH file is kept, and a new one is generated under out_mesh_file.

Parameters:
  • mesh (fenics.Mesh) – The mesh object in fenics that should be saved as Gmsh file.

  • original_msh_file (str) – Path to the original GMSH mesh file of the mesh object, has to end with .msh.

  • out_msh_file (str) – Path to the output mesh file, has to end with .msh.

Return type:

None

Notes

The method only works with GMSH 4.1 file format. Others might also work, but this is not tested or ensured in any way.