bempp_cl.api

Global initialization for Bempp.

Submodules

• bempp_cl.api.assembly
• bempp_cl.api.external
• bempp_cl.api.fmm
• bempp_cl.api.grid
• bempp_cl.api.integration
• bempp_cl.api.linalg
• bempp_cl.api.operators
• bempp_cl.api.shapes
• bempp_cl.api.space
• bempp_cl.api.utils

Attributes

CONSOLE_LOGGING_HANDLER
DEFAULT_LOGGING_FORMAT
DEBUG
TIMING
INFO
WARNING
ERROR
CRITICAL
LOG_LEVEL
GLOBAL_PARAMETERS
LOGGER
BEMPP_PATH
TMP_PATH
GMSH_PATH
__version__
PLOT_BACKEND
ipy
USE_JIT
CPU_OPENCL_DRIVER_FOUND
GPU_OPENCL_DRIVER_FOUND
DEFAULT_DEVICE_INTERFACE
DEFAULT_PRECISION
VECTORIZATION_MODE
BOUNDARY_OPERATOR_DEVICE_TYPE
POTENTIAL_OPERATOR_DEVICE_TYPE
ALL

Classes

DefaultParameters	Default parameters for Bempp.
MemProfiler	Context manager to measure mem usage in bytes.
Grid	The Grid class.
GridFunction	Representation of functions on a grid.
ZeroBoundaryOperator	A boundary operator that represents a zero operator.
MultiplicationOperator	Returns a weak multiplication operator with a grid function.
BlockedOperator	Construct an m x n blocked boundary operator.
GeneralizedBlockedOperator	Construct a generalized blocked operator.
Timer	Context manager to measure time in Bempp.

Functions

assign_parameters(parameters)	Assign a parameter object based on input.
import_grid(filename)	Import a grid.
export(filename[, grid, grid_function, data_type, ...])	Export grids and grid functions.
real_callable(*args[, jit])	Wrap function as a real Numba callable.
complex_callable(*args[, jit])	Wrap function as a complex Numba callable.
callable(*args[, complex, jit, parameterized, vectorized])	Wrap a callable for Bempp.
function_space(grid, kind, degree[, scatter])	Initialize a function space.
lu(A, b[, lu_factor])	Perform an LU solve.
compute_lu_factors(A)	Precompute the LU factors of a dense operator A.
gmres(A, b[, tol, restart, maxiter, use_strong_form, ...])	Perform GMRES solve via interface to scipy.
cg(A, b[, tol, maxiter, use_strong_form, ...])	Perform CG solve via interface to scipy.
as_matrix(operator)	Convert a discrte operator into a dense matrix.
clear_fmm_cache()	Clean the FMM cache.
create_device_pool(identifier[, buffer_size, log, ...])	Create a pool based on a given platform identifer.
_init_logger()	Initialize the Bempp logger.
log(message[, level, flush])	Log including default flushing for IPython.
flush_log()	Flush all handlers. Necessary for Jupyter.
enable_console_logging([level])	Enable console logging and return the console handler.
set_logging_level(level)	Set the logging level.
_gmsh_path()	Find Gmsh.
check_for_fmm()	Return true of compatible FMM found.
_get_version()	Get version string.

Package Contents

class bempp_cl.api.DefaultParameters

Bases: object

Default parameters for Bempp.

verbosity

output

quadrature

assembly

fmm

class bempp_cl.api.MemProfiler

Context manager to measure mem usage in bytes.

_process

start = 0

end = 0

interval = 0

__enter__()

Enter.

__exit__(*args)

Exit.

bempp_cl.api.assign_parameters(parameters)

Assign a parameter object based on input.

If parameters is None return the global_parameters object. Otherwise, return the parameters object again.

bempp_cl.api.import_grid(filename)

Import a grid.

This routine uses the meshio library to export grids. A number of types are supported, including vtk, vtu, gmsh, dolphin xml. For a full list see

https://github.com/nschloe/meshio

bempp_cl.api.export(filename, grid=None, grid_function=None, data_type=None, transformation=None, write_binary=True)

Export grids and grid functions.

This method internally uses the meshio library. For a full list of supported data types see

https://github.com/nschloe/meshio

Note that export of domain indices is only possible for Gmsh (.msh) format files.

Parameters

filenamestring

The name of the file to write out. The data type is chosen based on the file ending.

gridGrid object

A grid object to export.

grid_functionGridFunction object

Grid function to export

data_typestring

Either ‘node’ for vertex data or ‘element’ for data at element centers.

