TimeSteppers::History< Vars > Class Template Reference

The past-time data used by TimeStepper classes to update the evolved variables. More...

#include <History.hpp>

Classes
struct	NoValue
	Type and value used to indicate that a record is to be created without the value field set. More...

Public Types
using	DerivVars = db::prefix_variables<::Tags::dt, Vars >
using	UntypedVars = math_wrapper_type< Vars >
	The wrapped type presented by the type-erased history. One of the types in MATH_WRAPPER_TYPES.
Public Types inherited from stl_boilerplate::RandomAccessSequence< History< Vars >, StepRecord< Vars >, false >
using	value_type = StepRecord< Vars >
using	reference = value_type &
using	const_reference = const value_type &
using	pointer = StepRecord< Vars > *
using	const_pointer = const StepRecord< Vars > *
using	reverse_iterator = std::reverse_iterator< iterator >
using	const_reverse_iterator = std::reverse_iterator< const_iterator >
using	difference_type = typename std::iterator_traits< const_iterator >::difference_type
using	size_type = size_t

Public Member Functions
	History (const size_t integration_order)
	History (const History &other)
	History (History &&)=default
History &	operator= (const History &other)
History &	operator= (History &&)=default
ConstUntypedAccess	untyped () const
	Immutable, type-erased access to the history. This method returns a class derived from ConstUntypedHistory<UntypedVars>. Any modifications to the History class invalidate the object returned by this function.
MutableUntypedAccess	untyped ()
	Mutable, type-erased access to the history. This method returns a class derived from MutableUntypedHistory<UntypedVars>. Any modifications to the History class invalidate the object returned by this function, except for modifications performed through the object itself.
size_t	size () const
	The number of stored step (not substep) entries.
const Vars &	latest_value () const
	Get the value at the latest step or substep in the history, even if the value in that record has been discarded. This is not available if undo_latest has been called since the last insertion. More...
const StepRecord< Vars > &	complete_step_start () const
	Get the record for the start of the latest complete step. This is the step with substeps stored if there is one, and otherwise the most recent step.
bool	at_step_start () const
	Check whether we are at the start of a step, i.e, the most recent entry in the history is not a substep.
void	discard_value (const TimeStepId &id_to_discard)
	Clear the value in the indicated record. It is an error if there is no record with the passed TimeStepId. Any memory allocations will be cached for future reuse.
void	pop_front ()
	Drop the oldest step (not substep) entry in the history. Any memory allocations will be cached for future reuse.
void	undo_latest ()
	Drop the newest step or substep entry in the history. Any memory allocations will be cached for future reuse.
void	clear_substeps ()
	Remove all substep entries from the history. Any memory allocations will be cached for future reuse.
void	clear ()
	Remove all (step and substep) entries from the history. Any memory allocations will be cached for future reuse.
void	shrink_to_fit ()
	Release any cached memory allocations.
template<typename F >
void	map_entries (F &&func)
	Apply func to make_not_null(&e) for e every derivative and valid *value in records held by the history.
void	pup (PUP::er &p)
std::ostream &	print (std::ostream &os) const
size_t	integration_order () const
	Get or set the order the time stepper is running at. Many time steppers expect this to have a particular value. This has no effect on the storage of past data.
void	integration_order (const size_t new_integration_order)
	Get or set the order the time stepper is running at. Many time steppers expect this to have a particular value. This has no effect on the storage of past data.
void	insert (const TimeStepId &time_step_id, const Vars &value, const DerivVars &derivative)
	Insert a new entry into the history. It will be inserted as a step or substep as appropriate. More...
void	insert (const TimeStepId &time_step_id, NoValue, const DerivVars &derivative)
	Insert a new entry into the history. It will be inserted as a step or substep as appropriate. More...
template<typename ValueFunc , typename DerivativeFunc >
void	insert_in_place (const TimeStepId &time_step_id, ValueFunc &&value_inserter, DerivativeFunc &&derivative_inserter)
	Insert a new entry in the history by modifying the fields of the record directly, instead of passing a value to copy. More...
template<typename DerivativeFunc >
void	insert_in_place (const TimeStepId &time_step_id, NoValue, DerivativeFunc &&derivative_inserter)
	Insert a new entry in the history by modifying the fields of the record directly, instead of passing a value to copy. More...
void	insert_initial (TimeStepId time_step_id, Vars value, DerivVars derivative)
	Insert data at the start of the history, similar to push_front on some STL containers. This can be useful when initializing a multistep integrator. More...
