Update-scheme aware engine. More...

#include <tpl_ca_async_engine.H>

Collaboration diagram for Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >:

Public Types
using	lattice_type = Lattice

using	rule_type = Rule

using	neighborhood_type = Neighborhood

using	scheme_type = Update_Scheme

using	state_type = typename Lattice::state_type

using	coord_type = typename Lattice::coord_type

using	extents_type = typename Lattice::extents_type

using	hook_type = std::function< void(std::size_t, const Lattice &)>
	Hook signature: `(step_index, frame)`.

Public Member Functions
	Async_Engine (Lattice initial, Rule r, Neighborhood n, Update_Scheme s={})
	Build an engine.

	Async_Engine (Lattice initial, Rule r, Update_Scheme s={})
	Build an engine with a default-constructed neighborhood.

const Lattice &	frame () const noexcept

std::size_t	steps_run () const noexcept

const extents_type &	extents () const noexcept

const Neighborhood &	neighborhood () const noexcept

Lattice &	current_buffer () noexcept

const Lattice &	current_buffer () const noexcept

Lattice &	write_lattice () noexcept
	Alias for `current_buffer()`. Used by checkpoint restore.

void	set_step_count (const std::size_t s) noexcept
	Override the completed-step counter.

Lattice &	next_buffer () noexcept

Rule &	rule () noexcept

const Rule &	rule () const noexcept

const Update_Scheme &	scheme () const noexcept

std::size_t	step_count () const noexcept

void	swap_buffers () noexcept(noexcept(cur_.swap(nxt_)))
	O(1) swap of the two buffers (called by double-buffer schemes).

template<typename F >
void	on_pre_step (F &&f)
	Register a hook fired before every `step()`.

template<typename F >
void	on_post_step (F &&f)
	Register a hook fired after every `step()`.

void	step ()
	Run one engine step using the configured update scheme.

void	step_back ()
	Reverse the most recent step (Margolus only).

void	run (const std::size_t steps)
	Run several steps.

void	run_back (const std::size_t steps)
	Reverse several steps (Margolus only).

Static Public Attributes
static constexpr std::size_t	rank = Lattice::rank
	Lattice dimension.

Private Attributes
Lattice	cur_

Lattice	nxt_

Rule	rule_

Neighborhood	nh_

Update_Scheme	scheme_

hook_type	pre_hook_

hook_type	post_hook_

std::size_t	step_count_ = 0

Detailed Description

template<typename Lattice, typename Rule, typename Neighborhood, typename Update_Scheme = Synchronous_Update<RowMajor>>
class Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >

Update-scheme aware engine.

Owns a current lattice buffer (and, when Update_Scheme::requires_double_buffer is true, a next buffer of identical extents). Each step() dispatches to the scheme's apply() method, which is responsible for visiting the cells in the desired order and updating the lattice in place or by double buffering.

Template Parameters

Lattice	lattice type.
Rule	rule (cell rule or block rule depending on the scheme).
Neighborhood	neighbourhood (`Null_Neighborhood<Rank>` for block-rule schemes).
Update_Scheme	update strategy (default `Synchronous_Update<RowMajor>`).

Definition at line 162 of file tpl_ca_async_engine.H.

Member Typedef Documentation

◆ coord_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

using Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::coord_type = typename Lattice::coord_type

Definition at line 177 of file tpl_ca_async_engine.H.

◆ extents_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

using Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::extents_type = typename Lattice::extents_type

Definition at line 178 of file tpl_ca_async_engine.H.

◆ hook_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

using Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::hook_type = std::function<void(std::size_t, const Lattice &)>

Hook signature: (step_index, frame).

Definition at line 184 of file tpl_ca_async_engine.H.

◆ lattice_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

using Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::lattice_type = Lattice

Definition at line 171 of file tpl_ca_async_engine.H.

◆ neighborhood_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

using Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::neighborhood_type = Neighborhood

Definition at line 173 of file tpl_ca_async_engine.H.

◆ rule_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

using Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::rule_type = Rule

Definition at line 172 of file tpl_ca_async_engine.H.

◆ scheme_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

using Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::scheme_type = Update_Scheme

Definition at line 174 of file tpl_ca_async_engine.H.

◆ state_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

using Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::state_type = typename Lattice::state_type

Definition at line 176 of file tpl_ca_async_engine.H.

Constructor & Destructor Documentation

◆ Async_Engine() [1/2]

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::Async_Engine	(	Lattice	initial,
		Rule	r,
		Neighborhood	n,
		Update_Scheme	s = `{}`
	)

inline

Build an engine.

Allocates the next-buffer only when Update_Scheme::requires_double_buffer is true. For in-place schemes (Sequential, Random_Asynchronous, Margolus) the next-buffer member stays empty.

Parameters

[in]	initial	initial lattice (consumed by move).
[in]	r	rule instance (consumed by move).
[in]	n	neighborhood instance (consumed by move).
[in]	s	update-scheme instance (consumed by move).

