Rules on Entities

Algorithms for conveniently applying function objects on entities. More...

Collaboration diagram for Rules on Entities:

Namespaces
namespace	Utopia::GraphUtils

Classes
class	Utopia::rule_invoke_result< State, Rule, Args >
	Helper class for checking rule signatures and return types. More...
class	Utopia::StateContainer< StateType, mode >
	Container for states. More...
class	Utopia::StateContainer< StateType, Update::manual >
	A very simple, default constructible container with public members. More...
class	Utopia::StateContainer< StateType, Update::async >
	State Container specialization for async states. More...
class	Utopia::StateContainer< StateType, Update::sync >
	State Container specialization for sync states. More...

Typedefs
template<typename State , typename Rule , typename... Args>
using	Utopia::rule_invoke_result_t = typename rule_invoke_result< State, Rule, Args... >::type
	Helper definition to query the rule result type.

Enumerations
enum class	Utopia::Shuffle { Utopia::Shuffle::on , Utopia::Shuffle::off }
	Switch for enabling/disabling shuffling the cells for asynchronous updates. More...
enum class	Utopia::Update { Utopia::Update::manual , Utopia::Update::sync , Utopia::Update::async }
	Update modes when applying rules. More...

Functions
template<typename State , typename Rule , typename... Args>
constexpr bool	Utopia::is_void_rule ()
	Helper function to check if the rule returns void
template<class Tuple , std::size_t... I>
constexpr decltype(auto)	Utopia::make_tuple_from_tuple_impl (Tuple &&t, std::index_sequence< I... >)
	Helper function to create a tuple from a tuple using an index sequence.
template<class Tuple >
constexpr decltype(auto)	Utopia::make_tuple_from_tuple (Tuple &&t)
	Helper function to create a tuple from a tuple.
template<Update mode, class Rule , class ContTarget , class... ContArgs, typename std::enable_if_t< mode==Update::sync, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0>
void	Utopia::apply_rule (Rule &&rule, const ContTarget &cont_target, ContArgs &&... cont_args)
	Sequential overload.
template<Update mode, class Rule , class ContTarget , class... ContArgs, typename std::enable_if_t< mode==Update::sync, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0>
void	Utopia::apply_rule (const Utopia::ExecPolicy policy, Rule &&rule, const ContTarget &cont_target, ContArgs &&... cont_args)
	Apply a rule synchronously to manually updated states.
template<Update mode, Shuffle shuffle = Shuffle::on, class Rule , class ContTarget , class... ContArgs, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0, typename std::enable_if_t< shuffle==Shuffle::off, int > = 0>
void	Utopia::apply_rule (Rule &&rule, const ContTarget &cont_target, ContArgs &&... cont_args)
	Sequential case overload.
template<Update mode, Shuffle shuffle = Shuffle::on, class Rule , class ContTarget , class... ContArgs, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0, typename std::enable_if_t< shuffle==Shuffle::off, int > = 0>
void	Utopia::apply_rule (const Utopia::ExecPolicy policy, Rule &&rule, const ContTarget &cont_target, ContArgs &&... cont_args)
	Apply a rule asynchronously to manually updated states.
template<Update mode, Shuffle shuffle = Shuffle::on, class Rule , class ContTarget , class RNG , class... ContArgs, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0, typename std::enable_if_t< shuffle==Shuffle::on, int > = 0>
void	Utopia::apply_rule (Rule &&rule, const ContTarget &cont_target, RNG &&rng, ContArgs &&... cont_args)
	Sequential case overload.
template<Update mode, Shuffle shuffle = Shuffle::on, class Rule , class ContTarget , class RNG , class... ContArgs, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0, typename std::enable_if_t< shuffle==Shuffle::on, int > = 0>
void	Utopia::apply_rule (const Utopia::ExecPolicy policy, Rule &&rule, const ContTarget &cont_target, RNG &&rng, ContArgs &&... cont_args)
	Apply a rule asynchronously and shuffled to manually updated states.
template<class Rule , class Container , bool sync = impl::entity_t<Container>::is_sync()>
std::enable_if_t< sync, void >	Utopia::apply_rule (const Rule &rule, const Container &container)
	Apply a rule synchronously on the state of all entities of a container.
