Skip to main content
`Ctrl`+`K`

# DMLocatePoints

Locate the points in `v` in the mesh and return a `PetscSF` of the containing cells

## Synopsis

    #include "petscdm.h"
    PetscErrorCode DMLocatePoints(DM dm, Vec v, DMPointLocationType ltype, PetscSF *cellSF)

Collective

## Input Parameters

- dm - The `DM`

- ltype - The type of point location, e.g. `DM_POINTLOCATION_NONE` or `DM_POINTLOCATION_NEAREST`

## Input/Output Parameters

- v - The `Vec` of points, on output contains the nearest mesh points to the given points if `DM_POINTLOCATION_NEAREST` is used

- cellSF - Points to either `NULL`, or a `PetscSF` with guesses for which cells contain each point; on output, the `PetscSF` containing the MPI ranks and local indices of the containing points

## Notes

To do a search of the local cells of the mesh, `v` should have `PETSC_COMM_SELF` as its communicator. To do a search of all the cells in the distributed mesh, `v` should have the same MPI communicator as `dm`.

Points will only be located in owned cells, not overlap cells arising from `DMPlexDistribute()` or other overlapping distributions.

If *cellSF is `NULL` on input, a `PetscSF` will be created. If *cellSF is not `NULL` on input, it should point to an existing `PetscSF`, whose graph will be used as initial guesses.

An array that maps each point to its containing cell can be obtained with

        const PetscSFNode *cells;
        PetscInt           nFound;
        const PetscInt    *found;

        PetscSFGetGraph(cellSF,NULL,&nFound,&found,&cells);

Where cells[i].rank is the MPI rank of the process owning the cell containing point found[i] (or i if found == NULL), and cells[i].index is the index of the cell in its MPI process’ local numbering. This rank is in the communicator for `v`, so if `v` is on `PETSC_COMM_SELF` then the rank will always be 0.

## See Also

`DM`, `DMSetCoordinates()`, `DMSetCoordinatesLocal()`, `DMGetCoordinates()`, `DMGetCoordinatesLocal()`, `DMPointLocationType`

## Level

developer

## Location

src/dm/interface/dmcoordinates.c

## Implementations

DMLocatePoints_Plex() in src/dm/impls/plex/plexgeometry.c

Index of all DM routines
Table of Contents for all manual pages
Index of all manual pages