Core

cimba.native_version()

Return the version string reported by the bundled Cimba C library.

cimba.run_experiment(trial_fn, n=None, *, seed=None, seeds=None, backend='process', processes=None)

Run independent replications of trial_fn(index, seed) and return results indexed by replication.

The default backend="process" uses forked worker processes and is recommended for Python-defined simulations. Return pickleable values such as floats, tuples, or dictionaries. processes controls the worker count and defaults to multiprocessing.Pool behavior.

backend="thread" uses Cimba’s native pthread worker pool inside one Python process. It can return in-process native Cimba objects and only parallelizes on free-threaded Python builds; GIL-enabled interpreters run the trials serially with a warning.

cimba.run_native_experiment(experiment_buffer, trial_struct_size, trial_func_capsule)

Run native Cimba pthread replications over a writable C-contiguous trial buffer using a cimba.trial_func capsule. Python callables are rejected.

cimba.set_native_thread_hooks(init_capsule=None, user_arg_capsule=None, exit_capsule=None)

Set native pthread init/user-context/exit hook capsules, or clear them by calling with no arguments.

cimba.time()

Return the current simulation clock time for the active event queue.

class cimba.Simulation(start_time=0.0, seed=None, log_info=False)

Own the thread-local Cimba event queue, simulation clock, and random generator. Use it as a context manager.

seed_used

Seed used to initialize the PRNG stream.

closed

Whether native simulation state has been released.

now

Current simulation time.

event_count

Number of scheduled future events.

current_event

Handle of the currently or most recently executed event.

stop_at(when, priority=0)

Schedule cooperative cancellation of owned Python processes, then stop the run at absolute simulation time when.

schedule(callback, when, subject=None, obj=None, priority=0)

Schedule callback(subject, obj) at absolute simulation time when. This is a Python-dispatch event; native queue ordering and handle lookup still stay in C.

schedule_native(action_capsule, when, subject_capsule=None, object_capsule=None, priority=0)

Schedule a native cmb_event_func from a cimba.event_func capsule. The caller owns any native subject/object pointer lifetimes.

cancel_event(handle)

Cancel a scheduled event by handle and return whether it was found.

reschedule_event(handle, when)

Move a scheduled event to another absolute simulation time.

reprioritize_event(handle, priority)

Change a scheduled event’s priority.

is_event_scheduled(handle)

Return whether the event handle is still scheduled.

event_time(handle)

Return the scheduled absolute time for an event.

event_priority(handle)

Return the scheduled priority for an event.

clear()

Clear scheduled events, ending the current run.

execute_next()

Execute one event and return False if the event queue is empty.

execute()

Run until the event queue is empty.

close()

Cooperatively cancel owned running processes and release Cimba’s thread-local state.