Class for running Kinetic Monte-Carlo simulations. More...

#include <CD_KMCSolver.H>

Public Types
using	ReactionList = std::vector< std::shared_ptr< const R > >

Public Member Functions
	KMCSolver () noexcept
	Default constructor – must subsequently define the object.

	KMCSolver (const KMCSolver &)=default
	Disallowed copy constructor.

	KMCSolver (const KMCSolver &&)=delete
	Disallowed move constructor.

	KMCSolver (const ReactionList &a_reactions) noexcept
	Full constructor. More...

virtual	~KMCSolver () noexcept
	Destructor.

KMCSolver &	operator= (const KMCSolver &)=default
	Copy assignment operator.

KMCSolver &	operator= (const KMCSolver &&)=delete
	Disallowed move assignment operator.

void	define (const ReactionList &a_reactions) noexcept
	Define function. Sets the reactions. More...

void	setSolverParameters (const T a_numCrit, const T a_numSSA, const Real a_eps, const Real a_SSAlim) noexcept
	Set solver parameters. More...

std::vector< Real >	propensities (const State &a_state) const noexcept
	Compute propensities for ALL reactions. More...

std::vector< Real >	propensities (const State &a_state, const ReactionList &a_reactions) const noexcept
	Compute propensities for a subset of reactions. More...

Real	totalPropensity (const State &a_state) const noexcept
	Compute the total propensity for ALL reactions. More...

Real	totalPropensity (const State &a_state, const ReactionList &a_reactions) const noexcept
	Compute the total propensity for a subset of reactions. More...

std::pair< ReactionList, ReactionList >	partitionReactions (const State &a_state) const noexcept
	Partition reactions into critical and non-critical reactions. More...

std::pair< ReactionList, ReactionList >	partitionReactions (const State &a_state, const ReactionList &a_reactions) const noexcept
	Partition reactions into critical and non-critical reactions. More...

Real	getCriticalTimeStep (const State &a_state) const noexcept
	Get the time to the next critical reaction. More...

Real	getCriticalTimeStep (const State &a_state, const ReactionList &a_criticalReactions) const noexcept
	Get the time to the next critical reaction. More...

Real	getCriticalTimeStep (const std::vector< Real > &a_propensities) const noexcept
	Get the time to the next critical reaction. More...

Real	getCriticalTimeStep (const Real &a_totalPropensity) const noexcept
	Get the time to the next critical reaction. More...

Real	getNonCriticalTimeStep (const State &a_state) const noexcept
	Get the non-critical time step. More...

Real	getNonCriticalTimeStep (const State &a_state, const ReactionList &a_reactions) const noexcept
	Get the non-critical time step. More...

Real	getNonCriticalTimeStep (const State &a_state, const ReactionList &a_nonCriticalReactions, const std::vector< Real > &a_nonCriticalPropensities) const noexcept
	Get the non-critical time step. More...

void	stepTauPlain (State &a_state, const Real a_dt) const noexcept
	Perform one plain tau-leaping step using ALL reactions. More...

void	stepTauPlain (State &a_state, const ReactionList &a_reactions, const Real a_dt) const noexcept
	Perform one plain tau-leaping step over the input reactions using a time step a_dt. More...

void	stepTauPlain (State &a_state, const ReactionList &a_reactions, const std::vector< Real > &a_propensities, const Real a_dt) const noexcept
	Perform one plain tau-leaping step over the input reactions using a time step a_dt. More...

void	advanceTauPlain (State &a_state, const Real a_dt) const noexcept
	Advance with plain tau-leaping step over the input time. This can end up using substepping. More...

void	advanceTauPlain (State &a_state, const ReactionList &a_reactions, const Real a_dt) const noexcept
	Advance with plain tau-leaping step over the input time. This can end up using substepping. More...

void	stepTauMidpoint (State &a_state, const Real a_dt) const noexcept
	Perform one leaping step using the midpoint method for ALL reactions over a time step a_dt. More...

void	stepTauMidpoint (State &a_state, const ReactionList &a_reactions, const Real a_dt) const noexcept
	Perform one leaping step using the midpoint method for the input reactions over a time step a_dt. More...

void	advanceTauMidpoint (State &a_state, const Real a_dt) const noexcept
	Perform one leaping step using the midpoint method all reactions over a time step a_dt. More...

void	advanceTauMidpoint (State &a_state, const ReactionList &a_reactions, const Real a_dt) const noexcept
	Perform one leaping step using the midpoint method for the input reactions over a time step a_dt. More...

void	stepSSA (State &a_state) const noexcept
	Perform a single SSA step. More...

