nest::RandomManager Class Reference

Manage the kernel's random number generators. More...

#include <random_manager.h>

Inheritance diagram for nest::RandomManager:

Collaboration diagram for nest::RandomManager:

Public Member Functions
	RandomManager ()
	~RandomManager () override
void	initialize (const bool) override
	Register available RNG types, set default RNG type and create RNGs.
void	finalize (const bool) override
	Take down manager after operation.
void	set_status (const Dictionary &) override
	Set the status of the manager.
void	get_status (Dictionary &) override
	Retrieve the status of the manager.
RngPtr	get_rank_synced_rng () const
	Get rank-synchronized random number generator.
RngPtr	get_vp_synced_rng (size_t tid) const
	Get VP-synchronized random number generator.
RngPtr	get_vp_specific_rng (size_t tid) const
	Get VP-specific random number generator.
void	check_rng_synchrony () const
	Confirm that rank- and thread-synchronized RNGs are in sync.
template<typename RNG_TYPE >
void	register_rng_type (const std::string &name)
	Register new random number generator type with manager.
Public Member Functions inherited from nest::ManagerInterface
	ManagerInterface (ManagerInterface const &)=delete
void	operator= (ManagerInterface const &)=delete
	ManagerInterface ()
virtual	~ManagerInterface ()
virtual void	prepare ()
virtual void	cleanup ()

Private Attributes
std::map< std::string, BaseRandomGeneratorFactory * >	rng_types_
	Available RNG types.
std::string	current_rng_type_
	Name of currently used RNG type.
std::uint32_t	base_seed_
	Base seed used when RNGs were last created.
RngPtr	rank_synced_rng_
	Random number generator synchronized across ranks.
std::vector< RngPtr >	vp_synced_rngs_
	Random number generators synchronized across VPs.
std::vector< RngPtr >	vp_specific_rngs_
	Random number generators specific to VPs.

Static Private Attributes
static const std::string	DEFAULT_RNG_TYPE_ = "mt19937_64"
	RNG type used by default.
static const std::uint32_t	DEFAULT_BASE_SEED_ = 143202461
	Base seed used by default.
static const std::uint32_t	RANK_SYNCED_SEEDER_ = 0xc229212d
	Rank-synchronized seed-sequence initializer component.
static const std::uint32_t	THREAD_SYNCED_SEEDER_ = 0x37722d5e
	Thread-synchronized seed-sequence initializer component.
static const std::uint32_t	THREAD_SPECIFIC_SEEDER_ = 0xb84c9bae
	Thread-specific seed-sequence initializer component.

Detailed Description

Manage the kernel's random number generators.

This manager provides one random number generator per thread plus the global RNG. It also handles selection of RNG type and seeding.

Constructor & Destructor Documentation

RandomManager()

nest::RandomManager::RandomManager

(

)

~RandomManager()

nest::RandomManager::~RandomManager ( )

override

Member Function Documentation

check_rng_synchrony()

void nest::RandomManager::check_rng_synchrony

(

)

const

Confirm that rank- and thread-synchronized RNGs are in sync.

Exceptions

KernelException

if RNGs are out of sync.

References nest::BaseRandomGenerator::drand(), nest::VPManager::get_num_threads(), nest::kernel(), rank_synced_rng_, nest::KernelManager::vp_manager, and vp_synced_rngs_.

Referenced by nest::SimulationManager::run().

Here is the call graph for this function:

Here is the caller graph for this function:

finalize()

void nest::RandomManager::finalize ( const bool  adjust_number_of_threads_or_rng_only )

overridevirtual

Take down manager after operation.

After this method has completed, all dynamic data structures created by the manager shall be deallocated and containers emptied. Plain variables need not be reset.

Note

Finalization of any given manager may depend on other managers not having been finalized yet. KernelManager::finalize() is responsible for calling the initialization routines on the specific managers in correct order, i.e., the opposite order of initialize() calls.

Parameters

adjust_number_of_threads_or_rng_only

Pass true if calling from kernel_manager::change_number_of_threads() to limit operations to those necessary for thread adjustment.

See also

initialize()

Implements nest::ManagerInterface.

References rank_synced_rng_, rng_types_, vp_specific_rngs_, and vp_synced_rngs_.

Referenced by set_status().

Here is the caller graph for this function:

get_rank_synced_rng()

RngPtr nest::RandomManager::get_rank_synced_rng ( ) const

inline

Get rank-synchronized random number generator.

The rank-synchronized generator provides identical random number sequences on all MPI ranks. It may be used only by the master thread on each rank and must be used in lock-step across all ranks. Synchronization is checked by MPI exchange at certain points during a simulation.

References rank_synced_rng_.

Referenced by nest::get_rank_synced_rng().

Here is the caller graph for this function:

get_status()

void nest::RandomManager::get_status ( Dictionary &  )

overridevirtual

Retrieve the status of the manager.

Note

This would ideally be a const function. However, some managers delay the update of internal variables up to the point where they are needed (e.g., before reporting their values to the user, or before simulate is called). An example for this pattern is the call to update_delay_extrema_() right at the beginning of ConnectionManager::get_status().

See also

set_status()

Implements nest::ManagerInterface.