transformationstring or callable

One of ‘real’, ‘imag’, ‘abs’, ‘log_abs’, None or a callable object. Transforms the data on input. A callable must return numpy arrays with the same number of dimensions as the input. If transformation is None the data is not modified.

write_binaryBoolean

Use binary format (write_binary=True) for the data if supported by the file format.

class bempp_cl.api.Grid(vertices, elements, domain_indices=None, grid_id=None, scatter=True)

Bases: object

The Grid class.

_vertices = None

_elements = None

_domain_indices = None

_edges = None

_element_edges = None

_edge_adjacency = None

_vertex_adjacency = None

_element_neighbors = None

_vertex_on_boundary = None

_edge_on_boundary = None

_edge_neighbors = None

_vertex_neighbors = None

_barycentric_grid = None

_volumes = None

_normals = None

_jacobians = None

_jacobian_inverse_transposed = None

_diameters = None

_integration_elements = None

_centroids = None

_device_interfaces

_element_to_vertex_matrix = None

_element_to_element_matrix = None

_grid_data_double

_grid_data_single

_is_scattered = False

property vertex_adjacency

Vertex adjacency information.

Returns a matrix with 4 rows. Each column has the entries e0, e1, ind0, ind1, which means that element e0 is connected to element e1 via local vertex index ind0 in e0 and ind1 in e1. Only returnes connectivity via a single vertex. For connectivity via edges see edge_adjacency.

property edge_adjacency

Edge adjacency information.

Returns a matrix with 6 rows. Each column has the entries e0, e1, v00, v01, v11, v12, which means that element e0 is connected to element e1. Vertex v00 in element e0 is identical to vertex v11 in element e1, and vertex v01 in element 0 is identical to vertex v12 in element e1.

property element_to_vertex_matrix

Return the matrix mapping vertices to elements.

property element_to_element_matrix

Return element to element matrix.

If entry (i,j) has the value n > 0, element i and element j are connected via n vertices.

property element_neighbors

Return named tuple (indices, indexptr).

The neighbors of element i are given as element_neighbors.indices[

element_neighbors.indptr[i] : element_neighbors.indptr[i +1]].

Note that the element i is contained in the list of neighbors.

property number_of_vertices

Return number of vertices.

property number_of_edges

Return number of edges.

property number_of_elements

Return number of elements.

property vertices

Return vertices.

property elements

Return elements.

property edges

Return edges.

property centroids

Return the centroids of the elements.

property domain_indices

Return domain indices.

property element_edges

Return an array of edge indices for each element.

element_edges[i, j] is the index of the ith edge in the jth element.

property device_interfaces

Return the dictionary of device interfaces for the grid.

property as_array

Convert the grid to an array.

For a grid with N elements returns a 1d array with 9 * N entries. The three nodes for element with index e can be found in [9 * e, 9 * (e + 1)].

property bounding_box

Return the bounding box for the grid.

The bounding box is a 3x2 array box such that box[:, 0] contains (xmin, ymin, zmin) and box[:, 1] contains (xmax, ymax, zmax).

property volumes

Return element volumes.

property diameters

Return element diameters.

property maximum_element_diameter

Return the maximum element diameter.

property minimum_element_diameter

Return the maximum element diameter.

property normals

Return normals.

property jacobians

Return Jacobians.

property integration_elements

Return integration elements.

property jacobian_inverse_transposed

Return the jacobian inverse transposed.

property vertex_on_boundary

Return vertex boundary information.

property edge_on_boundary

Return edge boundary information.

property edge_neighbors

Return for each edge the list of neighboring elements..

data(precision='double')

Return Numba container with all relevant grid data.

property vertex_neighbors

Return for each vertex the list of neighboring elements.

property barycentric_refinement

Return the barycentric refinement of this grid.

property id

Return a unique id for the grid.

_scatter()

Initialise the grid on all workers.

entity_count(codim)

Return the number of entities of given codimension.

plot()

Plot the grid.

get_element(index)

Return element with a given index.

entity_iterator(codim)

Return an iterator for a given codim.

map_to_point_cloud(order=None, local_points=None, precision='double')

Return a point cloud representation of the grid on quadratur points.

Return a representation of the grid as a point cloud using points on each element either defined through a triangle Gauss qudrature order or by directly specifying an array of local points.

Parameters

orderInteger

Optional parameter. Specify a quadrature order for the point cloud generation.

local_points: Numpy array

A 2 x N array of N points in local reference coordinates that specify the points to use for each triangle.

precision: String

