bempp_cl.api ============ .. py:module:: bempp_cl.api .. autoapi-nested-parse:: Global initialization for Bempp. Submodules ---------- .. toctree:: :maxdepth: 1 /docs/bempp_cl/api/assembly/index /docs/bempp_cl/api/external/index /docs/bempp_cl/api/fmm/index /docs/bempp_cl/api/grid/index /docs/bempp_cl/api/integration/index /docs/bempp_cl/api/linalg/index /docs/bempp_cl/api/operators/index /docs/bempp_cl/api/shapes/index /docs/bempp_cl/api/space/index /docs/bempp_cl/api/utils/index Attributes ---------- .. autoapisummary:: bempp_cl.api.CONSOLE_LOGGING_HANDLER bempp_cl.api.DEFAULT_LOGGING_FORMAT bempp_cl.api.DEBUG bempp_cl.api.TIMING bempp_cl.api.INFO bempp_cl.api.WARNING bempp_cl.api.ERROR bempp_cl.api.CRITICAL bempp_cl.api.LOG_LEVEL bempp_cl.api.GLOBAL_PARAMETERS bempp_cl.api.LOGGER bempp_cl.api.BEMPP_PATH bempp_cl.api.TMP_PATH bempp_cl.api.GMSH_PATH bempp_cl.api.__version__ bempp_cl.api.PLOT_BACKEND bempp_cl.api.ipy bempp_cl.api.USE_JIT bempp_cl.api.CPU_OPENCL_DRIVER_FOUND bempp_cl.api.GPU_OPENCL_DRIVER_FOUND bempp_cl.api.DEFAULT_DEVICE_INTERFACE bempp_cl.api.DEFAULT_PRECISION bempp_cl.api.VECTORIZATION_MODE bempp_cl.api.BOUNDARY_OPERATOR_DEVICE_TYPE bempp_cl.api.POTENTIAL_OPERATOR_DEVICE_TYPE bempp_cl.api.ALL Classes ------- .. autoapisummary:: bempp_cl.api.DefaultParameters bempp_cl.api.MemProfiler bempp_cl.api.Grid bempp_cl.api.GridFunction bempp_cl.api.ZeroBoundaryOperator bempp_cl.api.MultiplicationOperator bempp_cl.api.BlockedOperator bempp_cl.api.GeneralizedBlockedOperator bempp_cl.api.Timer Functions --------- .. autoapisummary:: bempp_cl.api.assign_parameters bempp_cl.api.import_grid bempp_cl.api.export bempp_cl.api.real_callable bempp_cl.api.complex_callable bempp_cl.api.callable bempp_cl.api.function_space bempp_cl.api.lu bempp_cl.api.compute_lu_factors bempp_cl.api.gmres bempp_cl.api.cg bempp_cl.api.as_matrix bempp_cl.api.clear_fmm_cache bempp_cl.api.create_device_pool bempp_cl.api._init_logger bempp_cl.api.log bempp_cl.api.flush_log bempp_cl.api.enable_console_logging bempp_cl.api.set_logging_level bempp_cl.api._gmsh_path bempp_cl.api.check_for_fmm bempp_cl.api._get_version Package Contents ---------------- .. py:class:: DefaultParameters Bases: :py:obj:`object` Default parameters for Bempp. .. py:attribute:: verbosity .. py:attribute:: output .. py:attribute:: quadrature .. py:attribute:: assembly .. py:attribute:: fmm .. py:class:: MemProfiler Context manager to measure mem usage in bytes. .. py:attribute:: _process .. py:attribute:: start :value: 0 .. py:attribute:: end :value: 0 .. py:attribute:: interval :value: 0 .. py:method:: __enter__() Enter. .. py:method:: __exit__(*args) Exit. .. py:function:: 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. .. py:function:: 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 .. py:function:: 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 ---------- filename : string The name of the file to write out. The data type is chosen based on the file ending. grid : Grid object A grid object to export. grid_function : GridFunction object Grid function to export data_type : string Either 'node' for vertex data or 'element' for data at element centers. transformation : string 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_binary : Boolean Use binary format (write_binary=True) for the data if supported by the file format. .. py:class:: Grid(vertices, elements, domain_indices=None, grid_id=None, scatter=True) Bases: :py:obj:`object` The Grid class. .. py:attribute:: _vertices :value: None .. py:attribute:: _elements :value: None .. py:attribute:: _domain_indices :value: None .. py:attribute:: _edges :value: None .. py:attribute:: _element_edges :value: None .. py:attribute:: _edge_adjacency :value: None .. py:attribute:: _vertex_adjacency :value: None .. py:attribute:: _element_neighbors :value: None .. py:attribute:: _vertex_on_boundary :value: None .. py:attribute:: _edge_on_boundary :value: None .. py:attribute:: _edge_neighbors :value: None .. py:attribute:: _vertex_neighbors :value: None .. py:attribute:: _barycentric_grid :value: None .. py:attribute:: _volumes :value: None .. py:attribute:: _normals :value: None .. py:attribute:: _jacobians :value: None .. py:attribute:: _jacobian_inverse_transposed :value: None .. py:attribute:: _diameters :value: None .. py:attribute:: _integration_elements :value: None .. py:attribute:: _centroids :value: None .. py:attribute:: _device_interfaces .. py:attribute:: _element_to_vertex_matrix :value: None .. py:attribute:: _element_to_element_matrix :value: None .. py:attribute:: _grid_data_double .. py:attribute:: _grid_data_single .. py:attribute:: _is_scattered :value: False .. py: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. .. py: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. .. py:property:: element_to_vertex_matrix Return the matrix mapping vertices to elements. .. py: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. .. py: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. .. py:property:: number_of_vertices Return number of vertices. .. py:property:: number_of_edges Return number of edges. .. py:property:: number_of_elements Return number of elements. .. py:property:: vertices Return vertices. .. py:property:: elements Return elements. .. py:property:: edges Return edges. .. py:property:: centroids Return the centroids of the elements. .. py:property:: domain_indices Return domain indices. .. py: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. .. py:property:: device_interfaces Return the dictionary of device interfaces for the grid. .. py: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)]. .. py: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). .. py:property:: volumes Return element volumes. .. py:property:: diameters Return element diameters. .. py:property:: maximum_element_diameter Return the maximum element diameter. .. py:property:: minimum_element_diameter Return the maximum element diameter. .. py:property:: normals Return normals. .. py:property:: jacobians Return Jacobians. .. py:property:: integration_elements Return integration elements. .. py:property:: jacobian_inverse_transposed Return the jacobian inverse transposed. .. py:property:: vertex_on_boundary Return vertex boundary information. .. py:property:: edge_on_boundary Return edge boundary information. .. py:property:: edge_neighbors Return for each edge the list of neighboring elements.. .. py:method:: data(precision='double') Return Numba container with all relevant grid data. .. py:property:: vertex_neighbors Return for each vertex the list of neighboring elements. .. py:property:: barycentric_refinement Return the barycentric refinement of this grid. .. py:property:: id Return a unique id for the grid. .. py:method:: _scatter() Initialise the grid on all workers. .. py:method:: entity_count(codim) Return the number of entities of given codimension. .. py:method:: plot() Plot the grid. .. py:method:: get_element(index) Return element with a given index. .. py:method:: entity_iterator(codim) Return an iterator for a given codim. .. py:method:: 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 ---------- order : Integer 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. .. py:method:: refine() Return a new grid with all elements refined. .. py:method:: _compute_vertex_neighbors() Return all elements adjacent to a given vertex. .. py:method:: _normalize_and_assign_input(vertices, elements, domain_indices) Convert input into the right form. .. py:method:: _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. .. py:method:: _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). .. py:method:: _compute_geometric_quantities() Compute geometric quantities for the grid. .. py:method:: _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. .. py:method:: _compute_edge_neighbors() Get the neighbors of each edge. .. py:class:: GridFunction(space, dual_space=None, fun=None, coefficients=None, projections=None, parameters=None, function_parameters=None) Bases: :py:obj:`object` Representation of functions on a grid. Attributes ---------- coefficients : np.ndarray Return or set the vector of coefficients. component_count : int Return the number of components of the grid function values. space : bemp.api.space.Space Return the space over which the GridFunction is defined. grid : bempp_cl.api.grid.Grid Return the underlying grid. parameters : bempp_cl.api.ParameterList Return the set of parameters. representation : string Return 'primal' if the coefficients of the Gridfunction are known. Return 'dual' if only the coefficients in the dual space are known. .. py:attribute:: _space :value: None .. py:attribute:: _dual_space :value: None .. py:attribute:: _coefficients :value: None .. py:attribute:: _grid_coefficients :value: None .. py:attribute:: _projections :value: None .. py:attribute:: _representation :value: None .. py:attribute:: _comp_domain .. py:attribute:: _comp_dual :value: None .. py:attribute:: _parameters .. py:property:: space Return space. .. py:property:: dtype Return type. .. py:property:: parameters Return parameters. .. py:property:: dual_space Return dual space. .. py: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'. .. py:property:: coefficients Return coefficient vector. .. py:property:: grid_coefficients Return grid coefficients. .. py:property:: real Return a new grid function consisting of the real part of this function. .. py:property:: imag Return a new grid function consisting of the imaginary part of this function. .. py:property:: component_count Return number of components. .. py:method:: projections(dual_space=None) Compute the vector of projections onto the given dual space. Parameters ---------- dual_space : bempp_cl.api.space.Space A representation of the dual space. If not specified then fun.dual_space is used. Returns ------- out : np.ndarray A vector of projections onto the dual space. .. py:method:: project_to_space(space) Return an L^2 projection on another space. .. py:method:: plot(mode=None, transformation=None) Plot the grid function. Attributes ---------- mode : string 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 transformation : string 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. .. py:method:: evaluate(element_index, local_coordinates) Evaluate grid function on a single element. .. py:method:: evaluate_on_element_centers() Evaluate the grid function on all element centers. .. py:method:: 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. .. py:method:: integrate() Integrate grid function over a grid. .. py:method:: l2_norm() Calculate the L^2 norm of the function. .. py:method:: __add__(other) Add two grid functions. .. py:method:: __mul__(alpha) Multiply a grid function. .. py:method:: __rmul__(alpha) Multiply a grid function. .. py:method:: __div__(alpha) Divide a grid function. .. py:method:: __truediv__(alpha) Divide a grid function. .. py:method:: __neg__() Negate a grid function. .. py:method:: __sub__(other) Subtract grid functions. .. py:method:: from_random(space) :classmethod: Create a random grid function normalized to unit norm. .. py:method:: from_ones(space) :classmethod: Create a grid function with all coefficients set to one. .. py:method:: from_zeros(space) :classmethod: Create a grid function with all coefficients set to one. .. py:function:: real_callable(*args, jit=True) Wrap function as a real Numba callable. .. py:function:: complex_callable(*args, jit=True) Wrap function as a complex Numba callable. .. py:function:: callable(*args, complex=False, jit=True, parameterized=False, vectorized=False) Wrap a callable for Bempp. .. py:function:: function_space(grid, kind, degree, scatter=True, **kwargs) Initialize a function space. Parameters ---------- grid : bempp_cl.Grid The grid that the space is defined on. kind : str The space type degree : int The polynomial degree of the space support_elements : np.array The element indices of elements that make up the part of the mesh on which the space is defined. segments : list The segment numbers of the part of the mesh on which the space is defined. swapped_normals : bool TODO scatter : bool TODO include_boundary_dofs : bool Should degrees of freedom on the boundary of the grid segments be included? truncate_at_segment_edge : bool 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. .. py:function:: 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 ---------- A : bempp_cl.api.BoundaryOperator The left-hand side boundary operator b : bempp_cl.api.GridFunction The right-hand side grid function lu_decomp : tuple Optionally pass the tuple (lu, piv) obtained by the scipy method scipy.linalg.lu_factor .. py:function:: 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. .. py:function:: 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. .. py:function:: 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. .. py:function:: as_matrix(operator) Convert a discrte operator into a dense matrix. Parameters ---------- operator : scipy.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. .. py:class:: ZeroBoundaryOperator(domain, range_, dual_to_range) Bases: :py:obj:`BoundaryOperator` A boundary operator that represents a zero operator. Parameters ---------- domain : bempp_cl.api.space.Space Domain space of the operator. range_ : bempp_cl.api.space.Space Range space of the operator. dual_to_range : bempp_cl.api.space.Space Dual space to the range space. .. py:method:: _assemble() .. py:method:: __iadd__(other) Add. .. py:method:: __isub__(other) Subtract. .. py:class:: MultiplicationOperator(grid_function, domain, range_, dual_to_range, parameters=None, mode='component') Bases: :py:obj:`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. .. py:attribute:: _mode :value: 'component' .. py:attribute:: _grid_fun .. py:method:: _assemble() Assemble the operator. .. py:class:: BlockedOperator(m, n) Bases: :py:obj:`BlockedOperatorBase` Construct an m x n blocked boundary operator. .. py:attribute:: _operators .. py:attribute:: _rows .. py:attribute:: _cols .. py:attribute:: _dual_to_range_spaces .. py:attribute:: _range_spaces .. py:attribute:: _domain_spaces .. py:method:: __getitem__(key) Return a component operator with a key of the form (i, j). .. py:method:: __setitem__(key, operator) Set a component operator with a key of the form (i, j). .. py:method:: _fill_complete() Check if each row and column contain at least one operator. .. py:method:: _assemble() Implement the weak form. .. py:property:: range_spaces Return the list of range spaces. .. py:property:: dual_to_range_spaces Return the list of dual_to_range spaces. .. py:property:: domain_spaces Return the list of domain spaces. .. py:class:: GeneralizedBlockedOperator(array) Bases: :py:obj:`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 .. py:attribute:: _ops :value: [] .. py:attribute:: _components_per_row :value: None .. py:attribute:: _components_per_column :value: None .. py:method:: _assemble() Implement the weak form. .. py:property:: range_spaces Return the list of range spaces. .. py:property:: dual_to_range_spaces Return the list of dual_to_range spaces. .. py:property:: domain_spaces Return the list of domain spaces. .. py:function:: clear_fmm_cache() Clean the FMM cache. .. py:function:: 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. identifier : string A unique identifier that is part of the platform name. Used to find the correct platform. buffer_size : int Shared memory buffer size in MB log : Boolean Set to True to log workers. log_level : String Logging level. One of 'debug', 'info', 'warning', 'error', 'critical' max_workers : int Maximum number of workers. If max_workers=-1 (default) the maximum number of workers is identical to the number of devices in the pool. precision : string 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. .. py:data:: CONSOLE_LOGGING_HANDLER :value: None .. py:data:: DEFAULT_LOGGING_FORMAT :value: '%(name)s:%(levelname)s: %(message)s' .. py:data:: DEBUG :value: 10 .. py:data:: TIMING :value: 11 .. py:data:: INFO :value: 20 .. py:data:: WARNING :value: 30 .. py:data:: ERROR :value: 40 .. py:data:: CRITICAL :value: 50 .. py:data:: LOG_LEVEL .. py:data:: GLOBAL_PARAMETERS .. py:function:: _init_logger() Initialize the Bempp logger. .. py:function:: log(message, level='info', flush=True) Log including default flushing for IPython. .. py:function:: flush_log() Flush all handlers. Necessary for Jupyter. .. py:function:: enable_console_logging(level='info') Enable console logging and return the console handler. .. py:function:: set_logging_level(level) Set the logging level. .. py:class:: Timer(enable_log=True, message='', level='timing') Context manager to measure time in Bempp. .. py:attribute:: start :value: 0 .. py:attribute:: end :value: 0 .. py:attribute:: interval :value: 0 .. py:attribute:: enable_log :value: True .. py:attribute:: level :value: 'timing' .. py:attribute:: message :value: '' .. py:method:: __enter__() Enter. .. py:method:: __exit__(*args) Exit. .. py:data:: LOGGER .. py:data:: BEMPP_PATH :value: b'.' .. py:data:: TMP_PATH :value: b'.' .. py:function:: _gmsh_path() Find Gmsh. .. py:function:: check_for_fmm() Return true of compatible FMM found. .. py:function:: _get_version() Get version string. .. py:data:: GMSH_PATH :value: 'gmsh.exe' .. py:data:: __version__ :value: '0.4.2' .. py:data:: PLOT_BACKEND :value: 'gmsh' .. py:data:: ipy .. py:data:: USE_JIT :value: True .. py:data:: CPU_OPENCL_DRIVER_FOUND :value: False .. py:data:: GPU_OPENCL_DRIVER_FOUND :value: False .. py:data:: DEFAULT_DEVICE_INTERFACE :value: 'numba' .. py:data:: DEFAULT_PRECISION :value: 'double' .. py:data:: VECTORIZATION_MODE :value: 'auto' .. py:data:: BOUNDARY_OPERATOR_DEVICE_TYPE :value: 'cpu' .. py:data:: POTENTIAL_OPERATOR_DEVICE_TYPE :value: 'cpu' .. py:data:: ALL :value: -1