void	stepSSA (State &a_state, const ReactionList &a_reactions) const noexcept
	Perform a single SSA step. More...

void	stepSSA (State &a_state, const ReactionList &a_reactions, const std::vector< Real > &a_propensities) const noexcept
	Perform a single SSA step. This version has pre-computed propensities (for optimization reasons) More...

void	advanceSSA (State &a_state, const Real a_dt) const noexcept
	Advance with the SSA over the input time. This can end up using substepping. More...

void	advanceSSA (State &a_state, const ReactionList &a_reactions, const Real a_dt) const noexcept
	Advance with the SSA over the input time. This can end up using substepping. More...

void	advanceHybrid (State &a_state, const Real a_dt, const KMCLeapPropagator &a_leapPropagator=KMCLeapPropagator::TauPlain) const noexcept
	Advance using Cao et. al. hybrid algorithm over the input time. This can end up using substepping. More...

void	advanceHybrid (State &a_state, const ReactionList &a_reactions, const Real a_dt, const KMCLeapPropagator &a_leapPropagator=KMCLeapPropagator::TauPlain) const noexcept
	Advance using Cao et. al. hybrid algorithm over the input time. This can end up using substepping. More...

void	advanceHybrid (State &a_state, const ReactionList &a_reactions, const Real a_dt, const std::function< void(State &, const ReactionList &a_reactions, const Real a_dt)> &a_propagator) const noexcept
	Advance using Cao et. al. hybrid algorithm over the input time. This can end up using substepping. More...

Protected Attributes
ReactionList	m_reactions
	List of reactions used when advancing states.

T	m_Ncrit
	Definition of critical reactions. More...

T	m_numSSA
	Maximum number of SSA steps to run when switching into SSA-based advancement for non-critical reactions.

Real	m_eps
	Maximum permitted change in propensities for non-critical reactions.

Real	m_SSAlim
	Threshold for switching to SSA-based algorithm within the Cao algorithm.

Detailed Description

template<typename R, typename State, typename T = long long>
class KMCSolver< R, State, T >

Class for running Kinetic Monte-Carlo simulations.

The template parameter State is the underlying state type that KMC operators on. There are no required member functions on the State parameter, but the reaction type (template parameter R) MUST be able to operate on the state through the following functions:

Real R::propensity(State) const -> Computes the reaction propensity for the input state.
T R::computeCriticalNumberOfReactions(State) const -> Computes the minimum number of reactions that exhausts one of the reactants.
void R::advanceState(State&, const T numReactions) const -> Advance state by numReactions
std::<some_container> getReactants() const -> Get reactants involved in the reactions.
T R::population(const <some_type> reactant, const State& a_state) -> Get the population of the input reactant in the input state.

The template parameter T should agree across both both R, State, and KMCSolver.

Constructor & Destructor Documentation

◆ KMCSolver()

template<typename R , typename State , typename T >

KMCSolver< R, State, T >::KMCSolver ( const ReactionList & a_reactions )

inlinenoexcept

Full constructor.

Parameters

[in] a_reactions List of reactions.

Member Function Documentation

◆ advanceHybrid() [1/3]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::advanceHybrid	(	State &	a_state,
		const ReactionList &	a_reactions,
		const Real	a_dt,
		const KMCLeapPropagator &	a_leapPropagator = `KMCLeapPropagator::TauPlain`
	)		const

inlinenoexcept

Advance using Cao et. al. hybrid algorithm over the input time. This can end up using substepping.

Parameters

[in,out]	a_state	State vector to advance.
[in]	a_reactions	Reactions to advance.
[in]	a_dt	Time increment.
[in]	a_leapPropagator	Which leap propagator to use.

Note: Calls the other version with stepTau as the leap propagator.

◆ advanceHybrid() [2/3]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::advanceHybrid	(	State &	a_state,
		const ReactionList &	a_reactions,
		const Real	a_dt,
		const std::function< void(State &, const ReactionList &a_reactions, const Real a_dt)> &	a_propagator
	)		const

inlinenoexcept

Advance using Cao et. al. hybrid algorithm over the input time. This can end up using substepping.

Parameters

[in,out]	a_state	State vector to advance
[in]	a_reactions	Reactions to advance with
[in]	a_dt	Time increment
[in]	a_leapPropagator	Leaping propagator

◆ advanceHybrid() [3/3]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::advanceHybrid	(	State &	a_state,
		const Real	a_dt,
		const KMCLeapPropagator &	a_leapPropagator = `KMCLeapPropagator::TauPlain`
	)		const

inlinenoexcept

Advance using Cao et. al. hybrid algorithm over the input time. This can end up using substepping.

