parma.h File Reference

The ParMA tools interface. More...

Go to the source code of this file.

Classes
struct	Parma_GroupCode
	User-defined code to run on process sub-groups. More...
Functions
void	Parma_GetEntImbalance (apf::Mesh *mesh, double(*entImb)[4])
	get entity imbalance
void	Parma_GetWeightedEntImbalance (apf::Mesh *mesh, apf::MeshTag *weight, double(*entImb)[4])
	see Parma_GetEntImbalance(...)
double	Parma_GetWeightedEntImbalance (apf::Mesh *mesh, apf::MeshTag *weight, int dim)
	see Parma_GetEntImbalance(...)
void	Parma_GetNeighborStats (apf::Mesh *m, int &max, int &maxNumParts, double &avg, int &loc)
	get the maximum and average number of vtx-connected neighboring parts
void	Parma_WriteSmallNeighbors (apf::Mesh *m, int small, const char *prefix)
	write the number of parts with neighbors formed by a small number of shared vtx
int	Parma_GetSmallestSideMaxNeighborParts (apf::Mesh *m)
	get the smallest number of shared vertices forming a neighbor ,a 'side', in a part with the maximum number of neigbhors
void	Parma_GetOwnedBdryVtxStats (apf::Mesh *m, int &loc, long &tot, int &min, int &max, double &avg)
	get the number of owned vertices on inter-part boundaries
void	Parma_GetSharedBdryVtxStats (apf::Mesh *m, int &loc, long &tot, int &min, int &max, double &avg)
	get the number of shared vertices on inter-part boundaries
void	Parma_GetMdlBdryVtxStats (apf::Mesh *m, int &loc, long &tot, int &min, int &max, double &avg)
	get the number of vertices classified on the model boundary
void	Parma_GetDisconnectedStats (apf::Mesh *m, int &max, double &avg, int &loc)
	get the maximum, average and local number of face-disconnected components
void	Parma_PrintPtnStats (apf::Mesh *m, std::string key, bool fine=false)
	prints partition stats
void	Parma_PrintWeightedPtnStats (apf::Mesh *m, apf::MeshTag *w, std::string key, bool fine=false)
	prints partition stats using entity weights
void	Parma_ProcessDisconnectedParts (apf::Mesh *m)
	re-connect disconnected parts
apf::Balancer *	Parma_MakeCentroidDiffuser (apf::Mesh *m, double stepFactor=0.1, int verbose=0)
	create an APF Balancer using centroid diffusion
apf::Balancer *	Parma_MakeShapeOptimizer (apf::Mesh *m, double stepFactor=0.1, int verbose=0)
	create an APF Balancer to optimize part shape
apf::Balancer *	Parma_MakeMPASDiffuser (apf::Mesh *m, int layers, int bridge, double stepFactor=0.1, int verbosity=0)
	create an APF Balancer for MPAS
apf::Balancer *	Parma_MakeGhostEdgeDiffuser (apf::Mesh *m, double stepFactor=0.1, int verbosity=0)
	create an edge balancer that is ghost aware
apf::Balancer *	Parma_MakeGhostDiffuser (apf::Mesh *m, int layers, double stepFactor=0.1, int verbosity=0)
	create an APF Balancer using ghost element aware diffusion for a vertex-based partition
apf::Balancer *	Parma_MakeGhostDiffuser (apf::Mesh *m, int layers, int bridge, double stepFactor=0.1, int verbosity=0)
	backward compatability
void	Parma_WriteVtxPtn (apf::Mesh *m, const char *prefix)
	write the vertex based partition to file
apf::Balancer *	Parma_MakeVtxBalancer (apf::Mesh *m, double stepFactor=0.1, int verbosity=0)
	create an APF Balancer targeting vertex imbalance
apf::Balancer *	Parma_MakeElmBalancer (apf::Mesh *m, double stepFactor=0.1, int verbosity=0)
	create an APF Balancer targeting element imbalance
apf::Balancer *	Parma_MakeVtxEdgeElmBalancer (apf::Mesh *m, double stepFactor=0.1, int verbosity=0)
	create an APF Balancer targeting vertex, edge, and elm imbalance
apf::Balancer *	Parma_MakeVtxElmBalancer (apf::Mesh *m, double stepFactor=0.1, int verbosity=0)
	create an APF Balancer targeting vertex, and elm imbalance
