Convenience bundle of a father, son, and attached ArrayTransformer. More...

#include <ArrayPair.hpp>

Inheritance diagram for DNDS::ArrayPair< TArray >:

Collaboration diagram for DNDS::ArrayPair< TArray >:

Public Types
using	t_self = ArrayPair< TArray >

using	t_arr = TArray

using	TTrans = typename ArrayTransformerType< TArray >::Type

template<DeviceBackend B>
using	t_deviceView = ArrayPairDeviceView< B, TArray >
	Device-view template alias: `t_deviceView<DeviceBackend::CUDA>` gives the mutable CUDA view type for this pair.

template<DeviceBackend B>
using	t_deviceViewConst = ArrayPairDeviceViewConst< B, TArray >
	Const-device-view template alias.

Public Member Functions
void	clone (const t_self &R)
	Deep-copy: allocate new father / son and copy their data; rebind trans.

decltype(father->operator[](index(0)))	operator[] (index i) const
	Read-only row-pointer access in the combined address space.

decltype(father->operator[](index(0)))	operator[] (index i)
	Mutable row-pointer access in the combined address space.

template<class... TOthers>
decltype(auto)	operator() (index i, TOthers... aOthers)
	N-ary element access in the combined space (mutable). Arguments after the row index are forwarded to the underlying `operator()`.

template<class... TOthers>
decltype(auto)	operator() (index i, TOthers... aOthers) const
	N-ary element access (const).

template<class TF >
auto	runFunctionAppendedIndex (index i, TF &&F)
	Invoke `F(array, localIndex)` on either father or son depending on which range `i` falls into.

auto	RowSize () const
	Uniform row width (delegates to father).

auto	RowSize (index i) const
	Per-row width in the combined address space.

void	ResizeRow (index i, rowsize rs)
	Resize a single row in the combined address space.

template<class... TOthers>
void	ResizeRow (index i, TOthers... aOthers)
	Variadic ResizeRow overload that forwards extra args.

index	Size () const
	Combined row count (`father->Size() + son->Size()`).

void	TransAttach ()
	Bind the transformer to the current father / son pointers.

template<typename... Args>
void	InitPair (const std::string &name, Args &&...args)
	Allocate both father and son arrays, forwarding all args to TArray constructor.

template<class TPrimaryPair >
void	BorrowAndPull (TPrimaryPair &primary)
	Attach, borrow ghost indexing from a primary pair, create MPI types, and pull once.

template<class TPrimaryPair >
void	BorrowSetup (TPrimaryPair &primary)
	Attach, borrow ghost indexing from a primary pair, and create MPI types (no pull).

void	CompressBoth ()
	Compress both father and son CSR arrays (no-op for non-CSR layouts).

void	CopyFather (t_self &R)
	Copy only the father's data from another pair (shallow).

void	SwapDataFatherSon (t_self &R)
	Swap both father and son data with another pair of the same type.

std::size_t	hash ()
	Combined hash across ranks. Used for determinism / equality checks in tests.

void	WriteSerialize (Serializer::SerializerBaseSSP serializerP, const std::string &name, bool includePIG=true, bool includeSon=true)
	Writes the ArrayPair (father, optional son, optional ghost mapping).

void	WriteSerialize (Serializer::SerializerBaseSSP serializerP, const std::string &name, const std::vector< index > &origIndex, bool includePIG=true, bool includeSon=true)
	Writes the ArrayPair with an origIndex companion dataset for redistribution support.

void	ReadSerialize (Serializer::SerializerBaseSSP serializerP, const std::string &name, bool includePIG=true, bool includeSon=true)
	Reads an ArrayPair written by WriteSerialize (same partition count).

void	ReadSerializeRedistributed (Serializer::SerializerBaseSSP serializerP, const std::string &name, const std::vector< index > &newOrigIndex)
	Reads ArrayPair data from HDF5 with redistribution support.

template<DeviceBackend B>
auto	deviceView ()
	Produce a mutable device view; both father and son must be allocated.

template<DeviceBackend B>
auto	deviceView () const
	Produce a const device view.

void	to_device (DeviceBackend backend)
	Mirror both father and son to the given device backend.

void	to_host ()
	Bring both father and son mirrors back to host memory.

Static Public Member Functions
static constexpr bool	IsCSR ()
	Whether the underlying array uses CSR storage.

Public Attributes
ssp< TArray >	father
	Owned-side array (must be resized before ghost setup).