Parameters

[in,out]	a_state	State vector to advance
[in]	a_dt	Time increment
[in]	a_leapPropagator	Which leap propagator to use.

Note: Calls the other version with m_reactions

◆ advanceSSA() [1/2]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::advanceSSA	(	State &	a_state,
		const ReactionList &	a_reactions,
		const Real	a_dt
	)		const

inlinenoexcept

Advance with the SSA over the input time. This can end up using substepping.

Parameters

[in,out]	a_state	State vector to advance
[in]	a_reactions	Reactions to advance with
[in]	a_dt	Time increment

◆ advanceSSA() [2/2]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::advanceSSA	(	State &	a_state,
		const Real	a_dt
	)		const

inlinenoexcept

Advance with the SSA over the input time. This can end up using substepping.

Parameters

[in,out]	a_state	State vector to advance
[in]	a_dt	Time increment

Note: Calls the other version with m_reactions

◆ advanceTauMidpoint() [1/2]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::advanceTauMidpoint	(	State &	a_state,
		const ReactionList &	a_reactions,
		const Real	a_dt
	)		const

inlinenoexcept

Perform one leaping step using the midpoint method for the input reactions over a time step a_dt.

Parameters

[in,out]	a_state	State vector to be advanced
[in]	a_reactions	List of reactions to advance with
[in]	a_dt	Time increment

◆ advanceTauMidpoint() [2/2]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::advanceTauMidpoint	(	State &	a_state,
		const Real	a_dt
	)		const

inlinenoexcept

Perform one leaping step using the midpoint method all reactions over a time step a_dt.

Parameters

[in,out]	a_state	State vector to be advanced
[in]	a_dt	Time increment

Note: Calls the other version with m_reactions.

◆ advanceTauPlain() [1/2]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::advanceTauPlain	(	State &	a_state,
		const ReactionList &	a_reactions,
		const Real	a_dt
	)		const

inlinenoexcept

Advance with plain tau-leaping step over the input time. This can end up using substepping.

Parameters

[in,out]	a_state	State vector to be advanced
[in]	a_reactions	List of reactions to advance with
[in]	a_dt	Time increment

◆ advanceTauPlain() [2/2]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::advanceTauPlain	(	State &	a_state,
		const Real	a_dt
	)		const

inlinenoexcept

Advance with plain tau-leaping step over the input time. This can end up using substepping.

Parameters

[in,out]	a_state	State vector to be advanced
[in]	a_dt	Time increment

Note: Calls the other version with m_reactions.

◆ define()

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::define ( const ReactionList & a_reactions )

inlinenoexcept

Define function. Sets the reactions.

Parameters

[in] a_reactions List of reactions.

◆ getCriticalTimeStep() [1/4]

template<typename R , typename State , typename T >

Real KMCSolver< R, State, T >::getCriticalTimeStep ( const Real & a_totalPropensity ) const

inlinenoexcept

Get the time to the next critical reaction.

Parameters

[in] a_totalPropensity Total propensity

◆ getCriticalTimeStep() [2/4]

template<typename R , typename State , typename T >

Real KMCSolver< R, State, T >::getCriticalTimeStep ( const State & a_state ) const

inlinenoexcept

Get the time to the next critical reaction.

Parameters

[in] a_state State vector

Note: Calls the other version with m_reactions

◆ getCriticalTimeStep() [3/4]

template<typename R , typename State , typename T >

Real KMCSolver< R, State, T >::getCriticalTimeStep	(	const State &	a_state,
		const ReactionList &	a_criticalReactions
	)		const

inlinenoexcept

Get the time to the next critical reaction.

Parameters

[in]	a_state	State vector
[in]	a_criticalReactions	Reaction list.

Note: Computes the total propensity and calls the other version.

◆ getCriticalTimeStep() [4/4]

template<typename R , typename State , typename T >

Real KMCSolver< R, State, T >::getCriticalTimeStep ( const std::vector< Real > & a_propensities ) const

inlinenoexcept

Get the time to the next critical reaction.

Parameters

[in] a_propensities Reaction propensities

◆ getNonCriticalTimeStep() [1/3]

template<typename R , typename State , typename T >

Real KMCSolver< R, State, T >::getNonCriticalTimeStep ( const State & a_state ) const

inlinenoexcept

Get the non-critical time step.

Parameters

[in] a_state State vector

Note: Calls the other version with m_reactions

◆ getNonCriticalTimeStep() [2/3]

template<typename R , typename State , typename T >

