Aleph-w 3.0
A C++ Library for Data Structures and Algorithms
Loading...
Searching...
No Matches
Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo > Class Template Reference

Lattice with Halo ghost layers around the user-visible cells. More...

#include <tpl_ca_ghost_lattice.H>

Public Types

using storage_type = Storage
 
using boundary_type = Boundary
 
using state_type = typename Storage::state_type
 
using coord_type = typename Storage::coord_type
 
using extents_type = typename Storage::extents_type
 

Public Member Functions

 Ghost_Lattice ()=default
 Construct an empty ghost lattice (no cells allocated).
 
 Ghost_Lattice (const extents_type &user_extents, const state_type &init=state_type{})
 Construct a ghost lattice with given user extents and init value.
 
ca_size_t size () const noexcept
 
ca_size_t size (std::size_t d) const
 User-visible extent along axis d.
 
const extents_type & extents () const noexcept
 
const extents_type & store_extents () const noexcept
 
state_type at (const coord_type &c) const
 Strict read through a user coordinate.
 
void set (const coord_type &c, const state_type &v)
 Strict write through a user coordinate.
 
state_type at_safe (const coord_type &c) const
 Boundary-aware read exploiting the halo as a fast path.
 
void refresh_halo ()
 Populate every ghost cell according to the boundary policy.
 
const Storage & storage () const noexcept
 Direct access to the underlying storage (read-only).
 
Storage & storage () noexcept
 Direct access to the underlying storage.
 
void fill (const state_type &value)
 Set every user-visible cell to value.
 
void swap (Ghost_Lattice &other) noexcept(noexcept(store_.swap(other.store_)))
 O(1) swap with another ghost lattice of the same type.
 

Static Public Member Functions

static constexpr std::size_t dimension () noexcept
 
static constexpr std::size_t halo_radius () noexcept
 

Static Public Attributes

static constexpr std::size_t rank = Storage::rank
 Number of axes (same as the underlying storage).
 
static constexpr std::size_t halo_v = Halo
 Halo thickness (ghost cells per side per axis).
 

Private Member Functions

coord_type to_store (const coord_type &c) const noexcept
 Convert a user coordinate into a store coordinate.
 
state_type out_of_range_value () const
 Value returned when at_safe sees a coordinate outside the halo.
 
state_type resolve_via_policy (coord_type c) const
 Resolve a user coordinate through the boundary policy (slow path).
 
template<typename F >
void for_each_halo_cell (F &&f) const
 Invoke f(user_coord) on every halo cell of the storage.
 
void store_set (const coord_type &user_c, const state_type &value)
 Write value directly into the store at the given user coord.
 
state_type store_get (const coord_type &user_c) const
 Read directly from the store at the given user coord.
 

Private Attributes

extents_type user_ext_ {}
 extents seen from the outside
 
extents_type store_ext_ {}
 extents of the backing storage (user + 2H)
 
Storage store_ {}
 underlying storage (allocated once)
 

Detailed Description

template<typename Storage, typename Boundary = OpenBoundary, std::size_t Halo = 1>
class Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >

Lattice with Halo ghost layers around the user-visible cells.

Template Parameters
Storagestorage type satisfying CA::LatticeLike. The storage is constructed with extents user + 2*Halo so that the halo is plain backing memory.
Boundaryboundary tag (default OpenBoundary). See the file-level documentation for the accepted tags.
Halohalo thickness in cells (default 1). The neighbourhood radius consumed by the engine must be <= Halo for the fast path to kick in.
Complexity
  • at, set, at_safe: O(rank) (a few additions per call).
  • refresh_halo: O(boundary-surface cells), i.e. linear in the halo volume (which for 2D/3D is O(n^{rank-1})).
Thread-safety
Same guarantees as the underlying Storage.

Definition at line 152 of file tpl_ca_ghost_lattice.H.

Member Typedef Documentation

◆ boundary_type

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
using Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::boundary_type = Boundary

Definition at line 158 of file tpl_ca_ghost_lattice.H.

◆ coord_type

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
using Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::coord_type = typename Storage::coord_type

Definition at line 160 of file tpl_ca_ghost_lattice.H.

◆ extents_type

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
using Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::extents_type = typename Storage::extents_type