ssp< TArray >	son
	Ghost-side array (sized automatically by createMPITypes / BorrowAndPull).

TTrans	trans
	Ghost-communication engine bound to father and son.

Detailed Description

template<class TArray = ParArray<real, 1>>
struct DNDS::ArrayPair< TArray >

Convenience bundle of a father, son, and attached ArrayTransformer.

ArrayPair is what most application code uses instead of manipulating a raw transformer. It wraps:

father (owned rows) and son (ghost rows) as shared_ptr<TArray>,
a trans transformer that binds the two together.

operator[] / operator() treat the pair as one contiguous array of size father->Size() + son->Size(). Typical construction pattern:

ArrayPair<ParArray<real, 5>> u;
u.InitPair("u", mpi);                  // allocates father and son
u.father->Resize(nLocal);              // fill father with local data
u.BorrowAndPull(primaryPair);          // ghost layout inherited; pull

See docs/guides/array_usage.md for the broader "primary pair" pattern: one pair (typically cell2cell) does the full four-step ghost setup; every other pair on the same partition borrows from it.

Template Parameters

TArray Underlying array type (e.g., ParArray<real, 5>, ArrayAdjacency, ArrayEigenVector).

Definition at line 162 of file ArrayPair.hpp.

Member Typedef Documentation

◆ t_arr

template<class TArray = ParArray<real, 1>>

using DNDS::ArrayPair< TArray >::t_arr = TArray

Definition at line 165 of file ArrayPair.hpp.

◆ t_deviceView

template<class TArray = ParArray<real, 1>>

template<DeviceBackend B>

using DNDS::ArrayPair< TArray >::t_deviceView = ArrayPairDeviceView<B, TArray>

Device-view template alias: t_deviceView<DeviceBackend::CUDA> gives the mutable CUDA view type for this pair.

Definition at line 653 of file ArrayPair.hpp.

◆ t_deviceViewConst

template<class TArray = ParArray<real, 1>>

template<DeviceBackend B>

using DNDS::ArrayPair< TArray >::t_deviceViewConst = ArrayPairDeviceViewConst<B, TArray>

Const-device-view template alias.

Definition at line 657 of file ArrayPair.hpp.

◆ t_self

template<class TArray = ParArray<real, 1>>

using DNDS::ArrayPair< TArray >::t_self = ArrayPair<TArray>

Definition at line 164 of file ArrayPair.hpp.

◆ TTrans

template<class TArray = ParArray<real, 1>>

using DNDS::ArrayPair< TArray >::TTrans = typename ArrayTransformerType<TArray>::Type

Definition at line 173 of file ArrayPair.hpp.

Member Function Documentation

◆ BorrowAndPull()

template<class TArray = ParArray<real, 1>>

template<class TPrimaryPair >

void DNDS::ArrayPair< TArray >::BorrowAndPull ( TPrimaryPair & primary )

inline

Attach, borrow ghost indexing from a primary pair, create MPI types, and pull once.

Replaces the 4-line sequence: this->TransAttach(); this->trans.BorrowGGIndexing(primary.trans); this->trans.createMPITypes(); this->trans.pullOnce();

Definition at line 336 of file ArrayPair.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ BorrowSetup()

template<class TArray = ParArray<real, 1>>

template<class TPrimaryPair >

void DNDS::ArrayPair< TArray >::BorrowSetup ( TPrimaryPair & primary )

inline

Attach, borrow ghost indexing from a primary pair, and create MPI types (no pull).

Useful when you need to set up communication but defer the pull (e.g., for persistent communication patterns).

Definition at line 349 of file ArrayPair.hpp.

Here is the call graph for this function:

◆ clone()

template<class TArray = ParArray<real, 1>>

void DNDS::ArrayPair< TArray >::clone ( const t_self & R )

inline

Deep-copy: allocate new father / son and copy their data; rebind trans.

Recreates the arrays through TArray's copy ctor, then assigns trans from R. If the source's transformer was already attached, re-attaches to the new local arrays.

rely on TArray's copy ctor!

rely on TTrans's copy assignment!

if R.trans already attached, then self trans attach self arrays

Definition at line 181 of file ArrayPair.hpp.

Here is the caller graph for this function:

◆ CompressBoth()

template<class TArray = ParArray<real, 1>>

void DNDS::ArrayPair< TArray >::CompressBoth ( )

inline