apf::Splitter *	Parma_MakeRibSplitter (apf::Mesh *m, bool sync=true)
	create an APF Splitter using recursive inertial bisection
apf::MeshTag *	Parma_WeighByMemory (apf::Mesh *m)
	create a mesh tag that weighs elements by their memory consumption
void	Parma_ShrinkPartition (apf::Mesh2 *m, int factor, Parma_GroupCode &toRun)
	Shrink the mesh into N/factor processes.
void	Parma_SplitPartition (apf::Mesh2 *m, int factor, Parma_GroupCode &toRun)
	Split the processes into groups of (factor).
int	Parma_MisNumbering (apf::Mesh *m, int d)
	Compute maximal independent set numbering.
apf::MeshTag *	Parma_BfsReorder (apf::Mesh *m, int verbosity=0)
	reorder the mesh via a breadth first search

---

Detailed Description

The ParMA tools interface.

Definition in file parma.h.

---

Function Documentation

apf::MeshTag* Parma_BfsReorder	(	apf::Mesh *	m,
		int	verbosity = 0
	)

reorder the mesh via a breadth first search

Remarks:

the returned tag has the reordered vertex order

Parameters:

	m	(In) partitioned mesh
	verbosity	(In) output control, higher values output more

Returns:

apf mesh tag

void Parma_GetDisconnectedStats	(	apf::Mesh *	m,
		int &	max,
		double &	avg,
		int &	loc
	)

get the maximum, average and local number of face-disconnected components

Parameters:

	m	(In) partitioned mesh
	max	(InOut) max disconnected
	avg	(InOut) average disconnected
	loc	(InOut) local disconnected

void Parma_GetEntImbalance	(	apf::Mesh *	mesh,
		double(*)	entImb[4]
	)

get entity imbalance

Parameters:

	mesh	(InOut) partitioned mesh
	entImb	(InOut) entity imbalance [vtx, edge, face, rgn]

void Parma_GetMdlBdryVtxStats	(	apf::Mesh *	m,
		int &	loc,
		long &	tot,
		int &	min,
		int &	max,
		double &	avg
	)

get the number of vertices classified on the model boundary

Parameters:

	m	(In) partitioned mesh
	loc	(InOut) local number of vertices
	tot	(InOut) total number of vertices
	min	(InOut) min number of vertices on a single part
	max	(InOut) max number of vertices on a single part
	avg	(InOut) average number of vertices per part

void Parma_GetNeighborStats	(	apf::Mesh *	m,
		int &	max,
		int &	maxNumParts,
		double &	avg,
		int &	loc
	)

get the maximum and average number of vtx-connected neighboring parts

Remarks:

for each part count the number of parts it shares mesh vertices with

Parameters:

	m	(In) partitioned mesh
	max	(InOut) max neighbors
	maxNumParts	(InOut) number of parts with max neighbors
	avg	(InOut) average neighbors
	loc	(InOut) local neighbors

void Parma_GetOwnedBdryVtxStats	(	apf::Mesh *	m,
		int &	loc,
		long &	tot,
		int &	min,
		int &	max,
		double &	avg
	)

get the number of owned vertices on inter-part boundaries

Parameters:

	m	(In) partitioned mesh
	loc	(InOut) local number of vertices
	tot	(InOut) total number of vertices
	min	(InOut) min number of vertices on a single part
	max	(InOut) max number of vertices on a single part
	avg	(InOut) average number of vertices per part

void Parma_GetSharedBdryVtxStats	(	apf::Mesh *	m,
		int &	loc,
		long &	tot,
		int &	min,
		int &	max,
		double &	avg
	)

get the number of shared vertices on inter-part boundaries

Parameters:

	m	(In) partitioned mesh
	loc	(InOut) local number of vertices
	tot	(InOut) total number of vertices
	min	(InOut) min number of vertices on a single part
	max	(InOut) max number of vertices on a single part
	avg	(InOut) average number of vertices per part

int Parma_GetSmallestSideMaxNeighborParts

(

apf::Mesh *

m

)

get the smallest number of shared vertices forming a neighbor ,a 'side', in a part with the maximum number of neigbhors

Parameters:

m

