rasad-sim 0.1.0__py3-none-any.whl

rasad/__init__.py

@@ -0,0 +1,84 @@
+"""Rasad — measuring the variability of simulation results."""
+
+from collections.abc import Callable
+from typing import Any
+
+from rasad.adapter import split_outputs
+from rasad.analyzer import (
+    THRESHOLDS,
+    classify,
+    divergence,
+    summarize,
+    validate_thresholds,
+)
+from rasad.report import Report
+from rasad.runner import run_all
+from rasad.sampler import make_plan
+
+__all__ = ["measure", "Report"]
+
+
+def measure(
+    fn: Callable[..., dict],
+    params: dict[str, Any],
+    runs: int = 100,
+    base_seed: int = 0,
+    thresholds: dict[str, float] | None = None,
+) -> Report:
+    """Measure the variability of a simulation model's output.
+
+    Parameters
+    ----------
+    fn
+        A model matching the simulation interface
+        ``def run(params: dict, seed: int) -> dict``.
+    params
+        The simulation parameters, fixed across every run.
+    runs
+        How many runs to make. Must be at least 2.
+    base_seed
+        The seed of the first run; run ``i`` gets ``base_seed + i``.
+    thresholds
+        The classification cutoffs. ``None`` means use the default
+        :data:`rasad.analyzer.THRESHOLDS`. These values are a convention
+        the caller owns — they describe what counts as "low" /
+        "moderate" / "high" variability for this measurement and are not
+        derived from the data. A supplied dict is validated before any run.
+
+    Returns
+    -------
+    Report
+        Per scalar output its summary plus a variability label, per series
+        output its divergence curve, the run count, and the thresholds used.
+
+    Raises
+    ------
+    ValueError
+        When ``runs`` is below 2, or when ``thresholds`` fails
+        :func:`rasad.analyzer.validate_thresholds`.
+    """
+    if thresholds is None:
+        thresholds = THRESHOLDS
+    thresholds = validate_thresholds(thresholds)
+
+    plan = make_plan(params, runs, base_seed)
+    results = run_all(fn, plan)
+
+    scalar_values: dict[str, list[float]] = {}
+    series_curves: dict[str, list[list[float]]] = {}
+    for out in results:
+        scalars, series = split_outputs(out)
+        for name, value in scalars.items():
+            scalar_values.setdefault(name, []).append(value)
+        for name, curve in series.items():
+            series_curves.setdefault(name, []).append(curve)
+
+    scalars: dict[str, dict[str, Any]] = {}
+    for name, values in scalar_values.items():
+        stats = summarize(values)
+        stats["variability"] = classify(stats["cv"], thresholds)
+        scalars[name] = stats
+
+    series = {name: divergence(curves) for name, curves in series_curves.items()}
+
+    return Report(scalars=scalars, series=series, runs=runs, thresholds=thresholds)

rasad/adapter.py

