Classes
class	ConstantDistribution

class	DiscreteDistribution

class	DistributedGenerator

class	DistributedGenerator< random_device >

class	Distribution

class	Generator

class	Generator< std::random_device >

class	Index

class	UniformRandomBitGenerator

Typedefs
template<typename IntType = int>
using	UniformIntDistribution = Distribution< std::uniform_int_distribution< IntType > >

template<typename FloatType = double>
using	UniformRealDistribution = Distribution< std::uniform_real_distribution< FloatType > >

typedef Distribution< std::bernoulli_distribution >	BernoulliDistribution

template<typename IntType = unsigned int>
using	BinomialDistribution = Distribution< std::binomial_distribution< IntType > >

template<typename FloatType = double>
using	NormalDistribution = Distribution< std::normal_distribution< FloatType > >

template<typename IntType = int>
using	PoissonDistribution = Distribution< std::poisson_distribution< IntType > >

typedef Generator< std::mt19937 >	mt19937

typedef Generator< std::mt19937_64 >	mt19937_64

typedef Generator< std::minstd_rand >	minstd_rand

typedef Generator< std::random_device >	random_device

typedef Index< int >	DistributedIndex

Functions
template<typename Gen , class CharT , class Traits >
std::basic_ostream< CharT, Traits > &	operator<< (std::basic_ostream< CharT, Traits > &ost, const Generator< Gen > &g)

template<typename Gen , class CharT , class Traits >
std::basic_istream< CharT, Traits > &	operator>> (std::basic_istream< CharT, Traits > &ost, Generator< Gen > &g)

template<class CharT , class Traits >
std::basic_ostream< CharT, Traits > &	operator<< (std::basic_ostream< CharT, Traits > &ost, const Generator< std::random_device > &)

template<class CharT , class Traits >
std::basic_istream< CharT, Traits > &	operator>> (std::basic_istream< CharT, Traits > &ost, Generator< std::random_device > &)

template<typename T , typename Generator_t >
std::vector< T >	local_choices (const std::vector< T > &local_items, std::size_t n, Generator_t &gen)

template<typename T >
std::vector< T >	local_choices (const std::vector< T > &local_items, std::size_t n)

template<typename T >
std::vector< std::vector< T > >	distributed_choices (api::communication::MpiCommunicator &comm, const std::vector< T > &local_items, std::size_t n)

template<typename T >
std::vector< T >	split_choices (api::communication::MpiCommunicator &comm, const std::vector< T > &local_items, std::size_t n)

template<typename T , typename Generator_t >
std::vector< T >	local_sample (const std::vector< T > &local_items, std::size_t n, Generator_t &gen)

template<typename T >
std::vector< T >	local_sample (const std::vector< T > &local_items, std::size_t n)

template<typename Index_t , typename Generator_t >
std::vector< Index_t >	sample_indexes (Index_t begin, Index_t end, std::size_t n, Generator_t &gen)

template<typename T >
std::vector< std::vector< T > >	distributed_sample (api::communication::MpiCommunicator &comm, const std::vector< T > &local_items, std::size_t n)

template<typename T >
std::vector< T >	split_sample (api::communication::MpiCommunicator &comm, const std::vector< T > &local_items, std::size_t n)

Variables
DistributedGenerator	rd_choices

const std::mt19937::result_type	default_seed {std::mt19937::default_seed}

mt19937::result_type	seed {default_seed}

Detailed Description

fpmas::api::random implementations

Typedef Documentation

◆ UniformIntDistribution

template<typename IntType = int>

using fpmas::random::UniformIntDistribution = typedef Distribution<std::uniform_int_distribution<IntType> >

Predefined UniformIntDistribution.

◆ UniformRealDistribution

template<typename FloatType = double>

using fpmas::random::UniformRealDistribution = typedef Distribution<std::uniform_real_distribution<FloatType> >

Predefined UniformRealDistribution.

◆ BernoulliDistribution

typedef Distribution<std::bernoulli_distribution> fpmas::random::BernoulliDistribution

Predefined BernoulliDistribution.

◆ BinomialDistribution

template<typename IntType = unsigned int>

using fpmas::random::BinomialDistribution = typedef Distribution<std::binomial_distribution<IntType> >

Predefined BinomialDistribution.

◆ NormalDistribution

template<typename FloatType = double>

