# Grids¶

In order to solve a problem using the boundary element method, we must first define the grid (or mesh) on which the problem will be discretised. In Bempp, the grid will be a triangulation of a 2D surface in 3D space. Bempp currently only supports grids consisting of flat surface triangles.

This section looks at how grids can be created and used in Bempp. Full documentation of the functionality of Bempp grids can be found on Read the Docs.

## Overview¶

A Bempp grid can be created using a built-in grid, by importing a gmsh file, or by providing the grid data.

We first import Bempp and NumPy.

```
import bempp.api
import numpy as np
```

### Built-in grids¶

Various shapes are included in the `bempp.api.shapes`

module, and discretisations with
different numbers of elements can be created using these.
In order for the these built-in grids to work, Gmsh must be
installed and the command `gmsh`

must be available in the path.

The command `regular_sphere`

creates a sphere by refining a
base octahedron. The number of elements in the sphere is given by
\(8 \times 4^n\), where \(n\) is the refinement level.
The following command creates a triangulation of a sphere with refinement level 3:

```
grid = bempp.api.shapes.regular_sphere(3)
```

The command `sphere`

creates a sphere with a chosen element size.
The following command creates a sphere with element diameter \(h=0.1\):

```
grid = bempp.api.shapes.sphere(h=0.1)
```

The command `cube`

creates a cube with a chosen element size.
The following command creates a cube with element diameter \(h=0.3\):

```
grid = bempp.api.shapes.cube(h=0.3)
```

Full automatically-generated documentation of Bempp’s available built-in grids can be found here.

### Importing a grid¶

Grids can be importedusing Bempp’s `import_grid`

command.
For example, the following command will load a grid from the Gmsh file `my_grid.msh`

.

```
grid = bempp.api.import_grid('my_grid.msh')
```

Bempp uses the file ending to recognise a number of grid formats. Importing grids is handled by the meshio library.

This works through the external `meshio`

library.
A list of all files types that can be imported can be found in the meshio documentation.
Frequently used formats with Bempp are `.msh`

(Gmsh),
`.vtk`

(Legacy VTK), and `.vtu`

(VTK Xml Format).

### Creating a grid from element data¶

Bempp grids can be generated from arrays containing vertex coordinates and connectivity information. For example, to create a grid consisting of two triangles with vertices \(\\{(0, 0, 0), (1, 0, 0), (0, 1, 0)\\}\) and \(\\{(1, 0, 0), (1, 1, 0), (0, 1, 0)\\}\) we use the following commands:

```
vertices = np.array(
[[0, 1, 0, 1], [0, 0, 1, 1], [0, 0, 0, 0]],
dtype=np.float64)
elements = np.array(
[[0, 1], [1, 3], [2, 2]], dtype=np.uint32)
grid = bempp.api.Grid(vertices, elements)
```

Note that the three arrays in the `vertices`

array are the \(x\)-coordinates,
then the \(y\)-coordinates, then the \(z\)-coordinates.
Similarly, the three arrays in the `elements`

array are the first points of each triangle,
then the second points, then the third points.
In general, the `vertices`

and `elements`

arrays should have shapes \(3\times M\) and \(3\times N\)
(respectively) for a grid with \(M\) vertices and \(N\) elements.

The array `vertices`

contains the 3D coordinates of all vertices. The array
`elements`

contains the connectivity information. In this case the first
triangle consists of the vertices 0, 1, 2, and the second triangle consists
of the vertices 1, 3, 2.

Optionally, we can specify a list `domain_indices`

that gives different groups of elements the same id. This can be used
for example to generate different types of boundary data on different parts
of the grid, or to specify function spaces only on parts of the grid. In this
example, both triangles automatically have the identifier 0 since nothing
else was specified. This is equivalent to running:

```
grid = bempp.api.Grid(vertices, elements, domain_indices=[0, 0])
```

## Using Grids¶

Once you have created a Bempp grid, you may want to use information about your grid. This page show how commonly used information can be obtained from a Bempp grid.

### Querying grid information¶

The number of elements, edges and vertices in a grid are given by:

```
grid.number_of_elements
grid.number_of_edges
grid.number_of_vertices
```

To query the maximum and minimum element diameter use the following attributes:

```
grid.maximum_element_diameter
grid.minimum_element_diameter
```

The vertex indices of the element 5 can be obtained using:

```
grid.elements[:, 5]
```

Note that the numbering of element starts at 0, so element 5 is the grid’s sixth element.

The vertex coordinates of element 5 can be found using:

```
grid.vertices[:, grid.elements[:, 5]]
```

The area of the element 5 is:

```
grid.volumes[5]
```

The edge indices associated with element 5 are:

```
grid.element_edges[5]
```

The vertex indices of the edges of element 5 can be obtained using:

```
grid.edges[:, grid.element_edges[:, 5]]
```

This returns a 2×3 array of the vertex coordinates associated with the three edges of the element. Edges in Bempp are ordered in the following way:

Edge |
First vertex |
Second vertex |
---|---|---|

0 |
0 |
1 |

1 |
0 |
2 |

2 |
1 |
2 |

Full automatically-generated documentation of the Bempp `Grid`

class can be found
here.

### Plotting and exporting grids¶

To export a grid, we can use the `export`

command:

```
bempp.api.export('grid.msh', grid=grid)
```

This commands export the object `grid`

as Gmsh file with the
name `grid.msh`

.

In order to plot a grid, we can simply use the command:

```
grid.plot()
```

By default, this will plot using Gmsh (or plotly if you are inside a Jupyter notebook). The following command can be used to change the plotting backend.

```
bempp.api.PLOT_BACKEND = "gmsh"
bempp.api.PLOT_BACKEND = "paraview"
```

This requires Gmsh or Paraview to be available in the system path.