Per-box CSR lookup from a source cell to the destination boxes whose ghosted region covers it. More...

#include <CD_ParticleGhostMask.H>

Public Member Functions
	ParticleGhostMask ()=default
	Default constructor. Leaves the table undefined; call define() before use.

	~ParticleGhostMask ()=default
	Destructor.

void	define (const Box &a_box) noexcept
	Reset to an empty table over a box (every cell has zero targets).

void	incrementCount (const IntVect &a_iv) noexcept
	Build pass 1: register that cell a_iv gains one more target.

void	allocate () noexcept
	Build step between the passes: turn the per-cell counts into CSR offsets and size the packed target array. Must be called after all incrementCount() and before any addTarget().

void	allocateTargetBoxes () noexcept
	Optional build step: size the per-target acceptance-box array to match the packed target array.

void	addTarget (const IntVect &a_iv, const LevelTiles::BoxIDs &a_target) noexcept
	Build pass 2: append one target for cell a_iv.

void	addTarget (const IntVect &a_iv, const LevelTiles::BoxIDs &a_target, const Box &a_targetBox) noexcept
	Build pass 2 with an acceptance box: append one target and its acceptance box for cell a_iv.

void	finalize () noexcept
	Finish the build: rewind m_start (advanced by addTarget) back to the CSR start offsets.

const Box &	box () const noexcept
	Get the box that the source cells live on.

int	numTargets (const IntVect &a_iv) const noexcept
	Get the number of scatter targets for a cell.

const LevelTiles::BoxIDs &	target (const IntVect &a_iv, const int a_i) const noexcept
	Get the i-th scatter target for a cell.

unsigned int	targetGridIndex (const IntVect &a_iv, const int a_i) const noexcept
	Get the destination grid index of the i-th target for a cell.

unsigned int	targetRank (const IntVect &a_iv, const int a_i) const noexcept
	Get the receiving rank of the i-th target for a cell.

const Box &	targetBox (const IntVect &a_iv, const int a_i) const noexcept
	Get the acceptance box of the i-th target for a cell.

bool	hasTargetBoxes () const noexcept
	Whether this mask carries per-target acceptance boxes.

Protected Attributes
Box	m_box
	Box that the source cells (and m_start/m_count) live on.

BaseFab< int >	m_start
	Per cell: first index into m_flat, or -1 if the cell has no targets.

BaseFab< int >	m_count
	Per cell: number of targets.

std::vector< LevelTiles::BoxIDs >	m_flat
	Packed targets, size == sum(m_count).

std::vector< Box >	m_flatBox
	Packed per-target acceptance boxes, parallel to m_flat. Empty unless the mask carries them.

Detailed Description

Per-box CSR lookup from a source cell to the destination boxes whose ghosted region covers it.

Each cell of the box maps to zero or more scatter targets, a target being a LevelTiles::BoxIDs pair = (grid index on the destination level, rank that owns and will receive that box). Storage is compressed-sparse-row: for a cell, m_start holds the offset into the packed target array m_flat and m_count the number of targets. A cell may map to several targets (overlapping ghosted boxes, e.g. diagonal coarse-fine cells) with no fixed cap; the sending rank is not stored.

Optionally (coarse-to-fine only) each target also carries an acceptance box: the destination box's ghost region measured in DESTINATION cells (grown by the ghost width). It lets the scatter prune whole-coarse-cell over-communication down to the exact sub-cell shell – a candidate particle is scattered only if its destination cell lies in the acceptance box. This parallel array m_flatBox is populated only when allocateTargetBoxes()/addTarget(...,box) are used; same-level and fine-to-coarse masks leave it empty (no per-target box, no memory cost).

The build API is a two-pass fill (define -> incrementCount per contribution -> allocate [-> allocateTargetBoxes] -> addTarget per contribution -> finalize). The query API (numTargets/target/ targetGridIndex/targetRank[/targetBox]) is inlined so downstream scatter code never touches the CSR internals.

Member Function Documentation

◆ addTarget() [1/2]

void ParticleGhostMask::addTarget	(	const IntVect &	a_iv,
		const LevelTiles::BoxIDs &	a_target
	)

inlinenoexcept

Build pass 2: append one target for cell a_iv.

Uses m_start as the advancing write head; call exactly numTargets(a_iv) times per cell (the same cells/counts as pass 1). finalize() restores m_start afterwards.

Parameters

