smash::Clock Class Reference

#include <clock.h>

Clock tracks the time in the simulation.

The basic unit is 1 fm in natural units which correspond to \(\frac{10^{-15}}{299\,792\,458}\,\mathrm{s} \approx 0.33\cdot10^{-23}\,\mathrm{s}\) in the international system of units. The resolution of the clock is \(0.000001\,\mathrm{fm}=10^{-6}\,\mathrm{fm}\), i.e. only multiples of \(0.000001\,\mathrm{fm}\) are internally representable.

Attention

There are two very different types of clocks implemented.

1. The UniformClock is meant to track time in a simulation and it has the quite peculiar feature that it is aware of the end time of the simulation. Therefore, although it can be ticked beyond such a time, its methods about the current time, the next time and the time-step duration will adjust their return value when the clock gets to or past the simulation end time.
2. The CustomClock is meant to track a list of time points and it is best suited for output. Ticking this clock means to consider the following point in time. Ticking beyond the last time point is considered an error.

Potential usage for adapting time steps:

const double end_time = 10.;
UniformClock lab_time(0., 0.1, end_time);
while (lab_time < end_time) {
  // do something
  // adapt the timestep size to external circumstances:
  if (system_is_very_dense()) {
    lab_time.set_timestep_duration(lab_time.timestep_duration() / 2.);
  }
  if (system_is_very_dilute()) {
    lab_time.set_timestep_duration(lab_time.timestep_duration() * 2.);
  }
  // let the clock tick
  ++lab_time;
}

Possible actions for Clock

• look at it and find out the current time

  See also

  current_time()

  next_time()

• advance the clock (by one tick, by several ticks, or by a given time)

  See also

  operator++()

  UniformClock::operator+=(T)

  operator+=(Representation)

• set / retrieve the timestep (length of one tick)

  See also

  UniformClock::set_timestep_duration(double)

  timestep_duration()

• compare time against different clock or fixed value

  See also

  operator<(const Clock&) const

  operator<(double) const

  operator>(double) const

Definition at line 86 of file clock.h.

Inheritance diagram for smash::Clock:

Public Types
using	Representation = std::int64_t
	The type used for counting ticks/time. More...

Public Member Functions
virtual double	timestep_duration () const =0
virtual double	current_time () const =0
virtual double	next_time () const =0
virtual void	reset (double start_time, bool is_output_clock)=0
	reset the clock to the starting time of the simulation More...
virtual void	remove_times_in_past (double start_time)=0
	Remove output times before the starting time of the simulation if this is a custom clock. More...
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
virtual double	present_internal_time () const =0
	This function always returns the clock time, even if children might attribute a different behaviour to current_time method (as UniformClock does). More...

Protected Attributes
Representation	counter_ = 0
	Internally used to count the number of time steps. More...

Member Typedef Documentation

Representation

using smash::Clock::Representation = std::int64_t

The type used for counting ticks/time.

Definition at line 89 of file clock.h.

Constructor & Destructor Documentation

~Clock()

virtual smash::Clock::~Clock ( )

virtualdefault

Member Function Documentation

timestep_duration()

virtual double smash::Clock::timestep_duration ( ) const

pure virtual

Returns

the duration of the current time step

Implemented in smash::CustomClock, and smash::UniformClock.

current_time()

virtual double smash::Clock::current_time ( ) const

pure virtual

Returns

the current time

Implemented in smash::CustomClock, and smash::UniformClock.

next_time()

virtual double smash::Clock::next_time ( ) const

pure virtual

Returns

the time of the next time step

Implemented in smash::CustomClock, and smash::UniformClock.

reset()

virtual void smash::Clock::reset ( double  start_time, bool  is_output_clock  )

pure virtual

reset the clock to the starting time of the simulation

Parameters

[in]	start_time	starting time of the simulation
[in]	is_output_clock	whether this is an output clock rather than a lab clock

Implemented in smash::CustomClock, and smash::UniformClock.

remove_times_in_past()

virtual void smash::Clock::remove_times_in_past ( double  start_time )

pure virtual

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

Implemented in smash::UniformClock, and smash::CustomClock.

operator++()

Clock& smash::Clock::operator++ ( )

inline

Advances the clock by one tick.

This operator is used as ++clock. The operator clock++ is not implemented deliberately, because that requires a copy of the clock being created.

Definition at line 118 of file clock.h.

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

operator+=()

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

inline

Advances the clock by an arbitrary number of ticks.

Parameters

[in]

advance_several_timesteps

Number of the time steps added to the clock

Exceptions

OverflowError

if the number of the added time steps exceeds the maximum value.

Definition at line 135 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;
  }

operator<() [1/2]

bool smash::Clock::operator< ( const Clock &  rhs ) const

inline

Compares the internal times of two clocks.

Parameters

[in]

rhs

The other clock.

Definition at line 149 of file clock.h.

                                         {
    return present_internal_time() < rhs.present_internal_time();
  }

operator<() [2/2]

bool smash::Clock::operator< ( double  time ) const

inline

Compares the internal time of the clock against a fixed time.

Parameters

[in]

time

The other time.

Definition at line 158 of file clock.h.

{ return present_internal_time() < time; }

operator>()

bool smash::Clock::operator> ( double  time ) const

inline

Compares the internal time of the clock against a fixed time.

Parameters

[in]

time

The other time.

Definition at line 165 of file clock.h.

{ return present_internal_time() > time; }

present_internal_time()

virtual double smash::Clock::present_internal_time ( ) const

protectedpure virtual

This function always returns the clock time, even if children might attribute a different behaviour to current_time method (as UniformClock does).

Warning

It is important to have this method that is in turn used in the comparison operators, so that clock comparisons are independent from other possible existing mechanism (like that of the UniformClock).

Returns

The present internal clock time.

Implemented in smash::CustomClock, and smash::UniformClock.

Member Data Documentation

counter_

Representation smash::Clock::counter_ = 0

protected

Internally used to count the number of time steps.

Definition at line 185 of file clock.h.

---

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

• src/include/smash/clock.h