Basic time management functionality for unsteady (and steady) solvers (class Equation). More...

#include <time_governor.hh>

Collaboration diagram for TimeGovernor:

Public Member Functions
	DECLARE_INPUT_EXCEPTION (ExcTimeGovernorMessage,<< EI_Message::val)

	TYPEDEF_ERR_INFO (EI_Index, int)

	TYPEDEF_ERR_INFO (EI_BackIndex, unsigned int)

	TYPEDEF_ERR_INFO (EI_HistorySize, unsigned int)

	DECLARE_EXCEPTION (ExcMissingTimeStep,<< "Time step index: "<< EI_Index::val<< ", history index: "<< EI_BackIndex::val<< " out of history of size: "<< EI_HistorySize::val)

	TimeGovernor (const Input::Record &input, TimeMark::Type fixed_time_mask=TimeMark::none_type)
	Constructor for unsteady solvers. More...

	TimeGovernor (double init_time=0.0, TimeMark::Type fixed_time_mask=TimeMark::none_type)
	Default constructor - steady time governor. More...

	TimeGovernor (double init_time, double dt)

bool	is_default ()

void	set_permanent_constraint (double min_dt, double max_dt)
	Sets permanent constraints for time step. More...

int	set_upper_constraint (double upper, std::string message)
	Sets upper constraint for the next time step estimating. More...

int	set_lower_constraint (double lower, std::string message)
	Sets lower constraint for the next time step estimating. More...

double	fix_dt_until_mark ()
	Fixing time step until fixed time mark. More...

void	next_time ()
	Proceed to the next time according to current estimated time step. More...

double	reduce_timestep (double factor)
	Force timestep reduction in particular in the case of failure of the non-linear solver. More...

const TimeStep &	step (int index=-1) const

TimeMark::Type	equation_mark_type () const

TimeMark::Type	equation_fixed_mark_type () const

void	add_time_marks_grid (double step, TimeMark::Type mark_type=TimeMark::none_type) const

bool	is_current (const TimeMark::Type &mask) const

TimeMarks::iterator	next (const TimeMark::Type &mask) const

TimeMarks::iterator	last (const TimeMark::Type &mask) const

double	upper_constraint () const

double	lower_constraint () const

double	end_of_fixed_dt () const

bool	is_changed_dt () const

double	init_time () const

double	t () const

double	last_dt () const

double	last_t () const

double	dt () const

double	estimate_dt () const
	Estimate choice of next time step according to actual setting of constraints. More...

double	estimate_time () const

double	end_time () const
	End time. More...

bool	is_end () const
	Returns true if the actual time is greater than or equal to the end time. More...

bool	is_steady () const
	Returns true if the time governor is used for steady problem. More...

int	tlevel () const

void	view (const char *name="") const

Static Public Member Functions
static const Input::Type::Record &	get_input_type ()

static TimeMarks &	marks ()

Static Public Attributes
static const double	max_end_time = MAX_END_TIME

static const double	inf_time = numeric_limits<double>::infinity()
	Infinity time used for steady case. More...

static const double	time_step_precision = 16*numeric_limits<double>::epsilon()

Private Member Functions
void	init_common (double init_time, double end_time, TimeMark::Type type)
	Common part of the constructors. Set most important parameters, check they are valid and set default values to other. More...

Private Attributes
boost::circular_buffer< TimeStep >	recent_steps_
	Circular buffer of recent time steps. Implicit size is 3. More...

double	init_time_
	Initial time. More...

double	end_of_fixed_dt_interval_
	End of interval if fixed time step. More...

double	end_time_
	End time of the simulation. More...

double	fixed_time_step_
	Next fixed time step. More...

bool	is_time_step_fixed_
	Flag that is set when the fixed step is set (lasts only one time step). More...

bool	time_step_changed_
	Flag is set if the time step has been changed (lasts only one time step). More...

std::string	upper_constraint_message_
	Description of the upper constraint. More...

std::string	lower_constraint_message_
	Description of the upper constraint. More...

double	upper_constraint_
	Upper constraint for the choice of the next time step. More...

double	lower_constraint_
	Lower constraint for the choice of the next time step. More...

double	max_time_step_
	Permanent upper limit for the time step. More...

double	min_time_step_
	Permanent lower limit for the time step. More...

