kansim 0.1.0__tar.gz

kansim-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Others
+results/

kansim-0.1.0/PKG-INFO

@@ -0,0 +1,239 @@
+Metadata-Version: 2.4
+Name: kansim
+Version: 0.1.0
+Summary: Add your description here
+Project-URL: Homepage, https://github.com/kdqed/kansim
+Project-URL: Issues, https://github.com/kdqed/kansim/issues
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=2.4.3
+Requires-Dist: pandas>=3.0.1
+Requires-Dist: plotly-express>=0.4.1
+Requires-Dist: scipy>=1.17.1
+
+# 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

kansim-0.1.0/README.md

@@ -0,0 +1,226 @@
+# 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

kansim-0.1.0/examples/poker_hand_equity.py

@@ -0,0 +1,57 @@
+import random
+from kansim import Simulation, Boolean
+
+RANKS = "23456789TJQKA"
+SUITS = "cdhs"
+DECK = [r + s for r in RANKS for s in SUITS]
+
+RANK_ORDER = {r: i for i, r in enumerate(RANKS)}
+
+def deal(deck, n):
+    hand = random.sample(deck, n)
+    for c in hand:
+        deck.remove(c)
+    return hand
+
+def best_hand_rank(cards):
+    """Returns a comparable tuple representing the best 5-card hand rank."""
+    from itertools import combinations
+    return max(_hand_rank(h) for h in combinations(cards, 5))
+
+def _hand_rank(hand):
+    ranks = sorted([RANK_ORDER[c[0]] for c in hand], reverse=True)
+    suits = [c[1] for c in hand]
+    flush = len(set(suits)) == 1
+    straight = (ranks[0] - ranks[4] == 4 and len(set(ranks)) == 5) or ranks == [12, 3, 2, 1, 0]
+    counts = sorted([ranks.count(r) for r in set(ranks)], reverse=True)
+    if straight and flush:  return (8, ranks)
+    if counts[0] == 4:      return (7, ranks)
+    if counts[:2] == [3,2]: return (6, ranks)
+    if flush:               return (5, ranks)
+    if straight:            return (4, ranks)
+    if counts[0] == 3:      return (3, ranks)
+    if counts[:2] == [2,2]: return (2, ranks)
+    if counts[0] == 2:      return (1, ranks)
+    return (0, ranks)
+
+class PokerHandEquity(Simulation):
+
+    def __init__(self):
+        deck = DECK.copy()
+
+        self.hole1, self.hole2 = deal(deck, 2), deal(deck, 2)
+        community = deal(deck, 5)
+
+        best1 = best_hand_rank(self.hole1 + community)
+        best2 = best_hand_rank(self.hole2 + community)
+
+        self.player1_wins = best1 > best2
+        self.player2_wins = best2 > best1
+        self.split =        best1 == best2
+
+        self.hole1 = " ".join(self.hole1)
+        self.hole2 = " ".join(self.hole2)
+
+result = PokerHandEquity.run(n=10_000, seed=42)
+print(result.df[["player1_wins", "player2_wins", "split"]].mean().round(3))
+result.plot_histogram("player1_wins")

kansim-0.1.0/examples/startup_runway.py

@@ -0,0 +1,34 @@
+from kansim import Simulation, Normal, Triangular, LogNormal, Boolean
+
+class StartupRunway(Simulation):
+
+    def __init__(self):
+        # Financials
+        self.initial_cash = 500_000
+        self.monthly_burn = Normal(mean=45_000, std=8_000)
+        self.monthly_revenue = LogNormal(mean=20_000, std=12_000)
+
+        # Growth
+        self.revenue_growth_rate = Triangular(min=0.02, most_likely=0.08, max=0.20)
+        self.churn_rate = Triangular(min=0.02, most_likely=0.06, max=0.15)
+
+        # Events
+        self.raised_bridge_round = Boolean(p=0.3)
+        self.bridge_amount = Normal(mean=150_000, std=50_000) if self.raised_bridge_round else 0
+        self.lost_anchor_customer = Boolean(p=0.2)
+        self.anchor_revenue_loss = Normal(mean=8_000, std=2_000) if self.lost_anchor_customer else 0
+
+        # Derived
+        net_revenue = self.monthly_revenue - self.anchor_revenue_loss
+        net_monthly_burn = self.monthly_burn - net_revenue
+        total_cash = self.initial_cash + self.bridge_amount
+
+        self.runway_months = total_cash / net_monthly_burn if net_monthly_burn > 0 else 999
+        self.default_risk = self.runway_months < 12
+        self.healthy = self.runway_months > 18
+
+
+if __name__=="__main__":
+    result = StartupRunway.run(n=10_000, seed=42)
+    result.plot_histogram("runway_months")
+    result.plot_tornado(target="runway_months")

kansim-0.1.0/examples/water_treatment_plant.py

@@ -0,0 +1,20 @@
+from kansim import *
+
+class WaterTreatmentPlant(Simulation):
+
+    def __init__(self):
+        self.flow_rate = Normal(mean=1000, std=50)
+        self.removal_efficiency = Beta(successes=9, failures=1)
+        self.operating_cost = Triangular(min=0.10, most_likely=0.15, max=0.25)
+
+        treated = self.flow_rate * self.removal_efficiency
+        self.treated_volume = treated
+        self.daily_cost = treated * self.operating_cost
+        self.pass_rate = treated > 900
+
+        
+if __name__ == "__main__":
+    result = WaterTreatmentPlant.run(n=10_000, seed=42)
+    print(result)
+    print(result.result_id)
+    print(result.df.describe())