#include <clock.h>

Clock with uniformly spaced time steps.

Internal clock mechanisms

This clock stores a time step size \(\Delta t\), a base time \(t_0\) as well as an end time \(t_{end}\) and a counter \(n\). The current time is calculated from \(t = t_0 + n \cdot \Delta t\). When \(\Delta t\) is changed, \(t_0\) is reset to the present time and \(n\) is set to 0. As soon as \(t\geq t_{end}\), the clock will always return \(t_{end}\) as current and next time. The time step size can be retrieved and the returned value is

\[ \begin{aligned} \Delta t \qquad&\mbox{if}& &t\leq t_{end}-\Delta t \\ t_{end}-t \qquad&\mbox{if}& t_{end}-\Delta t<{}&t<t_{end} \\ 0.0 \qquad&\mbox{if}& &t\geq t_{end} \\ \end{aligned} \]

In the last case, i.e. if the time step size is required when the clock ticked beyond the simulation end, a warning is given to the user.

Definition at line 210 of file clock.h.

Inheritance diagram for smash::UniformClock:

Public Member Functions
	UniformClock ()=default
	default initializer: Timestep size is set to 0! More...

	UniformClock (double time, double dt, double time_end)
	Initialize with base time and time step size. More...

double	current_time () const override

double	next_time () const override

double	timestep_duration () const override

void	set_timestep_duration (double dt)
	Sets the time step size (and resets the counter). More...

void	reset (double start_time, bool is_output_clock) override
	Resets the time to the starting time of an event. More...

void	remove_times_in_past (double) override
	Remove output times before the starting time of the simulation if this is a custom clock. More...

template<typename T >
std::enable_if< std::is_floating_point< T >::value, Clock & >::type	operator+= (T big_timestep)
	Advances the clock by an arbitrary timestep (multiple of 0.000001 fm). More...

Clock &	operator+= (Representation advance_several_timesteps)
	advances the clock by an arbitrary number of ticks. More...

Public Member Functions inherited from smash::Clock
Clock &	operator++ ()
	Advances the clock by one tick. More...

Clock &	operator+= (Representation advance_several_timesteps)
	Advances the clock by an arbitrary number of ticks. More...

bool	operator< (const Clock &rhs) const
	Compares the internal times of two clocks. More...

bool	operator< (double time) const
	Compares the internal time of the clock against a fixed time. More...

bool	operator> (double time) const
	Compares the internal time of the clock against a fixed time. More...

virtual	~Clock ()=default

Protected Member Functions
double	present_internal_time () const override
	Access the internal time of the clock, independently from the end time. More...

Static Private Member Functions
static Representation	convert (double x)
	Convert a double `x` into the internal int representation. More...

static double	convert (Representation x)
	Convert an internal int value `x` into the double representation. More...

Private Attributes
Representation	timestep_duration_ = 0
	The time step size \(\Delta t\) in \(10^{-6}\,\mathrm{fm}\). More...

Representation	reset_time_ = 0
	The time of last reset (when counter_ was set to 0). More...

Representation	time_end_ = 0
	The end time of the particle propagation. More...

Static Private Attributes
static constexpr double	resolution = 0.000001
	Defines the resolution of the clock (namely the smallest representable time difference). More...

static constexpr double	to_double = resolution
	A multiplier transferring the internal integer to the real time. More...

static constexpr double	from_double = 1. / resolution
	A multiplier transferring the real time to the internal integer. More...

Additional Inherited Members
Public Types inherited from smash::Clock
using	Representation = std::int64_t
	The type used for counting ticks/time. More...

Protected Attributes inherited from smash::Clock
Representation	counter_ = 0
	Internally used to count the number of time steps. More...

Constructor & Destructor Documentation

◆ UniformClock() [1/2]

smash::UniformClock::UniformClock ( )

default

default initializer: Timestep size is set to 0!

◆ UniformClock() [2/2]

smash::UniformClock::UniformClock	(	double	time,
		double	dt,
		double	time_end
	)

inline

Initialize with base time and time step size.

Parameters

[in]	time	base time
[in]	dt	step size
[in]	time_end	end time of particle propagation