Either ‘single’ or ‘double’.

If neither order nor local_points is specified the quadrature order is obtained from the global parameters.

Returns a M x 3 array of M points that represent the grid on the specified points.

refine()

Return a new grid with all elements refined.

_compute_vertex_neighbors()

Return all elements adjacent to a given vertex.

_normalize_and_assign_input(vertices, elements, domain_indices)

Convert input into the right form.

_enumerate_edges()

Enumerate all edges in a given grid.

Assigns a tuple (edges, element_edges) to self._edges and self._element_edges. element_edges is an array a such that a[i, j] is the index of the ith edge in the jth elements, and edges is a 2 x nedges array such that the jth column stores the two nodes associated with the jth edge.

_get_element_adjacency_for_edges_and_vertices()

Get element adjacency.

The array edge_adjacency has 6 rows, such that for index j the element edge_adjacency[0, j] is connected with element edge_adjacency[1, j] via the vertices edge_adjacency[2:4, j] in the first element and the vertices edge_adjacency[4:6, j] in the second element. The vertex numbers here are local numbers (0, 1 or 2).

The array vertex_adjacency has 4 rows, such that for index j the element vertex_adjacency[0, j] is connected with vertex_adjacency[1, j] via the vertex vertex_adjacency[2, j] in the first element and the vertex vertex_adjacency[3, j] in the second element. The vertex numbers here are local numbers (0, 1 or 2).

_compute_geometric_quantities()

Compute geometric quantities for the grid.

_compute_boundary_information()

Return a boolean array with boundary information.

Computes arr0, arr1 such that arr0[j] is True if vertex j lies on the boundary and arr1[i] is True if edge i lies on the boundary.

_compute_edge_neighbors()

Get the neighbors of each edge.

class bempp_cl.api.GridFunction(space, dual_space=None, fun=None, coefficients=None, projections=None, parameters=None, function_parameters=None)

Bases: object

Representation of functions on a grid.

Attributes

coefficientsnp.ndarray

Return or set the vector of coefficients.

component_countint

Return the number of components of the grid function values.

spacebemp.api.space.Space

Return the space over which the GridFunction is defined.

gridbempp_cl.api.grid.Grid

Return the underlying grid.

parametersbempp_cl.api.ParameterList

Return the set of parameters.

representationstring

Return ‘primal’ if the coefficients of the Gridfunction are known. Return ‘dual’ if only the coefficients in the dual space are known.

_space = None

_dual_space = None

_coefficients = None

_grid_coefficients = None

_projections = None

_representation = None

_comp_domain

_comp_dual = None

_parameters

property space

Return space.

property dtype

Return type.

property parameters

Return parameters.

property dual_space

Return dual space.

property representation

Return the representation of the grid function.

If the grid function is given in terms of coefficients in the domain space return ‘primal’. If the function is given by its projections return ‘dual’.

property coefficients

Return coefficient vector.

property grid_coefficients

Return grid coefficients.

property real

Return a new grid function consisting of the real part of this function.

property imag

Return a new grid function consisting of the imaginary part of this function.

property component_count

Return number of components.

projections(dual_space=None)

Compute the vector of projections onto the given dual space.

Parameters

dual_spacebempp_cl.api.space.Space

A representation of the dual space. If not specified then fun.dual_space is used.

Returns

outnp.ndarray

A vector of projections onto the dual space.

project_to_space(space)

Return an L^2 projection on another space.

plot(mode=None, transformation=None)

Plot the grid function.

Attributes

modestring

One of ‘element’ or ‘node’. If ‘element’ is chosen the color is determined by the mid-point of the faces of the grid. For ‘vertices’ the vertex values are chosen

transformationstring or object

One of ‘real’, ‘imag’, ‘abs’, ‘log_abs’ or ‘abs_squared’ or a callable object. Describes the data transformation before plotting. For functions with vector values only ‘abs’, ‘log_abs’ or ‘abs_squared’ are allowed. If a callable object is given this is applied instead. It is important that the callable returns numpy arrays with the same number of dimensions as before.

evaluate(element_index, local_coordinates)

Evaluate grid function on a single element.

evaluate_on_element_centers()

Evaluate the grid function on all element centers.

evaluate_on_vertices()

Evaluate the grid function on all vertices.

If a function is discontinuous across elements a weighted average of the element values at the vertices is taken.

integrate()

Integrate grid function over a grid.

l2_norm()

Calculate the L^2 norm of the function.

__add__(other)

Add two grid functions.

__mul__(alpha)