@@ -0,0 +1,133 @@
+"""Check that a user model fits the required interface and sort its output.
+
+A model is any plain function matching the required simulation
+interface::
+
+    def run(params: dict, seed: int) -> dict: ...
+
+This module validates that a candidate function actually has those two
+parameters, and splits a returned result dict into scalar results (a
+single final number) and time series (lists of numbers), rejecting
+anything a simulation should never produce.
+
+Numpy scalars of numeric dtype and one-dimensional numpy arrays of
+numeric dtype are accepted and converted to plain Python values.
+Booleans are never accepted, whether Python ``bool`` or ``numpy.bool_``.
+"""
+
+import inspect
+from collections.abc import Callable
+from typing import Any
+
+import numpy as np
+
+
+def validate_model(fn: Callable[..., dict]) -> None:
+    """Check that a function matches the required model interface.
+
+    Parameters
+    ----------
+    fn
+        The candidate model, expected to accept exactly ``params`` and
+        ``seed`` as its first two parameters.
+
+    Raises
+    ------
+    TypeError
+        When ``fn`` is not callable, or when its first two parameter
+        names are not exactly ``("params", "seed")``.
+    """
+    if not callable(fn):
+        raise TypeError(f"model must be callable, got {type(fn).__name__}")
+
+    names = [p.name for p in inspect.signature(fn).parameters.values()][:2]
+    if names != ["params", "seed"]:
+        raise TypeError(
+            f"model must accept (params, seed) as its first two arguments, got ({', '.join(names)})"
+        )
+
+
+def _is_number(value: Any) -> bool:
+    """True for a real number — never for a boolean, of either flavour.
+
+    ``isinstance(True, int)`` is True in Python and ``np.bool_`` is a numpy
+    scalar, so both must be excluded before any numeric test.
+    """
+    if isinstance(value, (bool, np.bool_)):
+        return False
+    if isinstance(value, (int, float)):
+        return True
+    return isinstance(value, np.generic) and np.issubdtype(value.dtype, np.number)
+
+
+def split_outputs(out: dict[str, Any]) -> tuple[dict[str, float], dict[str, list[float]]]:
+    """Split a model result into scalar results and time series.
+
+    Parameters
+    ----------
+    out
+        The dict returned by a model run. Each value must be a number
+        (a scalar result) or a list/tuple of numbers (a time series).
+        Numpy scalars of numeric dtype and zero-dimensional numpy arrays
+        of numeric dtype count as numbers; one-dimensional numpy arrays
+        of numeric dtype count as time series.
+
+    Returns
+    -------
+    tuple[dict[str, float], dict[str, list[float]]]
+        ``(scalars, series)``: scalars holds each single-number output
+        as a plain ``float``, series holds each sequence output as a
+        ``list[float]``.
+
+    Raises
+    ------
+    TypeError
+        When a value is a ``bool`` or ``numpy.bool_``, a ``str``,
+        ``bytes``, or any other type that is neither a single number
+        nor a sequence of numbers, including numpy arrays with two or
+        more dimensions and arrays of boolean or object dtype.
+    """
+    scalars: dict[str, float] = {}
+    series: dict[str, list[float]] = {}
+
+    for key, value in out.items():
+        if isinstance(value, (bool, np.bool_)):
+            raise TypeError(f"unsupported output {key!r}: boolean values are not allowed")
+        if isinstance(value, np.ndarray):
+            if value.ndim == 0 and np.issubdtype(value.dtype, np.number):
+                scalars[key] = float(value)
+            elif value.ndim == 1 and np.issubdtype(value.dtype, np.number):
+                series[key] = [float(item) for item in value]
+            elif np.issubdtype(value.dtype, np.bool_):
+                raise TypeError(
+                    f"unsupported output {key!r}: boolean arrays are not allowed"
+                )
+            else:
+                raise TypeError(
+                    f"unsupported output {key!r}: numpy array with dtype "
+                    f"{value.dtype} and {value.ndim} dimension(s) is not supported"
+                )
+        elif isinstance(value, (int, float)) or (
+            isinstance(value, np.generic) and np.issubdtype(value.dtype, np.number)
+        ):
+            scalars[key] = float(value)
+        elif isinstance(value, (list, tuple)):
+            # Every element is checked: a list of booleans or strings would
+            # otherwise pass silently and produce statistics over numbers
+            # that mean nothing.
+            bad = next(
+                ((i, v) for i, v in enumerate(value) if not _is_number(v)), None
+            )
+            if bad is not None:
+                index, item = bad
+                raise TypeError(
+                    f"unsupported output {key!r}: element {index} is "
+                    f"{type(item).__name__}, not a number"
+                )
+            series[key] = [float(item) for item in value]
+        else:
+            raise TypeError(
+                f"unsupported output {key!r}: must be a number or a sequence of numbers"
+            )
+
+    return scalars, series

rasad/adapters/omran.py

@@ -0,0 +1,70 @@
+"""Wrap Omran from the outside so Rasad can measure it.
+
+This file lives in the Rasad repository. It imports Omran's ``nation`` and
+``world`` modules by putting Omran's ``src`` directory on ``sys.path`` at
+call time, and drives Omran purely through its public interface. Nothing
+inside the Omran project is created, modified, or deleted.
+"""
+
+import contextlib
+import io
+import random
+import sys
+from collections.abc import Callable
+
+
+def make_omran_run(omran_src: str, years: int) -> Callable[[dict, int], dict]:
+    """Build a Rasad-compatible model function that runs Omran.
+
+    Parameters
+    ----------
+    omran_src
+        Absolute path to Omran's ``src`` directory. It is inserted at the
+        front of ``sys.path`` if not already present, so that ``nation``
+        and ``world`` can be imported from outside the Omran project.
+    years
+        How many simulated years each run performs.
+
+    Returns
+    -------
+    Callable[[dict, int], dict]
+        A closure ``run(params, seed)`` that seeds Python's global RNG,
+        builds a fresh set of nations, steps Omran's ``WorldModel`` for
+        ``years`` years with stdout suppressed, and returns Omran's output
+        as scalars plus a population trace.
+    """
+    if omran_src not in sys.path:
+        sys.path.insert(0, omran_src)
+
+    from nation import Nation
+    from world import WorldModel
+
+    def run(params: dict, seed: int) -> dict:
+        random.seed(seed)
+
+        nations = [
+            Nation(name="Nation_A", population=500, food=2000, growth_rate=0.03),
+            Nation(name="Nation_B", population=80, food=2000, growth_rate=0.035),
+            Nation(name="Nation_C", population=200, food=2000, growth_rate=0.032),
+        ]
+
+        population_trace = []
+        with contextlib.redirect_stdout(io.StringIO()):
+            world = WorldModel(nations)
+            for _ in range(years):
+                world.step()
+                population_trace.append(
+                    sum(n.population for n in world.nations if n.is_alive)
+                )
+
+        return {
+            "final_total_population": float(
+                sum(n.population for n in world.nations if n.is_alive)
+            ),
+            "survivors": float(sum(1 for n in world.nations if n.is_alive)),
+            "total_wars": float(sum(n.war_count for n in world.nations)),
+            "total_famines": float(sum(n.famine_count for n in world.nations)),
+            "population_trace": [float(value) for value in population_trace],
+        }
+
+    return run

