Utopia::Models::SimpleFlocking Namespace Reference

Classes
class	AgentState
	An agent's state. More...
struct	Infrastructure
class	SimpleFlocking
	The SimpleFlocking Model. More...

Typedefs
using	ModelTypes = Utopia::ModelTypes<>
	Type helper to define types used by the model.
using	AgentTraits = Utopia::AgentTraits< AgentState, Update::sync >
	Agent traits specialization using the state type.

Functions
	BOOST_FIXTURE_TEST_CASE (test_state_interface, Infrastructure, *utf::tolerance(1.e-12))
	Test the AgentState interface.
	BOOST_FIXTURE_TEST_CASE (test_state_angles, Infrastructure, *utf::tolerance(1.e-12))
	Check angles are used according to convention.
	BOOST_AUTO_TEST_SUITE (test_angles)
	BOOST_TEST (constrain_angle(+1.)==+1.)
	Assert the basic working of the regularisation function for angles.
	BOOST_TEST (constrain_angle(-1.)==-1.)
	BOOST_TEST (constrain_angle(+M_PI)==-M_PI)
	BOOST_TEST (constrain_angle(-M_PI)==-M_PI)
	BOOST_TEST (constrain_angle(+3 *M_PI)==-M_PI)
	BOOST_TEST (constrain_angle(-3 *M_PI)==-M_PI)
	BOOST_TEST (constrain_angle(+2 *M_PI)==0.)
	BOOST_TEST (constrain_angle(+4 *M_PI)==0.)
	BOOST_TEST (constrain_angle(+40 *M_PI)==0.)
	BOOST_TEST (constrain_angle(-2 *M_PI)==0.)
	BOOST_TEST (constrain_angle(-4 *M_PI)==0.)
	BOOST_TEST (constrain_angle(-40 *M_PI)==0.)
	BOOST_TEST (constrain_angle(+M_PI+1.)==-M_PI+1.)
	BOOST_TEST (constrain_angle(-M_PI - 1.)==+M_PI - 1.)
	BOOST_FIXTURE_TEST_CASE (test_random_angle, Infrastructure)
	Assert that there is no bias in the random angle function.
	BOOST_AUTO_TEST_SUITE_END ()
	BOOST_AUTO_TEST_SUITE (test_geometry)
	BOOST_AUTO_TEST_CASE (test_absolute_group_velocity)
	BOOST_AUTO_TEST_SUITE (test_circular_stats)
	BOOST_AUTO_TEST_CASE (test_circular_mean)
	Tests the circular_mean function.
	BOOST_AUTO_TEST_CASE (test_circular_mean_and_std)
	Tests the circular_mean_and_std function.
template<class RNG , class T = double>
T	random_angle (const std::shared_ptr< RNG > &rng)
	Returns a uniformly random angle value in [-π, +π)
template<class T >
T	constrain_angle (T angle)
	Constrains an angle value to interval [-π, +π)
template<class Container >
void	constrain_angles (Container &angles)
	In-place constrains all angles in a container to interval [-π, +π)
template<class Container >
double	absolute_group_velocity (const Container &velocities)
	Computes the absolute group velocity from a container of velocity vectors.
template<class Container >
auto	_circular_sin_cos_sum (const Container &angles)
	Compute sum of sine and cosine values from angles in a container.
template<class Container = std::vector<double>>
auto	circular_mean (const Container &angles)
	Computes the circular mean from a sample of (constrained) angles.
template<class Container = std::vector<double>>
auto	circular_mean_and_std (const Container &angles)
	Computes the circular mean and std from a sample of (constrained) angles.

Variables
constexpr double	TAU = 2*M_PI
constexpr double	NaN = std::numeric_limits<double>::quiet_NaN()

Typedef Documentation

AgentTraits

using Utopia::Models::SimpleFlocking::AgentTraits = typedef Utopia::AgentTraits<AgentState, Update::sync>

