Peano

Searching...

No Matches

Update the parallel state of particles and keep stats of them. More...

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

[legend]

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

[legend]

Public Member Functions
	__init__ (self, particle_set)

	get_constructor_body (self)
	Define a tailored constructor body.

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

	get_body_of_getGridControlEvents (self)

	get_action_set_name (self)
	Return unique action set name.

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

	get_includes (self)
	Return include statements that you need.

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

	get_body_of_prepareTraversal (self)

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)

Data Fields
	d

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

	parallel

Static Public Attributes
tuple	DefaultDescendInvocationOrder

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 Private Attributes
	__Template_BeginTraversal

	__Template_EndTraversal

	__Template_TouchVertexFirstTime

	__Template_TouchVertexLastTime

Detailed Description

Update the parallel state of particles and keep stats of them.

Particles within a parallel code hold a boolean flag ParallelState. It is this action set's responsibility to maintain this property. Users' codes may use the ParallelState, but as read-only only.

We have two options per particle (held within ParallelState): local and virtual. In our data model, particles are either local or virtual throughout the mesh traversal, but they might change their position and consequently alter their state. Virtual particles can fly in through the boundary, while particles can leave the local domain (and hence become virtual) by moving through the boundary. Virtual particles (another word would be halo particles) are mere copies of particles somewhere else. You should not alter their value, and we can safely throw them away after a traversal, as the subsequent merger at the parallel boundary will re-introduce them. We can also keep them as long as we know that their position doesn't change. In this case, the merger will update the copies in-situ.

To accommodate the fact that a particle moves and switches from local to virtual, we update its state in touchVertexFirstTime().

Validity/correctness

Particles may not change their position throughout the mesh traversal. They can change their position in touchVertexLastTime(). This effectively means they change x in-between two grid sweeps. Consequently, their state might be wrong in-between two sweeps.

This routine has to be injected after additional particles are added to the mesh. That can happen throughout boundary merges or due to resorts. This action set has to be used after each mesh sweep that alters particle positions.

The action set throws away halo particles in touchVertexFirstTime(). Therefore, if you don't use it after each and every mesh sweep, you might get redundant data at the boundary (due to repeated particle inflow) or outdated data. Both is automatically avoided in the boundary merges, which eliminate replica.

Merges along domain boundary

We would like all state updates to be localised within this action set. However, we cannot do everything here: We also have to update the parallel state when we merge along the domain boundary. This happens in the particle set's merge(). The documentation around merge() is summarise here, as we have multiple particle set implementations, but all of them are realised through Jinja templates. So it is better to have stuff in one place only.

The merge in principle is trivial: If a neighbour sends you in a virtual particle, don't do anything with it. Just ignore it. If it is local at the neighbour, we add it to our local vertex.

The sketch above illustrates why it is important to neglect virtual particles sent in: In the sketch, the left subdomain sends its particle (green) over to the right, where it is marked as virtual (red). The right one now sends this particle back (dark green) and we would hold redundant information.

The sketch also illustrates why we throw away virtual particles after the mesh sweep: If the particle moves on the owning rank - and it can only move there - the neighbour would have two virtual copies (as it cannot match old one to new one). So we better throw away all old stuff by default.

With that data flow in mind, particles crossing domain boundaries are automatically given the correct state. We wouldn't have to implement and local/non-local logic in the merge(). This could all be done in this action set. However, we still need some logic here.