double	last_upper_constraint_
	Upper constraint used for choice of current time. More...

double	last_lower_constraint_
	Lower constraint used for choice of current time. More...

TimeMark::Type	eq_mark_type_
	TimeMark type of the equation. More...

bool	steady_
	True if the time governor is used for steady problem. More...

friend	TimeMarks

Static Private Attributes
static const unsigned int	size_of_recent_steps_ = 3

static TimeMarks	time_marks_ = TimeMarks()

Detailed Description

Basic time management functionality for unsteady (and steady) solvers (class Equation).

Common features and unsteady time governor (TG)

This class provides algorithm for selecting next time step, and information about current time step frame. Step estimating is constrained by several bounds (permanent maximal and minimal time step, upper and lower constraint of time step). The permanent constraints are set in the constructor from the input record so that user can set the time step constraints for the whole simulation. Function set_permanent_constraint() should be used only in very specific cases and possibly right after the constructor before using other functions of TG.

Choice of the very next time step can be constrained using functions set_upper_constraint() and set_lower_constraint(). Lower and upper constraints are set equal to permanent ones in the constructor and can only become stricter. If one tries to set these constraints outside the interval of the previous constraints, nothing is changed and a specified value is returned. Upper and lower constraints are reset in function next_time() to the permanent constraints.

The later one can be called multiple times with various constraint values and we use the minimum of them. Function next_time() choose the next time step in such a way that it meets actual constraints and a uniform discrete time grid with this step hits the nearest fixed time in lowest possible number of steps.

The fixed times are time marks of TimeMarks object passed at construction time with particular mask.

There is just one set of time marks for the whole problem. Therefore TimeMarks object is static and is shared umong all the equations and time governors. Each equation creates its own specific time mark type.

Information provided by TG includes:

actual time, last time, end time
actual time step
number of the time level
end of interval with fixed time step
time comparison
static pointer to time marks

Steady time governor

Steady TG can be constructed by default constructor (initial time is zero) or by constructor with initial time as parameter. End time and time step are set to infinity. One can check if the time governor is steady by calling is_steady(). Calling estimate_dt() will return infinity.

Setting constraints have no consequences. Calling fix_dt_until_mark() will only return zero and will not do anything.

The steady TG works in two states. At first the time is set to initial and time level is equal zero. To use steady TG properly one should call next_time() after the computation of steady problem is done. Current time is then set to infinity, time level is set to 1 and calling estimate_dt() will return zero.

Note: For example class TransportNothing (which computes really nothing) uses also steady TG but it calls next_time() immediately after TG's construction. This means that the 'computation'of transport is done.

Definition at line 213 of file time_governor.hh.

Constructor & Destructor Documentation

TimeGovernor::TimeGovernor	(	const Input::Record &	input,
		TimeMark::Type	fixed_time_mask = `TimeMark::none_type`
	)

Constructor for unsteady solvers.

Parameters

input	accessor to input data
fixed_time_mask	TimeMark mask used to select fixed time marks from all the time marks. This value is bitwise added to the default one defined in TimeMarks::type_fixed_time().

Definition at line 125 of file time_governor.cc.

TimeGovernor::TimeGovernor	(	double	init_time = `0.0`,
		TimeMark::Type	fixed_time_mask = `TimeMark::none_type`
	)

explicit

Default constructor - steady time governor.

OBSOLETE.

We can have "zero step" steady problem (no computation, e.g. EquationNothing) and one step steady problem (e.g. steady water flow).

Time is set to zero, time step and end time to infinity.

First call of next_time() pushes the actual time to infinity.

However, you have to use full constructor for the "steady problem" that has time-variable input data.

Has a private pointer to static TimeMarks and can access them by marks().

Definition at line 185 of file time_governor.cc.

TimeGovernor::TimeGovernor	(	double	init_time,
		double	dt
	)

The aim of this constuctor is simple way to make a time governor without Input interface.

TODO: Partially tested as part of field test. Needs its own unit test.

Definition at line 163 of file time_governor.cc.

Member Function Documentation

void TimeGovernor::add_time_marks_grid	(	double	step,
		TimeMark::Type	mark_type = `TimeMark::none_type`
	)		const

Add sequence of time marks starting from the initial time up to the end time with given step. Time marks type combines given mark_type (none by default) and native mark type of the time governor.

