Synchronous double-buffered engine. More...

#include <tpl_ca_engine.H>

Collaboration diagram for Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >:

Public Types
using	lattice_type = Lattice
	Lattice type.

using	rule_type = Rule
	Rule type.

using	neighborhood_type = Neighborhood
	Neighborhood type.

using	order_type = Order
	Iteration order.

using	state_type = typename Lattice::state_type
	Cell state type.

using	coord_type = typename Lattice::coord_type
	Coordinate type.

using	extents_type = typename Lattice::extents_type
	Extents type.

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

Public Member Functions
	Synchronous_Engine (Lattice initial, Rule r, Neighborhood n)
	Build an engine on top of an existing initial lattice.

	Synchronous_Engine (Lattice initial, Rule r)
	Build an engine with a default-constructed neighbourhood.

const Lattice &	frame () const noexcept
	Return the current frame.

std::size_t	steps_run () const noexcept
	Return the number of completed steps.

const extents_type &	extents () const noexcept
	Return the frame extents.

const Rule &	rule () const noexcept
	Read-only access to the rule (used by checkpointing).

Rule &	rule () noexcept
	Mutable access to the rule (used by checkpointing to restore the master RNG seed of stochastic rules).

Lattice &	write_lattice () noexcept
	Mutable access to the current lattice buffer.

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

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 ()
	Apply the rule to every cell once and swap buffers.

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

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

static constexpr std::size_t	neighbour_count = Neighborhood::size_v
	Number of neighbours.

Private Attributes
Lattice	cur_buf_

Lattice	nxt_buf_

Rule	rule_

Neighborhood	nh_

hook_type	pre_hook_

hook_type	post_hook_

std::size_t	step_count_ = 0

Detailed Description

template<typename Lattice, typename Rule, typename Neighborhood, typename Order = RowMajor>
class Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >

Synchronous double-buffered engine.

Template Parameters

Lattice	lattice type (e.g. `Lattice<Dense_Cell_Storage<int,2>, ToroidalBoundary>`).
Rule	rule type satisfying `RuleLike<Rule, Lattice>`.
Neighborhood	neighbourhood type satisfying `NeighborhoodLike`.
Order	iteration order tag (`RowMajor` or `Tile<W, H>`).

Complexity: step() is O(N * S) where N is the cell count and S the neighbour count. Buffer swap is O(1).

Thread-safety: The engine itself is not thread-safe; engines are intended to be driven by a single thread. Phase 5 introduces a parallel variant.

Definition at line 183 of file tpl_ca_engine.H.

Member Typedef Documentation

◆ coord_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

using Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::coord_type = typename Lattice::coord_type

Coordinate type.

Definition at line 204 of file tpl_ca_engine.H.

◆ extents_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

using Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::extents_type = typename Lattice::extents_type

Extents type.

Definition at line 206 of file tpl_ca_engine.H.

◆ hook_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

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

Hook signature: (step_index_just_completed, frame).

Definition at line 214 of file tpl_ca_engine.H.

◆ lattice_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

using Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::lattice_type = Lattice

Lattice type.

Definition at line 193 of file tpl_ca_engine.H.

◆ neighborhood_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

using Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::neighborhood_type = Neighborhood

Neighborhood type.

Definition at line 197 of file tpl_ca_engine.H.

◆ order_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

using Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::order_type = Order

Iteration order.

Definition at line 199 of file tpl_ca_engine.H.

◆ rule_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

using Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::rule_type = Rule

Rule type.

Definition at line 195 of file tpl_ca_engine.H.

◆ state_type

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

using Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::state_type = typename Lattice::state_type

Cell state type.

Definition at line 202 of file tpl_ca_engine.H.

Constructor & Destructor Documentation

◆ Synchronous_Engine() [1/2]

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::Synchronous_Engine	(	Lattice	initial,
		Rule	r,
		Neighborhood	n
	)

inline

Build an engine on top of an existing initial lattice.

The next-step buffer is allocated with the same extents and a default-constructed cell value.

Parameters

[in]	initial	initial lattice (consumed by move).
[in]	r	rule instance.
[in]	n	neighbourhood instance.

Exceptions

std::bad_alloc if allocating the next buffer fails.

Complexity: O(N) for allocating the next buffer, where N is the cell count.