Definition at line 161 of file tpl_ca_ghost_lattice.H.

◆ state_type

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
using Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::state_type = typename Storage::state_type

Definition at line 159 of file tpl_ca_ghost_lattice.H.

◆ storage_type

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
using Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::storage_type = Storage

Definition at line 157 of file tpl_ca_ghost_lattice.H.

Constructor & Destructor Documentation

◆ Ghost_Lattice() [1/2]

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::Ghost_Lattice ( )
default

Construct an empty ghost lattice (no cells allocated).

◆ Ghost_Lattice() [2/2]

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::Ghost_Lattice ( const extents_type &  user_extents,
const state_type &  init = state_type{} 
)
inlineexplicit

Construct a ghost lattice with given user extents and init value.

Allocates prod(user_ext + 2*Halo) cells and initialises every interior and halo cell with init. refresh_halo() is not called automatically, since the initial state of a CA is a pure user responsibility.

Parameters
[in]user_extentsper-axis user-visible sizes.
[in]initinitial value for every cell (default state_type{}).
Exceptions
std::bad_allocon allocation failure.

Definition at line 325 of file tpl_ca_ghost_lattice.H.

Member Function Documentation

◆ at()

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
state_type Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::at ( const coord_type &  c) const
inline

Strict read through a user coordinate.

Parameters
[in]cuser coordinate in [0, size(d)).
Exceptions
std::out_of_rangeif any component of c is out of range.

Definition at line 372 of file tpl_ca_ghost_lattice.H.

References ah_out_of_range_error_if, Aleph::blossom_maximum_cardinality_matching(), Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::rank, Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::store_get(), and Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::user_ext_.

◆ at_safe()

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
state_type Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::at_safe ( const coord_type &  c) const
inline

Boundary-aware read exploiting the halo as a fast path.

For a coordinate inside [-Halo, size(d) + Halo) on every axis this method performs a single direct read from the backing storage — no branch on the boundary policy, so interior steps are branch-free as long as the neighbourhood radius is <= Halo. For coordinates further out the slow path applies the policy on the fly so the function still honours the declared semantics.

Parameters
[in]cpossibly out-of-range user coordinate.
Returns
the cell value resolved through the halo/policy pipeline.
Precondition
The halo is clean (i.e., refresh_halo() has been called after the last set() that modified an interior cell whose boundary reflection falls into the halo). If the halo is stale, reads of halo coordinates return the previously cached (potentially out-of-date) value.

Definition at line 418 of file tpl_ca_ghost_lattice.H.

References Aleph::blossom_maximum_cardinality_matching(), h, Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::out_of_range_value(), Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::rank, Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::resolve_via_policy(), Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::store_get(), and Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::user_ext_.

◆ dimension()

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
static constexpr std::size_t Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::dimension ( )
inlinestaticconstexprnoexcept
Returns
the compile-time lattice dimension.

Definition at line 337 of file tpl_ca_ghost_lattice.H.

References Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::rank.

◆ extents()

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
const extents_type & Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::extents ( ) const
inlinenoexcept
Returns
the per-axis user extents.

Definition at line 360 of file tpl_ca_ghost_lattice.H.

References Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::user_ext_.

◆ fill()

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
void Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::fill ( const state_type &  value)
inline

Set every user-visible cell to value.

The halo is left untouched; call refresh_halo() afterwards if you need it synchronised with the new interior.

Definition at line 524 of file tpl_ca_ghost_lattice.H.

References Aleph::blossom_maximum_cardinality_matching(), Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::rank, Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::store_set(), Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::user_ext_, and value.

◆ for_each_halo_cell()

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
template<typename F >
void Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::for_each_halo_cell ( F &&  f) const
inlineprivate

Invoke f(user_coord) on every halo cell of the storage.

user_coord uses the same convention as at(c): axes are in the user frame, so values in [-Halo, 0) or [user_ext[d], user_ext[d] + Halo) mean "halo cell on that side".

Definition at line 237 of file tpl_ca_ghost_lattice.H.

References Aleph::blossom_maximum_cardinality_matching(), Aleph::enumerate(), h, Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::rank, and Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::user_ext_.

Referenced by Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::refresh_halo().

◆ halo_radius()

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
static constexpr std::size_t Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::halo_radius ( )
inlinestaticconstexprnoexcept
Returns
the halo thickness.