Definition at line 333 of file time_governor.cc.

TimeGovernor::DECLARE_EXCEPTION	(	ExcMissingTimeStep	,
		<< "Time step index: "<< EI_Index::val<< "	,
		history index:"<< EI_BackIndex::val<< "out of history of size:"<< EI_HistorySize::val
	)

TimeGovernor::DECLARE_INPUT_EXCEPTION	(	ExcTimeGovernorMessage	,
		<< EI_Message::val
	)

double TimeGovernor::dt ( ) const

inline

Length of actual time interval; i.e. the actual time step.

Definition at line 450 of file time_governor.hh.

Here is the caller graph for this function:

double TimeGovernor::end_of_fixed_dt ( ) const

inline

End of interval with currently fixed time step. Can be changed by next call of method fix_dt_until_mark.

Definition at line 408 of file time_governor.hh.

double TimeGovernor::end_time ( ) const

inline

End time.

Definition at line 476 of file time_governor.hh.

Here is the caller graph for this function:

TimeMark::Type TimeGovernor::equation_fixed_mark_type ( ) const

inline

Specific time mark of the fixed times of the equation owning the time governor.

Definition at line 366 of file time_governor.hh.

Here is the caller graph for this function:

TimeMark::Type TimeGovernor::equation_mark_type ( ) const

inline

Specific time mark of the equation owning the time governor.

Definition at line 360 of file time_governor.hh.

Here is the caller graph for this function:

double TimeGovernor::estimate_dt ( ) const

Estimate choice of next time step according to actual setting of constraints.

Precedence of constraints:

meet next fixed time (always satisfied)
permanent upper constraint (always satisfied)
upper constraint (always satisfied)
lower constraint (satisfied if not in conflict with 1.)
permanent lower constraint (satisfied if 4.)
else writes the difference between lower constraint and estimated time step
If there are more then one step to the next fixed time, try to use the last time step if it is nearly the same.

Definition at line 356 of file time_governor.cc.

double TimeGovernor::estimate_time ( ) const

inline

Estimate next time.

Definition at line 472 of file time_governor.hh.

double TimeGovernor::fix_dt_until_mark ( )

Fixing time step until fixed time mark.

Fix time step until first fixed time mark. When called inside an already fixed interval, it overwrites previous setting.

Returns: actual end of fixed time step.

Definition at line 322 of file time_governor.cc.

Here is the caller graph for this function:

const Record & TimeGovernor::get_input_type ( )

static

Definition at line 41 of file time_governor.cc.

Here is the caller graph for this function:

void TimeGovernor::init_common	(	double	init_time,
		double	end_time,
		TimeMark::Type	type
	)

private

Common part of the constructors. Set most important parameters, check they are valid and set default values to other.

Set main parameters to given values. Check they are correct. Set soft and permanent constrains to the same, the least restricting values. Set time marks for the start time and end time (if finite).

Definition at line 196 of file time_governor.cc.

double TimeGovernor::init_time ( ) const

inline

Initial time getter.

Definition at line 421 of file time_governor.hh.

Here is the caller graph for this function:

bool TimeGovernor::is_changed_dt ( ) const

inline

Getter for dt_changed. Returns whether the time step has been changed.

Definition at line 414 of file time_governor.hh.

Here is the caller graph for this function:

bool TimeGovernor::is_current ( const TimeMark::Type & mask ) const

Simpler interface to TimeMarks::is_current().

Definition at line 348 of file time_governor.cc.

bool TimeGovernor::is_default ( )

inline

Returns true if the time governor was set from default values

Definition at line 274 of file time_governor.hh.

Here is the caller graph for this function:

bool TimeGovernor::is_end ( ) const

inline

Returns true if the actual time is greater than or equal to the end time.

Definition at line 480 of file time_governor.hh.

Here is the caller graph for this function:

bool TimeGovernor::is_steady ( ) const

inline

Returns true if the time governor is used for steady problem.

Definition at line 484 of file time_governor.hh.

TimeMarks::iterator TimeGovernor::last ( const TimeMark::Type & mask ) const

inline

Simpler interface to TimeMarks::last().

Definition at line 390 of file time_governor.hh.

double TimeGovernor::last_dt ( ) const

inline