using fpmas::random::NormalDistribution = typedef Distribution<std::normal_distribution<FloatType> >

Predefined NormalDistribution.

◆ PoissonDistribution

template<typename IntType = int>

using fpmas::random::PoissonDistribution = typedef Distribution<std::poisson_distribution<IntType> >

Predefined PoissonDistribution.

◆ mt19937

typedef Generator<std::mt19937> fpmas::random::mt19937

Predefined mt19937 engine.

◆ mt19937_64

typedef Generator<std::mt19937_64> fpmas::random::mt19937_64

Predefined mt19937_64 engine.

◆ minstd_rand

typedef Generator<std::minstd_rand> fpmas::random::minstd_rand

Predefined minstd_rand engine.

◆ random_device

typedef Generator<std::random_device> fpmas::random::random_device

Predefined random_device engine.

◆ DistributedIndex

typedef Index<int> fpmas::random::DistributedIndex

Represents a continuous index distributed across processes.

A distributed index is represented as a (process, local_offset) pair. Processes are indexed from 0 to p-1. Each process is assigned to a given number of items n_p.

The sequence of values iterated by the index is as all processes items were iterated in a single sequence, from process 0 to p-1:

(0, 0) (0, 1) ... (0, n_0-1) (1, 0) ... (1, n_1-1) ... (p-1, 0) ... (p-1, n_(p-1)-1) (p, 0)

The interest of this structure is that local offsets associated to a process p can for exemple be used as indexes in a vector hosted by the process p.

Function Documentation

◆ operator<<() [1/2]

template<typename Gen , class CharT , class Traits >

std::basic_ostream< CharT, Traits > & fpmas::random::operator<<	(	std::basic_ostream< CharT, Traits > &	ost,
		const Generator< Gen > &	g
	)

Serializes the specified generator to an output stream.

The implementation is directly based on the C++11 standard RandomNumberEngine operator<< specification.

◆ operator>>() [1/2]

template<typename Gen , class CharT , class Traits >

std::basic_istream< CharT, Traits > & fpmas::random::operator>>	(	std::basic_istream< CharT, Traits > &	ost,
		Generator< Gen > &	g
	)

Unserializes a generator from an input stream.

The produced generator continues to generate its random number sequence from the state it had when serialized.

The implementation is directly based on the C++11 standard RandomNumberEngine operator>> specification.

◆ operator<<() [2/2]

template<class CharT , class Traits >

std::basic_ostream< CharT, Traits > & fpmas::random::operator<<	(	std::basic_ostream< CharT, Traits > &	ost,
		const Generator< std::random_device > &
	)

random_device specialization of the generator output stream operator.

Does not need to serialize anything.

◆ operator>>() [2/2]

template<class CharT , class Traits >

std::basic_istream< CharT, Traits > & fpmas::random::operator>>	(	std::basic_istream< CharT, Traits > &	ost,
		Generator< std::random_device > &
	)

random_device specialization of the generator input stream operator.

Does not need to unserialize anything.

◆ local_choices() [1/2]

template<typename T , typename Generator_t >

std::vector< T > fpmas::random::local_choices	(	const std::vector< T > &	local_items,
		std::size_t	n,
		Generator_t &	gen
	)

Randomly selects n elements from the local_items, with replacement. In consequence, n can be greater than the number of elements of local_items.

A case of interest occurs when the local_items are the same on all processes. If the provided random number generator is sequential, the same choices are performed on all processes (provided that generators are in the same state on each process). If the generator is distributed, different choices are performed on each process.

Parameters

local_items	local items from which random choices should be made
n	number of items to chose
gen	random number generator

Returns: random choices

◆ local_choices() [2/2]

template<typename T >

std::vector< T > fpmas::random::local_choices	(	const std::vector< T > &	local_items,
		std::size_t	n
	)

Same as local_choices(const std::vector<T>&, std::size_t, Generator_t), but uses the predefined rd_choices distributed generator instead.

Different choices are performed on all processes, even if the local_items are the same.

The rd_choices instance can be seeded with the fpmas::seed() method.

◆ distributed_choices()

template<typename T >

std::vector< std::vector< T > > fpmas::random::distributed_choices	(	api::communication::MpiCommunicator &	comm,
		const std::vector< T > &	local_items,
		std::size_t	n
	)