Definition at line 366 of file tpl_ca_ghost_lattice.H.

References Aleph::blossom_maximum_cardinality_matching().

◆ out_of_range_value()

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
state_type Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::out_of_range_value ( ) const
inlineprivate

Value returned when at_safe sees a coordinate outside the halo.

Definition at line 183 of file tpl_ca_ghost_lattice.H.

Referenced by Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::at_safe(), and Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::resolve_via_policy().

◆ refresh_halo()

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
void Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::refresh_halo ( )
inline

Populate every ghost cell according to the boundary policy.

The engine calls this automatically before each step() so the rule loop can read neighbour values without any boundary branch. Calling it manually is harmless (idempotent under every policy implemented here).

Postcondition
All halo cells reflect the current interior state under the active boundary policy; at_safe() is now safe to call for any coordinate in [-Halo, size(d) + Halo).
Complexity
Linear in the number of halo cells (O(surface_area * Halo)).

Definition at line 456 of file tpl_ca_ghost_lattice.H.

References Aleph::blossom_maximum_cardinality_matching(), Aleph::CA::ca_ghost_detail::clamp_index(), Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::for_each_halo_cell(), Aleph::CA::ca_ghost_detail::positive_mod(), Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::rank, Aleph::CA::ca_ghost_detail::reflect_index(), Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::store_get(), Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::store_set(), and Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::user_ext_.

◆ resolve_via_policy()

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
state_type Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::resolve_via_policy ( coord_type  c) const
inlineprivate

◆ set()

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
void Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::set ( const coord_type &  c,
const state_type &  v 
)
inline

Strict write through a user coordinate.

Parameters
[in]cuser coordinate in [0, size(d)).
[in]vvalue to write.
Exceptions
std::out_of_rangeif any component of c is out of range.
Precondition
c must be a valid user coordinate (each component in [0, size(d))).
Postcondition
The interior cell at c holds v. Halo cells that mirror interior cells (e.g. under ToroidalBoundary) are not updated automatically; call refresh_halo() before the next at_safe() call that may read the halo region.

Definition at line 391 of file tpl_ca_ghost_lattice.H.

References ah_out_of_range_error_if, Aleph::blossom_maximum_cardinality_matching(), Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::rank, Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::store_set(), and Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::user_ext_.

Referenced by TEST(), and TEST().

◆ size() [1/2]

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
ca_size_t Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::size ( ) const
inlinenoexcept
Returns
total user-visible cell count (excludes the halo).

Definition at line 340 of file tpl_ca_ghost_lattice.H.

References Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::rank, and Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::user_ext_.

◆ size() [2/2]

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
ca_size_t Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::size ( std::size_t  d) const
inline

User-visible extent along axis d.

Parameters
[in]daxis index.
Exceptions
std::out_of_rangeif d >= rank.

Definition at line 352 of file tpl_ca_ghost_lattice.H.

References ah_out_of_range_error_if, Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::rank, and Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::user_ext_.

◆ storage() [1/2]

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
const Storage & Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::storage ( ) const
inlinenoexcept

Direct access to the underlying storage (read-only).

Definition at line 516 of file tpl_ca_ghost_lattice.H.

References Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::store_.

◆ storage() [2/2]

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
Storage & Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::storage ( )
inlinenoexcept

Direct access to the underlying storage.

Definition at line 519 of file tpl_ca_ghost_lattice.H.

References Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::store_.

◆ store_extents()

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
const extents_type & Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::store_extents ( ) const
inlinenoexcept
Returns
the per-axis storage extents (user + 2*Halo on every axis).

Definition at line 363 of file tpl_ca_ghost_lattice.H.

References Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::store_ext_.

◆ store_get()

◆ store_set()

◆ swap()

◆ to_store()

Member Data Documentation

◆ halo_v

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
constexpr std::size_t Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::halo_v = Halo
staticconstexpr

Halo thickness (ghost cells per side per axis).

Definition at line 166 of file tpl_ca_ghost_lattice.H.

◆ rank

◆ store_

◆ store_ext_

template<typename Storage , typename Boundary = OpenBoundary, std::size_t Halo = 1>
extents_type Aleph::CA::Ghost_Lattice< Storage, Boundary, Halo >::store_ext_ {}
private

◆ user_ext_


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