Previous time step.

Definition at line 433 of file time_governor.hh.

Here is the caller graph for this function:

double TimeGovernor::last_t ( ) const

inline

Previous time.

Definition at line 441 of file time_governor.hh.

Here is the caller graph for this function:

double TimeGovernor::lower_constraint ( ) const

inline

Returns lower constraint.

Definition at line 402 of file time_governor.hh.

Here is the caller graph for this function:

static TimeMarks& TimeGovernor::marks ( )

inlinestatic

Getter for time marks.

Definition at line 231 of file time_governor.hh.

Here is the caller graph for this function:

TimeMarks::iterator TimeGovernor::next ( const TimeMark::Type & mask ) const

inline

Simpler interface to TimeMarks::next().

Definition at line 384 of file time_governor.hh.

void TimeGovernor::next_time ( )

Proceed to the next time according to current estimated time step.

The timestep constraints are relaxed to the permanent constraints.

Definition at line 395 of file time_governor.cc.

Here is the caller graph for this function:

double TimeGovernor::reduce_timestep ( double factor )

Force timestep reduction in particular in the case of failure of the non-linear solver.

Calling this method also force immediate end of the fixed timestep interval. Returns true reduce factor used. It is larger then given factor if we hit the lower timestep constraint.

TODO: How to keep constraints active for the last next_time call.

Definition at line 444 of file time_governor.cc.

int TimeGovernor::set_lower_constraint	(	double	lower,
		std::string	message
	)

Sets lower constraint for the next time step estimating.

This function can only make the constraint stricter. Lower constraint is reset to min_dt after the next_time() call. The return value mimics result of the comparison: current constraint compared to

Parameters

upper.	In particular the return values is: -1: Current upper constraint is less then the
lower.	No change happen. 0: Current constraint interval contains the
lower.	The lower constraint is set. +1: Current upper constraint is greater then the
lower.	No change happen. Sets lower constraint for the next time step estimating.
lower	is the lower constraint for time step
message	describes the origin of the constraint

Returns: -1, 0 or 1 according to the success.

See also: set_upper_constrain().

Definition at line 301 of file time_governor.cc.

void TimeGovernor::set_permanent_constraint	(	double	min_dt,
		double	max_dt
	)

Sets permanent constraints for time step.

This function should not be normally used. These values are to be set in constructor from the input record or by default.

Parameters

min_dt	is the minimal value allowed for time step
max_dt	is the maximal value allowed for time step

Definition at line 257 of file time_governor.cc.

int TimeGovernor::set_upper_constraint	(	double	upper,
		std::string	message
	)

Sets upper constraint for the next time step estimating.

This function can only make the constraint stricter. Upper constraint is reset to max_dt after the next_time() call. The return value mimics result of the comparison: current constraint compared to

Parameters

upper.
message	describes the origin of the constraint In particular the return values is: -1: Current upper constraint is less then the
upper.	No change happen. 0: Current constraint interval contains the
upper.	The upper constraint is set. +1: Current lower constraint is greater then the
upper.	No change happen.

Definition at line 280 of file time_governor.cc.

Here is the caller graph for this function:

const TimeStep & TimeGovernor::step ( int index = -1 ) const

Returns reference to required time step in the recent history. Without parameter the actual time step is returned. Use negative indices to get recent time steps: step(-1) the actual step, step(-2) the last one. Use positive index to get time step by its index: step(0) the first time step. However only limited number of last time steps is stored. If the time step is not accessible any more, we throw an exception ExcMissingTimeStep.

Definition at line 469 of file time_governor.cc.

Here is the caller graph for this function:

double TimeGovernor::t ( ) const

inline

End of actual time interval; i.e. where the solution is computed.

Definition at line 427 of file time_governor.hh.

Here is the caller graph for this function:

int TimeGovernor::tlevel ( ) const

inline

Returns the time level.

Definition at line 492 of file time_governor.hh.

Here is the caller graph for this function:

TimeGovernor::TYPEDEF_ERR_INFO	(	EI_Index	,
		int
	)

TimeGovernor::TYPEDEF_ERR_INFO	(	EI_BackIndex	,
		unsigned	int
	)

TimeGovernor::TYPEDEF_ERR_INFO	(	EI_HistorySize	,
		unsigned	int
	)