rasad/analyzer.py

@@ -0,0 +1,178 @@
+"""Arithmetic on sequences of numbers, nothing more.
+
+This module knows nothing about simulations or how the numbers it is
+given were produced. It only describes the spread and location of a
+sample: count, mean, sample standard deviation, coefficient of
+variation, extrema, and percentile interval.
+"""
+
+import math
+from collections.abc import Sequence
+
+import numpy as np
+
+# Default classification cutoffs. These are a convention chosen by the
+# project's authors, not a derived or theoretical result: a caller may
+# pass their own thresholds to ``classify`` and ``rasad.measure``, in
+# which case these defaults are ignored.
+THRESHOLDS: dict[str, float] = {"low": 0.05, "moderate": 0.20}
+
+
+def summarize(values: Sequence[float]) -> dict[str, float | int]:
+    """Summarize a sample of numbers.
+
+    Parameters
+    ----------
+    values
+        A sequence of numeric values, e.g. repeated simulation runs.
+
+    Returns
+    -------
+    dict
+        Keys ``n``, ``mean``, ``std``, ``cv``, ``min``, ``max``, ``p05``, ``p95``.
+        ``std`` is the sample standard deviation (``ddof=1``); ``cv`` is
+        ``std / abs(mean)``; it is zero whenever ``std`` is zero, and
+        infinite when the mean is zero but the values still vary.
+
+    Raises
+    ------
+    ValueError
+        When fewer than two values are provided.
+    """
+    arr = np.asarray(values, dtype=float)
+    if arr.size < 2:
+        raise ValueError("need at least 2 values to summarize")
+    if not np.isfinite(arr).all() :
+        raise ValueError("non-finite values")
+
+    n = int(arr.size)
+    mean = float(arr.mean())
+    std = float(arr.std(ddof=1))
+    # The order of these checks is deliberate: zero spread means a fully
+    # determined value whatever the mean. Without this, an output constantly
+    # at zero would be classified "high" when it is the most stable one
+    # there is.
+    if std == 0.0:
+        cv = 0.0
+    elif mean == 0.0:
+        cv = math.inf
+    else:
+        cv = std / abs(mean)
+    p05 = float(np.percentile(arr, 5))
+    p95 = float(np.percentile(arr, 95))
+
+    return {
+        "n": n,
+        "mean": mean,
+        "std": std,
+        "cv": cv,
+        "min": float(arr.min()),
+        "max": float(arr.max()),
+        "p05": p05,
+        "p95": p95,
+    }
+
+
+def validate_thresholds(thresholds: dict[str, float]) -> dict[str, float]:
+    """Check caller-supplied classification cutoffs and copy them.
+
+    The thresholds are a convention, not a measured property of the data,
+    so whatever the caller passes is taken as-is once it passes these
+    checks.
+
+    Parameters
+    ----------
+    thresholds
+        A dict with exactly the keys ``low`` and ``moderate``. Both
+        values must be finite numbers greater than 0, and ``low``
+        must be strictly below ``moderate``.
+
+    Returns
+    -------
+    dict[str, float]
+        A plain-float copy of ``thresholds``, so mutating the caller's
+        dict afterwards cannot change the classification.
+
+    Raises
+    ------
+    ValueError
+        When the keys, the positivity/finiteness, or the ordering of the
+        values do not satisfy the rules above.
+    """
+    keys = set(thresholds)
+    if keys != {"low", "moderate"}:
+        raise ValueError(
+            f"thresholds must have exactly the keys 'low' and 'moderate', got {sorted(keys)}"
+        )
+    low = thresholds["low"]
+    moderate = thresholds["moderate"]
+    for name, value in (("low", low), ("moderate", moderate)):
+        if not (math.isfinite(value) and value > 0):
+            raise ValueError(f"{name} threshold must be a finite positive number, got {value!r}")
+    if not low < moderate:
+        raise ValueError("low must be below moderate")
+    return {"low": float(low), "moderate": float(moderate)}
+
+
+def classify(cv: float, thresholds: dict[str, float] | None = None) -> str:
+    """Label a coefficient of variation by its variability cutoff.
+
+    Parameters
+    ----------
+    cv
+        The coefficient of variation of a sample.
+    thresholds
+        The classification cutoffs. ``None`` means use the module-level
+        :data:`THRESHOLDS` default; any other dict is validated with
+        :func:`validate_thresholds` first.
+
+    Returns
+    -------
+    str
+        ``"low"`` below the low threshold, ``"moderate"`` up to and
+        including the moderate threshold, ``"high"`` beyond it.
+    """
+    # kept as if/else rather than a ternary: the two branches do different
+    # things — one picks a default, the other validates untrusted input.
+    if thresholds is None:  # noqa: SIM108
+        thresholds = THRESHOLDS
+    else:
+        thresholds = validate_thresholds(thresholds)
+    if cv < thresholds["low"]:
+        return "low"
+    if cv <= thresholds["moderate"]:
+        return "moderate"
+    return "high"
+
+
+def divergence(series: Sequence[Sequence[float]]) -> list[float]:
+    """Measure how far apart a set of time series has drifted by time step.
+
+    At each time step the runs are treated as a sample and the sample
+    standard deviation is taken across runs; a flat zero curve means the
+    runs agree, a growing curve means they are drifting apart.
+
+    Parameters
+    ----------
+    series
+        A sequence of equal-length time series, one per simulation run.
+
+    Returns
+    -------
+    list[float]
+        One sample standard deviation per time step, across runs.
+
+    Raises
+    ------
+    ValueError
+        When fewer than two series are provided, or when the series do
+        not all have the same length.
+    """
+    rows = [np.asarray(row, dtype=float) for row in series]
+    if len(rows) < 2:
+        raise ValueError("need at least 2 series to measure divergence")
+    if any(len(row) != len(rows[0]) for row in rows):
+        raise ValueError("all series must have the same length")
+
+    stack = np.stack(rows)
+    return [float(std) for std in stack.std(axis=0, ddof=1)]

