cashocs.io#

Inputs and outputs.

Functions

`convert`(input_file[, output_file, mode, quiet])	Converts the input mesh file to a xdmf mesh file for cashocs to work with.
`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.
`import_function`(filename, name, function_space)	Imports a function from an xdmf file to cashocs.
`import_mesh`(mesh_file[, comm])	Imports a mesh file for use with cashocs / FEniCS.
`load_config`(path)	Loads a config object from a config file.
`read_function_from_xdmf`(filename, name, ...)	Reads a function from a .xdmf file containing a checkpointed function.
`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

`Config`([config_file])	Class for handling the config in cashocs.
`OutputManager`(db)	Class handling all the output.

class cashocs.io.Config(config_file=None)[source]#

Bases: ConfigParser

Class for handling the config in cashocs.

Initializes self.

Parameters:: config_file (Optional[str]) – Path to the config file.

getlist(section, option, **kwargs)[source]#

Extracts a list from a config file.

Parameters:

section (str) – The section where the list is placed.
option (str) – The option which contains the list.
**kwargs (Any) – A list of keyword arguments that get passed to :py:meth:self.get

Returns:

The list which is specified in section section and key option.

Return type:

List

validate_config()[source]#

Validates the configuration file.

Return type:: None

class cashocs.io.OutputManager(db)[source]#

Bases: object

Class handling all the output.

Initializes self.

Parameters:: db (database.Database) – The database of the problem.

output()[source]#

Writes the desired output to files and console.

Return type:: None

output_summary()[source]#

Writes the summary to files and console.

Return type:: None

post_process()[source]#

Performs a postprocessing of the output.

Return type:: None

cashocs.io.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.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.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.import_function(filename, name, function_space, step=0)[source]#

Imports a function from an xdmf file to cashocs.

Parameters:

filename (str) – The path / filename to the xdmf file.
name (str) – The name of the function in the xdmf file.
function_space (fenics.FunctionSpace) – The corresponding function space for the function. Note that this must be created on a suitable mesh, which has been reimported with cashocs.io.reimport_mesh().
step (int) – The checkpoint number. Default is 0.

Returns:

The fenics function which is stored in the xdmf file.

Return type:

fenics.Function

cashocs.io.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.load_config(path)[source]#

Loads a config object from a config file.

Loads the config from a .ini file via the configparser package.

Parameters:: path (str) – The path to the .ini file storing the configuration.
Returns:: The output config file, which includes the path to the .ini file.
Return type:: ConfigParser

cashocs.io.read_function_from_xdmf(filename, name, family, degree, vector_dim=0, step=0, comm=None)[source]#

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

Parameters:

filename (str) – The name of the .xdmf file.
name (str) – The name of the function.
family (str) – The finite element family of the function.
degree (int) – The degree of the finite element.
vector_dim (int) – The dimension of the vector, if the function is vector-valued. In case that this is 0, a scalar finite element is assumed. Default is 0.
step (int) – The checkpoint number. Default is 0.
comm (Optional[MPI.Comm]) – The MPI communicator that shall be used. Default is None, which means that fenics.MPI.comm_world is used.

Returns:

A fenics representation of the function stored in the file.

Return type:

fenics.Function

cashocs.io.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.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.

Modules

`cashocs.io.config`	Management of configuration files.
`cashocs.io.function`	Function input and output.
`cashocs.io.managers`	Output managers for cashocs.
`cashocs.io.mesh`	Mesh input and output.
`cashocs.io.output`	Management of cashocs output.