template<bool shuffle = true, class Rule , class Container , bool sync = impl::entity_t<Container>::is_sync()>
std::enable_if_t< not sync &&not shuffle, void >	Utopia::apply_rule (const Rule &rule, const Container &container)
	Apply a rule on asynchronous states without prior shuffling.
template<bool shuffle = true, class Rule , class Container , class RNG , bool sync = impl::entity_t<Container>::is_sync()>
std::enable_if_t< not sync &&shuffle, void >	Utopia::apply_rule (const Rule &rule, const Container &container, RNG &&rng)
	Apply a rule on asynchronous states with prior shuffling.
template<IterateOver iterate_over, Update mode, typename Graph , typename Rule , typename std::enable_if_t< mode==Update::sync, int > = 0>
void	Utopia::apply_rule (Rule &&rule, Graph &&g)
	Synchronously apply a rule to graph entities.
template<IterateOver iterate_over, Update mode, Shuffle shuffle, typename Graph , typename Rule , typename std::enable_if_t< mode==Update::async, int > = 0>
void	Utopia::apply_rule (Rule &&rule, Graph &&g)
	Asynchronously apply a rule to graph entities, without shuffling.
template<IterateOver iterate_over, Update mode, Shuffle shuffle = Shuffle::on, typename Graph , typename Rule , typename RNG , typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< shuffle==Shuffle::on, int > = 0>
void	Utopia::apply_rule (Rule &&rule, Graph &&g, RNG &&rng)
	Asynchronously, in shuffled order, apply a rule to graph entities.
template<IterateOver iterate_over, Update mode, typename Graph , typename Rule , typename VertexDesc = typename boost::graph_traits< std::remove_reference_t<Graph>>::vertex_descriptor, typename std::enable_if_t< mode==Update::sync, int > = 0>
void	Utopia::apply_rule (Rule &&rule, const VertexDesc ref_vertex, Graph &&g)
	Synchronously apply a rule to graph entities.
template<IterateOver iterate_over, Update mode, Shuffle shuffle = Shuffle::on, typename Graph , typename Rule , typename VertexDesc = typename boost::graph_traits< std::remove_reference_t<Graph>>::vertex_descriptor, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< shuffle==Shuffle::off, int > = 0>
void	Utopia::apply_rule (Rule &&rule, const VertexDesc ref_vertex, Graph &&g)
	Asynchronously apply a rule to graph entities, without shuffling.
template<IterateOver iterate_over, Update mode, Shuffle shuffle = Shuffle::on, typename Graph , typename Rule , typename RNG , typename VertexDesc = typename boost::graph_traits< std::remove_reference_t<Graph>>::vertex_descriptor>
void	Utopia::apply_rule (Rule &&rule, const VertexDesc ref_vertex, Graph &&g, RNG &&rng)
	Asynchronously, in shuffled order, apply a rule to graph entities.

Detailed Description

Algorithms for conveniently applying function objects on entities.

The General Idea

A rule is a function that computes the new state of the entity it is applied to.

Synchronous vs Asynchronous Updates

Applying a rule synchronously means that its result is applied to all entities simultaneously. In practice, one uses a cache for storing the intermediate states of the cells and then copies/moves the cache entries into the respective cell states.

Applying a rule asynchronously means that its result for a single entity is immediately imposed onto this entity. To avoid preferences in execution order, users may choose to use shuffling before iterating over the cells.

Implementation

A rule must be implemented by the programmer as a function (object). The function it represents must take a pointer to the entity as first argument and any number of additional arguments, and may capture arbitrary objects. The function's return value is the new state of the entity it is applied to.

For asynchronously applied rules, no return value is required; the state may be changed directly.

Currently, rules may also alter other members (i.e., tags) of the entity they are applied to, and may even change states of other entities. Notice that this does not make sense if you intend to apply such a rule synchronously!

A rule is applied with the Utopia::apply_rule() function. All overloads of this function take the rule, a container of entities, and optionally additional containers as arguments. The latter two are iterated and their elements are applied to the rule in order of their occurance in the containers. The number of containers the function is called with must match the number of arguments of the rule. All containers must have the same size.

Warning

There will be no runtime check if the inserted containers match in size! The zip iterator will cause undefined behavior in that case.

Defining a rule taking two arguments and passing an additional container with arguments to be applied can look like this:

auto my_rule = [](auto&& cell, auto&& arg){ return cell->state * arg; };
Utopia::apply_rule<Utopia::Update::async,
                   Utopia::Shuffle::off>(my_rule, my_cells, my_args);