Definition at line 235 of file clock.h.

       : timestep_duration_(convert(dt)),
         reset_time_(convert(time)),
         time_end_(convert(time_end)) {
     if (dt <= 0.) {
       throw std::range_error("Time increment must be positive and non-zero");
     }
     if (reset_time_ >= time_end_) {
       throw std::range_error(
           "The initial time of UniformClock must be smaller than the end time. "
           "(Attempt to set initial time to " +
           std::to_string(time) + " and end time to " +
           std::to_string(time_end) + " not possible)");
     }
   }

Member Function Documentation

◆ current_time()

double smash::UniformClock::current_time ( ) const

inlineoverridevirtual

Returns: the current time or the end time if the clock ticked beyond it.

Implements smash::Clock.

Definition at line 253 of file clock.h.

                                        {
     auto present_time = present_internal_time();
     // Do comparison in internal representation unit and return converted values
     if (convert(present_time) > time_end_) {
       return convert(time_end_);
     } else {
       return present_time;
     }
   }

◆ next_time()

double smash::UniformClock::next_time ( ) const

inlineoverridevirtual

Returns: the time in the next tick or the end time if the clock ticked beyond it.

Note: This function is needed, because current_time() + timestep_duration() is not the same as the next tick (numerically; this is due to floating point arithmetic).

Implements smash::Clock.

Definition at line 270 of file clock.h.

                                     {
     if (counter_ * timestep_duration_ >=
         std::numeric_limits<Representation>::max() - timestep_duration_) {
       throw std::overflow_error("Too many timesteps, clock overflow imminent");
     }
     auto next_point_in_time = reset_time_ + timestep_duration_ * (counter_ + 1);
     if (next_point_in_time > time_end_) {
       return convert(time_end_);
     } else {
       return convert(next_point_in_time);
     }
   }

◆ timestep_duration()

double smash::UniformClock::timestep_duration ( ) const

inlineoverridevirtual

Returns: the time step size from the current time. If a full tick would result in a time larger then the end time, a smaller size is returned. If the clock is already beyond the end time, 0.0 is returned and a warning is printed.

See also: UniformClock description.

Implements smash::Clock.

Definition at line 289 of file clock.h.

                                             {
     auto present_time = convert(present_internal_time());
     if (present_time > time_end_) {
       logg[LClock].warn() << "UniformClock asked for timestep duration beyond "
                              "end of simulation, returning 0.";
       return 0.0;
     } else if (present_time + timestep_duration_ > time_end_) {
       return convert(time_end_ - present_time);
     } else {
       return convert(timestep_duration_);
     }
   }

◆ set_timestep_duration()

void smash::UniformClock::set_timestep_duration ( double dt )

inline

Sets the time step size (and resets the counter).

Parameters

[in] dt new time step size

Definition at line 306 of file clock.h.

                                         {
     if (dt <= 0.) {
       throw std::range_error("Time increment must be positive and non-zero!");
     }
     reset_time_ += timestep_duration_ * counter_;
     counter_ = 0;
     timestep_duration_ = convert(dt);
   }

◆ reset()

void smash::UniformClock::reset	(	double	start_time,
		bool	is_output_clock
	)

inlineoverridevirtual

Resets the time to the starting time of an event.

Parameters

[in]	start_time	Starting time of the simulation
[in]	is_output_clock	whether this is an output clock or a lab clock

Implements smash::Clock.

Definition at line 321 of file clock.h.

                                                                {
     double reset_time;
     if (is_output_clock) {
       auto delta_t = convert(timestep_duration_);
       reset_time = std::floor(start_time / delta_t) * delta_t;
     } else {
       reset_time = start_time;
     }
     if (reset_time < current_time()) {
       logg[LClock].debug("Resetting clock from", current_time(), " fm to ",
                          reset_time, " fm");
     }
     reset_time_ = convert(reset_time);
     counter_ = 0;
   }

◆ remove_times_in_past()

void smash::UniformClock::remove_times_in_past ( double start_time )

inlineoverridevirtual

Remove output times before the starting time of the simulation if this is a custom clock.

Parameters

[in] start_time starting time of the simulation

Implements smash::Clock.

Definition at line 337 of file clock.h.

337 {};

◆ operator+=() [1/2]

template<typename T >

std::enable_if<std::is_floating_point<T>::value, Clock&>::type smash::UniformClock::operator+= ( T big_timestep )

inline

Advances the clock by an arbitrary timestep (multiple of 0.000001 fm).

Template Parameters