rasad/report.py

@@ -0,0 +1,136 @@
+"""Presentation of a measurement, and nothing else.
+
+This is the only module concerned with how a measurement is shown to a
+human. No assumption about the command line may leak below it: a future
+web layer becomes a second view over the same data, built from the same
+:class:`Report`.
+"""
+
+import math
+from typing import Any
+
+import plotly.graph_objects as go
+
+# Fixed precision so two runs with the same seeds render byte-identically.
+_VALUE_DECIMALS = 2
+_RATIO_DECIMALS = 4
+
+
+def _fmt(value: float) -> str:
+    """Format a magnitude — grouped thousands, fixed decimals, inf-safe."""
+    if math.isinf(value):
+        return "inf"
+    return f"{value:,.{_VALUE_DECIMALS}f}"
+
+
+def _fmt_ratio(value: float) -> str:
+    """Format a dimensionless ratio, which needs more decimals than a magnitude."""
+    if math.isinf(value):
+        return "inf"
+    return f"{value:.{_RATIO_DECIMALS}f}"
+
+
+class Report:
+    """The result of measuring one model.
+
+    Attributes
+    ----------
+    scalars
+        Output name to the summary dict from :func:`rasad.analyzer.summarize`
+        plus a ``variability`` key holding the string from
+        :func:`rasad.analyzer.classify`.
+    series
+        Output name to the divergence curve from
+        :func:`rasad.analyzer.divergence`.
+    runs
+        How many runs the report was built from.
+    thresholds
+        The classification cutoffs that were used, as a plain dict of
+        floats (see :data:`rasad.analyzer.THRESHOLDS`).
+    """
+
+    def __init__(
+        self,
+        scalars: dict[str, dict[str, Any]],
+        series: dict[str, list[float]],
+        runs: int,
+        thresholds: dict[str, float],
+    ) -> None:
+        self.scalars = scalars
+        self.series = series
+        self.runs = runs
+        self.thresholds = thresholds
+
+    def summary(self) -> str:
+        """Render the report as a plain-text table.
+
+        Returns
+        -------
+        str
+            A header with the run count, one row per scalar output
+            (name, mean, standard deviation, coefficient of variation,
+            p05-p95 interval, variability) and, when present, one
+            line per series showing how the divergence grew.
+        """
+        lines = [f"Rasad report of {self.runs} runs"]
+        lines.append(
+            f"thresholds (a convention, not a rule): low < "
+            f"{_fmt_ratio(self.thresholds['low'])} <= moderate <= "
+            f"{_fmt_ratio(self.thresholds['moderate'])} < high"
+        )
+
+        if self.scalars:
+            lines.append("Scalar outputs:")
+            for name, stats in self.scalars.items():
+                lines.append(
+                    f"  {name}: mean {_fmt(stats['mean'])} | "
+                    f"std {_fmt(stats['std'])} | "
+                    f"cv {_fmt_ratio(stats['cv'])} | "
+                    f"p05-p95 [{_fmt(stats['p05'])}, {_fmt(stats['p95'])}] | "
+                    f"variability: {stats['variability']}"
+                )
+
+        if self.series:
+            lines.append("Series:")
+            for name, curve in self.series.items():
+                lines.append(
+                    f"  {name}: divergence from {_fmt(curve[0])} to "
+                    f"{_fmt(curve[-1])} over {len(curve)} steps"
+                )
+
+        return "\n".join(lines)
+
+    def plot(self) -> go.Figure:
+        """Render the report as a divergence chart.
+
+        Returns
+        -------
+        plotly.graph_objects.Figure
+            One line trace per series in :attr:`series`, x being the
+            time step and y the standard deviation between runs.
+
+        Raises
+        ------
+        ValueError
+            When there is no time series to plot.
+        """
+        if not self.series:
+            raise ValueError("no time series to plot")
+
+        fig = go.Figure()
+        for name, curve in self.series.items():
+            fig.add_trace(
+                go.Scatter(
+                    x=list(range(len(curve))),
+                    y=curve,
+                    mode="lines",
+                    name=name,
+                )
+            )
+
+        fig.update_layout(
+            title=f"Rasad report of {self.runs} runs",
+            xaxis_title="time step",
+            yaxis_title="standard deviation between runs",
+        )
+        return fig