References base_seed_, current_rng_type_, nest::names::rng_seed(), nest::names::rng_type(), nest::names::rng_types(), and rng_types_.

Here is the call graph for this function:

get_vp_specific_rng()

RngPtr nest::RandomManager::get_vp_specific_rng ( size_t  tid ) const

inline

Get VP-specific random number generator.

Each VP (thread) can use this RNG freely and will receive an independent random number sequence.

References vp_specific_rngs_.

Referenced by nest::ThirdInBuilder::connect_(), and nest::get_vp_specific_rng().

Here is the caller graph for this function:

get_vp_synced_rng()

RngPtr nest::RandomManager::get_vp_synced_rng ( size_t  tid ) const

inline

Get VP-synchronized random number generator.

The kernel maintains one instance of a synchronized random number generator for each thread (and thus, across ranks, for each VP). The purpose of these synchronized generators is to provide identical random number sequences on each VP while VPs execute in parallel. All VPs (ie all threads on all ranks) must use the generators in lock-step to maintain synchrony. Synchronization is checked by MPI exchange at certain points during a simulation.

Parameters

tid	ID of thread requesting generator

References vp_specific_rngs_, and vp_synced_rngs_.

Referenced by nest::get_vp_synced_rng().

Here is the caller graph for this function:

initialize()

void nest::RandomManager::initialize ( const bool  adjust_number_of_threads_or_rng_only )

overridevirtual

Register available RNG types, set default RNG type and create RNGs.

Implements nest::ManagerInterface.

References base_seed_, current_rng_type_, DEFAULT_BASE_SEED_, DEFAULT_RNG_TYPE_, nest::VPManager::get_num_threads(), nest::VPManager::get_thread_id(), nest::VPManager::get_vp(), nest::kernel(), rank_synced_rng_, RANK_SYNCED_SEEDER_, rng_types_, THREAD_SPECIFIC_SEEDER_, THREAD_SYNCED_SEEDER_, nest::KernelManager::vp_manager, vp_specific_rngs_, and vp_synced_rngs_.

Referenced by set_status().

Here is the call graph for this function:

Here is the caller graph for this function:

register_rng_type()

template<typename RNG_TYPE >

void nest::RandomManager::register_rng_type

(

const std::string &

name

)

Register new random number generator type with manager.

This allows NEST modules to add new RNG types.

Parameters

RNG_TYPE

Class fulfilling requirements of C++ RNG.

References rng_types_.

set_status()

void nest::RandomManager::set_status ( const Dictionary &  )

overridevirtual

Set the status of the manager.

See also

get_status()

Implements nest::ManagerInterface.

References base_seed_, current_rng_type_, finalize(), initialize(), nest::names::rng_seed(), nest::names::rng_type(), and rng_types_.

Here is the call graph for this function:

Member Data Documentation

base_seed_

std::uint32_t nest::RandomManager::base_seed_

private

Base seed used when RNGs were last created.

Referenced by get_status(), initialize(), and set_status().

current_rng_type_

std::string nest::RandomManager::current_rng_type_

private

Name of currently used RNG type.

Referenced by get_status(), initialize(), and set_status().

DEFAULT_BASE_SEED_

const std::uint32_t nest::RandomManager::DEFAULT_BASE_SEED_ = 143202461

staticprivate

Base seed used by default.

Referenced by initialize().

DEFAULT_RNG_TYPE_

const std::string nest::RandomManager::DEFAULT_RNG_TYPE_ = "mt19937_64"

staticprivate

RNG type used by default.

Referenced by initialize().

rank_synced_rng_

RngPtr nest::RandomManager::rank_synced_rng_

private

Random number generator synchronized across ranks.

Referenced by check_rng_synchrony(), finalize(), get_rank_synced_rng(), and initialize().

RANK_SYNCED_SEEDER_

const std::uint32_t nest::RandomManager::RANK_SYNCED_SEEDER_ = 0xc229212d

staticprivate

Rank-synchronized seed-sequence initializer component.

Referenced by initialize().

rng_types_

std::map< std::string, BaseRandomGeneratorFactory* > nest::RandomManager::rng_types_

private

Available RNG types.

Referenced by finalize(), get_status(), initialize(), register_rng_type(), and set_status().

THREAD_SPECIFIC_SEEDER_

const std::uint32_t nest::RandomManager::THREAD_SPECIFIC_SEEDER_ = 0xb84c9bae

staticprivate

Thread-specific seed-sequence initializer component.

Referenced by initialize().

THREAD_SYNCED_SEEDER_

const std::uint32_t nest::RandomManager::THREAD_SYNCED_SEEDER_ = 0x37722d5e

staticprivate

Thread-synchronized seed-sequence initializer component.

Referenced by initialize().

vp_specific_rngs_

std::vector< RngPtr > nest::RandomManager::vp_specific_rngs_

private

Random number generators specific to VPs.

Referenced by finalize(), get_vp_specific_rng(), get_vp_synced_rng(), and initialize().

vp_synced_rngs_

std::vector< RngPtr > nest::RandomManager::vp_synced_rngs_

private

Random number generators synchronized across VPs.

Referenced by check_rng_synchrony(), finalize(), get_vp_synced_rng(), and initialize().

---

The documentation for this class was generated from the following files:

• random_manager.h
• random_manager.cpp