Metadata-Version: 2.4
Name: cimba
Version: 0.6.1
Summary: Python bindings for Cimba, a multithreaded discrete-event-simulation C library
Keywords: simulation,discrete-event-simulation,cimba,numba
Author-Email: =?utf-8?q?Francisco_Barrag=C3=A1n_Castro?= <franbarragan87@gmail.com>
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: C
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Project-URL: Homepage, https://github.com/FBarrca/cimba_python
Project-URL: Repository, https://github.com/FBarrca/cimba_python
Project-URL: Issues, https://github.com/FBarrca/cimba_python/issues
Project-URL: Upstream C library, https://github.com/ambonvik/cimba
Requires-Python: >=3.13
Requires-Dist: cffi>=1.15
Requires-Dist: numpy>=1.20
Requires-Dist: numba>=0.57
Requires-Dist: statsmodels>=0.14
Provides-Extra: plot
Requires-Dist: matplotlib>=3.8; extra == "plot"
Requires-Dist: PySide6>=6.6; extra == "plot"
Description-Content-Type: text/markdown

![Cimba logo](docs/static/cimba_logo_large.jpg)

# Cimba Python

## Fast discrete event simulation for Python

Cimba Python is a Python interface to [Cimba](https://github.com/ambonvik/cimba),
a multithreaded discrete event simulation engine written in C and assembly.

It is designed for Python simulation models that need more speed than pure
Python event scheduling can usually provide. In the included M/M/1 benchmark,
Cimba Python runs about **24.5–31.3x faster than SimPy** after its one-time Numba
compile, while keeping model code in Python.

On an AMD Ryzen 7 9700X under WSL Ubuntu 24.04, averaged over 10 runs:

| Benchmark | SimPy | Cimba Python | Cimba C |
| --- | ---: | ---: | ---: |
| Single core, single trial | 2.856 s | 0.117 s | 0.078 s |
| Multicore, 100 trials | 38.723 s | 1.238 s | 0.800 s |

The benchmark data and charts are in
[`benchmark/AMD_Ryzen_7_9700X_WSL.ods`](benchmark/AMD_Ryzen_7_9700X_WSL.ods).

## Install

```bash
pip install cimba
```

or with `uv`:

```bash
uv add cimba
```

Python 3.13 or newer is required. The Linux, Windows, and macOS wheels embed
our fork of Cimba **3.0.0-RC2**, so you do not need to install Cimba separately. Native
macOS wheels are available for Apple Silicon. Numba does not currently publish
the required llvmlite wheels for Intel Macs.

The bindings manage the strict native object lifecycle required since Cimba
3.0.0 RC1: initialize before use, terminate after use, and destroy allocated
objects. This includes temporary statistics objects and spawned processes.
Abandoned trials also release the bindings' spawned-process registry before
the worker runs another trial. Python models do not need manual lifecycle calls.

## What is it?

Cimba Python gives Python models access to Cimba's native simulation engine
through the `cimba.sim` API: processes, event queues, buffers, queues, stores,
priority queues, resources, resource pools, conditions, timers, events, logging
helpers, and experiment tables. Random distributions live in `cimba.random`.

## What does the code look like?

```python
import cimba.sim as sim
import cimba.random as random


class MM1(sim.Model):
    utilization: sim.Param
    avg_queue_length: sim.Output
    queue: sim.Queue

    @sim.process
    def arrival(self: "MM1"):
        while True:
            sim.hold(random.exponential(1.0 / self.utilization))
            self.queue.put(1)

    @sim.process
    def service(self: "MM1"):
        while True:
            self.queue.get(1)
            sim.hold(random.exponential(1.0))

    @sim.collect
    def collect_stats(self: "MM1"):
        self.avg_queue_length = self.queue.mean_level()


model = MM1("MM1")

exp = model.experiment(
    utilization=0.75,
    replications=100,
    duration=1000.0,
    warmup=100.0,
    seed=123,
)
exp.run()

print(exp.results.avg_queue_length.mean())
```

More examples, tutorials, background notes, and the API reference are in the
[documentation](https://fbarrca.github.io/cimba_python/).

## Development

From a fresh clone:

```bash
uv sync
uv run pytest
```

## License

Cimba Python is licensed under Apache-2.0. See [`LICENSE`](LICENSE) and
[`NOTICE`](NOTICE).

The bundled Cimba C library is also Apache-2.0 licensed. See
`subprojects/cimba/NOTICE` for attribution.
