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)

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

int	set_upper_constraint (double upper)
	Sets upper constraint for the next time step estimating. More...

int	set_lower_constraint (double lower)
	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...

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 TimeMarks &	marks ()

Static Public Attributes
static Input::Type::Record	input_type

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

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 2. 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...

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...

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 double	time_step_precision = 16*numeric_limits<double>::epsilon()

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 214 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 127 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.

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 181 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 162 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 341 of file time_governor.cc.

Here is the caller graph for this function:

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 417 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 375 of file time_governor.hh.

double TimeGovernor::end_time ( ) const

inline

End time.

Definition at line 443 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 333 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 327 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 357 of file time_governor.cc.

Here is the caller graph for this function:

double TimeGovernor::estimate_time ( ) const

inline

Estimate next time.

Definition at line 439 of file time_governor.hh.

Here is the caller graph for this function:

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 330 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 193 of file time_governor.cc.

Here is the caller graph for this function:

double TimeGovernor::init_time ( ) const

inline

Initial time getter.

Definition at line 388 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 381 of file time_governor.hh.

Here is the caller graph for this function:

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

inline

Simpler interface to TimeMarks::is_current().

Definition at line 345 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 447 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 451 of file time_governor.hh.

Here is the caller graph for this function:

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

inline

Simpler interface to TimeMarks::last().

Definition at line 357 of file time_governor.hh.

double TimeGovernor::last_dt ( ) const

inline

Previous time step.

Definition at line 400 of file time_governor.hh.

double TimeGovernor::last_t ( ) const

inline

Previous time.

Definition at line 408 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 369 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 232 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 351 of file time_governor.hh.

void TimeGovernor::next_time ( )

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

Definition at line 395 of file time_governor.cc.

Here is the caller graph for this function:

int TimeGovernor::set_lower_constraint ( double lower )

Sets lower constraint for the next time step estimating.

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

See Also: set_upper_constrain().

Definition at line 303 of file time_governor.cc.

Here is the caller graph for this function:

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.

Here is the caller graph for this function:

int TimeGovernor::set_upper_constraint ( double upper )

Sets upper constraint for the next time step estimating.

This function can only make the constraint stricter. Upper constraint is reset to max_dt in next_time().

Parameters

upper is the upper constraint for time step

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

-1: constraint is higher than the permanent upper constraint max_dt. Setting failed, no change happened.
0: constraint is in the interval of permanent constraints min_dt and max_dt. The upper constraint has been set.
1: constraint is lower than permanent lower constraint min_dt. Setting failed, no change happened.

Definition at line 277 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 442 of file time_governor.cc.

double TimeGovernor::t ( ) const

inline

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

Definition at line 394 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 459 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 363 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 458 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 496 of file time_governor.hh.

double TimeGovernor::end_time_

private

End time of the simulation.

Definition at line 498 of file time_governor.hh.

TimeMark::Type TimeGovernor::eq_mark_type_

private

TimeMark type of the equation.

Definition at line 525 of file time_governor.hh.

double TimeGovernor::fixed_time_step_

private

Next fixed time step.

Definition at line 501 of file time_governor.hh.

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

static

Infinity time used for steady case.

Definition at line 470 of file time_governor.hh.

double TimeGovernor::init_time_

private

Initial time.

Definition at line 494 of file time_governor.hh.

Record TimeGovernor::input_type

static

Initial value:

= Record("TimeGovernor",
            "Setting of the simulation time. (can be specific to one equation)")
    .allow_auto_conversion("max_dt")
    .declare_key("start_time", Double(), Default("0.0"),
                "Start time of the simulation.")
    .declare_key("end_time", Double(), Default::read_time("Infinite end time."),
                "End time of the simulation.")
    .declare_key("init_dt", Double(0.0), Default("0.0"),
            "Initial guess for the time step.\n"
            "Only useful for equations that use adaptive time stepping."
            "If set to 0.0, the time step is determined in fully autonomous"
            " way if the equation supports it.")
    .declare_key("min_dt", Double(0.0),
            Default::read_time("Machine precision."),
            "Soft lower limit for the time step. Equation using adaptive time stepping can not"
            "suggest smaller time step, but actual time step could be smaller in order to match "
            "prescribed input or output times.")
    .declare_key("max_dt", Double(0.0),
            Default::read_time("Whole time of the simulation if specified, infinity else."),
            "Hard upper limit for the time step. Actual length of the time step is also limited"
            "by input and output times.")

Definition at line 227 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 503 of file time_governor.hh.

double TimeGovernor::lower_constraint_

private

Lower constraint for the choice of the next time step.

Definition at line 510 of file time_governor.hh.

double TimeGovernor::max_time_step_

private

Permanent upper limit for the time step.

Definition at line 512 of file time_governor.hh.

double TimeGovernor::min_time_step_

private

Permanent lower limit for the time step.

Definition at line 514 of file time_governor.hh.

boost::circular_buffer<TimeStep> TimeGovernor::recent_steps_

private

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

Definition at line 492 of file time_governor.hh.

bool TimeGovernor::steady_

private

True if the time governor is used for steady problem.

Definition at line 528 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 522 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 505 of file time_governor.hh.

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

staticprivate

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

Definition at line 489 of file time_governor.hh.

friend TimeGovernor::TimeMarks

private

Definition at line 530 of file time_governor.hh.

double TimeGovernor::upper_constraint_

private

Upper constraint for the choice of the next time step.

Definition at line 508 of file time_governor.hh.

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

/home/builder/jenkins/F123-linux-release/flow123d/src/tools/time_governor.hh
/home/builder/jenkins/F123-linux-release/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