rasad/runner.py

@@ -0,0 +1,60 @@
+"""Execute a plan of simulation runs and collect the raw outputs.
+
+The runner turns a plan from :mod:`rasad.sampler` into results: it
+calls the model once per plan entry, in plan order, and returns the
+output dicts in that same order. Execution is deliberately sequential;
+parallelism is explicitly out of scope for this version.
+
+The model is validated up front so a bad model fails immediately
+instead of after wasted work, and every run must return the same set of
+output keys or the batch is rejected — a report built from shifting keys
+could not be summarized.
+"""
+
+from collections.abc import Callable
+
+from rasad.adapter import validate_model
+
+
+def run_all(fn: Callable[..., dict], plan: list[tuple[dict, int]]) -> list[dict]:
+    """Run a model once per plan entry and return the outputs in order.
+
+    Parameters
+    ----------
+    fn
+        A model matching the simulation interface
+        ``def run(params: dict, seed: int) -> dict``.
+    plan
+        The list of ``(params, seed)`` pairs produced by
+        :func:`rasad.sampler.make_plan`.
+
+    Returns
+    -------
+    list[dict]
+        One output dict per plan entry, in plan order.
+
+    Raises
+    ------
+    TypeError
+        When ``fn`` is not a valid model, or when a run returns
+        something other than a dict.
+    ValueError
+        When runs do not all return the same set of output keys.
+    """
+    validate_model(fn)
+
+    results: list[dict] = []
+    for params, seed in plan:
+        out = fn(params, seed)
+        if not isinstance(out, dict):
+            raise TypeError(
+                f"model must return a dict, got {type(out).__name__} from seed {seed}"
+            )
+        if results and out.keys() != results[0].keys():
+            raise ValueError(
+                "every run must return the same output keys, "
+                f"got {sorted(out)} after {sorted(results[0])}"
+            )
+        results.append(out)
+
+    return results

rasad/sampler.py

@@ -0,0 +1,41 @@
+"""Decide what the simulation runs will be.
+
+In this version the parameters stay fixed across every run and only the
+random seed varies, so the measurement isolates one question: how much
+of the result is pure randomness? Each plan entry is a fresh deep copy
+of the parameters paired with a seed, so later runs can never disturb
+earlier ones or the caller's original dict.
+"""
+
+import copy
+
+
+def make_plan(params: dict, runs: int, base_seed: int = 0) -> list[tuple[dict, int]]:
+    """Build the list of (params, seed) pairs for a batch of runs.
+
+    Parameters
+    ----------
+    params
+        The simulation parameters. The same value is used for every
+        run, and each run gets its own deep copy so mutations never
+        leak between runs.
+    runs
+        How many runs to plan. Must be at least 2 so the results can
+        be summarized.
+    base_seed
+        The seed of the first run; run ``i`` gets ``base_seed + i``.
+
+    Returns
+    -------
+    list[tuple[dict, int]]
+        One ``(params, seed)`` pair per run, in run order.
+
+    Raises
+    ------
+    ValueError
+        When ``runs`` is below 2.
+    """
+    if runs < 2:
+        raise ValueError(f"need at least 2 runs to summarize, got {runs}")
+
+    return [(copy.deepcopy(params), base_seed + i) for i in range(runs)]

rasad_sim-0.1.0.dist-info/METADATA