Utopia::apply_rule() uses the Zip iteration utilities. The above function call is equivalent to the Python code:

for cell, arg in zip(my_cells, my_args):
    cell.state = rule(cell, arg)

Note

Additional argument containers are only available with Utopia::apply_rule() overloads for manual state update (see next section).

Choosing Update Type When Calling <tt>apply_rule</tt>

Previously, the state cache for synchronous updates was implemented in the entity itself. Therefore, users had to opt for either sync or async updates when choosing the state data type. We now encourage the usage of the Utopia::StateContainer with the specialization for the Utopia::Update::manual tag (see Utopia::StateContainer<StateType, Update::manual>). This allows for choosing the update type via the Utopia::Update switch directly when calling Utopia::apply_rule.

using EntityTraits = Utopia::CellTraits<int, Utopia::Update::manual>;
using CellManager = Utopia::CellManager<EntityTraits, MyModel>;
 
CellManager cm = get_cm_from_somewhere();
Utopia::apply_rule<Utopia::Update::async,
                   Utopia::Shuffle::off>(my_rule, cm.cells());

Multithreading Rules

Rules can also be applied in parallel, speeding up the entire computation. This requires the optional dependencies to be installed (consult the README.md for further information). Overloads for manual state update of apply_rule() can take a Utopia::ExecPolicy as first argument. Omitting this policy argument has the same effect as using the Utopia::ExecPolicy::seq policy. Parallel execution of Utopia algorithms can be selected at runtime. See Multithreading for details.

// Sequential execution
Utopia::apply_rule<Utopia::Update::async>(my_rule, my_cells, my_args);
 
// Possibly parallel execution
// NOTE: `my_rule` must avoid data races!
Utopia::apply_rule<Utopia::Update::async>(
    Utopia::ExecPolicy::par,
    my_rule,
    my_cells,
    my_args
);

{}

Typedef Documentation

rule_invoke_result_t

template<typename State , typename Rule , typename... Args>

using Utopia::rule_invoke_result_t = typedef typename rule_invoke_result<State, Rule, Args...>::type

Helper definition to query the rule result type.

See also

rule_invoke_result

Enumeration Type Documentation

Shuffle

enum class Utopia::Shuffle

strong

Switch for enabling/disabling shuffling the cells for asynchronous updates.

Enumerator
on	Shuffle the container before applying the rule sequentially.
off	Immediately apply the rule sequentially.

                   {
    on,
    off
};

Update

enum class Utopia::Update

strong

Update modes when applying rules.

It is recommended to use Update::manual in the EntityTraits because this gives full flexibility when applying the rules.

Note

To retain compatiblity with older implementations, this switch is used twice: For specializing the StateContainer, and for setting the update type in apply_rule() if said specialization is for Update::manual.

Enumerator
manual	User chooses update type when calling apply_rule()
sync	Synchronous update.
async	Asynchronous update.

                  {
    manual, 
    sync, 
    async 
};

Function Documentation

apply_rule() [1/15]

template<class Rule , class Container , bool sync = impl::entity_t<Container>::is_sync()>

std::enable_if_t< sync, void > Utopia::apply_rule	(	const Rule &	rule,
		const Container &	container
	)

Apply a rule synchronously on the state of all entities of a container.

Applies the rule function to each of the entities' states and stores the result in a buffer. Afterwards, it iterates over all entities again and applies the buffer to the actual state.

Parameters

rule	An application rule, see rule
Container	A container with the entities upon whom rule is applied

{
    // Apply the rule, distinguishing by return type of the rule
    using ReturnType =
        std::invoke_result_t<Rule, typename Container::value_type>;
 
    if constexpr(std::is_same_v<ReturnType, void>) {
        std::for_each(
            std::begin(container), std::end(container),
            [&rule](const auto& entity){ rule(entity); }
        );
    }
    else {
        std::for_each(
            std::begin(container), std::end(container),
            [&rule](const auto& entity){ entity->state_new() = rule(entity); }
        );
    }
 
    // Let the entity update its state, moving it from the buffer state to the
    // actual state and potentially applying other updating operations
    std::for_each(
        std::begin(container), std::end(container),
        [](const auto& entity){ entity->update(); }
    );
}

apply_rule() [2/15]