Exceptions

std::bad_alloc on allocation failure.

Definition at line 209 of file tpl_ca_async_engine.H.

◆ Async_Engine() [2/2]

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::Async_Engine	(	Lattice	initial,
		Rule	r,
		Update_Scheme	s = `{}`
	)

inline

Build an engine with a default-constructed neighborhood.

Parameters

[in]	initial	initial lattice (consumed by move).
[in]	r	rule instance.
[in]	s	update-scheme instance.

Exceptions

std::bad_alloc on allocation failure.

Definition at line 222 of file tpl_ca_async_engine.H.

Member Function Documentation

◆ current_buffer() [1/2]

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

const Lattice & Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::current_buffer ( ) const

inlinenoexcept

Returns: read-only access to the current lattice (used by schemes).

Definition at line 258 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::cur_.

◆ current_buffer() [2/2]

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

Lattice & Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::current_buffer ( )

inlinenoexcept

Returns: read-write access to the current lattice (used by schemes).

Definition at line 252 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::cur_.

◆ extents()

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

const extents_type & Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::extents ( ) const

inlinenoexcept

Returns: the lattice extents.

Definition at line 240 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::cur_, and Aleph::CA::Lattice< Storage, Boundary >::extents().

◆ frame()

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

const Lattice & Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::frame ( ) const

inlinenoexcept

Returns: read-only view of the current frame.

Definition at line 228 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::cur_.

◆ neighborhood()

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

const Neighborhood & Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::neighborhood ( ) const

inlinenoexcept

Returns: read-only access to the underlying neighborhood.

Definition at line 246 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::nh_.

◆ next_buffer()

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

Lattice & Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::next_buffer ( )

inlinenoexcept

Returns: read-write access to the next lattice (only valid for schemes that require double buffering).

Definition at line 282 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::nxt_.

◆ on_post_step()

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

template<typename F >

void Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::on_post_step ( F && f )

inline

Register a hook fired after every step().

Template Parameters

F	callable accepting `(std::size_t, const Lattice &)`.

Parameters

[in] f hook to install.

Definition at line 332 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::post_hook_.

◆ on_pre_step()

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

template<typename F >

void Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::on_pre_step ( F && f )

inline

Register a hook fired before every step().

Template Parameters

F	callable accepting `(std::size_t, const Lattice &)`.

Parameters

[in] f hook to install.

Definition at line 322 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::pre_hook_.

◆ rule() [1/2]

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

const Rule & Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::rule ( ) const

inlinenoexcept

Returns: read-only access to the rule.

Definition at line 294 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::rule_.

◆ rule() [2/2]

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

Rule & Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::rule ( )

inlinenoexcept

Returns: read-write access to the rule.

Definition at line 288 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::rule_.

◆ run()

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

void Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::run ( const std::size_t steps )

inline

Run several steps.

Parameters

[in] steps number of step() invocations.

Exceptions

Any	exception propagated by `step()`.

Definition at line 396 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::step(), and steps.

◆ run_back()

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

void Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::run_back ( const std::size_t steps )

inline

Reverse several steps (Margolus only).

Parameters

[in] steps number of step_back() invocations.

Exceptions

Any	exception propagated by `step_back()`.

Definition at line 406 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::step_back(), and steps.

◆ scheme()

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

const Update_Scheme & Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::scheme ( ) const

inlinenoexcept

Returns: read-only access to the update scheme.

Definition at line 300 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::scheme_.

◆ set_step_count()

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

void Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::set_step_count ( const std::size_t s )

inlinenoexcept

Override the completed-step counter.

Used by load_checkpoint_into to resume a simulation from the exact step recorded in the snapshot.

Parameters

[in] s new step counter value.

Definition at line 275 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::step_count_.

◆ step()

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

void Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::step ( )

inline

Run one engine step using the configured update scheme.

Calls refresh_halo() on lattices that have a halo, fires the pre-step hook, dispatches to scheme_.apply(*this, rule_), then fires the post-step hook.

Exceptions

Any	exception propagated by the rule, the scheme or the hooks.

Definition at line 346 of file tpl_ca_async_engine.H.

References Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::cur_, Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::post_hook_, Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::pre_hook_, Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::rule_, Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::scheme_, and Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::step_count_.

Referenced by Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::run(), and TEST().

◆ step_back()

template<typename Lattice , typename Rule , typename Neighborhood , typename Update_Scheme = Synchronous_Update<RowMajor>>

void Aleph::CA::Async_Engine< Lattice, Rule, Neighborhood, Update_Scheme >::step_back ( )

inline

Reverse the most recent step (Margolus only).

When the scheme exposes apply_with_origin(engine, rule, origin) (the Margolus contract) and the rule is an involution, applying the rule with the same partition origin that produced the forward step undoes the step bit-by-bit. This method decrements the step counter and re-applies the scheme with the parity that generated the now-discarded forward step.