The reason is simple: A merge happens in each and every mesh sweep, even if particles do not move. When a particle flies into a domain (it doesn't have to fly, most of the time it has been there anyway) and is a local one at the neighbour, we cannot imply toggle it to virtual here, as it might be owned redundantly if it sits directly on the domain boundaries. We have to rerun the "is local here" analysis after each merge.

Statistics

The mapping keeps some statistics on any state update. These statistics however are not shared via MPI. Instead, we hand them over to the particle set which then can consolidate the data among ranks and cores.

Definition at line 12 of file UpdateParallelState.py.

Constructor & Destructor Documentation

◆ init()

peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.__init__	(		self,
			particle_set )

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Definition at line 113 of file UpdateParallelState.py.

References peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.__init__(), peano4.toolbox.particles.api.AbstractUpdateParticleGridAssociation.AbstractUpdateParticleGridAssociation.DefaultDescendInvocationOrder, peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.DefaultDescendInvocationOrder, and peano4.toolbox.particles.GatherParticlesInMemoryPool.GatherParticlesInMemoryPool.DefaultDescendInvocationOrder.

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

Here is the call graph for this function:

Here is the caller graph for this function:

Member Function Documentation

◆ get_action_set_name()

peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.get_action_set_name ( self )

Return unique action set name.

Returns a description (word) for the mapping which is also used as class name for the generated type. As a consequence, the result should be one word (if possible) and uppercase. Also, every subclass should overwrite this routine.

The generator will take the result and construct eventually classes similar to MyStep2Dummy.h and MyStep2Dummy.cpp or similar for the example below, where we return Dummy.

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Definition at line 285 of file UpdateParallelState.py.

◆ get_attributes()

peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.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.

Definition at line 308 of file UpdateParallelState.py.

◆ get_body_of_getGridControlEvents()

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

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Definition at line 282 of file UpdateParallelState.py.

◆ get_body_of_operation()

peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.get_body_of_operation	(		self,
			operation_name )

Return actual C++ code snippets to be inserted into C++ code.

See class' string constants starting with OPERATION_ for possible values of operation_name.

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Definition at line 270 of file UpdateParallelState.py.

◆ get_body_of_prepareTraversal()

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

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Definition at line 317 of file UpdateParallelState.py.

◆ get_constructor_body()

peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.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.

Definition at line 265 of file UpdateParallelState.py.

◆ get_includes()

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

Return include statements that you need.

All of these includes will eventually end up in the header of the generated C++ code.

Reimplemented from peano4.solversteps.ActionSet.ActionSet.

Definition at line 291 of file UpdateParallelState.py.

◆ user_should_modify_template()

peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.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 288 of file UpdateParallelState.py.

Field Documentation

◆ __Template_BeginTraversal

peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.__Template_BeginTraversal

staticprivate

Initial value:

=  jinja2.Template(
        
    )

Definition at line 125 of file UpdateParallelState.py.

Referenced by peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.get_body_of_operation(), peano4.toolbox.particles.PlotParticlesInVTKFormat.PlotParticlesInVTKFormat.get_body_of_operation(), peano4.toolbox.PlotCellDataInPeanoBlockFormat.PlotCellDataInPeanoBlockFormat.get_body_of_operation(), peano4.toolbox.PlotGridInPeanoBlockFormat.PlotGridInPeanoBlockFormat.get_body_of_operation(), peano4.toolbox.PlotVertexDataInPeanoBlockFormat.PlotVertexDataInPeanoBlockFormat.get_body_of_operation(), solvers.api.actionsets.PlotDGDataInPeanoBlockFormat.PlotDGDataInPeanoBlockFormat.get_body_of_operation(), solvers.api.actionsets.PlotDGPatchesInPeanoBlockFormat.PlotDGPatchesInPeanoBlockFormat.get_body_of_operation(), solvers.api.actionsets.PlotVertexDataInPeanoBlockFormat.PlotVertexDataInPeanoBlockFormat.get_body_of_operation(), and api.actionsets.PlotDGDataInPeanoBlockFormat.PlotDGDataInPeanoBlockFormat.get_body_of_operation().

◆ __Template_EndTraversal

peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.__Template_EndTraversal

staticprivate

Initial value:

=  jinja2.Template(
        
    )

Definition at line 137 of file UpdateParallelState.py.

◆ __Template_TouchVertexFirstTime

peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.__Template_TouchVertexFirstTime

staticprivate

Initial value:

=  jinja2.Template(
        
    )

Definition at line 151 of file UpdateParallelState.py.

◆ __Template_TouchVertexLastTime

peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.__Template_TouchVertexLastTime

staticprivate

Initial value:

=  jinja2.Template(
        
    )

Definition at line 204 of file UpdateParallelState.py.

◆ _particle_set

peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState._particle_set

protected

Definition at line 120 of file UpdateParallelState.py.

◆ d

peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.d

Definition at line 121 of file UpdateParallelState.py.

◆ DefaultDescendInvocationOrder

tuple peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.DefaultDescendInvocationOrder

static

Initial value:

=  (
        AbstractUpdateParticleGridAssociation.DefaultDescendInvocationOrder + 1
    )

Definition at line 109 of file UpdateParallelState.py.

Referenced by peano4.toolbox.particles.api.UpdateParallelState.UpdateParallelState.__init__(), and peano4.toolbox.particles.GatherParticlesInMemoryPool.GatherParticlesInMemoryPool.__init__().

The documentation for this class was generated from the following file:

python/peano4/toolbox/particles/api/UpdateParallelState.py

Public Member Functions

Data Fields

Static Public Attributes

Protected Attributes

Static Private Attributes

Detailed Description

Validity/correctness

Merges along domain boundary

Statistics

Constructor & Destructor Documentation

◆ __init__()

Member Function Documentation

◆ get_action_set_name()

◆ get_attributes()

◆ get_body_of_getGridControlEvents()

◆ get_body_of_operation()

◆ get_body_of_prepareTraversal()

◆ get_constructor_body()

◆ get_includes()

◆ user_should_modify_template()

Field Documentation

◆ __Template_BeginTraversal

◆ __Template_EndTraversal

◆ __Template_TouchVertexFirstTime

◆ __Template_TouchVertexLastTime

◆ _particle_set

◆ d

◆ DefaultDescendInvocationOrder

◆ init()