StateAgeFunction< FP > Struct Template Reference

CPP API: mio::StateAgeFunction< FP > Struct Template Reference

CPP API

A generic function depending on the state age, i.e. More...

#include <state_age_function.h>

Inheritance diagram for mio::StateAgeFunction< FP >:

Public Member Functions
std::unique_ptr< StateAgeFunction< FP > >	clone () const
	Clones unique pointer to a StateAgeFunction. More...

virtual FP	eval (FP state_age)=0
	Here a pure virtual function is defined that depends on the state_age. More...

FP	get_distribution_parameter () const
	Get the m_distribution_parameter object. More...

FP	get_location () const
	Get the m_location object. More...

virtual FP	get_mean (FP dt=1.0, FP tol=1e-10)
	Computes the mean value of the function using the time step size dt and some tolerance tol. More...

FP	get_scale () const
	Get the m_scale object. More...

std::string	get_state_age_function_type () const
	Get type of StateAgeFunction, i.e.which derived class is used. More...

virtual FP	get_support_max (FP dt, FP tol=1e-10)
	Computes the maximum of the support of the function using the time step size dt and some tolerance tol. More...

StateAgeFunction< FP > &	operator= (const StateAgeFunction< FP > &other)=default
	Copy assignment operator. More...

StateAgeFunction< FP > &	operator= (StateAgeFunction< FP > &&other)=default
	Move assignment operator. More...

bool	operator== (const StateAgeFunction< FP > &other) const
	Comparison operator. More...

void	set_distribution_parameter (FP new_distribution_parameter)
	Set the m_distribution_parameter object. More...

void	set_location (FP new_location)
	Set the m_location object. More...

void	set_scale (FP new_scale)
	Set the m_scale object. More...

	StateAgeFunction (const StateAgeFunction< FP > &other)=default
	Copy constructor. More...

	StateAgeFunction (FP init_distribution_parameter, FP init_location=0, FP init_scale=1)
	Constructs a new StateAgeFunction object. More...

	StateAgeFunction (StateAgeFunction< FP > &&other)=default
	Move constructor. More...

virtual	~StateAgeFunction ()=default
	Virtual destructor. More...

Protected Member Functions
virtual StateAgeFunction< FP > *	clone_impl () const =0
	Pure virtual method that implements cloning. More...

Protected Attributes
FP	m_distribution_parameter
	Parameter for function in derived class. More...

FP	m_location
	Location parameter for function in derived class. More...

FP	m_mean
	Mean value of the function. More...

FP	m_mean_tol {-1.0}
	Tolerance for computation of the mean (initialize as not set). More...

FP	m_scale
	Scale parameter for function in derived class. More...

FP	m_support_max
	Maximum of the support of the function. More...

FP	m_support_tol {-1.0}
	Tolerance for computation of the support (initialize as not set). More...

Detailed Description

template<typename FP>
struct mio::StateAgeFunction< FP >

A generic function depending on the state age, i.e.

the time already spent in some #InfectionState. This is an abstract class and cannot be instantiated on its own.

By construction, StateAgeFunctions S(x) are only defined for non-negative values x>=0 with S(0)>=0. In order to approximate the support (size) of a StateAgeFunction it is thus sufficient to evaluate the function for positive x.

Derived StateAgeFunctions can be used for two types of functionality. a) Monotonously decreasing functions describing the share of individuals that have not yet transitioned to the next #InfectionState. These functions are denoted as #TransitionDistributions since 1 - TransitionDistribution represents a cumulative distribution function. Such functions are also called survival functions. b) Arbitrary non-negative functions used for parameters such as TransmissionProbabilityOnContact.

Derived classes must implement the eval method which implements the actual function that is evaluated at some state age. This function can depend on the parameter 'scale' to scale the function and on the parameter 'location' to shift the function. Location should be a positive number to fulfill the characteristics of a TransitionDistribution and scale has to be positive. For a Function F we normally use these parameters at state age x as F(x,location,scale)=F((x-location)/scale). These two parameters are optional and a derived class does not have to use them. Additionally there is one parameter which specifies the distribution.

The derived classes must also implement the clone_impl method which allows to deepcopy the derived class.

The get_support_max method is virtual and implements a basic version to determine the maximum of the support. For some derived classes there is a more efficient way (see e.g., SmootherCosine) to do this which is why it can be overridden. The base class implementation uses the fact that the StateAgeFunction is monotonously decreasing. This is no limitation as the support is only needed for StateAgeFunctions of Type a) as given above. For classes of type b) a dummy implementation logging an error and returning -2 for get_support_max() should be implemented.

The get_mean method is virtual and implements a basic version to determine the mean value of the StateAgeFunction. The base class implementation uses the fact that the StateAgeFunction is a survival function (i.e. 1-CDF for any cumulative distribution function CDF). Therefore, the base class implementation should only be used for StateAgeFunctions of type a). For some derived classes there is a more efficient way (see e.g., ExponentialSurvivalFunction) to do this which is why it can be overridden.

See ExponentialSurvivalFunction, SmootherCosine and ConstantFunction for examples of derived classes.