Compress both father and son CSR arrays (no-op for non-CSR layouts).

Definition at line 357 of file ArrayPair.hpp.

Here is the caller graph for this function:

◆ CopyFather()

template<class TArray = ParArray<real, 1>>

void DNDS::ArrayPair< TArray >::CopyFather ( t_self & R )

inline

Copy only the father's data from another pair (shallow).

Definition at line 364 of file ArrayPair.hpp.

◆ deviceView() [1/2]

template<class TArray = ParArray<real, 1>>

template<DeviceBackend B>

auto DNDS::ArrayPair< TArray >::deviceView ( )

inline

Produce a mutable device view; both father and son must be allocated.

Definition at line 661 of file ArrayPair.hpp.

◆ deviceView() [2/2]

template<class TArray = ParArray<real, 1>>

template<DeviceBackend B>

auto DNDS::ArrayPair< TArray >::deviceView ( ) const

inline

Produce a const device view.

Definition at line 673 of file ArrayPair.hpp.

◆ hash()

template<class TArray = ParArray<real, 1>>

std::size_t DNDS::ArrayPair< TArray >::hash ( )

inline

Combined hash across ranks. Used for determinism / equality checks in tests.

Definition at line 385 of file ArrayPair.hpp.

Here is the call graph for this function:

◆ InitPair()

template<class TArray = ParArray<real, 1>>

template<typename... Args>

void DNDS::ArrayPair< TArray >::InitPair	(	const std::string &	name,
		Args &&...	args
	)

inline

Allocate both father and son arrays, forwarding all args to TArray constructor.

Replaces the common two-line DNDS_MAKE_SSP(pair.father, ...) + DNDS_MAKE_SSP(pair.son, ...) pattern.

The name tag is set on both arrays as "name.father" / "name.son". Constructor args are forwarded as-is to TArray (same order as ParArray constructors, e.g., (mpi) or (dataType, commMult, mpi)).

Usage: pair.InitPair("cell2node", mpi); pair.InitPair("cellElemInfo", ElemInfo::CommType(), ElemInfo::CommMult(), mpi);

Definition at line 322 of file ArrayPair.hpp.

Here is the caller graph for this function:

◆ IsCSR()

template<class TArray = ParArray<real, 1>>

static constexpr bool DNDS::ArrayPair< TArray >::IsCSR ( )

inlinestaticconstexpr

Whether the underlying array uses CSR storage.

Definition at line 167 of file ArrayPair.hpp.

◆ operator()() [1/2]

template<class TArray = ParArray<real, 1>>

template<class... TOthers>

decltype(auto) DNDS::ArrayPair< TArray >::operator()	(	index	i,
		TOthers...	aOthers
	)

inline

N-ary element access in the combined space (mutable). Arguments after the row index are forwarded to the underlying operator().

Definition at line 226 of file ArrayPair.hpp.

Here is the call graph for this function:

◆ operator()() [2/2]

template<class TArray = ParArray<real, 1>>

template<class... TOthers>

decltype(auto) DNDS::ArrayPair< TArray >::operator()	(	index	i,
		TOthers...	aOthers
	)		const

inline

N-ary element access (const).

Definition at line 236 of file ArrayPair.hpp.

Here is the call graph for this function:

◆ operator[]() [1/2]

template<class TArray = ParArray<real, 1>>

decltype(father->operator[](index(0))) DNDS::ArrayPair< TArray >::operator[] ( index i )

inline

Mutable row-pointer access in the combined address space.

Definition at line 207 of file ArrayPair.hpp.

Here is the call graph for this function:

◆ operator[]() [2/2]

template<class TArray = ParArray<real, 1>>

decltype(father->operator[](index(0))) DNDS::ArrayPair< TArray >::operator[] ( index i ) const

inline

Read-only row-pointer access in the combined address space.

Definition at line 198 of file ArrayPair.hpp.

Here is the caller graph for this function:

◆ ReadSerialize()

template<class TArray = ParArray<real, 1>>

void DNDS::ArrayPair< TArray >::ReadSerialize	(	Serializer::SerializerBaseSSP	serializerP,
		const std::string &	name,
		bool	includePIG = `true`,
		bool	includeSon = `true`
	)

inline

Reads an ArrayPair written by WriteSerialize (same partition count).

Reads father (and optionally son and ghost mapping) from sub-path name. Requires the file to have been written with the same MPI size. The father and son arrays are resized internally by Array::ReadSerializer.

