My Project
programmer's documentation
Data Structures | Functions
cs_range_set.h File Reference
#include "cs_defs.h"
#include "fvm_group.h"
#include "fvm_selector.h"
#include "fvm_periodicity.h"
#include "cs_base.h"
#include "cs_halo.h"
#include "cs_interface.h"
#include "cs_numbering.h"
#include "cs_mesh_builder.h"
Include dependency graph for cs_range_set.h:

Go to the source code of this file.

Data Structures

struct  cs_range_set_t
 

Functions

void cs_range_set_define (const cs_interface_set_t *ifs, const cs_halo_t *halo, cs_lnum_t n_elts, bool balance, cs_gnum_t g_id_base, cs_gnum_t l_range[2], cs_gnum_t *g_id)
 Define global ids and a partitioning of data based on local ranges for elements which may be shared across ranks or have halo elements. More...
 
cs_range_set_tcs_range_set_create (const cs_interface_set_t *ifs, const cs_halo_t *halo, cs_lnum_t n_elts, bool balance, cs_gnum_t g_id_base)
 Create a range set (with associated range and global ids) for the partitioning of data based on local ranges for elements which may be shared across ranks or have halo elements. More...
 
cs_range_set_tcs_range_set_create_from_shared (const cs_interface_set_t *ifs, const cs_halo_t *halo, cs_lnum_t n_elts, cs_gnum_t l_range[2], cs_gnum_t *g_id)
 Create a range set (with associated range and global ids) from an existing partition of data based on local ranges for elements which may be shared across ranks or have halo elements. More...
 
void cs_range_set_destroy (cs_range_set_t **rs)
 Destroy a range set structure. More...
 
void cs_range_set_zero_out_of_range (const cs_range_set_t *rs, cs_datatype_t datatype, cs_lnum_t stride, void *val)
 Set values of a given array to zero for indexes of elements outside the local range. More...
 
void cs_range_set_sync (const cs_range_set_t *rs, cs_datatype_t datatype, cs_lnum_t stride, void *val)
 Synchronize values elements associated with a range set, using either a halo or an interface set. More...
 
void cs_range_set_gather (const cs_range_set_t *rs, cs_datatype_t datatype, cs_lnum_t stride, const void *src_val, void *dest_val)
 Gather element values associated with a range set to a compact set. More...
 
void cs_range_set_scatter (const cs_range_set_t *rs, cs_datatype_t datatype, cs_lnum_t stride, const void *src_val, void *dest_val)
 Scatter element values associated with a range set to the full set. More...
 

Function Documentation

◆ cs_range_set_create()

cs_range_set_t* cs_range_set_create ( const cs_interface_set_t ifs,
const cs_halo_t halo,
cs_lnum_t  n_elts,
bool  balance,
cs_gnum_t  g_id_base 
)

Create a range set (with associated range and global ids) for the partitioning of data based on local ranges for elements which may be shared across ranks or have halo elements.

Global id ranges are assigned to each rank of the interface set's associated communicator, and global ids are defined by a parallel scan type operation counting elements on parallel interfaces only once. Each element will appear inside one rank's range and outside the range of all other ranks. Ranges across different ranks are contiguous.

The range set maintains pointers to the optional interface set and halo structures, but does not copy them, so those structures should have a lifetime at least as long as the returned range set.

Parameters
[in]ifspointer to interface set structure, or NULL
[in]halopointer to halo structure, or NULL
[in]n_eltsnumber of elements
[in]balancetry to balance shared elements across ranks ? (for elements shared across an interface set)
[in]g_id_baseglobal id base index (usually 0, but 1 could be used to generate an IO numbering)
Returns
pointer to created range set structure

Global id ranges are assigned to each rank of the interface set's associated communicator, and global ids are defined by a parallel scan type operation counting elements on parallel interfaces only once. Each element will appear inside one rank's range and outside the range of all other ranks. Ranges across different ranks are contiguous.

The range set maintains pointers to the optional interface set and halo structures, but does not copy them, so those structures should have a lifetime at least as long as the returned range set.

Parameters
[in]ifspointer to interface set structure, or NULL
[in]halopointer to halo structure, or NULL
[in]n_eltsnumber of elements
[in]balancetry to balance shared elements across ranks? (for elements shared across an interface set)
[in]g_id_baseglobal id base index (usually 0, but 1 could be used to generate an IO numbering)
Returns
pointer to created range set structure

◆ cs_range_set_create_from_shared()

cs_range_set_t* cs_range_set_create_from_shared ( const cs_interface_set_t ifs,
const cs_halo_t halo,
cs_lnum_t  n_elts,
cs_gnum_t  l_range[2],
cs_gnum_t g_id 
)

Create a range set (with associated range and global ids) from an existing partition of data based on local ranges for elements which may be shared across ranks or have halo elements.

The optional interface set, halo, and global element id array are only shared by the range set, not copied, so they should have a lifetime at least as long as the returned range set.

