CGAL 4.7 - Kinetic Framework
Kinetic::Simulator Concept Reference

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

CGAL::Kinetic::Simulator_objects_listener<Simulator_listener, KDS>
CGAL::Kinetic::Simulator_kds_listener<Simulator_listener, KDS>
Has Models:
CGAL::Kinetic::Default_simulator<FunctionKernel, EventQueue>

## Concepts

conceptEvent
The concept Event represents a single event. Models of Event should be passed to the Kinetic::Simulator when scheduling events which will in turn pass them to the EventQueue. More...

conceptTime
The concept Time represents time in the simulator. More...

## Types

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

typedef unspecified_type Listener
Extend this base class to listen to notifications from this Kinetic::Simulator. More...

typedef unspecified_type NT
The basic number type used in computations.

typedef unspecified_type Handle
A reference counted pointer to be used for storing references to the object.

typedef unspecified_type Const_handle
A reference counted pointer to be used for storing references to the object.

## Creation

Simulator (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 function_kernel_object () const
Access the Function_kernel object used by the Kinetic::Simulator.

Time current_time ()
Return the current time.

void set_current_time (Time t)
Set the current time to t, which cannot be less than current_time. More...

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

bool has_current_time_as_nt () const
Return true if there is a rational number which is equivalent to the current time. More...

bool has_audit_time () const
Returns true if the current time is a rational number and there are no events at the current time. More...

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

Time end_time () const
Return the time the simulation will end. More...

void set_interval (Time t_cur, Time t_end)
Set the current time to $$t_{cur}$$ and the end time to $$t_{end}$$. More...

template<class Event >
Event_key new_event (Time t, const Event event)
Schedule a new event at time t. More...

template<class Event >
Event_key new_final_event (const Event event)
Schedule a new event that will occur at the end of the simulation. More...

Event_key null_event () const
This method returns an Event_key which is guaranteed never to be assigned to any real event. More...

void audit_event (Event_key) const
Performs some checks as to whether the key corresponds to a valid event. More...

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

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

template<class Ev >
Queue::Event_handle< Ev >::Handle 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. More...

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

template<class Ev >
Event_key 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. More...

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

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

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

void set_current_event_number (unsigned int i) const
Process all events up to the ith event. More...

## Member Typedef Documentation

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.

## Member Function Documentation

 void Kinetic::Simulator::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().

 Time Kinetic::Simulator::end_time ( ) const

Return the time the simulation will end.

If time is running backwards, then this returns Time::infinity().

template<class Ev >
 Queue::Event_handle::Handle Kinetic::Simulator::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.

 bool Kinetic::Simulator::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.

 bool Kinetic::Simulator::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.

template<class Event >
 Event_key Kinetic::Simulator::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 Kinetic::Simulator::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.

 NT Kinetic::Simulator::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.

 Event_key Kinetic::Simulator::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 Kinetic::Simulator::set_current_event_number ( unsigned int i) const

Process all events up to the ith event.

i cannot be less than current_event_number.

 void Kinetic::Simulator::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.

template<class Ev >
 Event_key Kinetic::Simulator::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.

 void Kinetic::Simulator::set_interval ( Time t_cur, Time t_end )

Set the current time to $$t_{cur}$$ and the end time to $$t_{end}$$.

The event queue must be empty. Use this method if you want to reset or extend the simulation.