Agent traits specialization using the state type.

The first template parameter specifies the type of the cell state, the second sets them to be synchronously updated.

ModelTypes

using Utopia::Models::SimpleFlocking::ModelTypes = typedef Utopia::ModelTypes<>

Type helper to define types used by the model.

Function Documentation

_circular_sin_cos_sum()

template<class Container >

auto Utopia::Models::SimpleFlocking::_circular_sin_cos_sum

(

const Container &

angles

)

Compute sum of sine and cosine values from angles in a container.

                                                     {
    static_assert(
        std::is_floating_point<typename Container::value_type>::value,
        "need angles specified as floating-point types!"
    );
 
    const auto sin_sum = std::accumulate(
        angles.begin(), angles.end(), 0.,
        [](auto a1, auto a2){ return a1 + std::sin(a2); }
    );
    const auto cos_sum = std::accumulate(
        angles.begin(), angles.end(), 0.,
        [](auto a1, auto a2){ return a1 + std::cos(a2); }
    );
 
    return std::make_pair(sin_sum, cos_sum);
}

absolute_group_velocity()

template<class Container >

double Utopia::Models::SimpleFlocking::absolute_group_velocity

(

const Container &

velocities

)

Computes the absolute group velocity from a container of velocity vectors.

Essentially: the 2-norm of the sum of all velocity vectors, divided by the number of vectors. Returns NaN if the given container is empty.

                                                             {
    if (velocities.empty()) {
        return std::numeric_limits<double>::quiet_NaN();
    }
 
    using Vec = typename Container::value_type;
    Vec zero = velocities[0];
    zero.fill(0.);
 
    const Vec group_velocity = std::accumulate(
        velocities.begin(), velocities.end(), zero
    );
    return arma::norm(group_velocity, 2) / velocities.size();
}

BOOST_AUTO_TEST_CASE() [1/3]

Utopia::Models::SimpleFlocking::BOOST_AUTO_TEST_CASE

(

test_absolute_group_velocity

)

{
    using Vec = arma::Col<double>;
    using VecCont = std::vector<Vec>;
 
    const auto zero = Vec(2, arma::fill::zeros);
    const auto one = Vec(2, arma::fill::ones);
 
    // Empty container yields NaN
    BOOST_TEST(std::isnan(absolute_group_velocity(VecCont{})));
 
    // Zero-sum group velocities
    BOOST_TEST(
        absolute_group_velocity(VecCont({zero, zero, zero})) == 0.
    );
    BOOST_TEST(
        absolute_group_velocity(VecCont({zero, -1*one, +1*one})) == 0.
    );
 
    // Non-zero sum group velocities
    BOOST_TEST(
        absolute_group_velocity(VecCont({one})) == std::sqrt(2.),
        tt::tolerance(1.e-10)
    );
}

BOOST_AUTO_TEST_CASE() [2/3]

Utopia::Models::SimpleFlocking::BOOST_AUTO_TEST_CASE

(

test_circular_mean

)

Tests the circular_mean function.

{
    const double pi = M_PI;
 
    // Mean at zero
    BOOST_TEST(circular_mean({pi/2, -pi/2}) == 0.);
    BOOST_TEST(circular_mean({pi/2, -pi/2, 0., -1., +1.}) == 0.);
 
    // Cone of angles not crossing the discontinuity
    BOOST_TEST(circular_mean({1, 1, 1, 2, 0}) == +1);
    BOOST_TEST(circular_mean({-1, -1, -1, -2, -0}) == -1);
 
    // Check for mean value near or at discontinuity (at ±π)
    BOOST_TEST(circular_mean({.5*pi, -.5*pi}) == 0.);
    BOOST_TEST(circular_mean({.5001*pi, -.5001*pi}) == -pi);
    BOOST_TEST(circular_mean({.9*pi, -.9*pi}) == -pi);
 
    // No values: will return NaN
    BOOST_TEST(std::isnan(circular_mean({})));
}