Parameters
[in]ifspointer to interface set structure, or NULL
[in]halopointer to halo structure, or NULL
[in]n_eltsnumber of elements
[in]l_rangeglobal id range assigned to local rank: [start, past-the-end[
[in]g_idglobal id assigned to elements
Returns
pointer to created range set structure

◆ cs_range_set_define()

void cs_range_set_define ( const cs_interface_set_t ifs,
const cs_halo_t halo,
cs_lnum_t  n_elts,
bool  balance,
cs_gnum_t  g_id_base,
cs_gnum_t  l_range[2],
cs_gnum_t g_id 
)

Define global ids and a partitioning of data based on local ranges for elements which may be shared across ranks or have halo elements.

This is a utility function, allowing a similar call for cases where matching elements or parallel ranks are identified using an interface set (for elements which may be on rank boundaries, such as vertices or faces), elements with an associated a halo (such as for cells), or neither (in the single-rank case).

Global id ranges are assigned to each rank, and global ids are defined by a parallel scan type operation counting elements on parallel interfaces only once. Each element will appear inside one rank's range and outside the range of all other ranks.

This allows building distribution information such as that used in many external libraries, such as PETSc, HYPRE, and may also simplify many internal operations, where it is needed that elements have a unique owner rank, and are ghosted on others (such as linear solvers operating on elements which may be on parallel boundaries, such as vertices, edges, and faces).

Elements and their periodic matches allways have distinct global ids;

Parameters
[in]ifspointer to interface set structure, or NULL
[in]halopointer to halo structure, or NULL
[in]n_eltsnumber of elements
[in]balancetry to balance shared elements across ranks ? (for elements shared across an interface set)
[in]g_id_baseglobal id base index (usually 0, but 1 could be used to generate an IO numbering)
[out]l_rangeglobal id range assigned to local rank: [start, past-the-end[
[out]g_idglobal id assigned to elements

This is a utility function, allowing a similar call for cases where matching elements or parallel ranks are identified using an interface set (for elements which may be on rank boundaries, such as vertices or faces), elements with an associated a halo (such as for cells), or neither (in the single-rank case).

Global id ranges are assigned to each rank, and global ids are defined by a parallel scan type operation counting elements on parallel interfaces only once. Each element will appear inside one rank's range and outside the range of all other ranks. Ranges across different ranks are contiguous.

This allows building distribution information such as that used in many external libraries, such as PETSc, HYPRE, and may also simplify many internal operations, where it is needed that elements have a unique owner rank, and are ghosted on others (such as linear solvers operating on elements which may be on parallel boundaries, such as vertices, edges, and faces).

Elements and their periodic matches allways have distinct global ids;

Parameters
[in]ifspointer to interface set structure, or NULL
[in]halopointer to halo structure, or NULL
[in]n_eltsnumber of elements
[in]balancetry to balance shared elements across ranks ? (for elements shared across an interface set)
[in]g_id_baseglobal id base index (usually 0, but 1 could be used to generate an IO numbering)
[out]l_rangeglobal id range assigned to local rank: [start, past-the-end[
[out]g_idglobal id assigned to elements

◆ cs_range_set_destroy()

void cs_range_set_destroy ( cs_range_set_t **  rs)

Destroy a range set structure.

Parameters
[in,out]rspointer to pointer to structure to destroy

◆ cs_range_set_gather()

void cs_range_set_gather ( const cs_range_set_t rs,
cs_datatype_t  datatype,
cs_lnum_t  stride,
const void *  src_val,
void *  dest_val 
)

Gather element values associated with a range set to a compact set.

Parameters
[in]rspointer to range set structure, or NULL
[in]datatypetype of data considered
[in]stridenumber of values per entity (interlaced)
[in]src_valsource values buffer
[out]dest_valdestination values buffer (may be identical to src_val, in which case operation is "in-place")

◆ cs_range_set_scatter()

void cs_range_set_scatter ( const cs_range_set_t rs,
cs_datatype_t  datatype,
cs_lnum_t  stride,
const void *  src_val,
void *  dest_val 
)

Scatter element values associated with a range set to the full set.

This includes parallel synchronization when the range set is associated with a halo or interface set structure.

Parameters
[in]rspointer to range set structure, or NULL
[in]datatypetype of data considered
[in]stridenumber of values per entity (interlaced)
[in]src_valsource values buffer
[out]dest_valdestination values buffer (may be identical to src_val, in which case operation is "in-place")

◆ cs_range_set_sync()

void cs_range_set_sync ( const cs_range_set_t rs,
cs_datatype_t  datatype,
cs_lnum_t  stride,
void *  val 
)

Synchronize values elements associated with a range set, using either a halo or an interface set.

Parameters
[in]rspointer to range set structure, or NULL
[in]datatypetype of data considered
[in]stridenumber of values per entity (interlaced)
[in,out]valvalues buffer

◆ cs_range_set_zero_out_of_range()

void cs_range_set_zero_out_of_range ( const cs_range_set_t rs,
cs_datatype_t  datatype,
cs_lnum_t  stride,
void *  val 
)

Set values of a given array to zero for indexes of elements outside the local range.

If an interface set used to define the range set is available, it may be used to accelerate this operation, as only elements on that interface need to be checked.

Parameters
[in]rspointer to range set structure, or NULL
[in]datatypetype of data considered
[in]stridenumber of values per entity (interlaced)
[in,out]valpointer to array values