All reads are collective for H5 serializers. Every rank must call this, including ranks whose local size is 0.

Warning: If includePIG is true, the caller must call trans.createMPITypes() after this method returns.

Definition at line 486 of file ArrayPair.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ReadSerializeRedistributed()

template<class TArray = ParArray<real, 1>>

void DNDS::ArrayPair< TArray >::ReadSerializeRedistributed	(	Serializer::SerializerBaseSSP	serializerP,
		const std::string &	name,
		const std::vector< index > &	newOrigIndex
	)

inline

Reads ArrayPair data from HDF5 with redistribution support.

Handles three cases depending on the file contents and partition count:

No origIndex in file, same np: falls back to ReadSerialize (same-partition read, no redistribution).
Has origIndex, same np: reads father via ReadSerialize, reads origIndex, then uses RedistributeArrayWithTransformer to move data from the file's partition layout to the caller's partition layout.
Has origIndex, different np: reads father via EvenSplit (each rank reads ~nGlobal/nRanks rows regardless of the original partition), reads origIndex the same way, then uses RedistributeArrayWithTransformer to pull each rank's needed cells.

In case 3, some ranks may get 0 rows from EvenSplit when nGlobal < nRanks. This is handled correctly: the H5 collective reads proceed with 0-count hyperslab selections, and the redistribution operates on empty arrays.

All operations are collective. Every rank must call this method.

Parameters

serializerP	The serializer (must be H5 / collective)
name	Path name in the serializer hierarchy
newOrigIndex	Partition-independent keys for this rank's cells (e.g., from cell2cellOrig). Size must equal father->Size(). May be empty for ranks with 0 cells.

Definition at line 550 of file ArrayPair.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ResizeRow() [1/2]

template<class TArray = ParArray<real, 1>>

void DNDS::ArrayPair< TArray >::ResizeRow	(	index	i,
		rowsize	rs
	)

inline

Resize a single row in the combined address space.

Definition at line 273 of file ArrayPair.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ ResizeRow() [2/2]

template<class TArray = ParArray<real, 1>>

template<class... TOthers>

void DNDS::ArrayPair< TArray >::ResizeRow	(	index	i,
		TOthers...	aOthers
	)

inline

Variadic ResizeRow overload that forwards extra args.

Definition at line 283 of file ArrayPair.hpp.

Here is the call graph for this function:

◆ RowSize() [1/2]

template<class TArray = ParArray<real, 1>>

auto DNDS::ArrayPair< TArray >::RowSize ( ) const

inline

Uniform row width (delegates to father).

Definition at line 258 of file ArrayPair.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ RowSize() [2/2]

template<class TArray = ParArray<real, 1>>

auto DNDS::ArrayPair< TArray >::RowSize ( index i ) const

inline

Per-row width in the combined address space.

Definition at line 264 of file ArrayPair.hpp.

Here is the call graph for this function:

◆ runFunctionAppendedIndex()

template<class TArray = ParArray<real, 1>>

template<class TF >

auto DNDS::ArrayPair< TArray >::runFunctionAppendedIndex	(	index	i,
		TF &&	F
	)

inline

Invoke F(array, localIndex) on either father or son depending on which range i falls into.

Useful when per-side state must be updated alongside the indexed row (e.g., logging father vs son modifications).

Definition at line 249 of file ArrayPair.hpp.

Here is the call graph for this function:

◆ Size()

template<class TArray = ParArray<real, 1>>

index DNDS::ArrayPair< TArray >::Size ( ) const

inline

Combined row count (father->Size() + son->Size()).

Definition at line 292 of file ArrayPair.hpp.

Here is the call graph for this function:

Here is the caller graph for this function:

◆ SwapDataFatherSon()

template<class TArray = ParArray<real, 1>>

void DNDS::ArrayPair< TArray >::SwapDataFatherSon ( t_self & R )

inline

Swap both father and son data with another pair of the same type.

Warning: Because the data pointers change, persistent MPI requests (if any) are rebuilt on both sides via #reInitPersistentPullPush. a situation: the data pointer should remain static as long as initPersistentPuxx is done

Definition at line 376 of file ArrayPair.hpp.

◆ to_device()

template<class TArray = ParArray<real, 1>>

void DNDS::ArrayPair< TArray >::to_device ( DeviceBackend backend )

inline

Mirror both father and son to the given device backend.

Definition at line 684 of file ArrayPair.hpp.

