Simulations and Event Queues

The simulation context

cimba.Simulation initializes the native event queue and the thread-local random generator. Only one active simulation is supported per Python thread.

with cimba.Simulation(start_time=0.0, seed=123) as sim:
    ...

When the context exits, Cimba closes owned objects and releases native state. Objects are closed in reverse creation order, which matches the usual dependency order in a model.

Running events

execute() runs scheduled events until the queue is empty. execute_next() runs one event and returns False if there is nothing left to execute.

while sim.execute_next():
    if sim.now > 100.0:
        sim.clear()

Most models use execute() and an explicit stop condition.

Direct events

schedule(callback, when, subject=None, obj=None, priority=0) schedules a Python callback at an absolute simulation time and returns the native event handle. The callback is called as callback(subject, obj).

The returned handle can be used with cancel_event(), reschedule_event(), reprioritize_event(), is_event_scheduled(), event_time(), and event_priority(). These handle operations map directly to Cimba’s native event queue.

schedule_native() is the advanced path for Cython/native extensions that already have a cmb_event_func pointer in a cimba.event_func capsule. It keeps callback dispatch entirely native; callers are responsible for native pointer lifetimes.

Stopping

stop_at(when) schedules an event at absolute simulation time when that stops active processes and clears the event queue.

clear() immediately removes scheduled events. It is useful inside a process when the model has reached a condition that should end the current run.

Random seeds

Passing seed= makes runs reproducible. If no seed is supplied, Cimba uses a hardware-derived seed and exposes it as sim.seed_used.

with cimba.Simulation(seed=123) as sim:
    print(sim.seed_used)