template<bool shuffle = true, class Rule , class Container , bool sync = impl::entity_t<Container>::is_sync()>

std::enable_if_t< not sync &&not shuffle, void > Utopia::apply_rule	(	const Rule &	rule,
		const Container &	container
	)

Apply a rule on asynchronous states without prior shuffling.

Parameters

rule	An application rule, see rule
Container	A container with the entities upon whom rule is applied

{
    // Apply the rule, distinguishing by return type of the rule
    using ReturnType =
        std::invoke_result_t<Rule, typename Container::value_type>;
 
    if constexpr(std::is_same_v<ReturnType, void>) {
        std::for_each(
            std::begin(container), std::end(container),
            [&rule](const auto& entity){ rule(entity); }
        );
    }
    else {
        std::for_each(
            std::begin(container), std::end(container),
            [&rule](const auto& entity){ entity->state() = rule(entity); }
        );
    }
}

apply_rule() [3/15]

template<bool shuffle = true, class Rule , class Container , class RNG , bool sync = impl::entity_t<Container>::is_sync()>

std::enable_if_t< not sync &&shuffle, void > Utopia::apply_rule	(	const Rule &	rule,
		const Container &	container,
		RNG &&	rng
	)

Apply a rule on asynchronous states with prior shuffling.

Parameters

rule	An application rule, see rule
Container	A container with the entities upon whom rule is applied

{
    std::remove_const_t<Container> container_shuffled(container);
    std::shuffle(std::begin(container_shuffled),
                 std::end(container_shuffled),
                 std::forward<RNG>(rng));
 
    // Apply the rule, distinguishing by return type of the rule
    using ReturnType =
        std::invoke_result_t<Rule, typename Container::value_type>;
 
    if constexpr(std::is_same_v<ReturnType, void>)
    {
        std::for_each(
            std::begin(container_shuffled), std::end(container_shuffled),
            [&rule](const auto& entity){ rule(entity); }
        );
    }
    else
    {
        std::for_each(
            std::begin(container_shuffled), std::end(container_shuffled),
            [&rule](const auto& entity){ entity->state() = rule(entity); }
        );
    }
}

apply_rule() [4/15]

template<Update mode, class Rule , class ContTarget , class... ContArgs, typename std::enable_if_t< mode==Update::sync, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0>

void Utopia::apply_rule	(	const Utopia::ExecPolicy	policy,
		Rule &&	rule,
		const ContTarget &	cont_target,
		ContArgs &&...	cont_args
	)

Apply a rule synchronously to manually updated states.

This creates a cache for new states whose contents are moved into the respective state containers after all rules have been applied.

Template Parameters

mode	Update mode for this rule. This is the overload for synchronous updates (Update::sync).
Rule	The type of the rule function (object).
ContTarget	The type of entity container.
ContArgs	The types of argument containers.

Parameters

policy	Utopia::ExecPolicy for the rule when applied in parallel
rule	The function (object) to apply to the entities
cont_target	The container of entities the function will be applied to
cont_args	The containers of additional argument for the function.

{
    using State = typename impl::entity_t<ContTarget>::State;
 
    // Make sure to call `invoke_result_type` at least for a conversion check
    static_assert(not is_void_rule<State, Rule, ContTarget, ContArgs...>(),
                  "Cannot apply void rules in a synchronous update!");
 
    // Initialize the state cache
    // NOTE: Copy one element to avoid requirement of default initialization
    std::vector<State> state_cache(cont_target.size(),
                                   cont_target.front()->state);
 
    // create the input zip iterators
    auto range = Itertools::zip(cont_target, cont_args...);
    using std::begin, std::end;
 
    // Apply the rule
    // NOTE: Capture by reference is fine because rule is a temporary
    std::transform(policy,
                   begin(range),
                   end(range),
                   begin(state_cache),
                   [&rule](auto&& args) {
                       return std::apply(rule,
                                         std::forward<decltype(args)>(args));
                   });
 
    // move the cache
    auto move_range = Itertools::zip(cont_target, state_cache);
    std::for_each(Utopia::ExecPolicy::par_unseq,
                  begin(move_range),
                  end(move_range),
                  [](auto&& tpl) {
                      std::get<0>(tpl)->state = std::move(std::get<1>(tpl));
                  });
}

apply_rule() [5/15]