[in]	a_iv	Source cell (must have been counted in pass 1).
[in]	a_target	Destination (grid index, receiving rank).

◆ addTarget() [2/2]

void ParticleGhostMask::addTarget	(	const IntVect &	a_iv,
		const LevelTiles::BoxIDs &	a_target,
		const Box &	a_targetBox
	)

inlinenoexcept

Build pass 2 with an acceptance box: append one target and its acceptance box for cell a_iv.

Requires allocateTargetBoxes() to have been called. Writes the acceptance box at the same packed slot as the target, then delegates to addTarget() to store the target and advance the head.

Parameters

[in]	a_iv	Source cell (must have been counted in pass 1).
[in]	a_target	Destination (grid index, receiving rank).
[in]	a_targetBox	Acceptance box in destination cells (particle's dest cell must lie in it).

◆ allocateTargetBoxes()

void ParticleGhostMask::allocateTargetBoxes ( )

inlinenoexcept

Optional build step: size the per-target acceptance-box array to match the packed target array.

Call after allocate() and before any addTarget(...,box), only for masks that carry acceptance boxes (coarse-to-fine). Masks that skip it leave m_flatBox empty.

◆ box()

const Box & ParticleGhostMask::box ( ) const

inlinenoexcept

Get the box that the source cells live on.

Returns: m_box

◆ define()

void ParticleGhostMask::define ( const Box & a_box )

inlinenoexcept

Reset to an empty table over a box (every cell has zero targets).

Parameters

[in] a_box Box that the source cells live on.

◆ hasTargetBoxes()

bool ParticleGhostMask::hasTargetBoxes ( ) const

inlinenoexcept

Whether this mask carries per-target acceptance boxes.

Returns: True if allocateTargetBoxes() was used (coarse-to-fine masks), false otherwise.

◆ incrementCount()

void ParticleGhostMask::incrementCount ( const IntVect & a_iv )

inlinenoexcept

Build pass 1: register that cell a_iv gains one more target.

Parameters

[in] a_iv Source cell.

◆ numTargets()

int ParticleGhostMask::numTargets ( const IntVect & a_iv ) const

inlinenoexcept

Get the number of scatter targets for a cell.

Parameters

[in] a_iv Source cell (must lie in box()).

Returns: Number of targets (0 if the cell scatters nowhere in this direction).

◆ target()

const LevelTiles::BoxIDs & ParticleGhostMask::target	(	const IntVect &	a_iv,
		const int	a_i
	)		const

inlinenoexcept

Get the i-th scatter target for a cell.

Parameters

[in]	a_iv	Source cell (must lie in box()).
[in]	a_i	Target index in [0, numTargets(a_iv)).

Returns: (grid index on the destination level, receiving rank).

◆ targetBox()

const Box & ParticleGhostMask::targetBox	(	const IntVect &	a_iv,
		const int	a_i
	)		const

inlinenoexcept

Get the acceptance box of the i-th target for a cell.

Only valid when the mask was built with acceptance boxes (hasTargetBoxes()).

Parameters

[in]	a_iv	Source cell (must lie in box()).
[in]	a_i	Target index in [0, numTargets(a_iv)).

Returns: Acceptance box in destination cells.

◆ targetGridIndex()

unsigned int ParticleGhostMask::targetGridIndex	(	const IntVect &	a_iv,
		const int	a_i
	)		const

inlinenoexcept

Get the destination grid index of the i-th target for a cell.

Parameters

[in]	a_iv	Source cell (must lie in box()).
[in]	a_i	Target index in [0, numTargets(a_iv)).

Returns: Grid index on the destination level.

◆ targetRank()

unsigned int ParticleGhostMask::targetRank	(	const IntVect &	a_iv,
		const int	a_i
	)		const

inlinenoexcept

Get the receiving rank of the i-th target for a cell.

Parameters

[in]	a_iv	Source cell (must lie in box()).
[in]	a_i	Target index in [0, numTargets(a_iv)).

Returns: Rank that owns (and will receive) the destination box.

The documentation for this class was generated from the following files:

Source/AmrMesh/CD_ParticleGhostMask.H
Source/AmrMesh/CD_ParticleGhostMaskImplem.H

Public Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ addTarget() [1/2]

◆ addTarget() [2/2]

◆ allocateTargetBoxes()

◆ box()

◆ define()

◆ hasTargetBoxes()

◆ incrementCount()

◆ numTargets()

◆ target()

◆ targetBox()

◆ targetGridIndex()

◆ targetRank()