Censor Event Time

Home > Model Development Topics > Censor Event Time

The censor_event_time option enables a model-specific optimization which can reduce event queue size and improve simulation speed.

Related topics

• Model Code

Topic contents

• Introduction and Background
• Syntax and Use How to activate and use
• Modgen-specific Modgen issues Coding approaches for a x-compatible model

Introduction and Background

An event in an entity has an associated future time when the event will occur, provided that other intervening events do not affect that future time due to a change in attributes. If the event is represented as a hazard, code in the event time function might draw a random time to the event from an exponential distribution, like

tEventTime = WAIT( - log( RandUniform(1) ) / EventHazard );

or from some other distribution if the hazard is non-constant.

If the hazard of the event is small, the associated distribution of time-to-event will have a long tail, and the probability of drawing a time far in the future will be high. A future event time drawn from that distribution may even exceed the maximum lifespan of the entity.

If an event time exceeds the maximum lifespan of the entity, it does not need to compete with other events in the simulation because it will never occur. The event is in effect 'right-censored' by the entity's maximum lifespan.

The simulation framework arranges all the events of a model by time-to-occurrence in an event queue, and maintains that ordered queue as the simulation evolves and event times change. The work to maintain the event queue is reduced if right-censored events do not have to be inserted into their correct ordered position in the queue. Leaving out censored events also reduces the total size of the event queue, making all queue operations more efficient. Excluding right-censored events from the queue has no effect on the simulation because they are guaranteed not to occur.

Models with many rare events can gain a noticeable performance boost with event censoring. That's because a rare event occurs only rarely because its randomly drawn event time is usually far in the entity’s future. In a test with one such model, simulation time decreased by 17% with the censor_event_time option activated.

Independent of the censor_event_time option, an event with a future time of time_infinite will not be entered into the event queue because the event will never occur. In a sense, the censor_event_time option can be thought of as a generalization of this behaviour.

[back to topic contents]

Syntax and Use

The censor_event_time option activates the ability to specify, for each entity, a 'right-censor' time after which the entity is guaranteed to have left the simulation. By default, the option is off. To turn it on, insert the following options statement in a source code module:

options censor_event_time = on;

A natural place to insert this statement could be the module ompp_framework.ompp.

If an event time exceeds the right-censor time, the simulation framework will not insert the event into the event queue, improving efficiency. The right-censor test is redone whenever an event time changes during the simulation.

To specify the right-censor time for an entity, supply it as argument to the built-in entity function set_censor_time before the entity enters the simulation. If the censor time is based on other attributes such as time or age, ensure that they are assigned before the call to set_censor_time.

If the censor_event_time option is off, a call to the function set_censor_time has no effect.

If the censor_event_time option is on and the function set_censor_time is not called, the right-censor time is set to time_infinite.

Here's an example. Consider a model with two parameters, MaxLife and MaxYear. An event in the model uses MaxLife to stop the simulation of an entity when age attains the value MaxLife, which might, for example, be 119. Another event truncates the simulation of all entities when time attains the value MaxYear.

In this example, the right-censor time is set to the minimum of these two censoring events in the initialization function Person::Start as follows:

// Event time censoring optimization requires the following call
// and also activating the option censor_event_time in ompp_framework.ompp.
// It is certain that Person will leave the simulation at age MaxLife, or at year MaxYear,
// whichever comes first.
set_censor_time(std::min(WAIT(MaxLife), MaxYear));

The censor_event_time optimization is valid only if the guarantee promised by the call to set_censor_time is correct. A model developer can probe the correctness of the guarantee by running the model with censor_event_time turned off, then on, and verifying that model outputs are identical in the two runs, perhaps by using the test_models utility. Such a test can also measure the efficiency gain by examining the model run log files for the two runs.

[back to topic contents]

Modgen issues

A Modgen model does not contain the built-in entity function set_censor_time, so a Modgen build will fail with a symbol not defined error in the link phase of the build. This can be avoided by supplying a 'do nothing' global function with that name when building the Modgen version of a model. That can be done by inserting the following code fragment in the model source file custom.h:

#if defined(MODGEN)
// Function to set censor time in ompp.
// Supply do-nothing global function to avoid symbol not found at link stage in Modgen build.
inline void set_censor_time(double t)
{
}
#endif

[back to topic contents]