Randomly selects n items from all local_items specified on all processes, with replacement.

A set of n choices is built independently on each process.

Distinct local_items lists of any size can be specified on each process. n items are returned independently on each process, so different values of n can be specified on each process.

The elements are selected as if choices where performed locally on a list representing the concatenation of all local_items specified on all processes.

This method performs collective communications within the specified MPI communicator. In consequence, the method must be called from all processes.

The complete item list is never centralized, in order to limit communications and memory usage.

Results are returned in an std::vector v of size comm.getSize(), such that v[i] contains items selected from process i.

Tip: A one dimensional vector can be generated from the result with std::vector<T> choices = std::accumulate(v.begin(), v.end(), std::vector<T>(), fpmas::utils::Concat()).

See also: split_choices

Parameters

comm	MPI communicator
local_items	local items provided by the current process
n	local number of items to select from all items (might be different on all processes)

Returns: a choices list of size n, selected from all the processes.

◆ split_choices()

template<typename T >

std::vector< T > fpmas::random::split_choices	(	api::communication::MpiCommunicator &	comm,
		const std::vector< T > &	local_items,
		std::size_t	n
	)

Randomly selects n items from all local_items specified on all processes, with replacement.

Contrary to distributed_choices(), a single choices list of size n is built across processes. Return values correspond to the subset of values selected on the current process, so that all returned items are contained in local_items and n items are chosen in total.

In consequence, the specified n must be the same on all processes.

This method performs collective communications within the specified MPI communicator. In consequence, the method must be called from all processes.

The complete item list is never centralized, in order to limit communications and memory usage.

Parameters

comm	MPI communicator
local_items	local items provided by the current process
n	local number of items to select from all items (must be the same on all processes)

Returns: selected local items, so that the concatenation of results from all processes is a valid choices list of size n selected from all local_items.

◆ local_sample() [1/2]

template<typename T , typename Generator_t >

std::vector< T > fpmas::random::local_sample	(	const std::vector< T > &	local_items,
		std::size_t	n,
		Generator_t &	gen
	)

Randomly selects n elements from the local_items, without replacement. If n is greater that the number of elements of local_items, all items are returned (and the size of the sample is less than n).

A case of interest occurs when the local_items are the same on all processes. If the provided random number generator is sequential, the same sample is built on all processes (provided that generators are in the same state on each process). If the generator is distributed, different samples are built on each process.

Parameters

local_items	local items from which random choices should be made
n	number of items to chose
gen	random number generator

Returns: random choices

◆ local_sample() [2/2]

template<typename T >

std::vector< T > fpmas::random::local_sample	(	const std::vector< T > &	local_items,
		std::size_t	n
	)

Same as local_sample(const std::vector<T>&, std::size_t, Generator_t), but uses the predefined rd_choices distributed generator instead.

Different samples are built on all processes, even if the local_items are the same.

The rd_choices instance can be seeded with the fpmas::seed() method.

◆ sample_indexes()

template<typename Index_t , typename Generator_t >

std::vector< Index_t > fpmas::random::sample_indexes	(	Index_t	begin,
		Index_t	end,
		std::size_t	n,
		Generator_t &	gen
	)

Algorithm used to build a sample of generic indexes, without replacement.

Index_t can be anything that fulfill the following requirements:

Index_t is CopyConstructible
Given an instance index, index++ and ++index are valid expressions and correspond to the expected behaviors.
Given instances i1 and i2, i1!=i2 and i1==i2 is valid.
Considering index=begin, successively applying index++ necessarily reaches a point were index!=end is false (and index==end is true). The behavior of applying index++ when index==end is however not specified.

Indexes are randomly selected in the range [begin, end). n is assumed to be less than or equal to the number of items in the [begin, end) range.

This algorithm can be used to generate the same sample on all processes if n and the specified [begin, end) range are the same on all processes, and the specified sequential random number generator is in the same state on all processes.

Parameters

begin	range start, included in the selection
end	range end, not included in the selection
n	sample size (must be the same on all processes)
gen	random number generator

Returns: indexes sample of size n

Template Parameters

Index_t	(automatically deduced) an abstract index type that support increment. Returned indexes are a sample of indexes selected in `[begin, end)`. Such indexes can for example be used to retrieve items in a local vector to actually build a sample from the selected indexes. `Index_t` could also represent some discrete grid coordinates for example.
Generator_t	(automatically deduced) type of random generator

