CGAL 4.7 - Kinetic Framework: Kinetic::Simulator Concept Reference

\( \newcommand{\E}{\mathrm{E}} \) \( \newcommand{\A}{\mathrm{A}} \) \( \newcommand{\R}{\mathrm{R}} \) \( \newcommand{\N}{\mathrm{N}} \) \( \newcommand{\Q}{\mathrm{Q}} \) \( \newcommand{\Z}{\mathrm{Z}} \) \( \def\ccSum #1#2#3{ \sum_{#1}^{#2}{#3} } \def\ccProd #1#2#3{ \sum_{#1}^{#2}{#3} }\)

CGAL 4.7 - Kinetic Framework

All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Groups Pages
List of all members | Classes
Kinetic::Simulator Concept Reference
Main Concepts

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

See Also
  `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

concept | Event
| 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...
concept | Time
| 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

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

## 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<Ev>::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.