Peano

Searching...

No Matches

Associate particles to spacetree vertices. More...

Inheritance diagram for peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation:

[legend]

Collaboration diagram for peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation:

[legend]

Public Member Functions
	__init__ (self, particle_set, guard="true")

	get_body_of_getGridControlEvents (self)

	user_should_modify_template (self)
	Is the user allowed to modify the output.

	get_includes (self)
	Inject all the default includes.

	get_constructor_body (self)
	Define a tailored constructor body.

	get_attributes (self)
	Return attributes as copied and pasted into the generated class.

	get_body_of_prepareTraversal (self)
	Create prepareTraversal function.

Public Member Functions inherited from peano4.solversteps.ActionSet.ActionSet
	get_static_initialisations (self, full_qualified_classname)

	get_destructor_body (self)

	get_body_of_unprepareTraversal (self)

	get_body_of_operation (self, operation_name)
	Return actual C++ code snippets to be inserted into C++ code.

	get_action_set_name (self)
	Return unique action set name.

Data Fields
	d

Data Fields inherited from peano4.solversteps.ActionSet.ActionSet
	descend_invocation_order

	parallel

Static Public Attributes
int	DefaultDescendInvocationOrder = -65536

Static Public Attributes inherited from peano4.solversteps.ActionSet.ActionSet
str	OPERATION_BEGIN_TRAVERSAL = "beginTraversal"

str	OPERATION_END_TRAVERSAL = "endTraversal"

str	OPERATION_CREATE_PERSISTENT_VERTEX = "createPersistentVertex"

str	OPERATION_DESTROY_PERSISTENT_VERTEX = "destroyPersistentVertex"

str	OPERATION_CREATE_HANGING_VERTEX = "createHangingVertex"

str	OPERATION_DESTROY_HANGING_VERTEX = "destroyHangingVertex"

str	OPERATION_CREATE_PERSISTENT_FACE = "createPersistentFace"

str	OPERATION_DESTROY_PERSISTENT_FACE = "destroyPersistentFace"

str	OPERATION_CREATE_HANGING_FACE = "createHangingFace"

str	OPERATION_DESTROY_HANGING_FACE = "destroyHangingFace"

str	OPERATION_CREATE_CELL = "createCell"

str	OPERATION_DESTROY_CELL = "destroyCell"

str	OPERATION_TOUCH_VERTEX_FIRST_TIME = "touchVertexFirstTime"

str	OPERATION_TOUCH_VERTEX_LAST_TIME = "touchVertexLastTime"

str	OPERATION_TOUCH_FACE_FIRST_TIME = "touchFaceFirstTime"

str	OPERATION_TOUCH_FACE_LAST_TIME = "touchFaceLastTime"

str	OPERATION_TOUCH_CELL_FIRST_TIME = "touchCellFirstTime"

str	OPERATION_TOUCH_CELL_LAST_TIME = "touchCellLastTime"

Protected Attributes
	_particle_set

Static Protected Attributes
	_Template_BeginTraversal

	_Template_EndTraversal

	_Template_ValidateParticleLevelAssociation

	_Template_Drop

	_Template_LiftAllParticles

Detailed Description

Associate particles to spacetree vertices.

Use one of the subclasses which realise various sorting algorithms. All subclasses realise the particle in dual tree storage scheme. Please read through Multiscale particle storage within mesh and Sorting: Preserving the mesh-particle data consistency besides the current class documentation. If you use a particle memory pool, i.e. if you don't hold the particles scattered all over the place, then it is also relevant to read through the implications for any particle sorting.

If you add the action set peano4.toolbox.particles.PlotParticlesInVTKFormat to your algorithm step, the resulting file will contain all associativity information. You can plot to which vertex a particle belongs to.

Here's a hand-written cartoon to explain the particle storage:

A tree with three levels. Particles with a large search radius (red) are held on rather coarse levels. Particles with very small search radius are sorted (dropped) into the fine grid levels. Each particle is always associated to its closest vertex (dotted line). It is the mesh which holds (owns) the vertices. The toolset's predefined action set can automatically maintain/update these associations after each grid sweep. It also moves particles up and down the grid hierarchy if the particles' search radius changes or the grid changes.

Move particles

To move a particle, all you have to do is to alter its position:

myParticle->setX( {17.3, 8.2} );

setX

state setX(0.0)

Obviously, any change of a particle position could mean that the particle is no longer associated to its nearest vertex. We have to sort them.

Peano automatically maintains these relations if you add the action set peano4.toolbox.particles.UpdateParticleGridAssociation to your algorithmic steps. As the convention relies on a smaller-equals sign, adaptive meshes are automatically supported. If particles travel through your domain and the mesh is not very fine, they end up in the tree leaves. If particles have a large search radius, they are stored in rather coarse levels of the tree.

If you change the search radius or the position of a particle, the particle will stay within its current cell/vertex within the tree. In the next grid sweep, it will however we held by the `‘correct’' vertex, i.e. its grid-vertex association will be updated: The action set UpdateParticleGridAssociation updates the particle-tree association, i.e.~sorts the particles, on-the-fly between two mesh traversals.

While you do not have to worry about how this sorting is realised, it is important to study the action set's documentation (just open the Python code documentation of subclasses) and read when data is consistent. Here is the general invariants that hold for all of them:

The very moment you alter a particle's position, you cannot be sure that it is still associated with the nearest vertex. Consequently, neighbourhood searchers might yield invalid results.
In the grid sweep after the position change, the particle will be associated with the correct vertex (unless you change its position once again obviously).

The action set UpdateParticleGridAssociation relies on some global data. Therefore, you have to call finishTraversal() on the used particle set in your main routine on each rank after all rank-local traversals have termined.

Domain decomposition

You should combine this action set (or any subclass in fact) with the action set UpdateParallelState. Actually, it is sufficient if only the second grid sweep - remember that association updates always have to be added to two grid sweeps in a row - is added an additional action set that updates the particles' parallel state.

Priorities

The update association should precede any other action set in your step. The descend_invocation_order value thus should be very small. As priorities are inverted when we walk from fine to coarse resolutions, this means that all dropping into the mesh (in the second grid sweep) happens before anybody else touches the particles, while the extraction of particles or moves from fine to coarse are epilogues to any operation in the primary mesh sweep.

Number of sweeps

All update flavours need 2+ mesh sweeps. In the first sweep, they check if a particle sits with the right vertex. If not, is it either lifted locally or added to a global sort set. In the second sweep, we then insert particles from global sort sets into the domain or we drop the particles down further in the mesh hierarchy.

Horizontal tree cuts, i.e. situations where the parent cell of a cell belongs to another tree, are challenging: We cannot know prior to the drop if we would drop into such a cut. If we do however, we have to take the respective particle, send it to the neighbour, pick it up in the next mesh traversal and continue dropping. For a tree with depth L, we have up to L-1 drop iterations.

Grid resorting followed by particle-particle interactions

If you have particle-particle interactions while particles may drop within the mesh (due to dynamic AMR or particle movements), you have to be extra careful. There are two major issues to consider, which both can be illustrated with the sketch below.

Particles along AMR boundaries

In the sketch, the green particle would logically belong into the finer mesh level. However, we should not move it up and down: The routine touchVertexFirstTime() should grab particles from the coarser level and drop them, but the routine createHangingVertex() should not. If we dropped them, we would have to lift them immediately afterwards again, as hanging vertices are not persistent in Peano.

This would yield a lot of memory movements and also potentially destroy any well-aligned and ordered memory arrangement which is poisonous for vectorisation. Therefore, we leave particles on coarser levels. The green particles is not dropped.

Let the green particle affect the blue one. As a consequence of the constraint above, the green particle has to be updated with contributions from blue. We need a proper multiscale interaction.

Multiscale interaction

Let green and blue interact. If blue resides on the coarser level and is dropped in the very same mesh traversal, we have to be extra careful:

The blue and the green particle are both cleared on the coarse level. Blue gets contributions from green within the coarse cell, and green gets contributions from blue.
Now we drop blue.
Blue is cleared due to the drop.
Blue is now getting contributions from the coarser level, i.e. green. As this is a multiscale relation, green is also added (fine grid) contributions from blue.

Consequently, the particles on the coarser level gets two times the contributions from the particle which is dropped in this very mesh traversal. To avoid this, we either veto any particle-particle interaction in a mesh traversal which also drops, or we find a mechanism to remove the contributions to coarse meshes whenever we drop a particle. I don't do the latter usually, as it is more complicated.

Sieving

It is the sieving where the various subclasses differ. Sieving has to be used whenever particles move through horizontal cuts. Some subclasses use it to manage all particle transitions (bucket sort), while others only use it for these special cuts plus tunneling particles. Consult the discussion at Sorting: Preserving the mesh-particle data consistency for further contextualisation.

The sieve set is managed via a static attribute of the particle: Each particle has an instance of toolbox::particles::SieveParticles tied to its class. From hereon, we have to options:

Let each action set clone the particle set and then hand out sieved particles from there.
Work against one global cloned version.

Which stategy is the right one depends upon the chosen sieving strategy.

Definition at line 9 of file AbstractUpdateParticleGridAssociation.py.

Constructor & Destructor Documentation

◆ init()

peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation.__init__	(	self,
		particle_set,
		guard = "true" )

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Reimplemented in peano4.toolbox.particles.api.UpdateParticleGridAssociation_BucketSort.UpdateParticleGridAssociation_BucketSort, peano4.toolbox.particles.api.UpdateParticleGridAssociation_LiftDrop.UpdateParticleGridAssociation_LiftDrop, and peano4.toolbox.particles.api.UpdateParticleGridAssociation_Reassign.UpdateParticleGridAssociation_Reassign.

Definition at line 206 of file AbstractUpdateParticleGridAssociation.py.

References peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation.__init__().

Referenced by peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation.__init__().

Here is the call graph for this function:

Here is the caller graph for this function:

Member Function Documentation

◆ get_attributes()

peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation.get_attributes ( self )

Return attributes as copied and pasted into the generated class.

Please note that action sets are not persistent, i.e. there is one object creation per grid sweep per tree.

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Reimplemented in peano4.toolbox.particles.api.UpdateParticleGridAssociation_BucketSort.UpdateParticleGridAssociation_BucketSort.

Definition at line 525 of file AbstractUpdateParticleGridAssociation.py.

◆ get_body_of_getGridControlEvents()

peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation.get_body_of_getGridControlEvents ( self )

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Definition at line 486 of file AbstractUpdateParticleGridAssociation.py.

◆ get_body_of_prepareTraversal()

peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation.get_body_of_prepareTraversal ( self )

Create prepareTraversal function.

Every particle resorting has to invoke

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ vertexdata::{{PARTICLE}}Set::finishedTraversal(DomainOffset, DomainSize, PeriodicBC); ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

after each and every time step to consolidate the global data exchange containers. This routine has to know the domain size and whether there are periodic boundary conditions, as it also is responsible for the mirroring/translation along periodic BCs. Therefore, we have to include the global constants in get_includes().

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Definition at line 538 of file AbstractUpdateParticleGridAssociation.py.

◆ get_constructor_body()

peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation.get_constructor_body ( self )

Define a tailored constructor body.

By default, the constructor of an action set is empty. If you you assign attributes to your action set, you however might want to initialise them here. We do not support initialisation lists, to all has to be done via setters unless you create attributes on the heap.

The constructor's signature will look similar to

   EnumerateAndInitSolution2petsc_actionsets_InitVertexDoFs0(int treeNumber);

where the treeNumber is -1 if this is the global instance of the action set owned by a rank, or a number greater or equal 0 if this action set is a clone of the glocal action set that's used by one tree traversal.

See also: get_attributes() to add attributes to your action set

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Reimplemented in peano4.toolbox.particles.api.UpdateParticleGridAssociation_BucketSort.UpdateParticleGridAssociation_BucketSort.

Definition at line 515 of file AbstractUpdateParticleGridAssociation.py.

Referenced by peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation.get_constructor_body().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ get_includes()

peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation.get_includes ( self )

Inject all the default includes.

See also: get_body_of_prepareTraversal().

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Definition at line 492 of file AbstractUpdateParticleGridAssociation.py.

◆ user_should_modify_template()

peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation.user_should_modify_template ( self )

Is the user allowed to modify the output.

Return whether you expect the user to modify the generated code. If this is the case, then the API places the generated output in the directory actions. Otherwise, it goes into the observer directory and will be overwritten in each and every Python run.

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Definition at line 489 of file AbstractUpdateParticleGridAssociation.py.