void	insert_initial (TimeStepId time_step_id, NoValue, DerivVars derivative)
	Insert data at the start of the history, similar to push_front on some STL containers. This can be useful when initializing a multistep integrator. More...
const StepRecord< Vars > &	operator[] (const size_t index) const
	Access the StepRecord for a step (not substep).
StepRecord< Vars > &	operator[] (const size_t index)
	Access the StepRecord for a step (not substep).
const StepRecord< Vars > &	operator[] (const TimeStepId &id) const
	Access the StepRecord for a step or substep with a given TimeStepId. It is an error if there is no entry with that id.
StepRecord< Vars > &	operator[] (const TimeStepId &id)
	Access the StepRecord for a step or substep with a given TimeStepId. It is an error if there is no entry with that id.
ConstSubsteps	substeps () const
	Container view of the StepRecords for the history substeps. These methods return classes providing an STL-like container interface to the substep data. These containers are zero-indexed, so substeps()[0] will have a substep value of 1. More...
MutableSubsteps	substeps ()
	Container view of the StepRecords for the history substeps. These methods return classes providing an STL-like container interface to the substep data. These containers are zero-indexed, so substeps()[0] will have a substep value of 1. More...
Public Member Functions inherited from stl_boilerplate::RandomAccessSequence< History< Vars >, StepRecord< Vars >, false >
iterator	begin () &
const_iterator	begin () const &
const_iterator	cbegin () const &
iterator	end () &
const_iterator	end () const &
const_iterator	cend () const &
reverse_iterator	rbegin () &
const_reverse_iterator	rbegin () const &
const_reverse_iterator	crbegin () const &
reverse_iterator	rend () &
const_reverse_iterator	rend () const &
const_reverse_iterator	crend () const &
size_type	max_size () const
bool	empty () const
reference	front ()
const_reference	front () const
reference	back ()
const_reference	back () const
reference	at (const size_type n)
const_reference	at (const size_type n) const
void	begin () &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	begin () const &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	cbegin () &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	cbegin () const &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	end () &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	end () const &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	cend () &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	cend () const &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	rbegin () &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	rbegin () const &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	crbegin () &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	crbegin () const &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	rend () &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	rend () const &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	crend () &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.
void	crend () const &&=delete
	Not part of the standard, but any attempt to store the results of a call that would match one of these would be undefined behavior. Valid uses would be: use as temporaries, but that can usually be better done through the normal container access; and use in unevaluated contexts, but those should really be explicitly requesting lvalue references if that's what they're checking. Either of these can be easily worked around. If these things happen in code outside our control we may have to reconsider.

Static Public Member Functions
static constexpr size_t	max_size ()
	The maximum number of step (not substep) entries that can be stored in the history. This number is not very large, but will be sufficient for running a time stepper requiring history_max_past_steps past step values.

Static Public Attributes
static constexpr NoValue	no_value {}

Additional Inherited Members
Protected Member Functions inherited from stl_boilerplate::RandomAccessSequence< History< Vars >, StepRecord< Vars >, false >
	RandomAccessSequence (const RandomAccessSequence &)=default
	RandomAccessSequence (RandomAccessSequence &&)=default
RandomAccessSequence &	operator= (const RandomAccessSequence &)=default
RandomAccessSequence &	operator= (RandomAccessSequence &&)=default

Detailed Description

template<typename Vars>
class TimeSteppers::History< Vars >

The past-time data used by TimeStepper classes to update the evolved variables.

This class exposes an STL-like container interface for accessing the step (not substep) StepRecord data. The records can be freely modified through this interface, although modifying the time_step_id field is generally inadvisable.

This class is designed to minimize the number of memory allocations performed during a step, and so caches discarded entries for reuse if they contain dynamic allocations. During steady-state operation, this class will perform no heap allocations. If Vars and the associated DerivVars do not allocate internally, then this class will perform no heap allocations under any circumstances.

Member Function Documentation

insert() [1/2]

template<typename Vars >

void TimeSteppers::History< Vars >::insert	(	const TimeStepId &	time_step_id,
		const Vars &	value,
		const DerivVars &	derivative
	)

Insert a new entry into the history. It will be inserted as a step or substep as appropriate.

The supplied time_step_id must be later than the current latest entry, and if the substep of time_step_id is nonzero, the id must be consistent with the existing data for the current step.