@@ -0,0 +1,333 @@
+Metadata-Version: 2.4
+Name: rasad-sim
+Version: 0.1.0
+Summary: Measure how much of a stochastic simulation's result is a property of the model and how much is the random seed.
+Author: Ahmed Aly
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ahmedaly0904-bit64/rasad
+Project-URL: Source, https://github.com/ahmedaly0904-bit64/rasad
+Project-URL: Issues, https://github.com/ahmedaly0904-bit64/rasad/issues
+Keywords: simulation,reproducibility,agent-based-modeling,uncertainty-quantification,monte-carlo,sensitivity-analysis
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.26
+Requires-Dist: plotly>=5.9
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Provides-Extra: examples
+Requires-Dist: mesa>=3.5; extra == "examples"
+Requires-Dist: networkx>=3.0; extra == "examples"
+Requires-Dist: pandas>=2.0; extra == "examples"
+Requires-Dist: simpy>=4.1; extra == "examples"
+Dynamic: license-file
+
+# Rasad · رَصَد
+
+**Measure how much of your simulation's result is a property of the model, and how much is the random seed.**
+
+Stochastic simulations are usually reported without error bars. A paper says *"the civilisation
+collapsed in year 240"* and never answers two questions:
+
+1. If the random seed changes, is it still year 240?
+2. Is this a property of the model, or an accident of one run?
+
+Rasad answers both by measurement.
+
+---
+
+## Why this exists
+
+This tool was not designed in the abstract. It was built because another project needed it.
+
+**Omran** is a simulation of Ibn Khaldun's theory of *asabiyyah*. Ibn Khaldun (1332–1406) was
+a historian who argued in the *Muqaddimah* that civilisations rise and fall on a single
+force: **asabiyyah**, the cohesion that lets a group act as one. A group with strong
+cohesion overtakes a settled, comfortable one; then comfort erodes its own cohesion over
+generations, and it is overtaken in turn. The cycle repeats. He called the study of this
+*ʿilm al-ʿumran* — the science of human social organisation — which is where the project
+takes its name.
+
+Omran models that computationally: nations on a grid, populations that grow and starve,
+ideas that spread between neighbours like an infection, wars along contested borders. Run it
+and you get numbers — a final population, a count of wars, a year the collapse happened.
+
+The problem was that nobody knew whether those numbers meant anything.
+
+Change the random seed and they change. Was a collapse in year 240 a property of the model,
+or an accident of one run? There was no way to answer without measuring, and no tool that
+measured it — the frameworks that do sensitivity analysis are built for engineering and
+physics models, and the agent-based modelling field is repeatedly criticised for publishing
+results without error bars.
+
+So Rasad was written to answer that question, under one hard constraint: **it must not touch
+Omran.** It observes from the outside and modifies nothing, the way an instrument measures a
+specimen without altering it. That constraint shaped the architecture — and it is why Rasad
+works on any simulation, not just the one it was written for.
+
+What it found is in [`FINDINGS.md`](FINDINGS.md), and it was not what anyone expected.
+
+---
+
+## Install
+
+```bash
+pip install rasad-sim
+```
+
+The distribution is `rasad-sim` because `rasad` collides with an existing name on
+PyPI. The import is unaffected:
+
+```python
+import rasad
+```
+
+Python 3.12+ · numpy · plotly
+
+## Use
+
+Describe your simulation as one function:
+
+```python
+def run(params: dict, seed: int) -> dict:
+    """One run. A number is a final result; a list of numbers is a time series."""
+    ...
+```
+
+Then:
+
+```python
+import rasad
+
+report = rasad.measure(run, params={"growth": 0.03}, runs=100)
+print(report.summary())
+report.plot().write_html("divergence.html")
+```
+
+You get, for every output: mean, standard deviation, a 90% interval, and a variability class —
+**low**, **moderate**, or **high** — plus a curve showing how far the runs drift
+apart over time.
+
+---
+
+## What it found in practice
+
+### A simulation that could not reproduce itself
+
+Applied to [Omran](https://github.com/ahmedaly0904-bit64/Omran), an agent-based model of
+Ibn Khaldun's theory of *asabiyyah*, **without modifying a line of it**:
+
+```
+final_total_population: mean 4,649.39 | cv 0.2841 | p05-p95 [2,704.75, 6,774.30] | high
+survivors:              mean 1.14     | cv 0.3059 | p05-p95 [1.00, 2.00]        | high
+total_wars:             mean 13.44    | cv 0.3986 | p05-p95 [6.00, 22.10]       | high
+total_famines:          mean 0.00     | cv 0.0000 | p05-p95 [0.00, 0.00]        | low
+```
+
+No numeric output of the model had low variability. Worse, the measurement exposed something the author
+did not know: **the same seed produced different results in different processes.**
+
+Six runs with seed `1`, thirty simulated years:
+
+```
+1428 · 1428 · 1512 · 1426 · 1426 · 1512
+```
+
+Comparing the population curve year by year located the split: the runs are **identical for
+nineteen years**, then diverge at year twenty by **one individual** — which becomes hundreds
+by year one hundred. That is error propagation, measured.
+
+This was then confirmed with Rasad out of the path entirely: Omran's own `main.py` carries a
+hard-coded `random.seed(42)`, and running that file directly eight times gave **four distinct
+results**.
+
+Full write-up: [`FINDINGS.md`](FINDINGS.md)
+
+### Aggregates can be stable while their parts are noise
+
+On a [SimPy](https://simpy.readthedocs.io) machine-shop simulation
+([`examples/simpy_machine_shop.py`](examples/simpy_machine_shop.py)):
+
+| Output | cv | Verdict |
+|---|---|---|
+| total parts produced | 0.014 | **low** |
+| best machine · worst machine | 0.017 | **low** |
+| **gap between best and worst** | **0.31** | **high** |
+
+The shop's total output is stable. The gap between machines is pure noise. Anyone looking at
+one run and saying *"machine 7 is underperforming, investigate it"* is chasing a random seed.
+
+**Averages hide fragility.** That alone is a reason to measure what you publish.
+
+---
+
+## Verified against simulations it was not written for
+
+| Framework | Models | Result |
+|---|---|---|
+| [Mesa](https://github.com/projectmesa/mesa) | Schelling, WolfSheep, Boltzmann | works; WolfSheep's sheep population has high variability (cv 2.95 — usually extinct, occasionally not) |
+| [SimPy](https://simpy.readthedocs.io) | machine shop | works; see above |
+| [EoN](https://epidemicsonnetworks.readthedocs.io) | SIR on a network | works; epidemic duration has high variability (7.5 → 14.7) |
+| [Omran](https://github.com/ahmedaly0904-bit64/Omran) | asabiyyah model | works; see above |
+
+Examples: [`examples/`](examples/)
+
+A control worth stating: the SimPy and Mesa examples reproduce byte-identically across
+separate processes. That establishes that Omran's non-reproducibility is a bug in Omran,
+and that Rasad's own pipeline is deterministic.
+
+---
+
+## The class is a convention. The numbers are the result.
+
+The default cutoffs — 0.05 and 0.20 — **are a choice, not a theory**. An output at cv 0.21
+reads *high*; raise the cutoff to 0.25 and the same data reads *moderate*.
+
+So every report prints the thresholds it used and labels them as a convention:
+
+```
+thresholds (a convention, not a rule): low < 0.0500 <= moderate <= 0.2000 < high
+```
+
+And they belong to the caller:
+
+```python
+rasad.measure(run, params={}, runs=100,
+              thresholds={"low": 0.01, "moderate": 0.05})
+```
+
+**The real result is the interval.** `p05-p95 [7.46, 14.74]` says the duration may double,
+without needing a word on top of it.
+
+---
+
+## Limitations
+
+- **Only the seed varies.** Parameters are held fixed, so *"which parameter drives the
+  result?"* is not answered yet. Sensitivity analysis is the next version.
+- **Execution is sequential.** No parallelism.
+- **One value per output name per run.** A model whose keys change between runs is rejected.
+
+Accepted outputs: Python numbers, numpy scalars, 1-D numeric numpy arrays, lists and tuples.
+**Booleans are always rejected** — alone or inside a list — because an average of ones and
+zeros means nothing.
+
+---
+
+## Development
+
+```bash
+python -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+.venv/bin/pytest tests -v
+```
+
+73 tests · 97% line coverage · 357 of 452 mutants killed · linted with ruff
+
+The coverage figure is the weakest of the three. Mutation testing is what showed why:
+`validate_thresholds` was fully covered and still accepted two equal cutoffs, because
+no test passed the one input that separates `<` from `<=`.
+
+The statistics are tested against models whose answers are known analytically: a constant
+must give a standard deviation of exactly zero; a random walk's divergence must grow as the
+square root of time. Those tests caught real bugs — including a collapsed axis that would
+have produced plausible, meaningless numbers.
+
+## Notes on the implementation
+
+Three analyses of the code, in Arabic:
+
+- [فئات المدخلات](docs/input-classes.md) — the five input classes `summarize()` actually
+  distinguishes, each with the test that covers it, and why branch order decides which class
+  a list falls into.
+- [كم تشغيلة تكفي؟](docs/how-many-runs.md) — the standard error of the mean applied to Omran:
+  100 runs pin the mean to 2.8%, and reaching 1% costs 784.
+- [حدود الوحدات](docs/module-boundaries.md) — the deletion test applied to each of Rasad's own
+  modules, separating splits forced by something that happened from splits made on a guess.
+
+---
+
+## بالعربية
+
+**رَصَد** أداة تقيس صلابة نتائج المحاكاة: أيُّ المخرجات خاصيةٌ في النموذج، وأيُّها أثرٌ للبذرة العشوائية.
+
+تُنشر نتائج المحاكاة العشوائية غالبًا بلا حدود خطأ. يُقال «انهارت الحضارة في السنة ٢٤٠» دون
+الإجابة على سؤالين: هل يظل الرقم ٢٤٠ لو تغيّرت البذرة؟ وهل هذه خاصية في النموذج أم صدفة في
+تشغيلة واحدة؟ يجيب رَصَد عنهما بالقياس لا بالتقدير.
+
+يوصّف المستخدم محاكاته بدالةٍ واحدة تستقبل المعاملات والبذرة وترجّع قاموس مخرجات. يشغّلها
+رَصَد مرارًا ببذورٍ مختلفة، ثم يعرض لكل مخرَج متوسطه وانحرافه ومدى تسعين بالمئة وتصنيفًا لتغايره —
+**low** أو **moderate** أو **high** — مع منحنى يبيّن اتساع التباعد بين التشغيلات عبر الزمن.
+
+طُبِّق على أربعة مشاريع لم يُكتب لأجلها، فكشف في أحدها — محاكاة لنظرية العصبية عند ابن خلدون —
+أنها **لا تعيد إنتاج نتائجها بالبذرة نفسها**: تشغيلتان متطابقتان تفترقان عند السنة العشرين
+بفارق فردٍ واحد، يصير مئاتٍ بحلول السنة المئة. وهذا انتشار الخطأ في صورته المقيسة.
+
+### لماذا كُتب
+
+لم تُصمَّم هذه الأداة في الفراغ، بل كُتبت لأن مشروعًا آخر احتاجها.
+
+**عُمران** محاكاةٌ لنظرية العصبية عند ابن خلدون (١٣٣٢–١٤٠٦)، الذي رأى في *المقدمة* أن الحضارات
+تنهض وتسقط بقوةٍ واحدة: **العصبية**، أي التماسك الذي يجعل الجماعة تفعل كأنها واحد. جماعةٌ
+عصبيتها قوية تغلب جماعةً مستقرةً مترفة، ثم يُفسد الترف عصبيتها هي عبر الأجيال، فتُغلَب بدورها.
+وسمّى ابن خلدون دراسة ذلك **علم العمران**، ومنه أخذ المشروع اسمه.
+
+يحاكي عُمران هذا حاسوبيًّا: دولٌ على شبكة، وسكانٌ ينمون ويجوعون، وأفكارٌ تنتقل بين الجيران
+كالعدوى، وحروبٌ على الحدود المتنازعة. تشغّله فتخرج لك أرقام — سكانٌ في النهاية، وعدد حروب،
+وسنةٌ وقع فيها الانهيار.
+
+والمشكلة أن أحدًا لم يكن يعرف: هل لهذه الأرقام معنى؟ غيّر البذرة العشوائية تتغيّر. فهل الانهيار
+في السنة ٢٤٠ خاصيةٌ في النموذج أم صدفةُ تشغيلةٍ واحدة؟ لا سبيل إلى الجواب إلا بالقياس، ولم تكن
+هناك أداةٌ تقيسه.
+
+فكُتب رَصَد لهذا السؤال، بقيدٍ واحدٍ صارم: **ألّا يمسّ عُمران**. يراقبه من خارجه ولا يعدّل فيه
+حرفًا، كما يقيس المِجهر عيّنةً دون أن يغيّرها. وهذا القيد هو الذي شكّل بنية الأداة — وهو سبب
+عملها على أي محاكاة، لا على التي كُتبت لأجلها وحدها.
+
+### التصنيف
+
+وحدود التصنيف الافتراضية اصطلاحٌ لا قاعدة، ولذلك يعلنها كل تقرير ويتركها بيد المستخدم.
+**النتيجة الحقيقية هي المدى**، لا التصنيف الذي يعلوه.
+
+---
+
+## How this was built — full disclosure
+
+Most of the code here was written by AI models under explicit delegation and human review.
+
+| Stage | Owner |
+|---|---|
+| Specification and architecture | Ahmed, in dialogue with Claude (Opus 5) |
+| **Test authoring** | Written into each task brief **before** implementation; the implementer was forbidden from altering a character |
+| Implementation | DeepSeek V4 Flash, via `opencode` + AgentRouter — seven tasks |
+| Review gates | Claude (Opus 5): every diff read, tests run independently of the implementer's claim |
+| Decisions and merges | Ahmed — every commit after review |
+
+**The ordering is what matters, not the tooling: the tests came first and were the
+specification.** The model was never asked to write code and then write the thing that proves
+it correct. It was given a written contract and held to it.
+
+What the gates actually caught: a dead condition in a type check, a deprecated import, a
+missing return annotation, unreadable number formatting. **No logic error got through** —
+credit to the tests, not to the model.
+
+And what none of them caught: an output that was constantly zero was classified as *high* variability
+when it was the most stable number in the report. Neither the reference models nor the review
+found it — **the real data did, on the first run against Omran.**
+
+That is the boundary. Tests prove the arithmetic is right; only real data reveals the case
+nobody thought to write a test for.
+
+---
+
+## License
+
+MIT

rasad_sim-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+rasad/__init__.py,sha256=FlD_koEkFcd-ghAI85SQB3HdIvvoBEKWjZEUPHKnsHs,2687
+rasad/adapter.py,sha256=V1OWkEZRuYaursWF8x9ovfwoWRiadavxXpMTjC_uV-g,5084
+rasad/analyzer.py,sha256=SBEuN8zphRf_-5j0odVfKP1UAp0qvaq23DuGl6H7UNA,5858
+rasad/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rasad/report.py,sha256=T8-DP5pHkWkWv_Qsb4K5dJ1w1qRSJ-R04KoGFGFMGYI,4275
+rasad/runner.py,sha256=6zaygTJkreNZKtXHjeOWmVUtgYQyvtC_w8h_DY2B5BI,1935
+rasad/sampler.py,sha256=Oq8i741yagWPFLriCPn4uPfaSYHJdgfOw2-8goyhMqA,1291
+rasad/adapters/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+rasad/adapters/omran.py,sha256=erEkT6UiL0ewGHTMs9Bt-KZqLgSQS2fkpohZda3C7vs,2526
+rasad_sim-0.1.0.dist-info/licenses/LICENSE,sha256=afpSMmwbfdEODsOT84sfwc4LdduoQD1FQYc8sYa0gLc,1066
+rasad_sim-0.1.0.dist-info/METADATA,sha256=1p6S9C1nMDEHc5vk58SqdSn6NIGS7Q_kgQhA1ya4heo,15332
+rasad_sim-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+rasad_sim-0.1.0.dist-info/top_level.txt,sha256=E7IVloUBu5D9-POCvBj2uRoI9NeotDCcMaTlAjzztek,6
+rasad_sim-0.1.0.dist-info/RECORD,,

rasad_sim-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

rasad_sim-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ahmed Aly
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

rasad_sim-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+rasad