Multiply a grid function.

__rmul__(alpha)

Multiply a grid function.

__div__(alpha)

Divide a grid function.

__truediv__(alpha)

Divide a grid function.

__neg__()

Negate a grid function.

__sub__(other)

Subtract grid functions.

classmethod from_random(space)

Create a random grid function normalized to unit norm.

classmethod from_ones(space)

Create a grid function with all coefficients set to one.

classmethod from_zeros(space)

Create a grid function with all coefficients set to one.

bempp_cl.api.real_callable(*args, jit=True)

Wrap function as a real Numba callable.

bempp_cl.api.complex_callable(*args, jit=True)

Wrap function as a complex Numba callable.

bempp_cl.api.callable(*args, complex=False, jit=True, parameterized=False, vectorized=False)

Wrap a callable for Bempp.

bempp_cl.api.function_space(grid, kind, degree, scatter=True, **kwargs)

Initialize a function space.

Parameters

gridbempp_cl.Grid

The grid that the space is defined on.

kindstr

The space type

degreeint

The polynomial degree of the space

support_elementsnp.array

The element indices of elements that make up the part of the mesh on which the space is defined.

segmentslist

The segment numbers of the part of the mesh on which the space is defined.

swapped_normalsbool

TODO

scatterbool

TODO

include_boundary_dofsbool

Should degrees of freedom on the boundary of the grid segments be included?

truncate_at_segment_edgebool

Should basis functions be truncated at the edge of the grid segment? If this is set to true, continuous spaces will no longer be continuous across the segment edge.

bempp_cl.api.lu(A, b, lu_factor=None)

Perform an LU solve.

This function takes an operator and a grid function, converts the operator into a dense matrix and solves the system via LU decomposition. The result is again returned as a grid function.

Parameters

Abempp_cl.api.BoundaryOperator

The left-hand side boundary operator

bbempp_cl.api.GridFunction

The right-hand side grid function

lu_decomptuple

Optionally pass the tuple (lu, piv) obtained by the scipy method scipy.linalg.lu_factor

bempp_cl.api.compute_lu_factors(A)

Precompute the LU factors of a dense operator A.

This function returns a tuple of LU factors of A. This tuple can be used in the lu_factor attribute of the lu function so that the LU decomposition is not recomputed at each call to lu.

bempp_cl.api.gmres(A, b, tol=1e-05, restart=None, maxiter=None, use_strong_form=False, return_residuals=False, return_iteration_count=False)

Perform GMRES solve via interface to scipy.

This function behaves like the scipy.sparse.linalg.gmres function. But instead of a linear operator and a vector b it takes a boundary operator and a grid function or a blocked operator and a list of grid functions. The result is returned as a grid function or as a list of grid functions in the correct spaces.

bempp_cl.api.cg(A, b, tol=1e-05, maxiter=None, use_strong_form=False, return_residuals=False, return_iteration_count=False)

Perform CG solve via interface to scipy.

This function behaves like the scipy.sparse.linalg.cg function. But instead of a linear operator and a vector b it takes a boundary operator and a grid function. The result is returned as a grid function in the correct space.

bempp_cl.api.as_matrix(operator)

Convert a discrte operator into a dense matrix.

Parameters

operatorscipy.sparse.linalg.interface.LinearOperator

The linear operator to be converted into a matrix.

Notes

Note that this function may be slow depending on how the original discrete operator was stored. In the case of a dense assembly simple the underlying NumPy matrix is returned. For sparse matrices the corresponding Scipy sparse matrix is returned. Otherwise, the operator needs to be converted to an array, which can take a long time depending on the assembler type.

class bempp_cl.api.ZeroBoundaryOperator(domain, range_, dual_to_range)

Bases: BoundaryOperator

A boundary operator that represents a zero operator.

Parameters

domainbempp_cl.api.space.Space

Domain space of the operator.

range_bempp_cl.api.space.Space

Range space of the operator.

dual_to_rangebempp_cl.api.space.Space

Dual space to the range space.

_assemble()

__iadd__(other)

Add.

__isub__(other)

Subtract.

class bempp_cl.api.MultiplicationOperator(grid_function, domain, range_, dual_to_range, parameters=None, mode='component')

Bases: BoundaryOperator

Returns a weak multiplication operator with a grid function.

Given a grid function g, this operator assembles a sparse matrix that implements weak multiplication with g in a given basis.

_mode = 'component'

_grid_fun

_assemble()

Assemble the operator.

class bempp_cl.api.BlockedOperator(m, n)