T	type of the timestep

Parameters

[in] big_timestep Time step by which the clock is advanced.

Note: It uses a template parameter only for disambiguation with the overload below.

Definition at line 349 of file clock.h.

                              {
     if (big_timestep < 0.) {
       throw std::range_error("The clock cannot be turned back.");
     }
     reset_time_ += convert(big_timestep);
     return *this;
   }

◆ operator+=() [2/2]

Clock& smash::UniformClock::operator+= ( Representation advance_several_timesteps )

inline

advances the clock by an arbitrary number of ticks.

Parameters

[in] advance_several_timesteps Number of the timesteps added to the clock

Exceptions

OverflowError if the number of the added timesteps exceeds the maximum value.

Definition at line 364 of file clock.h.

                                                               {
     if (counter_ >= std::numeric_limits<Representation>::max() -
                         advance_several_timesteps) {
       throw std::overflow_error("Too many timesteps, clock overflow imminent");
     }
     counter_ += advance_several_timesteps;
     return *this;
   }

◆ present_internal_time()

double smash::UniformClock::present_internal_time ( ) const

inlineoverrideprotectedvirtual

Access the internal time of the clock, independently from the end time.

Returns: the internal clock time.

Implements smash::Clock.

Definition at line 379 of file clock.h.

                                                 {
     return convert(reset_time_ + timestep_duration_ * counter_);
   }

◆ convert() [1/2]

static Representation smash::UniformClock::convert ( double x )

inlinestaticprivate

Convert a double x into the internal int representation.

Definition at line 390 of file clock.h.

                                           {
     return numeric_cast<Representation>(std::round(x * from_double));
   }

◆ convert() [2/2]

static double smash::UniformClock::convert ( Representation x )

inlinestaticprivate

Convert an internal int value x into the double representation.

Definition at line 394 of file clock.h.

394 { return x * to_double; }

smash::UniformClock::to_double

static constexpr double to_double

A multiplier transferring the internal integer to the real time.

Definition: clock.h:385

Member Data Documentation

◆ resolution

constexpr double smash::UniformClock::resolution = 0.000001

staticconstexprprivate

Defines the resolution of the clock (namely the smallest representable time difference).

The value 0.000001 is very well suited because

It should be \(10^{-n},\;n\in\mathbb{N}\). That's because we want to use it to convert user input/output and that's in decimal representation.
The floating-point representation of the constant should have a small error. 0.000001 has the smallest error (i.e. 0.022 ulp) in the range \(1\leq n \leq 10\). The small error helps to convert the internal integer representation as precise as possible to floating-point.

Definition at line 223 of file clock.h.

◆ to_double

constexpr double smash::UniformClock::to_double = resolution

staticconstexprprivate

A multiplier transferring the internal integer to the real time.

Definition at line 385 of file clock.h.

◆ from_double

constexpr double smash::UniformClock::from_double = 1. / resolution

staticconstexprprivate

A multiplier transferring the real time to the internal integer.

Definition at line 387 of file clock.h.

◆ timestep_duration_

Representation smash::UniformClock::timestep_duration_ = 0

private

The time step size \(\Delta t\) in \(10^{-6}\,\mathrm{fm}\).

Definition at line 397 of file clock.h.

◆ reset_time_

Representation smash::UniformClock::reset_time_ = 0

private

The time of last reset (when counter_ was set to 0).

Definition at line 399 of file clock.h.

◆ time_end_

Representation smash::UniformClock::time_end_ = 0

private

The end time of the particle propagation.

Definition at line 401 of file clock.h.

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

src/include/smash/clock.h

Internal clock mechanisms

Public Member Functions

Protected Member Functions

Static Private Member Functions

Private Attributes

Static Private Attributes

Additional Inherited Members

Constructor & Destructor Documentation

◆ UniformClock() [1/2]

◆ UniformClock() [2/2]

Member Function Documentation

◆ current_time()

◆ next_time()

◆ timestep_duration()

◆ set_timestep_duration()

◆ reset()

◆ remove_times_in_past()

◆ operator+=() [1/2]

◆ operator+=() [2/2]

◆ present_internal_time()

◆ convert() [1/2]

◆ convert() [2/2]

Member Data Documentation

◆ resolution

◆ to_double

◆ from_double

◆ timestep_duration_

◆ reset_time_

◆ time_end_