template<Update mode, Shuffle shuffle = Shuffle::on, class Rule , class ContTarget , class... ContArgs, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0, typename std::enable_if_t< shuffle==Shuffle::off, int > = 0>

void Utopia::apply_rule	(	const Utopia::ExecPolicy	policy,
		Rule &&	rule,
		const ContTarget &	cont_target,
		ContArgs &&...	cont_args
	)

Apply a rule asynchronously to manually updated states.

Directly overwrite the states of the passed entities, according to the storage order inside the container.

Template Parameters

mode	Update mode for this rule. This is the overload for asynchronous updates (Update::async).
shuffle	Switch for enabling the shuffling of cells before applying the rule. This is the overload with shuffling disabled (Shuffle::off).
Rule	The type of the rule function (object).
Container	The type of entity container.
ContArgs	The types of argument containers.

Parameters

policy	Utopia::ExecPolicy for the rule when applied in parallel
rule	The function (object) to apply to the entities
container	The container of entities the function will be applied to
cont_args	The containers of additional argument for the function.

{
    // Create the input range zip iterators
    auto range = Itertools::zip(cont_target, cont_args...);
    using std::begin, std::end;
 
    // Apply the rule, distinguishing by return type of the rule
    using State = typename impl::entity_t<ContTarget>::State;
    if constexpr (is_void_rule<State, Rule, ContTarget, ContArgs...>()) {
        // Is a void-rule; no need to set the return value
        std::for_each(policy, begin(range), end(range), [&rule](auto&& args) {
            std::apply(rule,
                       std::forward<decltype(args)>(args));
        });
    }
    else {
        std::for_each(policy, begin(range), end(range), [&rule](auto&& args) {
            auto& cell = std::get<0>(args);
            cell->state = std::apply(rule,
                                    std::forward<decltype(args)>(args));
        });
    }
}

apply_rule() [6/15]

template<Update mode, Shuffle shuffle = Shuffle::on, class Rule , class ContTarget , class RNG , class... ContArgs, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0, typename std::enable_if_t< shuffle==Shuffle::on, int > = 0>

void Utopia::apply_rule	(	const Utopia::ExecPolicy	policy,
		Rule &&	rule,
		const ContTarget &	cont_target,
		RNG &&	rng,
		ContArgs &&...	cont_args
	)

Apply a rule asynchronously and shuffled to manually updated states.

Copy the container of (pointers to) entities, shuffle it, and apply the rule sequentially to the shuffled container. The original container remains unchanged.

Template Parameters

mode	Update mode for this rule. This is the overload for asynchronous updates (Update::async).
shuffle	Switch for enabling the shuffling of containers before applying the rule. This is the overload with shuffling enabled (Shuffle::on).
Rule	The type of the rule function (object).
Container	The type of entity container.
RNG	The type of the random number generator.
ContArgs	The types of argument containers.

Parameters

policy	Utopia::ExecPolicy for the rule when applied in parallel
rule	The function (object) to apply to the entities
cont_target	The container of entities the function will be applied to
rng	The random number generator used for shuffling the entities
cont_args	The containers of additional argument for the function.

Note

Shuffling only changes the order of execution of this function! It occurs on cont_target and all cont_args simultaneously, guaranteeing that entity at index i will be applied with additional arguments at index i for all container indices i. If you want to shuffle argument containers or entities independently from each other, you must do so yourself before applying this function. shuffle the arguments against the entities they are applied on, do so yourself before calling this function!