If the constant History::no_value is passed, the created record will not have its value field set. This is useful for histories other than the history of the primary evolution integration, such as the implicit portion of an IMEX evolution. These other uses adjust the result of the main history, and so do not require values (which are only used for the zeroth-order terms).

The value and derivative data will be copied into cached allocations, if any are available. That is, only a copy, not a memory allocation, will be performed when possible.

insert() [2/2]

template<typename Vars >

void TimeSteppers::History< Vars >::insert	(	const TimeStepId &	time_step_id,
		NoValue	,
		const DerivVars &	derivative
	)

Insert a new entry into the history. It will be inserted as a step or substep as appropriate.

The supplied time_step_id must be later than the current latest entry, and if the substep of time_step_id is nonzero, the id must be consistent with the existing data for the current step.

If the constant History::no_value is passed, the created record will not have its value field set. This is useful for histories other than the history of the primary evolution integration, such as the implicit portion of an IMEX evolution. These other uses adjust the result of the main history, and so do not require values (which are only used for the zeroth-order terms).

The value and derivative data will be copied into cached allocations, if any are available. That is, only a copy, not a memory allocation, will be performed when possible.

insert_in_place() [1/2]

template<typename Vars >

template<typename DerivativeFunc >

void TimeSteppers::History< Vars >::insert_in_place	(	const TimeStepId &	time_step_id,
		NoValue	,
		DerivativeFunc &&	derivative_inserter
	)

Insert a new entry in the history by modifying the fields of the record directly, instead of passing a value to copy.

The (optional) value_inserter must be a functor callable with single argument of type gsl::not_null<Vars*> and the derivative_inserter must be callable with a single argument of type gsl::not_null<DerivVars*>. The passed objects will be created from a cached memory allocation if one is available, and will otherwise be default-constructed.

All the restrictions on valid values time_step_id for the insert method apply here as well.

insert_in_place() [2/2]

template<typename Vars >

template<typename ValueFunc , typename DerivativeFunc >

void TimeSteppers::History< Vars >::insert_in_place	(	const TimeStepId &	time_step_id,
		ValueFunc &&	value_inserter,
		DerivativeFunc &&	derivative_inserter
	)

Insert a new entry in the history by modifying the fields of the record directly, instead of passing a value to copy.

The (optional) value_inserter must be a functor callable with single argument of type gsl::not_null<Vars*> and the derivative_inserter must be callable with a single argument of type gsl::not_null<DerivVars*>. The passed objects will be created from a cached memory allocation if one is available, and will otherwise be default-constructed.

All the restrictions on valid values time_step_id for the insert method apply here as well.

insert_initial() [1/2]

template<typename Vars >

void TimeSteppers::History< Vars >::insert_initial	(	TimeStepId	time_step_id,
		NoValue	,
		DerivVars	derivative
	)

Insert data at the start of the history, similar to push_front on some STL containers. This can be useful when initializing a multistep integrator.

This should only be used for initialization, and cannot be used for substep data. The supplied time_step_id must be earlier than the current first entry.

insert_initial() [2/2]

template<typename Vars >

void TimeSteppers::History< Vars >::insert_initial	(	TimeStepId	time_step_id,
		Vars	value,
		DerivVars	derivative
	)

Insert data at the start of the history, similar to push_front on some STL containers. This can be useful when initializing a multistep integrator.

This should only be used for initialization, and cannot be used for substep data. The supplied time_step_id must be earlier than the current first entry.

latest_value()

template<typename Vars >

const Vars & TimeSteppers::History< Vars >::latest_value

Get the value at the latest step or substep in the history, even if the value in that record has been discarded. This is not available if undo_latest has been called since the last insertion.

This function exists to allow access to the previous value after a potentially bad step has been taken without restricting how the time steppers can manage their history.

substeps() [1/2]

template<typename Vars >

MutableSubsteps TimeSteppers::History< Vars >::substeps ( )

inline

Container view of the StepRecords for the history substeps. These methods return classes providing an STL-like container interface to the substep data. These containers are zero-indexed, so substeps()[0] will have a substep value of 1.

These containers do not have methods to modify their sizes. Use the methods on the History class for those operations.

substeps() [2/2]

template<typename Vars >

ConstSubsteps TimeSteppers::History< Vars >::substeps ( ) const

inline

Container view of the StepRecords for the history substeps. These methods return classes providing an STL-like container interface to the substep data. These containers are zero-indexed, so substeps()[0] will have a substep value of 1.

These containers do not have methods to modify their sizes. Use the methods on the History class for those operations.

---

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

• src/Time/History.hpp