BOOST_AUTO_TEST_CASE() [3/3]

Utopia::Models::SimpleFlocking::BOOST_AUTO_TEST_CASE

(

test_circular_mean_and_std

)

Tests the circular_mean_and_std function.

{
    const double pi = M_PI;
    auto circ_mean = [](const std::vector<double>& angles){
        return circular_mean_and_std(angles).first;
    };
    auto circ_std = [](const std::vector<double>& angles){
        return circular_mean_and_std(angles).second;
    };
 
    // No values: will return NaN
    BOOST_TEST(std::isnan(circ_mean({})));
    BOOST_TEST(std::isnan(circ_std({})));
 
    // Mean is same as in separate function
    BOOST_TEST(circ_mean({1, 1, 1, 2, 0}) == +1);
    BOOST_TEST(circ_mean({.5*pi, -.5*pi}) == 0.);
    BOOST_TEST(circ_mean({.9*pi, -.9*pi}) == -pi);
 
    // Std. dev. of values distributed near the center of domain, not crossing
    // the discontinuity
    BOOST_TEST(circ_std({0., 0., 0.}) == 0.);
    BOOST_TEST(circ_std({1., 1., 1.}) == 0.);
    BOOST_TEST(circ_std({-1., -1., -1.}) == 0.);
 
    BOOST_TEST(
        circ_std({-1., 0., 1.}) == 0.855515936, tt::tolerance(1.e-9)
    );
    BOOST_TEST(
        circ_std({0, 0.1*pi/2, 0.001*pi, 0.03*pi/2}) ==
        0.063564063306, tt::tolerance(1.e-9)  // result from scipy example
    );
 
    // Angles near and crossing the discontinuity (at ±π)
    BOOST_TEST(
        circ_std({+pi-1., +pi, +pi+1.}) == 0.855515936, tt::tolerance(1.e-9)
    );
    BOOST_TEST(
        circ_std({-pi-1., -5*pi, -pi+1.}) == 0.855515936, tt::tolerance(1.e-9)
    );
 
    BOOST_TEST(
        circ_std({+pi, -pi+0.1*pi/2, -pi+0.001*pi, -pi+0.03*pi/2}) ==
        0.063564063306, tt::tolerance(1.e-10)  // result from scipy example
    );
    BOOST_TEST(
        circ_std({-pi, -3*pi+0.1*pi/2, +pi+0.001*pi, +5*pi+0.03*pi/2}) ==
        0.063564063306, tt::tolerance(1.e-10)  // result from scipy example
    );
}

BOOST_AUTO_TEST_SUITE() [1/3]

Utopia::Models::SimpleFlocking::BOOST_AUTO_TEST_SUITE

(

test_angles

)

BOOST_AUTO_TEST_SUITE() [2/3]

Utopia::Models::SimpleFlocking::BOOST_AUTO_TEST_SUITE

(

test_circular_stats

)

BOOST_AUTO_TEST_SUITE() [3/3]

Utopia::Models::SimpleFlocking::BOOST_AUTO_TEST_SUITE

(

test_geometry

)

BOOST_AUTO_TEST_SUITE_END()

Utopia::Models::SimpleFlocking::BOOST_AUTO_TEST_SUITE_END

(

)

BOOST_FIXTURE_TEST_CASE() [1/3]

Utopia::Models::SimpleFlocking::BOOST_FIXTURE_TEST_CASE	(	test_random_angle	,
		Infrastructure
	)

Assert that there is no bias in the random angle function.

This is not to test the properties of uniform_real_distribution or the RNG but of the hard-coded interval in the random_angle function, which should for consistency's sake be symmetric around zero.

{
    auto agg_angle = 0.;
    auto val = 0.;
    auto N = 100000u;
 
    for (auto i = 0u; i < N; i++) {
        val = random_angle(rng);
        BOOST_TEST(val <  +M_PI);
        BOOST_TEST(val >= -M_PI);
        agg_angle += val;
    }
 
    BOOST_TEST(std::abs(agg_angle/N) < 0.02);
}

