Concept

Kinetic::Simulator

Definition

The class Kinetic::Simulator controls kinetic data structures by maintaining a the current time and ensuring that events are processed when necessary.

In addition, the Kinetic::Simulator can call on the kinetic data structures to audit themselves at appropriate times. When the last event processed and the next to be processed have different times, then there is a rational value of time at which all kinetic data structures should be non-degenerate (since there are no events at that time). At such a time, kinetic data structures can easily verify their correctness by checking that all the certificate predicates have the correct value. When exactness checks are enabled, whenever the last event processed and the next event to be processed have different times, a Kinetic::Simulator::Listener::HAS_AUDIT_TIME notification is made. Kinetic data structures can listen for that event, and when it is made, they can call Kinetic::Simulator::audit_time() to get the time value and then verify that their structure is correct.

In addition, at such a time, the Event::audit(Key) is called on each event. This allows kinetic data structures to check that the event should be in the queue.

Typically, the simulator is created by the Kinetic:SimulationTraits class and kinetic data structures request a handle to it from there.

Events that occur at or after Kinetic::Simulator::end_time() will may not be processed. The exception are events which are scheduled using the new_final_event(Event) call which are guaranteed to occur after all other events (but have no particular order amongst themselves).

Types

Kinetic::Simulator::Function_kernel
The type of the function kernel used to instantiate this Kinetic::Simulator.


Kinetic::Simulator::Listener
Extend this base class to listen to notifications from this Kinetic::Simulator. There are two types of notifications: HAS_AUDIT_TIME and DIRECTION_OF_TIME. The first is made when kinetic data structures can perform an audit. The second is made when the direction of time is changed.


Kinetic::Simulator::Time
The representation type for times in the simulator. It is Function_kernel::Root_enumerator::Root.


Kinetic::Simulator::Event_key
The key to access scheduled Event in order to inspect or delete them.


Kinetic::Simulator::NT
The basic number type used in computations.


Kinetic::Simulator::Handle
A reference counted pointer to be used for storing references to the object.


Kinetic::Simulator::Const_handle
A reference counted pointer to be used for storing references to the object.

Creation

Kinetic::Simulator sim ( const Time start=Time(0), const Time end= Time::infinity());
Construct a Kinetic::Simulator which will process events between times start and end (events outside this window will be discarded).

Operations

Function_kernel sim.function_kernel_object () const
Access the Function_kernel object used by the Kinetic::Simulator.

Time sim.current_time () Return the current time.

void sim.set_current_time ( Time t) Set the current time to t, which cannot be less than current_time. Any events in the queue before time t are processed.

NT sim.next_time_reprsentable_as_nt () const
This function returns a time which can be represented using an instance of type NT which is shortly after the current time. You can then advance the current time to this one and act on the data structure using the return nt.

bool sim.has_current_time_as_nt () const
Return true if there is a rational number which is equivalent to the current time. Equivalent means that it has the same ordering relation to all previous and scheduled events.

bool sim.has_audit_time () const Returns true if the current time is a rational number and there are no events at the current time. This means that the simulation can be audited at this time.

Time sim.next_event_time () const Return the time of the next event in the queue.

Time sim.end_time () const Return the time the simulation will end. If time is running backwards, then this returns Time::infinity().

void sim.set_interval ( Time t_cur, Time t_end)
Set the current time to tcur and the end time to tend. The event queue must be empty. Use this method if you want to reset or extend the simulation.

template <class Event>
Event_key sim.new_event ( Time t, const Event event)
Schedule a new event at time t. The object event must implement the concept Event. The Event_key returned can be used to access or deschedule the event.

template <class Event>
Event_key sim.new_final_event ( const Event event)
Schedule a new event that will occur at the end of the simulation. This type of event is useful if, for example, you want to run for a while, change all motions, and then run some more.

Event_key sim.null_event () const This method returns an Event_key which is guaranteed never to be assigned to any real event. This is a very useful placeholder for events which are known never to occur (and allows data structures to differentiate between uninitialized and never failing).

void sim.audit_event ( Event_key) const
Performs some checks as to whether the key corresponds to a valid event. Generally, a event is valid if it is not defaultly constructed and either is in the queue or is the null_event().

bool sim.empty () const Return true if there are no more events.

void sim.delete_event ( const Event_key k)
Remove the event referenced by k from the event queue.

template <class Ev>
typename Queue::Event_handle<Ev>::Handle
sim.event ( const Event_key k, const Ev e) const
This method returns a pointer to an event, which can be used for recoving data, such as cached solvers, from that event. The second argument really shouldn't be there, but gcc seems to sometimes have issues if you try to specify the template value directly.

Time sim.event_time ( Event_key k) const
Return the time at which the event referenced by k occurs.

template <class Ev>
Event_key sim.set_event ( Event_key k, const Ev ev)
Set the event referenced by key k to ev, for example if you want to change what happens when that event occurs. A new event key is returned.

Sign sim.direction_of_time () const Return POSITIVE if time is running forwards or NEGATIVE if it is running backwards.

void sim.set_direction_of_time ( Sign dir) const
Set which direction time is running.

unsigned int sim.current_event_number () const Return the number of events which have been processed.

void sim.set_current_event_number ( unsigned int i) const
Process all events up to the ith event. i cannot be less than current_event_number.

See Also

Kinetic::Simulator_objects_listener<Simulator_listener, KDS>, Kinetic::Simulator_kds_listener<Simulator_listener, KDS>.

Has Models

Kinetic::Default_simulator<FunctionKernel, EventQueue>