Discretizations

QBX discretization

To compute a layer potential as an an end user, create a meshmode.discretization.Discretization with a meshmode.discretization.poly_element.InterpolatoryQuadratureSimplexGroupFactory as a discretization for the density.

Then create pytential.qbx.QBXLayerPotentialSource, pytential.bind() a layer potential operator to it, and you can start computing.

class pytential.qbx.QBXLayerPotentialSource(density_discr: Discretization, fine_order: int | None, qbx_order: int | None = None, fmm_order: bool | int | None = None, fmm_level_to_order: Literal[False] | Callable[..., int] | None = None, expansion_factory: QBXExpansionFactory | None = None, target_association_tolerance: float | type[_not_provided] | None = <class 'pytential.qbx._not_provided'>, debug: bool = True, _disable_refinement: bool = False, _expansions_in_tree_have_extent: bool = True, _expansion_stick_out_factor: float = 0.5, _max_leaf_refine_weight: int | None = None, _box_extent_norm: ExtentNorm | None = None, _tree_kind: str = 'adaptive', _well_sep_is_n_away: int = 2, _from_sep_smaller_crit: str | None = None, _from_sep_smaller_min_nsources_cumul: int | None = None, _use_target_specific_qbx: bool | None = None, geometry_data_inspector: Callable[..., bool] | None = None, cost_model: AbstractQBXCostModel | None = None, fmm_backend: FMMBackend = 'sumpy')

A source discretization for a QBX layer potential.

qbx_order

fmm_order

__init__(density_discr: Discretization, fine_order: int | None, qbx_order: int | None = None, fmm_order: bool | int | None = None, fmm_level_to_order: Literal[False] | Callable[..., int] | None = None, expansion_factory: QBXExpansionFactory | None = None, target_association_tolerance: float | type[_not_provided] | None = <class 'pytential.qbx._not_provided'>, debug: bool = True, _disable_refinement: bool = False, _expansions_in_tree_have_extent: bool = True, _expansion_stick_out_factor: float = 0.5, _max_leaf_refine_weight: int | None = None, _box_extent_norm: ExtentNorm | None = None, _tree_kind: str = 'adaptive', _well_sep_is_n_away: int = 2, _from_sep_smaller_crit: str | None = None, _from_sep_smaller_min_nsources_cumul: int | None = None, _use_target_specific_qbx: bool | None = None, geometry_data_inspector: Callable[..., bool] | None = None, cost_model: AbstractQBXCostModel | None = None, fmm_backend: FMMBackend = 'sumpy') → None

Parameters:

• fine_order – The total degree to which the (upsampled) underlying quadrature is exact.

• fmm_order – Use False for direct calculation or an integer otherwise. May not be given (i.e. left as None) if fmm_level_to_order is given.

• fmm_level_to_order – A callable that takes arguments of (kernel, kernel_args, tree, level) and returns the expansion order to be used on a given level of tree with kernel, where kernel is the sumpy.kernel.Kernel being evaluated, and kernel_args is a set of (key, value) tuples with evaluated kernel arguments. May not be given if fmm_order is given.

• fmm_backend – a string denoting the desired FMM backend to use, either “sumpy” or “fmmlib”. Only used if fmm_order or fmm_level_to_order are provided.

• expansion_factory – used to get local and multipole expansions for the FMM evaluations.

• target_association_tolerance – passed on to pytential.qbx.target_assoc.associate_targets_to_qbx_centers().

Experimental arguments without a promise of forward compatibility:

Parameters:

• _expansions_in_tree_have_extent – if True, target radii are passed to the tree build, see boxtree.TreeBuilder.__call__().

• _expansion_stick_out_factor – passed on to the tree builder, see boxtree.Tree.stick_out_factor for meaning.

• _max_leaf_refine_weight – passed on to the tree builder, see boxtree.TreeBuilder.__call__().

• _box_extent_norm – passed on to the tree builder, see boxtree.TreeBuilder.__call__().

• _tree_kind – passed on to the tree builder, see boxtree.TreeBuilder.__call__().

• _well_sep_is_n_away – see boxtree.traversal.FMMTraversalBuilder

• _from_sep_smaller_crit – see boxtree.traversal.FMMTraversalBuilder.

• _from_sep_smaller_min_nsources_cumul – see boxtree.traversal.FMMTraversalBuilder.__call__().