(In) partitioned mesh

Returns:

smallest number of shared vertices

void Parma_GetWeightedEntImbalance	(	apf::Mesh *	mesh,
		apf::MeshTag *	weight,
		double(*)	entImb[4]
	)

see Parma_GetEntImbalance(...)

Remarks:

On a part, if an entity order (vtx, edge, face, rgn) does not have weights set on all its entities then a weight of one will be assigned to each of the entities (of the given order)

Parameters:

	mesh	(InOut) partitioned mesh
	weight	(In) entity weights used for computing imbalance
	entImb	(InOut) entity imbalance [vtx, edge, face, rgn]

double Parma_GetWeightedEntImbalance	(	apf::Mesh *	mesh,
		apf::MeshTag *	weight,
		int	dim
	)

see Parma_GetEntImbalance(...)

Parameters:

	mesh	(InOut) partitioned mesh
	weight	(In) element weight used for computing imbalance
	dim	(In) entity dimension [vtx|edge|face|rgn]

Returns:

entity imbalance

apf::Balancer* Parma_MakeCentroidDiffuser	(	apf::Mesh *	m,
		double	stepFactor = 0.1,
		int	verbose = 0
	)

create an APF Balancer using centroid diffusion

Parameters:

	m	(In) partitioned mesh
	stepFactor	(In) amount of weight to migrate between parts during diffusion, lower values migrate fewer elements per iteration

Returns:

apf balancer instance

apf::Balancer* Parma_MakeElmBalancer	(	apf::Mesh *	m,
		double	stepFactor = 0.1,
		int	verbosity = 0
	)

create an APF Balancer targeting element imbalance

Parameters:

	m	(In) partitioned mesh
	verbosity	(In) output control, higher values output more

Returns:

apf balancer instance

apf::Balancer* Parma_MakeGhostDiffuser	(	apf::Mesh *	m,
		int	layers,
		double	stepFactor = 0.1,
		int	verbosity = 0
	)

create an APF Balancer using ghost element aware diffusion for a vertex-based partition

Remarks:

Ghosting for a vertex-based partition is asymetric; ghosts are only needed for vertices on the boundary that are owned.

Parameters:

	m	(In) partitioned mesh
	layers	(In) depth of ghosting
	stepFactor	(In) amount of weight to migrate between parts during diffusion, lower values migrate fewer elements per iteration
	verbosity	(In) output control, higher values output more

Returns:

apf balancer instance

apf::Balancer* Parma_MakeGhostEdgeDiffuser	(	apf::Mesh *	m,
		double	stepFactor = 0.1,
		int	verbosity = 0
	)

create an edge balancer that is ghost aware

Parameters:

	m	(In) partitioned mesh
	stepFactor	(In) amount of weight to migrate between parts during diffusion, lower values migrate fewer elements per iteration
	verbosity	(In) output control, higher values output more

Returns:

apf balancer instance

apf::Balancer* Parma_MakeMPASDiffuser	(	apf::Mesh *	m,
		int	layers,
		int	bridge,
		double	stepFactor = 0.1,
		int	verbosity = 0
	)

create an APF Balancer for MPAS

Parameters:

	m	(In) partitioned mesh
	layers	(In) depth of ghosting
	bridge	(In) dimension of entity ghosting depth is based on, typically meshDim-1
	stepFactor	(In) amount of weight to migrate between parts during diffusion, lower values migrate fewer elements per iteration
	verbosity	(In) output control, higher values output more

Returns:

apf balancer instance

apf::Splitter* Parma_MakeRibSplitter	(	apf::Mesh *	m,
		bool	sync = true
	)

create an APF Splitter using recursive inertial bisection

Parameters:

	m	(In) partitioned mesh
	sync	(In) true if all parts will be split, false o.w.

Returns:

apf splitter instance

apf::Balancer* Parma_MakeShapeOptimizer	(	apf::Mesh *	m,
		double	stepFactor = 0.1,
		int	verbose = 0
	)

create an APF Balancer to optimize part shape

Parameters:

	m	(In) partitioned mesh
	stepFactor	(In) amount of weight to migrate between parts during diffusion, lower values migrate fewer elements per iteration

Returns:

apf balancer instance

