1_minute_basic_demo.mp4

_{Visuals autogenerated from examples/visual/chash_example.py}

Happy Simulator

A simulation library for distributed systems.

Documentation · Examples · Blog Post

---

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.

Some articles using the library:

• Simulation-Enhanced Reasoning - enhancing AI with simulation.
• Adverse Advertising Amplification - consumer behaviour simulation.

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

pip install happysim

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

pip install happysim[visual]

# 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

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

Or install from source:

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.

License

Apache 2.0