• _use_target_specific_qbx – Whether to use target-specific acceleration by default if possible. None means “use if possible”.

• cost_model – Either None or an object implementing the AbstractQBXCostModel interface, used for gathering modeled costs if provided (experimental).

copy(density_discr=None, fine_order=None, qbx_order=None, fmm_order=<class 'pytential.qbx._not_provided'>, fmm_level_to_order=<class 'pytential.qbx._not_provided'>, expansion_factory=None, target_association_tolerance=<class 'pytential.qbx._not_provided'>, _expansions_in_tree_have_extent=<class 'pytential.qbx._not_provided'>, _expansion_stick_out_factor=<class 'pytential.qbx._not_provided'>, _max_leaf_refine_weight=None, _box_extent_norm=None, _from_sep_smaller_crit=None, _tree_kind=None, _use_target_specific_qbx=<class 'pytential.qbx._not_provided'>, geometry_data_inspector=None, cost_model=<class 'pytential.qbx._not_provided'>, fmm_backend=None, debug=<class 'pytential.qbx._not_provided'>, _disable_refinement=<class 'pytential.qbx._not_provided'>)

See QBX internals for some information on the inner workings of this.

class pytential.qbx.QBXTargetAssociationFailedError(refine_flags, failed_target_flags, message)

refine_flags

failed_target_flags

class pytential.qbx.DefaultExpansionFactory

An expansion factory to create QBX local, local and multipole expansions

class pytential.qbx.NonFFTExpansionFactory

A expansion factory to create QBX local, local and multipole expansions with no FFT for multipole-to-local translations

Unregularized discretization

class pytential.unregularized.UnregularizedLayerPotentialSource(density_discr: Discretization, fmm_order: Literal[False] | int | None = False, fmm_level_to_order: Literal[False] | Callable[..., int] | None = None, expansion_factory: ExpansionFactoryBase | None = None, debug=True)

A source discretization for a layer potential discretized with a Nyström method that uses element-based quadrature and does not modify the kernel.

fmm_level_to_order

Sources

class pytential.source.PotentialSource

abstract property ambient_dim: int

Ambient dimension of the points in the source geometry.

abstract property ndofs: int

Number of points (DOFs) in the source geometry.

abstract property real_dtype

dtype of real data living on the source geometry.

abstract property complex_dtype

dtype of complex data living on the source geometry.

abstractmethod op_group_features(expr: IntG) → tuple[Hashable, ...]

Parameters:

expr – a subclass of IntG.

Returns:

a characteristic tuple by which operators that can be executed together can be grouped.

abstractmethod get_p2p(actx: PyOpenCLArrayContext, target_kernels: tuple[Kernel, ...], source_kernels: tuple[Kernel, ...] | None = None) → P2PBase

Returns:

a subclass of P2PBase for evaluating the target_kernels and the source_kernels on the source geometry.

preprocess_optemplate(name: Hashable, discretizations: GeometryCollection, expr: T) → T

Returns:

a processed expr, where each IntG operator has been modified to work with the current source geometry.

class pytential.source.PointPotentialSource(nodes)

nodes

An pyopencl.array.Array of shape [ambient_dim, ndofs].

ndofs

cost_model_compute_potential_insn(actx, insn, bound_expr, evaluate, costs)

exec_compute_potential_insn(actx, insn, bound_expr, evaluate, return_timing_data)

class pytential.source.LayerPotentialSourceBase(density_discr: Discretization)

A discretization of a layer potential using element-based geometry, with support for refinement and upsampling.

Inherits from PotentialSource.

density_discr

Targets

Target discretizations are a simpler version of the full meshmode.discretization.Discretization interface. They do not provide any evaluation of integrals, norms, or layer potentials, but are instead only geared towards being used as evaluation targets.

class pytential.target.TargetBase

abstract property ambient_dim: int

Ambient dimension of the points in the target geometry.

abstract property ndofs: int

Number of points (DOFs) in the target geometry.

abstractmethod nodes() → Array

Returns:

an array of points of shape [ambient_dim, ndofs] that form the target geometry.

pytential.target.TargetOrDiscretization

alias of TargetBase | Discretization

class pytential.target.PointsTarget(nodes: Array, normals: Array | None = None)

A generic container for a set of target points.

The point of this class is to act as a container for some target points while presenting enough of the meshmode.discretization.Discretization interface to not necessitate a lot of special cases in that code path.

normals: Array | None

