Metadata-Version: 2.4
Name: happysim
Version: 0.2.5
Summary: Discrete event simulation library for Python.
Author: adamfilli
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/adamfilli/happy-simulator
Project-URL: Repository, https://github.com/adamfilli/happy-simulator
Project-URL: Issues, https://github.com/adamfilli/happy-simulator/issues
Keywords: simulation,discrete-event,event-driven,modeling,simevents
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Typing :: Typed
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pandas
Provides-Extra: visual
Requires-Dist: fastapi>=0.100; extra == "visual"
Requires-Dist: uvicorn[standard]>=0.20; extra == "visual"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Requires-Dist: mkdocs-material; extra == "dev"
Requires-Dist: mkdocstrings[python]>=0.25; extra == "dev"
Dynamic: license-file

<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 for distributed systems.</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://deepwiki.com/adamfilli/happy-simulator"><img src="https://deepwiki.com/badge.svg" alt="Ask DeepWiki"></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.

**Some articles using the library:**
- [Simulation-Enhanced Reasoning](https://adamfillion.com/posts/simulation-enhanced-reasoning/) - enhancing AI with simulation.
- [Adverse Advertising Amplification](https://adamfillion.com/posts/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

```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)
