This guide explains the functionality present in this component by describing the use of the different classes.

See package realtime in the LuciadLightspeed reference manual for more information regarding Realtime-specific classes.

The remainder of this guide makes a distinction between two different types of time:

  • real time, time as it flows in the physical world

  • simulation or simulated time, time as it flows in the simulated world.

TLcdSimulator

TLcdSimulator is the class that is responsible for the timing of the simulation: it produces the correct simulation time at each simulation step.

Associated with a TLcdSimulator are:

  • A simulator model

  • One or more layer factories

  • One or more views

The simulator model ILcdSimulatorModel is responsible for providing the TLcdSimulator with the ILcdModel objects holding the domain data to be simulated, and for putting these data in the state corresponding to a given simulation time.

For more information about the ILcdSimulatorModel, see ILcdSimulatorModel.

You can show simulations on views of type ILspView and ILcdGXYView.

The layer factories of type ILspLayerFactory and ILcdGXYLayerFactory are used by the TLcdSimulator to create layers for Lightspeed and GXY views respectively, for each of the different models that need to be simulated.

Using TLcdSimulator in a Lightspeed view

A TLcdSimulator is also capable of showing simulations in a Lightspeed view. The TLcdSimulator can be set to use specific Lightspeed views. Use the setLspView( ILspView[] ) method, or add a Lightspeed view through the addView( ILcdView ) method. However, a valid ILspLayerFactory needs to be set through the setLspLayerFactory(ILspLayerFactory) before any valid Lightspeed layers can be created for the set views.

Using TLcdSimulator in a GXY view

If the property UseSameGXYLayer is true, the TLcdSimulator will create one layer instance per model that needs to be simulated, and share this instance among the GXY views. If the property is set to false, a new layer instance is created per GXY view.

Program: Initializing a TLcdSimulator. shows a snippet. It demonstrates how to initialize a TLcdSimulator for a GXY view and how to set its simulator model and layer factory. At the end the current simulation time is set to be the begin time of the simulation.

Program: Initializing a TLcdSimulator. (from samples/realtime/gxy/tracksimulator/MainPanel) 
TLcdSimulator simulator;
simulator = new TLcdSimulator();

//Keep the simulator running at all times
simulator.setPauseOnMousePressed(false);

simulator.setGXYView(new ILcdGXYView[]{getView()});
simulator.setGXYLayerFactory(new SimulatorGXYLayerFactory());
simulator.setSimulatorModel(simulatorModel);
simulator.setDate(simulator.getBeginDate());
simulator.setDelayBetweenUpdateMs(DELAY_BETWEEN_UPDATES);

Available TLcdSimulator modes

TLcdSimulator can be used in two different modes:

Time factor mode

There is a predefined relation between real time and simulation time. This relation is defined by the property TimeFactor of the simulator. The TimeFactor gives the factor by which simulation time is accelerated with regards to real time. Setting the TimeFactor to 60 for example, will ensure that, on average, after every second that passes on your watch, 1 minute of simulated time has gone by, irrespective of the speed of your machine or how much CPU the process has available. Having a slower machine, or less CPU, will just result in a less smooth simulation, but the relation between the real and simulation time will always be respected.

This mode is used by default.

Time step mode

In this mode, there is no defined relation between real time and simulation time. The simulator will just perform a simulation at successive time-steps as fast as it can.

Turning on this mode can be done via the property UseTimeStep. The length of the time-step in simulation time is defined by the property TimeStep.

Setting maximum CPU usage

You can restrict the percentage of CPU used by a simulation through the property MaxCPUUsage.

Note that this setting is only considered an indication, not a strict value that will always be respected.

This property has no impact on the immediate CPU Usage, but only on the average CPU usage over time. During each simulation step, the full CPU power (100%) will be used. We will clarify this with an example: Suppose the MaxCPUUsage is restricted to 20%. We start the simulation and the first simulation step, using 100% CPU, takes 100ms. The second simulation step will not be started immediately after the previous one. Instead, the next step will only start after a wait of 400ms, so that, on average during these first 500ms, only 20% of the CPU was used by the simulation. When it is calculating these waiting times, the simulator uses the simplifying assumption that the CPU is not shared with any other threads or application.

All this means that you must make sure the time needed for one simulation step is relatively short. Otherwise, GUI response will be relatively poor, even if you set the MaxCPUUsage to a low value.

This property has priority over the DelayBetweenUpdateMs property when the time between updates according to the rules explained above is larger than that indicated by the DelayBetweenUpdateMs property. See Setting delays between updates for more information about DelayBetweenUpdateMs.

Setting delays between updates

The delay between updates can be set with the DelayBetweenUpdateMs property. This property controls the (real) time between consecutive simulation steps in milliseconds. As mentioned in Setting maximum CPU usage, this property is overruled by the MaxCPUUsage property.

ILcdSimulatorModel

The ILcdSimulatorModel is the class responsible for providing the TLcdSimulator with the ILcdModel objects holding the domain data to be simulated, and for putting this data in the state corresponding to a given simulation time.

TrackModels

A simulator can have only one single ILcdSimulatorModel. This does not mean that only one ILcdModel can be simulated at the same time. An ILcdSimulatorModel can encompass more than one ILcdModel. These different models are known as the TrackModels of the ILcdSimulatorModel. The simulator will create a different layer for each model returned by getTrackModels().

Updating the simulation data

It is the ILcdSimulatorModel that is responsible for updating the simulation data every time the simulation time changes. Every time the simulator performs a new simulation step, it will inform its ILcdSimulatorModel by calling setDate( Date aDate ) with the new simulation time aDate.

The ILcdSimulatorModel can either update each of its TrackModels itself, or it can delegate the new simulation time to other classes that are responsible for the actual updating of the data.

Available ILcdSimulatorModel implementations

The Real-time Engine component offers several abstract implementations of ILcdSimulatorModel to help you get started with the creation of your own implementations.

ALcdSimulatorModel

The ALcdSimulatorModel abstract class is convenient when you are implementing your own ILcdSimulatorModel, in that it deals with property change listeners and firing the required property change events.

TLcdSimulatorModelList

This class allows for the easy combination of several ILcdSimulatorModel instances together in one big ILcdSimulatorModel.Suppose you have to simulate both airplanes and ground vehicles. In this situation, it could be convenient to have one implementation of ILcdSimulatorModel that deals with the airplanes, and another one that deals with the ground vehicles. As the simulator can only handle one ILcdSimulatorModel, you can use the TLcdSimulatorModelList to combine them easily.

TLcdTimeFilteredSimulatorModel

By default, the simulator will take as begin and end time of the simulation the BeginTime and EndTime of its ILcdSimulatorModel. It is possible, however, that you are interested in only part of the full time span. Therefore, LuciadLightspeed provides a wrapper class around ILcdSimulatorModel that allows you to set the simulation interval to a sub-interval of that of the ILcdSimulatorModel. You can use the methods setBeginDate and setEndDate for this.

ALcdTimeIndexedSimulatorModel

Assume you need to simulate a very large data set, where only a small subset of the total data set is in motion at any given time, and that you are not interested in data that is not in motion. For this particular case, looping over all those objects that are not moving and that do not need to be updated anyway, can cause a considerable overhead.

ALcdTimeIndexedSimulatorModel was designed to avoid this overhead. Its time complexity for updating the data to a new time value is generally related to the amount of changes that are required, not to the total amount of data. It achieves this by indexing the begin and end times of all objects, so it does require some initial processing.