Real KMCSolver< R, State, T >::getNonCriticalTimeStep	(	const State &	a_state,
		const ReactionList &	a_nonCriticalReactions,
		const std::vector< Real > &	a_nonCriticalPropensities
	)		const

inlinenoexcept

Get the non-critical time step.

Parameters

[in]	a_state	State vector
[in]	a_nonCriticalReactions	Non-critical reactions
[in]	a_nonCriticalPropensities	Non-critical propensities

◆ getNonCriticalTimeStep() [3/3]

template<typename R , typename State , typename T >

Real KMCSolver< R, State, T >::getNonCriticalTimeStep	(	const State &	a_state,
		const ReactionList &	a_reactions
	)		const

inlinenoexcept

Get the non-critical time step.

Parameters

[in]	a_state	State vector
[in]	a_reactions	Reaction list

Note: Computes propensities and calls the other version.

◆ partitionReactions() [1/2]

template<typename R , typename State , typename T >

std::pair< typename KMCSolver< R, State, T >::ReactionList, typename KMCSolver< R, State, T >::ReactionList > KMCSolver< R, State, T >::partitionReactions ( const State & a_state ) const

inlinenoexcept

Partition reactions into critical and non-critical reactions.

First member in the pair is the critical reactions, then the non-critical reactions.

Parameters

[in] a_state State vector

Note: Calls the other version with m_reactions

◆ partitionReactions() [2/2]

template<typename R , typename State , typename T >

std::pair< typename KMCSolver< R, State, T >::ReactionList, typename KMCSolver< R, State, T >::ReactionList > KMCSolver< R, State, T >::partitionReactions	(	const State &	a_state,
		const ReactionList &	a_reactions
	)		const

inlinenoexcept

Partition reactions into critical and non-critical reactions.

First member in the pair is the critical reactions, then the non-critical reactions

Parameters

[in]	a_state	State vector
[in]	a_reactions	Reaction list to be partitioned

◆ propensities() [1/2]

template<typename R , typename State , typename T >

std::vector< Real > KMCSolver< R, State, T >::propensities ( const State & a_state ) const

inlinenoexcept

Compute propensities for ALL reactions.

Parameters

[in] a_state State vector

Note: Calls the other version with m_reactions.

◆ propensities() [2/2]

template<typename R , typename State , typename T >

std::vector< Real > KMCSolver< R, State, T >::propensities	(	const State &	a_state,
		const ReactionList &	a_reactions
	)		const

inlinenoexcept

Compute propensities for a subset of reactions.

Parameters

[in]	a_state	State vector
[in]	a_reactions	Reaction list

◆ setSolverParameters()

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::setSolverParameters	(	const T	a_numCrit,
		const T	a_numSSA,
		const Real	a_eps,
		const Real	a_SSAlim
	)

inlinenoexcept

Set solver parameters.

Parameters

[in]	a_numCrit	Determines critical reactions. This is the number of reactions that need to fire before depleting a reactant.
[in]	a_numSSA	Maximum number of SSA steps to run when switching from tau-leaping to SSA (hybrid algorithm only).
[in]	a_eps	Maximum permitted change in propensities when performing tau-leaping for non-critical reactions.
[in]	a_SSAlim	Threshold for switching from tau-leaping of non-critical reactions to SSA for all reactions (hybrid algorithm only)

◆ stepSSA() [1/3]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::stepSSA ( State & a_state ) const

inlinenoexcept

Perform a single SSA step.

Parameters

[in,out] a_state State vector to advance

Note: Calls the other version with m_reactions

◆ stepSSA() [2/3]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::stepSSA	(	State &	a_state,
		const ReactionList &	a_reactions
	)		const

inlinenoexcept

Perform a single SSA step.

Parameters

[in,out]	a_state	State vector to advance
[in]	a_reactions	Reactions to advance with

Note: Computes propensities and calls the other version

◆ stepSSA() [3/3]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::stepSSA	(	State &	a_state,
		const ReactionList &	a_reactions,
		const std::vector< Real > &	a_propensities
	)		const

inlinenoexcept

Perform a single SSA step. This version has pre-computed propensities (for optimization reasons)

Parameters

[in,out]	a_state	State vector to advance
[in]	a_reactions	Reactions to advance with
[in]	a_propensities	Propensities for the reactions

◆ stepTauMidpoint() [1/2]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::stepTauMidpoint	(	State &	a_state,
		const ReactionList &	a_reactions,
		const Real	a_dt
	)		const

inlinenoexcept

Perform one leaping step using the midpoint method for the input reactions over a time step a_dt.

Parameters

[in,out]	a_state	State vector to be advanced
[in]	a_reactions	List of reactions to advance with
[in]	a_dt	Time increment

