happysim 0.2.3
Discrete event simulation library for Python.
Requires Python: >=3.13
Keywords: simulation, discrete-event, event-driven, modeling, simevents

<p align="center">
  <video src="https://github.com/user-attachments/assets/a1c5ec2b-6dcc-48a3-9618-417cd9e58ed0" width="100%" autoplay loop muted playsinline></video>
</p>
<p align="center"><sub>Visuals autogenerated from <a href="examples/visual/chash_example.py">examples/visual/chash_example.py</a></sub></p>

<h1 align="center">Happy Simulator</h1>

<p align="center">
  <strong>A simulation library built for the modern world.</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/happysim/"><img src="https://img.shields.io/pypi/v/happysim" alt="PyPI" /></a>
  <a href="https://github.com/adamfilli/happy-simulator/actions/workflows/tests.yml"><img src="https://github.com/adamfilli/happy-simulator/actions/workflows/tests.yml/badge.svg" alt="Tests" /></a>
  <a href="https://adamfilli.github.io/happy-simulator/"><img src="https://github.com/adamfilli/happy-simulator/actions/workflows/docs.yml/badge.svg" alt="Docs" /></a>
  <a href="https://github.com/adamfilli/happy-simulator/blob/main/license"><img src="https://img.shields.io/badge/license-Apache--2.0-blue" alt="License" /></a>
</p>

<p align="center">
  <a href="https://adamfilli.github.io/happy-simulator/">Documentation</a> &middot;
  <a href="https://adamfilli.github.io/happy-simulator/examples/">Examples</a> &middot;
  <a href="https://adamfillion.com/posts/simulation-enhanced-reasoning/">Blog Post</a>
</p>

---

> [!WARNING]
> **Alpha** — Still in active development. Some features may not work as expected. Interfaces may change drastically.

Happy Simulator is a code-first simulation library for education, research, design, or entertainment.

## Features

- **Intuitive modeling** — convert real-world components into simulated equivalents.
- **Rich component library** — queues, load balancers, rate limiters, industrial components, behavioural models and more
- **Visual debugger** — browser-based UI generated from simulation model.
- **AI Compatible** - use your generative AI of choice to convert scenarios to simulations.

## Quick Start

```bash
pip install happysim
```

```python
from happysimulator import Simulation, Source, Sink, Server, Instant
from happysimulator.distributions import ExponentialLatency

sink = Sink()
server = Server("Server", service_time=ExponentialLatency(0.1), downstream=sink)
source = Source.poisson(rate=8, target=server)

sim = Simulation(sources=[source], entities=[server, sink], end_time=Instant.from_seconds(60))
summary = sim.run()
```

## Visual Debugger

```bash
pip install happysim[visual]
```

```python
# define sim
from happysimulator.visual import serve
serve(sim)  # opens browser at http://127.0.0.1:8765
```

Step through events, inspect entity state, and create interactive dashboards from the browser.

## Installation

```bash
pip install happysim              # core library
pip install happysim[visual]      # + browser debugger (FastAPI + uvicorn)
pip install happysim[dev]         # + testing & docs tools
```

Or install from source:

```bash
git clone https://github.com/adamfilli/happy-simulator.git
cd happy-simulator
pip install -e ".[dev]"
```

## Documentation

Full guides, API reference, and example walkthroughs at **[adamfilli.github.io/happy-simulator](https://adamfilli.github.io/happy-simulator/)**.

## License

[Apache 2.0](license)