{
    // Create the input range zip iterators
    auto range = Itertools::zip(cont_target, cont_args...);
    using std::begin, std::end;
 
    // NOTE: std::shuffle requires the container elements to be swappable.
    //       This is not the case for tuples of T& so we need a container of
    //       tuples of std::reference_wrapper<T>. For this to work, we must
    //       propagate the const-ness of the container to the wrapper.
    //       When applying the rule, we must convert the reference wrappers back
    //       to regular references, which can be done with std::make_tuple.
    using Tuple = std::tuple<
        // 'ContTarget' is always const
        std::reference_wrapper<
            const typename std::remove_reference_t<ContTarget>::value_type>,
        // Universal references to 'ContArgs' *can* be const
        std::conditional_t<
            // Check if container is const
            std::is_const_v<std::remove_reference_t<ContArgs>>,
            // If true:
            std::reference_wrapper<
                const typename std::remove_reference_t<ContArgs>::value_type>,
            // If false:
            std::reference_wrapper<
                typename std::remove_reference_t<ContArgs>::value_type>>...>;
 
    // Create a container of tuples of arguments and shuffle it
    std::vector<Tuple> args_container(begin(range), end(range));
    std::shuffle(
        begin(args_container), end(args_container), std::forward<RNG>(rng));
 
    // Apply the rule, distinguishing by return type of the rule
    using State = typename impl::entity_t<ContTarget>::State;
    if constexpr(is_void_rule<State, Rule, ContTarget, ContArgs...>())
    {
        // Is a void-rule; no need to set the return value
        std::for_each(policy,
                      begin(args_container),
                      end(args_container),
                      [&rule](auto&& args) {
                          // NOTE: 'args' is tuple of reference_wrappers, and we
                          // want a tuple of regular references.
                          std::apply(rule,
                                     make_tuple_from_tuple(
                                       std::forward<decltype(args)>(args)));
                      });
    }
    else
    {
        std::for_each(policy,
                      begin(args_container),
                      end(args_container),
                      [&rule](auto&& args) {
                          // NOTE: 'args' is tuple of reference_wrappers, and we
                          //       want a tuple of regular references.
                          auto tpl = make_tuple_from_tuple(
                            std::forward<decltype(args)>(args));
                          auto& entity = std::get<0>(tpl);
                          // NOTE: Do not move 'tpl' as this invalidates ref
                          //       'entity'
                          entity->state = std::apply(rule, tpl);
                      });
    }
}

apply_rule() [7/15]

template<Update mode, class Rule , class ContTarget , class... ContArgs, typename std::enable_if_t< mode==Update::sync, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0>

void Utopia::apply_rule	(	Rule &&	rule,
		const ContTarget &	cont_target,
		ContArgs &&...	cont_args
	)

Sequential overload.

{
    apply_rule<mode>(
        Utopia::ExecPolicy::seq, rule, cont_target, cont_args...);
}

apply_rule() [8/15]

template<Update mode, Shuffle shuffle = Shuffle::on, class Rule , class ContTarget , class... ContArgs, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0, typename std::enable_if_t< shuffle==Shuffle::off, int > = 0>

void Utopia::apply_rule	(	Rule &&	rule,
		const ContTarget &	cont_target,
		ContArgs &&...	cont_args
	)

Sequential case overload.

{
    apply_rule<mode, shuffle>(
        Utopia::ExecPolicy::seq, rule, cont_target, cont_args...);
}

apply_rule() [9/15]

template<Update mode, Shuffle shuffle = Shuffle::on, class Rule , class ContTarget , class RNG , class... ContArgs, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< impl::entity_t< ContTarget >::mode==Update::manual, int > = 0, typename std::enable_if_t< shuffle==Shuffle::on, int > = 0>

void Utopia::apply_rule	(	Rule &&	rule,
		const ContTarget &	cont_target,
		RNG &&	rng,
		ContArgs &&...	cont_args
	)

Sequential case overload.

{
    apply_rule<mode, shuffle>(
        Utopia::ExecPolicy::seq, rule, cont_target, rng, cont_args...);
}

apply_rule() [10/15]

template<IterateOver iterate_over, Update mode, typename Graph , typename Rule , typename VertexDesc = typename boost::graph_traits< std::remove_reference_t<Graph>>::vertex_descriptor, typename std::enable_if_t< mode==Update::sync, int > = 0>

void Utopia::apply_rule	(	Rule &&	rule,
		const VertexDesc	ref_vertex,
		Graph &&	g
	)

Synchronously apply a rule to graph entities.

This overload specified the apply_rule function for not shuffled entities where getting the correct iterator pair is dependent on a ref_vertex, for example if the rule should be applied to the neighbors, inv_neighbors, in_degree, out_degree or degree wrt. the ref_vertex.

Template Parameters

iterate_over	Over which kind of graph entity to iterate over. See IterateOver
mode	The update mode, see UpdateMode
Shuffle	Whether to shuffle the container
Graph	The graph type
Rule	The rule type

Parameters

rule	The rule function, expecting (descriptor, graph) as arguments. For the synchronous update, the rule function needs to return the new state.
ref_vertex	Reference vertex descriptor to create the iterator from
g	The graph