apf::Balancer* Parma_MakeVtxBalancer	(	apf::Mesh *	m,
		double	stepFactor = 0.1,
		int	verbosity = 0
	)

create an APF Balancer targeting vertex imbalance

Parameters:

	m	(In) partitioned mesh
	verbosity	(In) output control, higher values output more

Returns:

apf balancer instance

apf::Balancer* Parma_MakeVtxEdgeElmBalancer	(	apf::Mesh *	m,
		double	stepFactor = 0.1,
		int	verbosity = 0
	)

create an APF Balancer targeting vertex, edge, and elm imbalance

Parameters:

	m	(In) partitioned mesh
	verbosity	(In) output control, higher values output more

Returns:

apf balancer instance

apf::Balancer* Parma_MakeVtxElmBalancer	(	apf::Mesh *	m,
		double	stepFactor = 0.1,
		int	verbosity = 0
	)

create an APF Balancer targeting vertex, and elm imbalance

Parameters:

	m	(In) partitioned mesh
	verbosity	(In) output control, higher values output more

Returns:

apf balancer instance

int Parma_MisNumbering	(	apf::Mesh *	m,
		int	d
	)

Compute maximal independent set numbering.

Remarks:

This function will compute the maximal independent set numbering for the partition such that no two part neighbors that share dimension d mesh entities will be assigned the same number.

Parameters:

	m	(In) partitioned mesh
	d	(In) adjacency dimension

void Parma_PrintPtnStats	(	apf::Mesh *	m,
		std::string	key,
		bool	fine = false
	)

prints partition stats

Remarks:

includes face-disconnected components, number of vertices on inter-part boundaries, number of vtx-connected neighboring parts, entity imbalance, and number of empty parts

Parameters:

	m	(In) partitioned mesh
	key	(In) identifying string to write with stat output
	fine	(In) enable per part stat output

void Parma_PrintWeightedPtnStats	(	apf::Mesh *	m,
		apf::MeshTag *	w,
		std::string	key,
		bool	fine = false
	)

prints partition stats using entity weights

Remarks:

On a part, if an entity order (vtx, edge, face, rgn) does not have weights set on all its entities then a weight of one will be assigned to each of the entities (of the given order)

Parameters:

	m	(In) partitioned mesh
	w	(In) tag with entity weights
	key	(In) identifying string to write with stat output
	fine	(In) enable per part stat output

void Parma_ProcessDisconnectedParts

(

apf::Mesh *

m

)

re-connect disconnected parts

Parameters:

m

(In) partitioned mesh

void Parma_ShrinkPartition	(	apf::Mesh2 *	m,
		int	factor,
		Parma_GroupCode &	toRun
	)

Shrink the mesh into N/factor processes.

This function will take N=PCU_Comm_Peers() and generate (factor) subgroups, each of (N/factor) processes. It then migrates the mesh onto group 0 and then calls the user's group code on all groups. After the user's code completes, the mesh is repartitioned to all N processes and this function returns. groups are organized such that contiguous ranges of (factor) parts are combined into one and then that one is split back out into (factor) contiguous part ids again.

void Parma_SplitPartition	(	apf::Mesh2 *	m,
		int	factor,
		Parma_GroupCode &	toRun
	)

Split the processes into groups of (factor).

This function groups contiguous ranges of (factor) processes into (PCU_Comm_Peers()/factor) total groups, then calls the user's group code. After the user's code completes, execution returns to the global communicator. If a non-zero mesh pointer is given, then apf::remapPartition is used to maintain the mesh structure during these transitions.

apf::MeshTag* Parma_WeighByMemory

(

apf::Mesh *

m

)

create a mesh tag that weighs elements by their memory consumption

Parameters:

m

(In) partitioned mesh

Returns:

mesh tag

void Parma_WriteSmallNeighbors	(	apf::Mesh *	m,
		int	small,
		const char *	prefix
	)

write the number of parts with neighbors formed by a small number of shared vtx

Parameters:

	m	(In) partitioned mesh
	small	(In) report part counts with [1:small] number of shared vertices
	prefix	(In) string to prepend to output

void Parma_WriteVtxPtn	(	apf::Mesh *	m,
		const char *	prefix
	)

write the vertex based partition to file

Parameters:

	m	(In) partitioned mesh
	prefix	(In) prefix for file names