Constructor & Destructor Documentation

◆ StateAgeFunction() [1/3]

template<typename FP >

mio::StateAgeFunction< FP >::StateAgeFunction	(	FP	init_distribution_parameter,
		FP	init_location = `0`,
		FP	init_scale = `1`
	)

inline

Constructs a new StateAgeFunction object.

Parameters

[in]	init_distribution_parameter	Specifies the initial distribution parameter of the function.
[in]	init_location	A parameter to shift the function.
[in]	init_scale	A parameter to scale the function. Parameter has to be positive.

◆ ~StateAgeFunction()

template<typename FP >

virtual mio::StateAgeFunction< FP >::~StateAgeFunction ( )

virtualdefault

Virtual destructor.

◆ StateAgeFunction() [2/3]

template<typename FP >

mio::StateAgeFunction< FP >::StateAgeFunction ( const StateAgeFunction< FP > & other )

default

Copy constructor.

◆ StateAgeFunction() [3/3]

template<typename FP >

mio::StateAgeFunction< FP >::StateAgeFunction ( StateAgeFunction< FP > && other )

default

Move constructor.

Member Function Documentation

◆ clone()

template<typename FP >

std::unique_ptr<StateAgeFunction<FP> > mio::StateAgeFunction< FP >::clone ( ) const

inline

Clones unique pointer to a StateAgeFunction.

Calls the clone_impl method that is implemented by every derived class.

Returns: std::unique_ptr<StateAgeFunction> unique pointer to a StateAgeFunction

◆ clone_impl()

template<typename FP >

virtual StateAgeFunction<FP>* mio::StateAgeFunction< FP >::clone_impl ( ) const

protectedpure virtual

Pure virtual method that implements cloning.

Implemented in mio::ErlangDensity, mio::ConstantFunction< FP >, mio::LognormSurvivalFunction, mio::GammaSurvivalFunction, mio::SmootherCosine< FP >, and mio::ExponentialSurvivalFunction< FP >.

◆ eval()

template<typename FP >

virtual FP mio::StateAgeFunction< FP >::eval ( FP state_age )

pure virtual

Here a pure virtual function is defined that depends on the state_age.

The defined function ususally depends on some function parameter.

Parameters

[in] state_age Time at which the function is evaluated.

Implemented in mio::ErlangDensity, mio::LognormSurvivalFunction, mio::GammaSurvivalFunction, mio::ConstantFunction< FP >, mio::SmootherCosine< FP >, and mio::ExponentialSurvivalFunction< FP >.

◆ get_distribution_parameter()

template<typename FP >

FP mio::StateAgeFunction< FP >::get_distribution_parameter ( ) const

inline

Get the m_distribution_parameter object.

Can be used to access the m_distribution_parameter object, which specifies the used function.

Returns: ScalarType

◆ get_location()

template<typename FP >

FP mio::StateAgeFunction< FP >::get_location ( ) const

inline

Get the m_location object.

Can be used to access the m_location object, which specifies the shift of the function.

Returns: ScalarType

◆ get_mean()

template<typename FP >

virtual FP mio::StateAgeFunction< FP >::get_mean	(	FP	dt = `1.0`,
		FP	tol = `1e-10`
	)

inlinevirtual

Computes the mean value of the function using the time step size dt and some tolerance tol.

This is a basic version to determine the mean value of a survival function through numerical integration of the integral that describes the expected value. This basic implementation is only valid if the StateAgeFunction is of type a) since we assume that the considered function converges to zero. Otherwise it should be overridden.

For some specific derivations of StateAgeFunctions there are more efficient ways to determine the mean value which is why this member function is virtual and can be overridden (see, e.g., ExponentialSurvivalFunction). The mean value is only needed for StateAgeFunctions that are used as TransitionDistributions.

Parameters

[in]	dt	Time step size used for the numerical integration.
[in]	tol	The maximum support used for numerical integration is calculated using this tolerance.

Returns: ScalarType mean value.

Reimplemented in mio::ErlangDensity, mio::GammaSurvivalFunction, mio::ConstantFunction< FP >, mio::SmootherCosine< FP >, and mio::ExponentialSurvivalFunction< FP >.

◆ get_scale()

template<typename FP >

FP mio::StateAgeFunction< FP >::get_scale ( ) const

inline

Get the m_scale object.

Can be used to access the m_scale object, which is used to scale the function.

Returns: ScalarType

◆ get_state_age_function_type()

template<typename FP >

std::string mio::StateAgeFunction< FP >::get_state_age_function_type ( ) const

inline

Get type of StateAgeFunction, i.e.which derived class is used.

Parameters

[out] string

◆ get_support_max()

template<typename FP >

virtual FP mio::StateAgeFunction< FP >::get_support_max	(	FP	dt,
		FP	tol = `1e-10`
	)

inlinevirtual

Computes the maximum of the support of the function using the time step size dt and some tolerance tol.

This is a basic version to determine the maximum of the support of a monotonously decreasing function, evaluating the function at each time point until it reaches the boundaries of the support.

