Import and export of Gmsh files

Bempp may export and import grids and grid functions using the Gmsh v2.2 ASCII file format. In this tutorial, we describe the features of this interface.

Basic import and export

The most basic operation is to import a Gmsh grid into Bempp. The command for this operation is:

grid = bempp.api.import_grid("my_grid.msh")

To export a grid object grid to Gmsh you can use the following command:

bempp.api.export(grid=grid, file_name="my_grid.msh")

Similarly, to export a grid function to Gmsh use the command:

bempp.api.export(grid_function=fun, file_name="my_grid.msh")

The export function requires that exported data is real. If the data in the grid function is complex a transformation parameter can be given to map the grid function data into real data. For example, to just store the real part of a grid function use:

import numpy as np
bempp.api.export(grid_function=fun, file_name="my_grid.msh",
    transformation=np.real)

The transformation parameter takes a callable that accepts a number as its input and returns a real number. This function is applied to each data value in the grid function during the export.

Advanced handling of Gmsh node and element keys

The order in which Bempp stores the elements and nodes of a mesh will not necessarily be the same as the order in the imported Gmsh file. To obtain this information, the FileReader class may be used. It is initiated as follows:

from bempp.api.file_interfaces import FileReader
reader = FileReader(file_name="filename.msh")
grid = reader.grid

Please note that the file_name always needs to be given as a keyword argument. To find the Gmsh file key of the vertex with index v_index in Bempp, we can use the following command.

print(reader.vertex_index_to_file_key_map[v_index])

On the other hand, we can print the Bempp index associated with a vertex with key v_key in a Gmsh file using the command:

print(reader.vertex_file_key_to_index_map[v_key])

If the vertex associated with v_key has no correspondence in Bempp, a KeyError exception is thrown.

The corresponding element information can be obtained by replacing vertex by element in the above commands.

When exporting a grid function to Gmsh we would often like to preserve the indexing given in the original Gmsh file. This can be accomplished by passing the corresponding mapping information to the export function:

bempp.api.export(grid_function=grid_fun, file_name="export.msh"
    vertex_index_to_file_key_map=reader.vertex_index_to_file_key_map,
    element_index_to_file_key_map=reader.element_index_to_file_key_map)

If this mapping information is not given the export function uses a default map based on the Bempp indices.