◆ stepTauMidpoint() [2/2]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::stepTauMidpoint	(	State &	a_state,
		const Real	a_dt
	)		const

inlinenoexcept

Perform one leaping step using the midpoint method for ALL reactions over a time step a_dt.

Parameters

[in,out]	a_state	State vector to be advanced
[in]	a_dt	Time increment

Note: Calls the other version with m_reactions

◆ stepTauPlain() [1/3]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::stepTauPlain	(	State &	a_state,
		const ReactionList &	a_reactions,
		const Real	a_dt
	)		const

inlinenoexcept

Perform one plain tau-leaping step over the input reactions using a time step a_dt.

Parameters

[in,out]	a_state	State vector to be advanced
[in]	a_reactions	List of reactions to advance with
[in]	a_dt	Time increment

Note: Computes propensities and calls the other version.

◆ stepTauPlain() [2/3]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::stepTauPlain	(	State &	a_state,
		const ReactionList &	a_reactions,
		const std::vector< Real > &	a_propensities,
		const Real	a_dt
	)		const

inlinenoexcept

Perform one plain tau-leaping step over the input reactions using a time step a_dt.

Parameters

[in,out]	a_state	State vector to be advanced
[in]	a_reactions	List of reactions to advance with
[in]	a_propensities	Pre-computed propensities for the input reactions
[in]	a_dt	Time increment

◆ stepTauPlain() [3/3]

template<typename R , typename State , typename T >

void KMCSolver< R, State, T >::stepTauPlain	(	State &	a_state,
		const Real	a_dt
	)		const

inlinenoexcept

Perform one plain tau-leaping step using ALL reactions.

Parameters

[in,out]	a_state	State vector to be advanced
[in]	a_dt	Time increment

Note: Calls the other version with m_reactions

◆ totalPropensity() [1/2]

template<typename R , typename State , typename T >

Real KMCSolver< R, State, T >::totalPropensity ( const State & a_state ) const

inlinenoexcept

Compute the total propensity for ALL reactions.

Parameters

[in] a_state State vector

Note: Calls the other version with m_reactions.

◆ totalPropensity() [2/2]

template<typename R , typename State , typename T >

Real KMCSolver< R, State, T >::totalPropensity	(	const State &	a_state,
		const ReactionList &	a_reactions
	)		const

inlinenoexcept

Compute the total propensity for a subset of reactions.

Parameters

[in]	a_state	State vector
[in]	a_reactions	Reaction list

Member Data Documentation

◆ m_Ncrit

template<typename R , typename State , typename T = long long>

T KMCSolver< R, State, T >::m_Ncrit

protected

Definition of critical reactions.

A reaction is critical if it is m_Ncrit firings away from depleting a reactant.

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

Source/KineticMonteCarlo/CD_KMCSolver.H
Source/KineticMonteCarlo/CD_KMCSolverImplem.H

Public Types

Public Member Functions

Protected Attributes

Detailed Description

template<typename R, typename State, typename T = long long> class KMCSolver< R, State, T >

Constructor & Destructor Documentation

◆ KMCSolver()

Member Function Documentation

◆ advanceHybrid() [1/3]

◆ advanceHybrid() [2/3]

◆ advanceHybrid() [3/3]

◆ advanceSSA() [1/2]

◆ advanceSSA() [2/2]

◆ advanceTauMidpoint() [1/2]

◆ advanceTauMidpoint() [2/2]

◆ advanceTauPlain() [1/2]

◆ advanceTauPlain() [2/2]

◆ define()

◆ getCriticalTimeStep() [1/4]

◆ getCriticalTimeStep() [2/4]

◆ getCriticalTimeStep() [3/4]

◆ getCriticalTimeStep() [4/4]

◆ getNonCriticalTimeStep() [1/3]

◆ getNonCriticalTimeStep() [2/3]

◆ getNonCriticalTimeStep() [3/3]

◆ partitionReactions() [1/2]

◆ partitionReactions() [2/2]

◆ propensities() [1/2]

◆ propensities() [2/2]

◆ setSolverParameters()

◆ stepSSA() [1/3]

◆ stepSSA() [2/3]

◆ stepSSA() [3/3]

◆ stepTauMidpoint() [1/2]

◆ stepTauMidpoint() [2/2]

◆ stepTauPlain() [1/3]

◆ stepTauPlain() [2/3]

◆ stepTauPlain() [3/3]

◆ totalPropensity() [1/2]

◆ totalPropensity() [2/2]

Member Data Documentation

◆ m_Ncrit

template<typename R, typename State, typename T = long long>
class KMCSolver< R, State, T >