For some specific derivations of StateAgeFunctions there are more efficient ways to determine the support which is why this member function is virtual and can be overridden (see, e.g., SmootherCosine). The maximum of the support is only needed for StateAgeFunctions that are used as TransitionDistributions.

Parameters

[in]	dt	Time step size at which function will be evaluated.
[in]	tol	Tolerance used for cutting the support if the function value falls below.

Returns: ScalarType support_max

Reimplemented in mio::ErlangDensity, mio::ConstantFunction< FP >, and mio::SmootherCosine< FP >.

◆ operator=() [1/2]

template<typename FP >

StateAgeFunction<FP>& mio::StateAgeFunction< FP >::operator= ( const StateAgeFunction< FP > & other )

default

Copy assignment operator.

◆ operator=() [2/2]

template<typename FP >

StateAgeFunction<FP>& mio::StateAgeFunction< FP >::operator= ( StateAgeFunction< FP > && other )

default

Move assignment operator.

◆ operator==()

template<typename FP >

bool mio::StateAgeFunction< FP >::operator== ( const StateAgeFunction< FP > & other ) const

inline

Comparison operator.

◆ set_distribution_parameter()

template<typename FP >

void mio::StateAgeFunction< FP >::set_distribution_parameter ( FP new_distribution_parameter )

inline

Set the m_distribution_parameter object.

Can be used to set the m_distribution_parameter object, which specifies the used function. The maximum support of a function may be costly to evaluate. In order to not always reevaluate or recompute the support when the user asks for it, a cached value is used. If m_support_max is set to -1, the cached value is deleted and a recomputation is done the next time the user asks for the support. As the support (potentially) depends on the m_distribution_parameter object, the cached value has to be deleted. For details see get_support_max(). The same applies to the m_mean object. See get_mean().

Parameters

[in] new_distribution_parameter New parameter for StateAgeFunction.

◆ set_location()

template<typename FP >

void mio::StateAgeFunction< FP >::set_location ( FP new_location )

inline

Set the m_location object.

Can be used to set the m_location object, which specifies the shift of the function. The maximum support of a function may be costly to evaluate. In order to not always reevaluate or recompute the support when the user asks for it, a cached value is used. If m_support_max is set to -1, the cached value is deleted and a recomputation is done the next time the user asks for the support. As the support (potentially) depends on the m_location object, the cached value has to be deleted. For details see get_support_max(). The same applies to the m_mean object. See get_mean().

Parameters

[in] new_location New location for StateAgeFunction.

◆ set_scale()

template<typename FP >

void mio::StateAgeFunction< FP >::set_scale ( FP new_scale )

inline

Set the m_scale object.

Can be used to access the m_scale object, which is used to scale the function. The maximum support of a function may be costly to evaluate. In order to not always reevaluate or recompute the support when the user asks for it, a cached value is used. If m_support_max is set to -1, the cached value is deleted and a recomputation is done the next time the user asks for the support. As the support (potentially) depends on the m_scale object, the cached value has to be deleted. For details see get_support_max(). The same applies to the m_mean object. See get_mean().

Parameters

[in] new_scale New Scale for StateAgeFunction.

Member Data Documentation

◆ m_distribution_parameter

template<typename FP >

FP mio::StateAgeFunction< FP >::m_distribution_parameter

protected

Parameter for function in derived class.

◆ m_location

template<typename FP >

FP mio::StateAgeFunction< FP >::m_location

protected

Location parameter for function in derived class.

◆ m_mean

template<typename FP >

FP mio::StateAgeFunction< FP >::m_mean

protected

Mean value of the function.

◆ m_mean_tol

template<typename FP >

FP mio::StateAgeFunction< FP >::m_mean_tol {-1.0}

protected

Tolerance for computation of the mean (initialize as not set).

◆ m_scale

template<typename FP >

FP mio::StateAgeFunction< FP >::m_scale

protected

Scale parameter for function in derived class.

◆ m_support_max

template<typename FP >

FP mio::StateAgeFunction< FP >::m_support_max

protected

Maximum of the support of the function.

◆ m_support_tol

template<typename FP >

FP mio::StateAgeFunction< FP >::m_support_tol {-1.0}

protected

Tolerance for computation of the support (initialize as not set).

StateAgeFunction&lt; FP &gt; Struct Template Reference

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

template<typename FP> struct mio::StateAgeFunction< FP >

Constructor & Destructor Documentation

◆ StateAgeFunction() [1/3]

◆ ~StateAgeFunction()

◆ StateAgeFunction() [2/3]

◆ StateAgeFunction() [3/3]

Member Function Documentation

◆ clone()

◆ clone_impl()

◆ eval()

◆ get_distribution_parameter()

◆ get_location()

◆ get_mean()

◆ get_scale()

◆ get_state_age_function_type()

◆ get_support_max()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ operator==()

◆ set_distribution_parameter()

◆ set_location()

◆ set_scale()

Member Data Documentation

◆ m_distribution_parameter

◆ m_location

◆ m_mean

◆ m_mean_tol

◆ m_scale

◆ m_support_max

◆ m_support_tol

StateAgeFunction< FP > Struct Template Reference

template<typename FP>
struct mio::StateAgeFunction< FP >