# kansim

**Monte Carlo simulations as code. Free, open, and AI-ready.**

---

## Why simulation software should be free and open

Simulation models inform some of the most consequential decisions in engineering, finance, environment, and public health. Yet the tools used to build them are often expensive, proprietary, and locked behind GUIs that make models opaque and hard to reproduce.

This creates a problem: **a model you cannot read is a model you cannot trust.**

When simulation is code:

- **It is auditable.** Anyone can read, review, and challenge the assumptions.
- **It is reproducible.** Run the same model anywhere, any time, and get the same results.
- **It can be version-controlled.** Every change is tracked. You can see who changed what and why.
- **It is composable.** Models can import each other, share logic, and be tested like software.
- **It is free.** No license fees. No vendor lock-in. No expiry dates.

Science and engineering move faster when knowledge is shared. Simulation tooling should be no different.

---

## Why code beats a GUI

GUI simulation tools are approachable but they impose a ceiling. As models grow in complexity, the visual interface becomes the bottleneck: hard to navigate, impossible to diff, and painful to automate.

Code has no such ceiling.

```python
from kansim import Simulation, Normal, Triangular, LogNormal, Boolean

class StartupRunway(Simulation):

    def __init__(self):
        self.monthly_burn     = Normal(mean=45_000, std=8_000)
        self.monthly_revenue  = LogNormal(mean=20_000, std=12_000)
        self.raised_bridge    = Boolean(p=0.3)
        self.bridge_amount    = Normal(mean=150_000, std=50_000) if self.raised_bridge else 0

        net_burn = self.monthly_burn - self.monthly_revenue
        self.runway_months = (500_000 + self.bridge_amount) / net_burn if net_burn > 0 else 999
        self.default_risk  = self.runway_months < 12

result = StartupRunway.run(n=10_000, seed=42)
print(result.df.describe())
result.plot_tornado(target="runway_months")
```

This is the entire model. It fits in a code review. It runs in CI. It can be parameterized, tested, and shipped as a package.

---

## Installation

```bash
pip install kansim
```

Or 

```bash
uv add kansim
```

Or clone and run examples directly with [uv](https://github.com/astral-sh/uv):

```bash
git clone https://github.com/kansim/kansim
cd kansim
uv run examples/startup_runway.py
```

---

## How it works

Subclass `Simulation`. Assign inputs using distribution functions and compute outputs — all inside `__init__`. Call `.run(n=)` to get a `SimulationResult`.

```python
from kansim import Simulation, Triangular, Normal

class BridgeFatigue(Simulation):

    def __init__(self):
        self.daily_load    = Normal(mean=500, std=80)        # tonnes
        self.material_life = Triangular(min=40, most_likely=60, max=90)  # years
        self.cycles        = self.daily_load * 365
        self.failure_risk  = self.cycles > self.material_life * 150_000

result = BridgeFatigue.run(n=10_000, seed=42)
result.plot_histogram("material_life")
result.plot_tornado(target="failure_risk")
```

All results write to `results/<timestamp>/`. Pass `save="file.png"` to any plot to save instead of show.

```python
result.result_id          # "2024-03-10_143022"
result.df                 # pandas DataFrame — filter and pass back to any plot
result.save_csv()
result.save_parquet()
result.plot_histogram("col", save="hist.png")
result.plot_cdf("col")
result.plot_scatter("x", "y")
result.plot_tornado(target="col")

# filtered plots
passing = result.df[result.df.failure_risk == False]
result.plot_histogram("material_life", df=passing, save="safe_only.png")
```

---

## Distributions

| Function | Parameters |
|---|---|
| `Normal` | `mean, std, min=None, max=None` |
| `LogNormal` | `mean, std, min=None, max=None` |
| `Uniform` | `min, max, log=False` |
| `Triangular` | `min, most_likely, max` |
| `BetaPERT` | `min, most_likely, max` |
| `Beta` | `successes, failures` → 0–1 range |
| `GeneralizedBeta` | `mean, std, min, max` |
| `Exponential` | `mean` |
| `Gamma` | `mean, std, min=None, max=None` |
| `Weibull` | `scale, shape, min=0, max=None` |
| `Pareto` | `shape, mode, max=None` |
| `Poisson` | `expected` |
| `Binomial` | `n, p` |
| `NegativeBinomial` | `successes, p` |
| `StudentT` | `df` |
| `PearsonIII` | `location, scale, shape` |
| `ExtremeValue` | `location, scale` |
| `Discrete` | `values=[], probs=[]` |
| `Cumulative` | `values=[], probs=[]` |
| `SampledResults` | `values=[]` |
| `Boolean` | `p` |

---

## Using AI to generate simulations

kansim is designed to be written by humans or AI agents. The model structure is simple enough that a language model can draft a complete, runnable simulation from a plain English description.

### Instructions for an AI agent

Paste the following into your system prompt or alongside your request:

---

> Use the kansim framework by subclassing `Simulation` and assigning all variables in `__init__`.
> Inputs use distribution functions, outputs are computed from them. Everything assigned to `self` becomes a DataFrame column.
>
> ```python
> from kansim import Simulation, Normal, Triangular, Beta
>
> class MyModel(Simulation):
>     def __init__(self):
>         self.input_a = Normal(mean=100, std=10)
>         self.input_b = Triangular(min=1, most_likely=2, max=5)
>         self.output_x = self.input_a * self.input_b
>
> result = MyModel.run(n=10_000, seed=42)  
> ```
>
> `run()` returns a `SimulationResult` with:
> - `result.result_id` — human readable timestamp e.g. `"2024-03-10_143022"`
> - `result.df` — pandas DataFrame of all runs
> - `result.save_csv()`, `result.save_parquet()` — saves to `results/<result_id>/`
> - `result.plot_histogram(col, df=None, save=None)`
> - `result.plot_cdf(col, df=None, save=None)`
> - `result.plot_scatter(x, y, df=None, save=None)`
> - `result.plot_tornado(target, df=None, save=None)`
>
> All plots accept an optional `df` argument for filtered/modified DataFrames.
> All saves write to `results/<result_id>/` — pass `save="filename.png"` to save instead of show.
>
> Available distributions:
> `Normal(mean, std, min=None, max=None)`,
> `LogNormal(mean, std, min=None, max=None)`,
> `Uniform(min, max, log=False)`,
> `Triangular(min, most_likely, max)`,
> `BetaPERT(min, most_likely, max)`,
> `Beta(successes, failures)`,
> `GeneralizedBeta(mean, std, min, max)`,
> `Exponential(mean)`,
> `Gamma(mean, std, min=None, max=None)`,
> `Weibull(scale, shape, min=0, max=None)`,
> `Pareto(shape, mode, max=None)`,
> `Poisson(expected)`,
> `Binomial(n, p)`,
> `NegativeBinomial(successes, p)`,
> `StudentT(df)`,
> `PearsonIII(location, scale, shape)`,
> `ExtremeValue(location, scale)`,
> `Discrete(values=[], probs=[])`,
> `Cumulative(values=[], probs=[])`,
> `SampledResults(values=[])`,
> `Boolean(p)`.

---

### Example prompt

> Using kansim, simulate the cost overrun risk for a construction project. Inputs should include labor cost, material cost, and weather delay days. Output should include total cost and whether the project exceeds budget.

The AI will return a complete, runnable Python file.

---

## Examples

| File | Description |
|---|---|
| `examples/startup_runway.py` | Startup cash runway under uncertain growth and events |
| `examples/poker_hand_equity.py` | Heads-up poker equity over 10,000 deals |
| `examples/water_treatment_plant.py` | Water treatment plant throughput and cost |

---

## License

MIT