Bases: BlockedOperatorBase

Construct an m x n blocked boundary operator.

_operators

_rows

_cols

_dual_to_range_spaces

_range_spaces

_domain_spaces

__getitem__(key)

Return a component operator with a key of the form (i, j).

__setitem__(key, operator)

Set a component operator with a key of the form (i, j).

_fill_complete()

Check if each row and column contain at least one operator.

_assemble()

Implement the weak form.

property range_spaces

Return the list of range spaces.

property dual_to_range_spaces

Return the list of dual_to_range spaces.

property domain_spaces

Return the list of domain spaces.

class bempp_cl.api.GeneralizedBlockedOperator(array)

Bases: BlockedOperatorBase

Construct a generalized blocked operator.

A generalized blocked operator has as components either

• Simple operators

• Blocked operators

• Generalized blocked operators

• Arrays of simple/blocked/generalized blocked operators

_ops = []

_components_per_row = None

_components_per_column = None

_assemble()

Implement the weak form.

property range_spaces

Return the list of range spaces.

property dual_to_range_spaces

Return the list of dual_to_range spaces.

property domain_spaces

Return the list of domain spaces.

bempp_cl.api.clear_fmm_cache()

Clean the FMM cache.

bempp_cl.api.create_device_pool(identifier, buffer_size=100, log=False, log_level='info', max_workers=-1, precision=None)

Create a pool based on a given platform identifer.

identifierstring

A unique identifier that is part of the platform name. Used to find the correct platform.

buffer_sizeint

Shared memory buffer size in MB

logBoolean

Set to True to log workers.

log_levelString

Logging level. One of ‘debug’, ‘info’, ‘warning’, ‘error’, ‘critical’

max_workersint

Maximum number of workers. If max_workers=-1 (default) the maximum number of workers is identical to the number of devices in the pool.

precisionstring or None

Precision for the devices in the pool. If precision is None use single precision for GPU devices and double precision for CPU devices. If precision is ‘single’ or ‘double’ use the corresponding mode for the pool.

bempp_cl.api.CONSOLE_LOGGING_HANDLER = None

bempp_cl.api.DEFAULT_LOGGING_FORMAT = '%(name)s:%(levelname)s: %(message)s'

bempp_cl.api.DEBUG = 10

bempp_cl.api.TIMING = 11

bempp_cl.api.INFO = 20

bempp_cl.api.WARNING = 30

bempp_cl.api.ERROR = 40

bempp_cl.api.CRITICAL = 50

bempp_cl.api.LOG_LEVEL

bempp_cl.api.GLOBAL_PARAMETERS

bempp_cl.api._init_logger()

Initialize the Bempp logger.

bempp_cl.api.log(message, level='info', flush=True)

Log including default flushing for IPython.

bempp_cl.api.flush_log()

Flush all handlers. Necessary for Jupyter.

bempp_cl.api.enable_console_logging(level='info')

Enable console logging and return the console handler.

bempp_cl.api.set_logging_level(level)

Set the logging level.

class bempp_cl.api.Timer(enable_log=True, message='', level='timing')

Context manager to measure time in Bempp.

start = 0

end = 0

interval = 0

enable_log = True

level = 'timing'

message = ''

__enter__()

Enter.

__exit__(*args)

Exit.

bempp_cl.api.LOGGER

bempp_cl.api.BEMPP_PATH = b'.'

bempp_cl.api.TMP_PATH = b'.'

bempp_cl.api._gmsh_path()

Find Gmsh.

bempp_cl.api.check_for_fmm()

Return true of compatible FMM found.

bempp_cl.api._get_version()

Get version string.

bempp_cl.api.GMSH_PATH = 'gmsh.exe'

bempp_cl.api.__version__ = '0.4.2'

bempp_cl.api.PLOT_BACKEND = 'gmsh'

bempp_cl.api.ipy

bempp_cl.api.USE_JIT = True

bempp_cl.api.CPU_OPENCL_DRIVER_FOUND = False

bempp_cl.api.GPU_OPENCL_DRIVER_FOUND = False

bempp_cl.api.DEFAULT_DEVICE_INTERFACE = 'numba'

bempp_cl.api.DEFAULT_PRECISION = 'double'

bempp_cl.api.VECTORIZATION_MODE = 'auto'

bempp_cl.api.BOUNDARY_OPERATOR_DEVICE_TYPE = 'cpu'

bempp_cl.api.POTENTIAL_OPERATOR_DEVICE_TYPE = 'cpu'

bempp_cl.api.ALL = -1