cs_range_set.c File Reference

Operations related to handling of an owning rank for distributed entities. More...

#include "cs_defs.h"
#include <assert.h>
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include <limits.h>
#include <math.h>
#include "bft_mem.h"
#include "bft_printf.h"
#include "cs_base.h"
#include "cs_interface.h"
#include "cs_halo.h"
#include "cs_range_set.h"

Include dependency graph for cs_range_set.c:

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_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. More...
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. 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...

Detailed Description

Operations related to handling of an owning rank for distributed entities.

Global element 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;

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]	ifs	pointer to interface set structure, or NULL
[in]	halo	pointer to halo structure, or NULL
[in]	n_elts	number of elements
[in]	balance	try to balance shared elements across ranks? (for elements shared across an interface set)
[in]	g_id_base	global 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]	ifs	pointer to interface set structure, or NULL
[in]	halo	pointer to halo structure, or NULL
[in]	n_elts	number of elements
[in]	l_range	global id range assigned to local rank: [start, past-the-end[
[in]	g_id	global 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. 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]	ifs	pointer to interface set structure, or NULL
[in]	halo	pointer to halo structure, or NULL
[in]	n_elts	number of elements
[in]	balance	try to balance shared elements across ranks ? (for elements shared across an interface set)
[in]	g_id_base	global id base index (usually 0, but 1 could be used to generate an IO numbering)
[out]	l_range	global id range assigned to local rank: [start, past-the-end[
[out]	g_id	global 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]

rs

pointer 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]	rs	pointer to range set structure, or NULL
[in]	datatype	type of data considered
[in]	stride	number of values per entity (interlaced)
[in]	src_val	source values buffer
[out]	dest_val	destination 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]	rs	pointer to range set structure, or NULL
[in]	datatype	type of data considered
[in]	stride	number of values per entity (interlaced)
[in]	src_val	source values buffer
[out]	dest_val	destination 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]	rs	pointer to range set structure, or NULL
[in]	datatype	type of data considered
[in]	stride	number of values per entity (interlaced)
[in,out]	val	values 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]	rs	pointer to range set structure, or NULL
[in]	datatype	type of data considered
[in]	stride	number of values per entity (interlaced)
[in,out]	val	pointer to array values