See also: DistributedIndex

◆ distributed_sample()

template<typename T >

std::vector< std::vector< T > > fpmas::random::distributed_sample	(	api::communication::MpiCommunicator &	comm,
		const std::vector< T > &	local_items,
		std::size_t	n
	)

Randomly selects n items from all local_items specified on all processes, without replacement.

A sample of size n is built independently on each process.

Distinct local_items lists of any size can be specified on each process. n items are returned independently on each process, so different values of n can be specified on each process.

The elements are selected as if the sample was built locally from a list representing the concatenation of all local_items specified on all processes.

This method performs collective communications within the specified MPI communicator. In consequence, the method must be called from all processes.

The complete item list is never centralized, in order to limit communications and memory usage.

Results are returned in an std::vector v of size comm.getSize(), such that v[i] contains items selected from process i.

Tip: A one dimensional vector can be generated from the result with std::vector<T> sample = std::accumulate(v.begin(), v.end(), std::vector<T>(), fpmas::utils::Concat()).

See also: split_sample

Parameters

comm	MPI communicator
local_items	local items provided by the current process
n	local number of items to select from all items (might be different on all processes)

Returns: a sample of size n, selected from all the processes.

◆ split_sample()

template<typename T >

std::vector< T > fpmas::random::split_sample	(	api::communication::MpiCommunicator &	comm,
		const std::vector< T > &	local_items,
		std::size_t	n
	)

Randomly selects n items from all local_items specified on all processes, without replacement.

Contrary to distributed_sample(), a single sample of size n is built across processes. Returned values correspond to the subset of values selected on the current process, so that all returned items are contained in local_items and n items are chosen in total.

In consequence, the specified n must be the same on all processes. If n is greater than the total count of items on all processes, all items are selected, so all items from the local_items list are returned on each process in this context.

This can be useful in the Agent context to build a global agent sample:

AgentGroup group = model.buildGroup(...);
 
...
 
// Selects 10 agents from ALL the processes
std::vector<fpmas::api::model::Agent*> selected_agents
    = fpmas::random::split_sample(group.localAgents(), 10);
 
// We don't now how many agents are selected on this process, but it is
// guaranteed that selected_agents are LOCAL, so this can be used from
// all processes to safely, transparently and globally initialize the
// randomly selected agents.
for(auto agent : selected_agents)
    ((VirusAgent*) agent)->setState(INFECTED);

This method performs collective communications within the specified MPI communicator. In consequence, the method must be called from all processes.

The complete item list is never centralized, in order to limit communications and memory usage.

Parameters

comm	MPI communicator
local_items	local items provided by the current process
n	number of items to select from all items (must be the same on all processes)

Returns: selected local items, so that the concatenation of results from all processes is a valid sample of size n selected from all local_items.

Variable Documentation

◆ rd_choices

DistributedGenerator fpmas::random::rd_choices

A predefined distributed random number generator used by choice and sampling algorithms.

◆ default_seed

const std::mt19937::result_type fpmas::random::default_seed {std::mt19937::default_seed}

The default seed passed to fpmas::seed() when fpmas::init() is called.

◆ seed

fpmas::random::mt19937::result_type fpmas::random::seed {default_seed}

The seed currently in use by FPMAS.

Must be initialized by fpmas::seed(), otherwise default_seed is used.

Classes

Typedefs

Functions

Variables

Detailed Description

Typedef Documentation

◆ UniformIntDistribution

◆ UniformRealDistribution

◆ BernoulliDistribution

◆ BinomialDistribution

◆ NormalDistribution

◆ PoissonDistribution

◆ mt19937

◆ mt19937_64

◆ minstd_rand

◆ random_device

◆ DistributedIndex

Function Documentation

◆ operator<<() [1/2]

◆ operator>>() [1/2]

◆ operator<<() [2/2]

◆ operator>>() [2/2]

◆ local_choices() [1/2]

◆ local_choices() [2/2]

◆ distributed_choices()

◆ split_choices()

◆ local_sample() [1/2]

◆ local_sample() [2/2]

◆ sample_indexes()

◆ distributed_sample()

◆ split_sample()

Variable Documentation

◆ rd_choices

◆ default_seed

◆ seed