PETSC_EXTERN PetscErrorCode DMSwarmSortGetAccess(DM dm)Not collective
| dm | - a DMSwarm object |
Calling DMSwarmSortGetAccess() creates a list which enables easy identification of all points contained in a given cell. This method does not explicitly sort the data within the DMSwarm based on the cell index associated with a DMSwarm point.
The sort context is valid only for the DMSwarm points defined at the time when DMSwarmSortGetAccess() was called. For example, suppose the swarm contained NP points when DMSwarmSortGetAccess() was called. If the user subsequently adds 10 additional points to the swarm, the sort context is still valid, but only for the first NP points. The indices associated with the 10 new additional points will not be contained within the sort context. This means that the user can still safely perform queries via DMSwarmSortGetPointsPerCell() and DMSwarmSortGetPointsPerCell(), however the results return will be based on the first NP points.
If any DMSwam re-sizing method is called after DMSwarmSortGetAccess() which modifies any of the first NP entries in the DMSwarm, the sort context will become invalid. Currently there are no guards to prevent the user from invalidating the sort context. For this reason, we highly recommend you do not use DMSwarmRemovePointAtIndex() in between calls to DMSwarmSortGetAccess() and DMSwarmSortRestoreAccess().
To facilitate safe removal of points using the sort context, we suggest a "two pass" strategy in which the first pass "marks" points for removal, and the second pass actually removes the points from the DMSwarm.