An array of the same shape as TargetBase.nodes() that gives the normals at each of the target points.

preprocess_optemplate(name: str, discretizations: GeometryCollection, expr: T) → T

See PotentialSource.

class pytential.target.Array

See arraycontext.Array.

Geometry Collection

class pytential.collection.AutoWhereLike

Types accepted for auto_where arguments to aid in determining where an expression is evaluated.

class pytential.collection.GeometryLike

Types accepted by the GeometryCollection.

class pytential.collection.GeometryCollection(places: GeometryLike | tuple[GeometryLike, GeometryLike] | Mapping[GeometryId, GeometryLike], auto_where: AutoWhereLike | None = None)

A mapping from symbolic identifiers (“place IDs”, typically strings) to ‘geometries’, where a geometry can be a PotentialSource, a TargetBase or a Discretization.

This class is meant to hold a specific combination of sources and targets serve to host caches of information derived from them, e.g. FMM trees of subsets of them, as well as related common subexpressions such as metric terms.

Refinement of pytential.qbx.QBXLayerPotentialSource entries is performed on demand, i.e. on calls to get_discretization() with a specific discr_stage. To perform refinement explicitly, call pytential.qbx.refinement.refine_geometry_collection(), which allows more customization of the refinement process through parameters.

__init__(places: GeometryLike | tuple[GeometryLike, GeometryLike] | Mapping[GeometryId, GeometryLike], auto_where: AutoWhereLike | None = None) → None

Parameters:

• places – a scalar, tuple of or mapping of symbolic names to geometry objects. Supported objects are PotentialSource, TargetBase and Discretization. If this is a mapping, the keys that are strings must be valid Python identifiers. The tuple should contain only two entries, denoting the source and target geometries for layer potential evaluation, identified by auto_where.

• auto_where – a single or a tuple of two DOFDescriptors, or values that can be converted to one using as_dofdesc(). The two descriptors are used to define the default source and target geometries for layer potential evaluations. By default, they are set to unspecified, but unique objects.

auto_source

Default DOFDescriptor for the source geometry.

auto_target

Default DOFDescriptor for the target geometry.

get_geometry(geometry: Hashable) → pytential.collection.GeometryLike

Parameters:

geometry – the identifier of the geometry in the collection.

get_discretization(geometry: GeometryId, discr_stage: DiscretizationStage | None = None) → GeometryLike

Get the geometry or discretization in the collection.

If a specific QBX stage discretization is requested, refinement is performed on demand and cached for subsequent calls.

Parameters:

• geometry – the identifier of the geometry in the collection.

• discr_stage – if the geometry is a LayerPotentialSourceBase, this denotes the QBX stage of the returned discretization. Can be one of QBX_SOURCE_STAGE1 (default), QBX_SOURCE_STAGE2 or QBX_SOURCE_QUAD_STAGE2.

Returns:

a geometry object in the collection or a Discretization corresponding to discr_stage.

get_connection(from_dd: DOFDescriptorLike, to_dd: DOFDescriptorLike) → DiscretizationConnection

Construct a connection from from_dd to to_dd geometries.

Returns:

an object compatible with the DiscretizationConnection interface.

copy(places: Mapping[Hashable, TypeAliasForwardRef('pytential.collection.GeometryLike')] | None = None, auto_where: DOFDescriptor | Hashable | tuple[DOFDescriptor | Hashable, DOFDescriptor | Hashable] | None = None) → GeometryCollection

Get a shallow copy of the geometry collection.

merge(places: GeometryCollection | Mapping[Hashable, TypeAliasForwardRef('pytential.collection.GeometryLike')]) → GeometryCollection

Merges two geometry collections and returns the new collection.

Parameters:

places – a mapping or GeometryCollection to merge with the current collection. If it is empty, a copy of the current collection is returned.

pytential.collection.add_geometry_to_collection(places: GeometryCollection, geometries: Mapping[Hashable, TypeAliasForwardRef('pytential.collection.GeometryLike')]) → GeometryCollection

Adds a mapping of geometries to an existing collection.

This function is similar to GeometryCollection.merge(), but it makes an attempt to maintain the caches in places. In particular, a shallow copy of the following are passed to the new collection

• Any cached discretizations from refine_geometry_collection().

• Any cached expressions marked with cse_scope.DISCRETIZATION from the evaluation mapper.

This allows adding new targets to the collection without recomputing the source geometry data.