◆ to_host()

template<class TArray = ParArray<real, 1>>

void DNDS::ArrayPair< TArray >::to_host ( )

inline

Bring both father and son mirrors back to host memory.

Definition at line 693 of file ArrayPair.hpp.

◆ TransAttach()

template<class TArray = ParArray<real, 1>>

void DNDS::ArrayPair< TArray >::TransAttach ( )

inline

Bind the transformer to the current father / son pointers.

First step of the four-step ghost setup when not using BorrowAndPull. Both arrays must already be allocated.

Definition at line 301 of file ArrayPair.hpp.

Here is the caller graph for this function:

◆ WriteSerialize() [1/2]

template<class TArray = ParArray<real, 1>>

void DNDS::ArrayPair< TArray >::WriteSerialize	(	Serializer::SerializerBaseSSP	serializerP,
		const std::string &	name,
		bool	includePIG = `true`,
		bool	includeSon = `true`
	)

inline

Writes the ArrayPair (father, optional son, optional ghost mapping).

Creates a sub-path name containing:

MPIRank (per-rank only), MPISize — partition metadata.
father — the father array via ParArray::WriteSerializer (Parts offset).
son — the son (ghost) array, if includeSon is true.
pullingIndexGlobal — ghost pull indices, if includePIG is true.

All writes are collective for H5 serializers. Every rank must call this.

Definition at line 406 of file ArrayPair.hpp.

Here is the caller graph for this function:

◆ WriteSerialize() [2/2]

template<class TArray = ParArray<real, 1>>

void DNDS::ArrayPair< TArray >::WriteSerialize	(	Serializer::SerializerBaseSSP	serializerP,
		const std::string &	name,
		const std::vector< index > &	origIndex,
		bool	includePIG = `true`,
		bool	includeSon = `true`
	)

inline

Writes the ArrayPair with an origIndex companion dataset for redistribution support.

When origIndex is provided and the serializer is H5 (collective), an additional dataset "origIndex" is written alongside the father data. This enables reading the data back with a different MPI partition.

Parameters

serializerP	The serializer (H5 for redistribution support, JSON ignores origIndex)
name	Path name for this array in the serializer hierarchy
origIndex	Partition-independent key for each row (e.g., from cell2cellOrig). Must have size == father->Size().
includePIG	Whether to include ghost pull-index-global data
includeSon	Whether to include the son (ghost) array

Definition at line 454 of file ArrayPair.hpp.

Here is the call graph for this function:

Member Data Documentation

◆ father

template<class TArray = ParArray<real, 1>>

ssp<TArray> DNDS::ArrayPair< TArray >::father

Owned-side array (must be resized before ghost setup).

Definition at line 170 of file ArrayPair.hpp.

◆ son

template<class TArray = ParArray<real, 1>>

ssp<TArray> DNDS::ArrayPair< TArray >::son

Ghost-side array (sized automatically by createMPITypes / BorrowAndPull).

Definition at line 172 of file ArrayPair.hpp.

◆ trans

template<class TArray = ParArray<real, 1>>

TTrans DNDS::ArrayPair< TArray >::trans

Ghost-communication engine bound to father and son.

Definition at line 175 of file ArrayPair.hpp.

The documentation for this struct was generated from the following file:

/home/runner/work/DNDSR/DNDSR/src/DNDS/ArrayPair.hpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Detailed Description

Member Typedef Documentation

◆ t_arr

◆ t_deviceView

◆ t_deviceViewConst

◆ t_self

◆ TTrans

Member Function Documentation

◆ BorrowAndPull()

◆ BorrowSetup()

◆ clone()

◆ CompressBoth()

◆ CopyFather()

◆ deviceView() [1/2]

◆ deviceView() [2/2]

◆ hash()

◆ InitPair()

◆ IsCSR()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ operator[]() [1/2]

◆ operator[]() [2/2]

◆ ReadSerialize()

◆ ReadSerializeRedistributed()

◆ ResizeRow() [1/2]

◆ ResizeRow() [2/2]

◆ RowSize() [1/2]

◆ RowSize() [2/2]

◆ runFunctionAppendedIndex()

◆ Size()

◆ SwapDataFatherSon()

◆ to_device()

◆ to_host()

◆ TransAttach()

◆ WriteSerialize() [1/2]

◆ WriteSerialize() [2/2]

Member Data Documentation

◆ father

◆ son

◆ trans