{
    using namespace GraphUtils;
    auto [it, it_end] = iterator_pair<iterate_over>(ref_vertex, g);
    apply_sync(it, it_end, g, rule);
}

apply_rule() [11/15]

template<IterateOver iterate_over, Update mode, Shuffle shuffle = Shuffle::on, typename Graph , typename Rule , typename VertexDesc = typename boost::graph_traits< std::remove_reference_t<Graph>>::vertex_descriptor, typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< shuffle==Shuffle::off, int > = 0>

void Utopia::apply_rule	(	Rule &&	rule,
		const VertexDesc	ref_vertex,
		Graph &&	g
	)

Asynchronously apply a rule to graph entities, without shuffling.

This overload specifies the apply_rule function for an asynchronous update.

Warning

Not shuffling a rule often creates unwanted artifacts. Thus, to use this function, the Shuffle::off template argument needs to be given explicitly.

Template Parameters

iterate_over	Over which kind of graph entity to iterate over. See IterateOver
mode	The update mode, see UpdateMode
Graph	The graph type
Rule	The rule type

Parameters

rule	The rule function, expecting (descriptor, graph) as arguments. For an asynchronous update, returning the state is optional.
ref_vertex	Reference vertex descriptor to create the iterator from
g	The graph

{
    using namespace GraphUtils;
    auto [it, it_end] = iterator_pair<iterate_over>(ref_vertex, g);
    apply_async(it, it_end, g, rule);
}

apply_rule() [12/15]

template<IterateOver iterate_over, Update mode, Shuffle shuffle = Shuffle::on, typename Graph , typename Rule , typename RNG , typename VertexDesc = typename boost::graph_traits< std::remove_reference_t<Graph>>::vertex_descriptor>

void Utopia::apply_rule	(	Rule &&	rule,
		const VertexDesc	ref_vertex,
		Graph &&	g,
		RNG &&	rng
	)

Asynchronously, in shuffled order, apply a rule to graph entities.

This overload specified the apply_rule function for shuffled entities where getting the correct iterator pair is dependent on a ref_vertex, for example if the rule should be applied to the neighbors, inv_neighbors, in_degree, out_degree or degree wrt. the ref_vertex.

Template Parameters

iterate_over	Over which kind of graph entity to iterate over. See IterateOver
mode	The update mode, see UpdateMode
Shuffle	Whether to shuffle the iteration
Graph	The graph type
Rule	The rule type
RNG	The random number generator type

Parameters

rule	The rule function, expecting (descriptor, graph) as arguments. For an asynchronous update, returning the state is optional.
ref_vertex	Reference vertex descriptor to create the iterator from
g	The graph
rng	The random number generator

{
    static_assert(mode == Update::async,
                  "Shuffled apply_rule is only possible for Update::async!");
 
    using namespace GraphUtils;
 
    // Get the iterators and create a vector with a copy because the original
    // iterators are const, thus cannot be shuffled. Then shuffle.
    auto [it, it_end] = iterator_pair<iterate_over>(ref_vertex, g);
    std::vector<VertexDesc> it_shuffled(it, it_end);
 
    std::shuffle(std::begin(it_shuffled), std::end(it_shuffled), rng);
 
    apply_async(std::begin(it_shuffled), std::end(it_shuffled), g, rule);
}

apply_rule() [13/15]

template<IterateOver iterate_over, Update mode, typename Graph , typename Rule , typename std::enable_if_t< mode==Update::sync, int > = 0>

void Utopia::apply_rule	(	Rule &&	rule,
		Graph &&	g
	)

Synchronously apply a rule to graph entities.

This overload specifies the apply_rule function for a synchronous update. In such a case, it makes no sense to shuffle, so the shuffle option is not available here.

Template Parameters

iterate_over	Over which kind of graph entity to iterate over. See IterateOver
mode	The update mode, see UpdateMode
Graph	The graph type
Rule	The rule type

Parameters

rule	The rule function, expecting (descriptor, graph) as arguments. For the synchronous update, the rule function needs to return the new state.
g	The graph

{
    using namespace GraphUtils;
    auto [it, it_end] = iterator_pair<iterate_over>(g);
    apply_sync(it, it_end, g, rule);
}

apply_rule() [14/15]

template<IterateOver iterate_over, Update mode, Shuffle shuffle, typename Graph , typename Rule , typename std::enable_if_t< mode==Update::async, int > = 0>