double TimeGovernor::upper_constraint ( ) const

inline

Getter for upper constrain.

Definition at line 396 of file time_governor.hh.

Here is the caller graph for this function:

void TimeGovernor::view ( const char * name = "" ) const

Prints output of TimeGovernor.

Parameters

name	is the name of time governor that you want to show up in output (just for your convenience)

Definition at line 485 of file time_governor.cc.

Here is the caller graph for this function:

Member Data Documentation

double TimeGovernor::end_of_fixed_dt_interval_

private

End of interval if fixed time step.

Definition at line 537 of file time_governor.hh.

double TimeGovernor::end_time_

private

End time of the simulation.

Definition at line 539 of file time_governor.hh.

TimeMark::Type TimeGovernor::eq_mark_type_

private

TimeMark type of the equation.

Definition at line 575 of file time_governor.hh.

double TimeGovernor::fixed_time_step_

private

Next fixed time step.

Definition at line 542 of file time_governor.hh.

const double TimeGovernor::inf_time = numeric_limits<double>::infinity()

static

Infinity time used for steady case.

Definition at line 506 of file time_governor.hh.

double TimeGovernor::init_time_

private

Initial time.

Definition at line 535 of file time_governor.hh.

bool TimeGovernor::is_time_step_fixed_

private

Flag that is set when the fixed step is set (lasts only one time step).

Definition at line 544 of file time_governor.hh.

double TimeGovernor::last_lower_constraint_

private

Lower constraint used for choice of current time.

Definition at line 564 of file time_governor.hh.

double TimeGovernor::last_upper_constraint_

private

Upper constraint used for choice of current time.

Definition at line 562 of file time_governor.hh.

double TimeGovernor::lower_constraint_

private

Lower constraint for the choice of the next time step.

Definition at line 555 of file time_governor.hh.

std::string TimeGovernor::lower_constraint_message_

private

Description of the upper constraint.

Definition at line 551 of file time_governor.hh.

const double TimeGovernor::max_end_time = MAX_END_TIME

static

Definition at line 503 of file time_governor.hh.

double TimeGovernor::max_time_step_

private

Permanent upper limit for the time step.

Definition at line 557 of file time_governor.hh.

double TimeGovernor::min_time_step_

private

Permanent lower limit for the time step.

Definition at line 559 of file time_governor.hh.

boost::circular_buffer<TimeStep> TimeGovernor::recent_steps_

private

Circular buffer of recent time steps. Implicit size is 3.

Definition at line 533 of file time_governor.hh.

const unsigned int TimeGovernor::size_of_recent_steps_ = 3

staticprivate

Size of the time step buffer, i.e. recent_time_steps_.

Definition at line 530 of file time_governor.hh.

bool TimeGovernor::steady_

private

True if the time governor is used for steady problem.

Definition at line 578 of file time_governor.hh.

TimeMarks TimeGovernor::time_marks_ = TimeMarks()

staticprivate

When the next time is chosen we need only the lowest fix time. Therefore we use minimum priority queue of doubles based on the vector container. This is one global set of time marks for the whole problem and is shared among all equations. Therefore this object is static constant pointer.

Definition at line 572 of file time_governor.hh.

bool TimeGovernor::time_step_changed_

private

Flag is set if the time step has been changed (lasts only one time step).

Definition at line 546 of file time_governor.hh.

const double TimeGovernor::time_step_precision = 16*numeric_limits<double>::epsilon()

static

Rounding precision for computing time_step. Used as technical lower bound for the time step.

Definition at line 512 of file time_governor.hh.

friend TimeGovernor::TimeMarks

private

Definition at line 580 of file time_governor.hh.

double TimeGovernor::upper_constraint_

private

Upper constraint for the choice of the next time step.

Definition at line 553 of file time_governor.hh.

std::string TimeGovernor::upper_constraint_message_

private

Description of the upper constraint.

Definition at line 549 of file time_governor.hh.

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

/opt/flow123d/flow123d/src/tools/time_governor.hh
/opt/flow123d/flow123d/src/tools/time_governor.cc

Public Member Functions

Static Public Member Functions

Static Public Attributes

Private Member Functions

Private Attributes

Static Private Attributes

Detailed Description

Common features and unsteady time governor (TG)

Steady time governor

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation