Building a bucket index

The bucket index is an accelerating structure that samples the mesh domain and allows us to reduce the locating algorithms complexity. It distributes references to the mesh nodes/elements into the cells of a grid that includes the mesh domain. References are stored on buckets with the same storing capacity. A bucket can share a variable number of grid cells depending on the mesh distribution. Here is an exemple of how to build such a bucket index of a mesh:

local bucketOptions = {
  capacity         = 50,     -- Each bucket will have a maximum of 50 references stored in
  gridStartingSize = -1,     -- The grid size will be automatically initialized
  activeOnly       = false,  -- All mesh elements will be stored, active or not
  info             = true,   -- Will print informations about the mesh mapping
}
local bucketIndex_node  = mm.buildBucketIndex('meshId', 'node',  bucketOptions)  -- Bucket index with node references
local bucketIndex_elem  = mm.buildBucketIndex('meshId', 'cell',  bucketOptions)  -- Bucket index with cell references
local bucketIndex_gauss = mm.buildBucketIndex('meshId', 'gauss', bucketOptions)  -- Bucket index with gauss point references

mm.buildBucketIndex(meshId, bucketType, bucketOptions)
Description:	Stores the selected references of the mesh (nodes or elements) in a bucket index.
Parameters:	meshId	A string with the mesh id.
	bucketType	A string defining the type of bucket. The three available types are: 'node' - node references are stored (implementing the `nearestNode` spatial index object query capability); 'cell' - cell references are stored (implementing the `containingCell` spatial index object query capability); 'gauss' - gauss point references are stored (implementing the `nearestGauss` spatial index object query capability).
	bucketOptions	An optional lua table with a set of flags defining options for the bucket index, and described below.
Returns:	The resulting spatial (bucket) index object.

The bucketOptions table, optionally supplied as a parameter to the mm.buildBucketIndex() function, allows to customize the building process. The supported fields are:

Attribute	Description	Type	Required	Def. Value
capacity	The storing capacity of each bucket.	Integer	No	10
gridStartingSize	The grid partitionning the underlying mesh domain will start with a number of cells equals to `gridStartingSize` in each direction. Setting this value to -1 automatically computes a reasonable value for this number.	Integer	No	-1
nRefineMax	The maximum number of successive refinements a given cell should suffer before considering the bucket capacity is too small.	Integer	No	4
activeOnly	When set to true, only stores the active elements/cells of the mesh. No effect in case of nodes bucket.	Boolean	No	true
nodeSet	Optional filter stating that only the nodes belonging to the given node set should be included in the index. For node buckets only.	String	No	`nil`
cellGroup	Optional filter stating that only the cells belonging to the given cell group should be included in the index. For cell and gauss buckets only.	String	No	`nil`
ruleSet	For Gauss points based bucket indices, this option can be used to set the rule set that will be used for defining the Gauss points location inside each element. By default, the standard rule set (1) is used.	Integer	No	1
info	When set to true, prints informations about the bucket index, just after its creation.	Boolean	No	false

When filling this table, keep in mind that only options different from the default are needed. When an option is not present in the table its default value will be used.

The basic locating operations

Once we have the bucket index built we are able to process some basic operations like finding the closest node, the closest gauss point or identifying the containing cell of a point. In 3D, starting with the (x, y, z) coordinates of a point it is trivial to obtain the (i, j, k) coordinates of its cell position in the index grid. The cell is linked to its corresponding bucket which stores a limited number of references. Those references (nodes or elements) are entities in the neighbourhood of the point. Thus, a local evaluation of distances between the point and the entities can speed up any locating operation, avoiding the user to perform global evalutions. A didactic presentation of the location algorithms is available here

Since the returned bucket index object is a spatial index, location queries can be executed using the standard spatial index methods.