Definition at line 240 of file tpl_ca_engine.H.

◆ Synchronous_Engine() [2/2]

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::Synchronous_Engine	(	Lattice	initial,
		Rule	r
	)

inline

Build an engine with a default-constructed neighbourhood.

This overload is available only when Neighborhood is default constructible.

Parameters

[in]	initial	initial lattice (consumed by move).
[in]	r	rule instance.

Exceptions

std::bad_alloc if allocating the next buffer fails.

Complexity: O(N) for allocating the next buffer, where N is the cell count.

Definition at line 257 of file tpl_ca_engine.H.

Member Function Documentation

◆ extents()

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

const extents_type & Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::extents ( ) const

inlinenoexcept

Return the frame extents.

Returns: the lattice extents forwarded from the current buffer.

Definition at line 284 of file tpl_ca_engine.H.

References Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::cur_buf_, and Aleph::CA::Lattice< Storage, Boundary >::extents().

◆ frame()

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

const Lattice & Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::frame ( ) const

inlinenoexcept

Return the current frame.

Returns: read-only view of the current lattice buffer.

Definition at line 266 of file tpl_ca_engine.H.

References Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::cur_buf_.

Referenced by expect_engine_equivalence(), main(), TEST(), and TEST().

◆ on_post_step()

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

template<typename F >

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

inline

Register a hook fired after every step().

The hook receives the step index that just completed (steps_run() after the swap) and a const reference to the resulting frame.

Definition at line 347 of file tpl_ca_engine.H.

References Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::post_hook_.

◆ on_pre_step()

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

template<typename F >

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

inline

Register a hook fired before every step().

The hook receives the step index that is about to start (steps_run()) and a const reference to the current frame.

Definition at line 336 of file tpl_ca_engine.H.

References Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::pre_hook_.

◆ rule() [1/2]

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

const Rule & Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::rule ( ) const

inlinenoexcept

Read-only access to the rule (used by checkpointing).

Returns: const reference to the wrapped rule.

Definition at line 292 of file tpl_ca_engine.H.

References Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::rule_.

◆ rule() [2/2]

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

Rule & Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::rule ( )

inlinenoexcept

Mutable access to the rule (used by checkpointing to restore the master RNG seed of stochastic rules).

Returns: mutable reference to the wrapped rule.

Definition at line 301 of file tpl_ca_engine.H.

References Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::rule_.

◆ run()

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

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

inline

Run several synchronous steps.

Parameters

[in] steps number of consecutive step() calls to perform.

Exceptions

Any	exception propagated by `step()`.

Complexity: O(steps * N * K), where N is the cell count and K is the neighbourhood size.

Definition at line 432 of file tpl_ca_engine.H.

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

Referenced by expect_engine_equivalence(), main(), TEST(), TEST(), TEST(), TEST(), TEST(), TEST(), TEST(), and TEST().

◆ set_step_count()

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

void Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::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 326 of file tpl_ca_engine.H.

References Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::step_count_.

◆ step()

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

void Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::step ( )

inline

Apply the rule to every cell once and swap buffers.

step() gathers neighbours into a fixed-size stack buffer, writes the result into the next buffer, swaps the buffers in O(1), then fires the optional post-step hook.

Exceptions

Any	exception propagated by the rule, lattice or hooks.

Complexity: O(N * K), where N is the cell count and K is the neighbourhood size.

Definition at line 363 of file tpl_ca_engine.H.

Referenced by main(), Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::run(), run_engine_equivalence(), TEST(), and TEST().

◆ steps_run()

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

std::size_t Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::steps_run ( ) const

inlinenoexcept

Return the number of completed steps.

Returns: the number of step() invocations performed so far.

Definition at line 275 of file tpl_ca_engine.H.

References Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::step_count_.

Referenced by expect_engine_equivalence().

◆ write_lattice()

template<typename Lattice , typename Rule , typename Neighborhood , typename Order = RowMajor>

Lattice & Aleph::CA::Synchronous_Engine< Lattice, Rule, Neighborhood, Order >::write_lattice ( )

inlinenoexcept

Mutable access to the current lattice buffer.

Provided to support checkpoint restore (load_checkpoint_into): the loader rewrites every cell in place. Mutating the lattice outside of step() is otherwise discouraged.