void Utopia::apply_rule	(	Rule &&	rule,
		Graph &&	g
	)

Asynchronously apply a rule to graph entities, without shuffling.

This overload specifies the apply_rule function for an asynchronous update.

Warning

Not shuffling a rule often creates unwanted artifacts. Thus, to use this function, the Shuffle::off template argument needs to be given explicitly.

Template Parameters

iterate_over	Over which kind of graph entity to iterate over. See IterateOver
mode	The update mode, see UpdateMode
Graph	The graph type
Rule	The rule type

Parameters

rule	The rule function, expecting (descriptor, graph) as arguments. For an asynchronous update, returning the state is optional.
g	The graph

{
    static_assert(shuffle == Shuffle::off,
        "Refusing to asynchronously apply a rule without shuffling. Either "
        "explicitly specify Shuffle::off or pass an RNG to apply_rule to "
        "allow shuffling.");
 
    using namespace GraphUtils;
    auto [it, it_end] = iterator_pair<iterate_over>(g);
    apply_async(it, it_end, g, rule);
}

apply_rule() [15/15]

template<IterateOver iterate_over, Update mode, Shuffle shuffle = Shuffle::on, typename Graph , typename Rule , typename RNG , typename std::enable_if_t< mode==Update::async, int > = 0, typename std::enable_if_t< shuffle==Shuffle::on, int > = 0>

void Utopia::apply_rule	(	Rule &&	rule,
		Graph &&	g,
		RNG &&	rng
	)

Asynchronously, in shuffled order, apply a rule to graph entities.

Using the given RNG, the iteration order is shuffled before the rule is applied sequentially to the specified entities.

Template Parameters

iterate_over	Over which kind of graph entity to iterate over. See IterateOver
mode	The update mode, see UpdateMode
Shuffle	Whether to shuffle the container
Graph	The graph type
Rule	The rule type
RNG	The random number generator type

Parameters

rule	The rule function, expecting (descriptor, graph) as arguments. For an asynchronous update, returning the state is optional.
g	The graph
rng	The random number generator

{
    using namespace GraphUtils;
 
    // Get the iterators and create a vector with a copy because the original
    // iterators are const, thus cannot be shuffled. Then shuffle.
    auto [it, it_end] = Utopia::GraphUtils::iterator_pair<iterate_over>(g);
    using Desc = typename std::iterator_traits<decltype(it)>::value_type;
    std::vector<Desc> it_shuffled(it, it_end);
    
    std::shuffle(std::begin(it_shuffled),
                 std::end(it_shuffled),
                 std::forward<RNG>(rng));
 
    // Now with the shuffled container, apply the rule to each element
    apply_async(std::begin(it_shuffled), std::end(it_shuffled), g, rule);
}

is_void_rule()

template<typename State , typename Rule , typename... Args>

constexpr bool Utopia::is_void_rule ( )

constexpr

Helper function to check if the rule returns void

See also

rule_invoke_result

{
    return std::is_same_v<void, rule_invoke_result_t<State, Rule, Args...>>;
}

make_tuple_from_tuple()

template<class Tuple >

constexpr decltype(auto) Utopia::make_tuple_from_tuple ( Tuple &&  t )

constexpr

Helper function to create a tuple from a tuple.

This seems silly, but calling std::make_tuple decays objects of std::reference_wrapper<T> toT&`, which is exactly what we use this function for.

This function creates a index sequence for the tuple and calls the implementation helper make_tuple_from_tuple_impl().

Parameters

t	Tuple to create a tuple from

Returns

Tuple containing the elements of the input tuple

{
    return make_tuple_from_tuple_impl(
        std::forward<Tuple>(t),
        std::make_index_sequence<
            std::tuple_size_v<std::remove_reference_t<Tuple>>>{});
}

make_tuple_from_tuple_impl()

template<class Tuple , std::size_t... I>

constexpr decltype(auto) Utopia::make_tuple_from_tuple_impl ( Tuple &&  t, std::index_sequence< I... >    )

constexpr

Helper function to create a tuple from a tuple using an index sequence.

Template Parameters

I	Index sequence to access the elements of the tuple

Parameters

t	Tuple to create a tuple from

Returns

Tuple containing the elements of the input tuple

{
    return std::make_tuple(std::get<I>(std::forward<Tuple>(t))...);
}