BOOST_FIXTURE_TEST_CASE() [2/3]

Utopia::Models::SimpleFlocking::BOOST_FIXTURE_TEST_CASE	(	test_state_angles	,
		Infrastructure	,
		*	utf::tolerance1.e-12
	)

Check angles are used according to convention.

{
    auto state = AgentState(cfg["agent_state"], rng);
    state.set_speed(1.);
 
    // Zero: Movement in +x direction
    state.set_orientation(0.);
    BOOST_TEST(state.get_displacement()[0] == 1.);
    BOOST_TEST(state.get_displacement()[1] == 0.);
 
    // ± π/2: movement in ±y direction
    state.set_orientation(+M_PI/2.);
    BOOST_TEST(state.get_displacement()[0] == 0.);
    BOOST_TEST(state.get_displacement()[1] == +1.);
 
    state.set_orientation(-M_PI/2.);
    BOOST_TEST(state.get_displacement()[0] == 0.);
    BOOST_TEST(state.get_displacement()[1] == -1.);
 
    // ±M_PI: Movement in -x direction
    state.set_orientation(+M_PI);
    BOOST_TEST(state.get_displacement()[0] == -1.);
    BOOST_TEST(state.get_displacement()[1] == 0.);
 
    state.set_orientation(-M_PI);
    BOOST_TEST(state.get_displacement()[0] == -1.);
    BOOST_TEST(state.get_displacement()[1] == 0.);
}

BOOST_FIXTURE_TEST_CASE() [3/3]

Utopia::Models::SimpleFlocking::BOOST_FIXTURE_TEST_CASE	(	test_state_interface	,
		Infrastructure	,
		*	utf::tolerance1.e-12
	)

Test the AgentState interface.

{
    // Default construction
    auto state = AgentState();
    BOOST_TEST(state.get_speed() == 0.);
    BOOST_TEST(state.get_orientation() == 0.);
    BOOST_TEST(arma::norm(state.get_displacement(), 2) == 0.);
 
    // Config-based construction and assignment
    auto agent_cfg = cfg["agent_state"];
 
    state = AgentState(agent_cfg, rng);
    BOOST_TEST(state.get_speed() == get_as<double>("speed", agent_cfg));
    BOOST_TEST(state.get_orientation() != 0.);  // random value
    BOOST_TEST(arma::norm(state.get_displacement(), 2) != 0.);
 
    // Setting speed or orientation updates the displacement vector
    auto old_displacement = state.get_displacement();
    state.set_speed(0.);
    BOOST_TEST(arma::norm(state.get_displacement(), 2) == 0.);
    state.set_orientation(0.);
    BOOST_TEST(arma::norm(state.get_displacement(), 2) == 0.);
 
    state.set_speed(23.);
    BOOST_TEST(arma::norm(state.get_displacement(), 2) != 0.);
 
    // Displacement vector is normalized, but scaled with speed
    BOOST_TEST(arma::norm(state.get_displacement(), 2) == 23.);
 
    // Construction also works without speed specified
    state = AgentState(agent_cfg["i_do_not_exist"], rng);
    BOOST_TEST(state.get_speed() == 0.);
}

BOOST_TEST() [1/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(+1.)

= =+1.

)

Assert the basic working of the regularisation function for angles.

Values should always be in [-π, +π)

BOOST_TEST() [2/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(+2 *M_PI)

= =0.

)

BOOST_TEST() [3/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(+3 *M_PI)

= =-M_PI

)

BOOST_TEST() [4/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(+4 *M_PI)

= =0.

)

BOOST_TEST() [5/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(+40 *M_PI)

= =0.

)

BOOST_TEST() [6/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(+M_PI)

= =-M_PI

)

BOOST_TEST() [7/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(+M_PI+1.)

= =-M_PI+1.

)

BOOST_TEST() [8/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(-1.)

= =-1.

)

BOOST_TEST() [9/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(-2 *M_PI)

= =0.

)

BOOST_TEST() [10/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(-3 *M_PI)

= =-M_PI

)

BOOST_TEST() [11/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(-4 *M_PI)

= =0.

)

BOOST_TEST() [12/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(-40 *M_PI)

= =0.

)

BOOST_TEST() [13/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(-M_PI - 1.)

= =+M_PI - 1.

)

BOOST_TEST() [14/14]

Utopia::Models::SimpleFlocking::BOOST_TEST

(

constrain_angle(-M_PI)

= =-M_PI

)

circular_mean()

template<class Container = std::vector<double>>

auto Utopia::Models::SimpleFlocking::circular_mean

(

const Container &

angles

)

Computes the circular mean from a sample of (constrained) angles.

Uses circular statistics to compute the mean. Assumes angles to be in radians. While it does not matter in which interval they are, the resulting mean value will be in [-π, +π).

Returns NaN if the given container is empty.

See scipy implementation for reference: https://github.com/scipy/scipy/blob/v1.7.1/scipy/stats/morestats.py#L3474

                                             {
    if (angles.empty()) {
        return std::numeric_limits<double>::quiet_NaN();
    }
 
    const auto&& [sin_sum, cos_sum] = _circular_sin_cos_sum(angles);
    return constrain_angle(std::atan2(sin_sum, cos_sum));
}

circular_mean_and_std()

template<class Container = std::vector<double>>

auto Utopia::Models::SimpleFlocking::circular_mean_and_std

(

const Container &

angles

)

Computes the circular mean and std from a sample of (constrained) angles.

Uses circular statistics to compute the mean and standard deviation. Assumes angles to be in radians. While it does not matter in which interval they are, the resulting mean value will be in [-π, +π).

Returns NaN if the given container is empty.

See scipy implementation for reference: https://github.com/scipy/scipy/blob/v1.7.1/scipy/stats/morestats.py#L3595

                                                     {
    if (angles.empty()) {
        return std::make_pair(NaN, NaN);
    }
 
    const auto&& [sin_sum, cos_sum] = _circular_sin_cos_sum(angles);
    const auto mean = constrain_angle(std::atan2(sin_sum, cos_sum));
 
    const auto r = std::min(
        1., std::sqrt(sin_sum*sin_sum + cos_sum*cos_sum) / angles.size()
    );
    const auto std = std::sqrt(-2. * std::log(r));
 
    return std::make_pair(mean, std);
}

constrain_angle()

template<class T >

T Utopia::Models::SimpleFlocking::constrain_angle

(

T

angle

)

Constrains an angle value to interval [-π, +π)

                            {
    angle = std::fmod(angle + M_PI, TAU);
    while (angle < 0.) {
        angle += TAU;
    }
    return angle - M_PI;
}

constrain_angles()

template<class Container >

void Utopia::Models::SimpleFlocking::constrain_angles

(

Container &

angles

)

In-place constrains all angles in a container to interval [-π, +π)

                                          {
    std::transform(
        angles.begin(), angles.end(), angles.begin(),
        [](auto angle){ return constrain_angle(angle); }
    );
}

random_angle()

template<class RNG , class T = double>

T Utopia::Models::SimpleFlocking::random_angle

(

const std::shared_ptr< RNG > &

rng

)

Returns a uniformly random angle value in [-π, +π)

                                               {
    return std::uniform_real_distribution<T>(-M_PI, +M_PI)(*rng);
}

Variable Documentation

NaN

constexpr double Utopia::Models::SimpleFlocking::NaN = std::numeric_limits<double>::quiet_NaN()

constexpr

TAU

constexpr double Utopia::Models::SimpleFlocking::TAU = 2*M_PI

constexpr