pmcontrols 0.1.0__py3-none-any.whl

pmcontrols/__init__.py

@@ -0,0 +1,27 @@
+"""pmcontrols — project scheduling and earned value control for Python.
+
+Validated, pandas-native, automation-first project controls.
+
+    import pmcontrols as pm
+
+    r = pm.cpm(activities)        # critical path, slack, float
+    r = pm.pert(activities)       # three-point + Monte Carlo risk
+    r = pm.crash(activities, target=14)   # cheapest compression (LP)
+
+    # plan once, freeze, control forever:
+    pm.plan(periods, pv).save("project_pmb.json")
+    r = pm.evm("project_pmb.json", ev=30_000, ac=35_000, at=4)
+    r.ok          # True iff CPI and SPI(t) clear thresholds
+    r.summary()   # plain-language verdict
+"""
+
+from ._result import PMB, Alert, Result
+from ._version import __version__
+from .crash import crash
+from .evm import earned_schedule, evm, plan
+from .network import cpm, pert
+
+__all__ = [
+    "cpm", "pert", "crash", "evm", "plan", "earned_schedule",
+    "Result", "Alert", "PMB", "__version__",
+]

pmcontrols/_result.py

@@ -0,0 +1,173 @@
+"""The Result protocol: the one object every pmcontrols analysis returns.
+
+Design contract (append-only from v0.1 on):
+
+    Result.method    stable analysis alias ("cpm", "pert", "evm", "crash")
+    Result.params    echo of the user's inputs
+    Result.stats     named scalars (durations, indices, forecasts, costs)
+    Result.alerts    tuple of structured threshold events; empty == on track
+    Result.meta      provenance: n, version, input hash, timestamp
+    Result.table     tidy per-activity / per-period DataFrame
+
+    r.ok             True iff no alerts  ->  sys.exit(0 if r.ok else 1)
+    r.summary()      fixed-width audit text with a plain-language verdict
+    r.to_dict()      JSON-safe, integer-versioned schema
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import datetime
+import hashlib
+import json
+import pathlib
+from typing import Any, Mapping
+
+import numpy as np
+import pandas as pd
+
+_SCHEMA = 1
+
+
+def utcnow() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds")
+
+
+def data_hash(values: Any) -> str:
+    payload = json.dumps(values, sort_keys=True, default=str).encode()
+    return "sha256:" + hashlib.sha256(payload).hexdigest()[:16]
+
+
+def _jsonable(obj: Any) -> Any:
+    if isinstance(obj, (str, int, float, bool)) or obj is None:
+        return obj
+    if isinstance(obj, Mapping):
+        return {str(k): _jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_jsonable(v) for v in obj]
+    if isinstance(obj, (np.integer, np.floating)):
+        return obj.item()
+    return str(obj)
+
+
+@dataclasses.dataclass(frozen=True)
+class Alert:
+    """One threshold event: which indicator, where, how bad."""
+
+    indicator: str
+    value: float
+    threshold: float
+    note: str = ""
+
+    def to_dict(self) -> dict:
+        return {
+            "indicator": self.indicator,
+            "value": self.value,
+            "threshold": self.threshold,
+            "note": self.note,
+        }
+
+    def __str__(self) -> str:
+        base = f"{self.indicator}={self.value:.3f} breaches {self.threshold:g}"
+        return base + (f" - {self.note}" if self.note else "")
+
+
+@dataclasses.dataclass(frozen=True)
+class Result:
+    method: str
+    params: Mapping[str, Any]
+    stats: Mapping[str, float]
+    table: pd.DataFrame
+    alerts: tuple[Alert, ...] = ()
+    meta: Mapping[str, Any] = dataclasses.field(default_factory=dict)
+
+    @property
+    def ok(self) -> bool:
+        return len(self.alerts) == 0
+
+    def to_dict(self) -> dict:
+        return {
+            "schema": _SCHEMA,
+            "method": self.method,
+            "params": _jsonable(self.params),
+            "stats": _jsonable(self.stats),
+            "alerts": [a.to_dict() for a in self.alerts],
+            "meta": _jsonable(self.meta),
+            "table": _jsonable(self.table.to_dict(orient="list")),
+        }
+
+    def summary(self) -> str:
+        lines = [f"pmcontrols {self.method} — {self.meta.get('computed_at', '')}"]
+        for k, v in self.stats.items():
+            lines.append(f"  {k:<24} {v:>12.4f}" if isinstance(v, float) else f"  {k:<24} {v}")
+        if self.alerts:
+            lines.append("Alerts:")
+            lines += [f"  ! {a}" for a in self.alerts]
+            lines.append("Verdict: ATTENTION — indicators breach thresholds.")
+        else:
+            lines.append("Verdict: on track — no indicator breaches thresholds.")
+        return "\n".join(lines)
+
+
+@dataclasses.dataclass(frozen=True)
+class PMB:
+    """Performance Measurement Baseline: plan once, freeze, control forever.
+
+    The EVM sibling of a control-chart baseline: the time-phased planned
+    value curve and budget at completion are fixed at planning time,
+    committed to version control, and every reporting period is evaluated
+    against them.
+    """
+
+    periods: tuple[float, ...]
+    pv: tuple[float, ...]
+    bac: float
+    created_at: str
+    version: str
+
+    def __post_init__(self) -> None:
+        if len(self.periods) != len(self.pv):
+            raise ValueError("periods and pv must have the same length")
+        if len(self.periods) < 2:
+            raise ValueError("a PMB needs at least two points")
+        if any(b > a for a, b in zip(self.pv[1:], self.pv[:-1])):
+            raise ValueError("planned value must be non-decreasing")
+        if abs(self.pv[-1] - self.bac) > 1e-9 * max(1.0, self.bac):
+            raise ValueError("planned value must end at BAC")
+
+    @property
+    def planned_duration(self) -> float:
+        return float(self.periods[-1] - self.periods[0])
+
+    def to_json(self) -> str:
+        return json.dumps(
+            {
+                "schema": _SCHEMA,
+                "periods": list(self.periods),
+                "pv": list(self.pv),
+                "bac": self.bac,
+                "created_at": self.created_at,
+                "pmcontrols_version": self.version,
+            },
+            indent=2,
+        )
+
+    def save(self, path: str | pathlib.Path) -> pathlib.Path:
+        path = pathlib.Path(path)
+        path.write_text(self.to_json() + "\n", encoding="utf-8")
+        return path
+
+    @classmethod
+    def from_json(cls, text: str) -> "PMB":
+        raw = json.loads(text)
+        return cls(
+            periods=tuple(float(x) for x in raw["periods"]),
+            pv=tuple(float(x) for x in raw["pv"]),
+            bac=float(raw["bac"]),
+            created_at=raw["created_at"],
+            version=raw["pmcontrols_version"],
+        )
+
+    @classmethod
+    def load(cls, path: str | pathlib.Path) -> "PMB":
+        return cls.from_json(pathlib.Path(path).read_text(encoding="utf-8"))

pmcontrols/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

pmcontrols/crash.py

@@ -0,0 +1,128 @@
+"""Minimum-cost schedule compression (crashing) as a linear program.
+
+Decision variables are activity start times s_i, crash amounts y_i and
+the project finish time F:
+
+    minimize    sum_i  c_i * y_i
+    subject to  s_j >= s_i + (d_i - y_i)      for every precedence i -> j
+                F   >= s_i + (d_i - y_i)      for every terminal activity i
+                F   <= T_target
+                0 <= y_i <= d_i - crash_i,    s_i >= 0
+
+This is the classical CPM time/cost trade-off LP (Kelley 1961), solved
+with scipy.optimize.linprog (HiGHS).
+"""
+
+from __future__ import annotations
+
+from typing import Iterable, Mapping
+
+import numpy as np
+from scipy.optimize import linprog
+
+from ._result import Result, data_hash, utcnow
+from ._version import __version__
+from .network import _normalize, _passes
+
+__all__ = ["crash"]
+
+
+def crash(
+    activities: Iterable[Mapping[str, object]],
+    target: float,
+    duration: str = "duration",
+    crash_duration: str = "crash_duration",
+    cost_per_period: str = "crash_cost",
+) -> Result:
+    """Cheapest set of crash decisions meeting a target completion time.
+
+    Each activity mapping must carry: ``id``, ``predecessors``, a normal
+    duration, a fully-crashed duration, and a (linear) crash cost per
+    period.  Returns the optimal crash amount per activity, the resulting
+    schedule, and the total crash cost.
+    """
+    acts = _normalize(activities)
+    names = list(acts)
+    idx = {a: i for i, a in enumerate(names)}
+    n = len(names)
+    d = np.array([float(acts[a][duration]) for a in names])
+    dc = np.array([float(acts[a][crash_duration]) for a in names])
+    cost = np.array([float(acts[a][cost_per_period]) for a in names])
+    if np.any(dc > d):
+        raise ValueError("crash duration cannot exceed normal duration")
+    if np.any(cost < 0):
+        raise ValueError("crash costs must be non-negative")
+
+    normal = _passes(acts, {a: float(acts[a][duration]) for a in names})
+    normal_finish = float(normal["ef"].max())
+    if target > normal_finish:
+        raise ValueError(
+            f"target {target} exceeds the uncrashed duration {normal_finish}; "
+            "nothing to crash"
+        )
+
+    # Variables: [s_0..s_{n-1}, F, y_0..y_{n-1}]
+    nv = 2 * n + 1
+    c = np.zeros(nv)
+    c[n + 1:] = cost
+
+    A_ub, b_ub = [], []
+    succs: dict[str, list[str]] = {a: [] for a in acts}
+    for a in acts:
+        for p in acts[a]["preds"]:
+            succs[p].append(a)
+    # Precedence: s_i + d_i - y_i - s_j <= 0
+    for a in names:
+        for s in succs[a]:
+            row = np.zeros(nv)
+            row[idx[a]] = 1.0
+            row[idx[s]] = -1.0
+            row[n + 1 + idx[a]] = -1.0
+            A_ub.append(row)
+            b_ub.append(-d[idx[a]])
+    # Terminal: s_i + d_i - y_i - F <= 0
+    for a in names:
+        if not succs[a]:
+            row = np.zeros(nv)
+            row[idx[a]] = 1.0
+            row[n] = -1.0
+            row[n + 1 + idx[a]] = -1.0
+            A_ub.append(row)
+            b_ub.append(-d[idx[a]])
+
+    bounds = [(0, None)] * n + [(0, target)] + [
+        (0, float(d[i] - dc[i])) for i in range(n)
+    ]
+    res = linprog(c, A_ub=np.array(A_ub), b_ub=np.array(b_ub), bounds=bounds,
+                  method="highs")
+    if not res.success:
+        raise RuntimeError(f"crashing LP infeasible or failed: {res.message}")
+
+    y = res.x[n + 1:]
+    new_dur = {a: float(d[idx[a]] - y[idx[a]]) for a in names}
+    sched = _passes(acts, new_dur)
+    sched["normal_duration"] = sched["activity"].map(
+        {a: float(d[idx[a]]) for a in names}
+    )
+    sched["crash_amount"] = sched["activity"].map(
+        {a: float(y[idx[a]]) for a in names}
+    )
+    sched["crash_cost"] = sched["activity"].map(
+        {a: float(y[idx[a]] * cost[idx[a]]) for a in names}
+    )
+
+    stats = {
+        "normal_duration_total": normal_finish,
+        "target": float(target),
+        "achieved_duration": float(sched["ef"].max()),
+        "total_crash_cost": float(res.fun),
+    }
+    meta = {
+        "computed_at": utcnow(),
+        "version": __version__,
+        "input_hash": data_hash({a: [float(d[idx[a]]), float(dc[idx[a]]),
+                                     float(cost[idx[a]])] for a in names}),
+        "solver": "scipy.linprog/highs",
+    }
+    return Result(method="crash", params={"target": target}, stats=stats,
+                  table=sched, meta=meta)

pmcontrols/evm.py

@@ -0,0 +1,136 @@
+"""Earned value management and earned schedule.
+
+Cost indicators follow the standard EVM formulation (PMBOK; EIA-748
+practice): CV = EV - AC, SV = EV - PV, CPI = EV/AC, SPI = EV/PV, with
+the classical estimate-at-completion family and TCPI.
+
+Time indicators follow Lipke's earned schedule: ES(t) is the time at
+which the planned value curve equals current EV (linear interpolation
+between baseline periods), SV(t) = ES - AT, SPI(t) = ES / AT, and the
+duration forecast IEAC(t) = PD / SPI(t).
+"""
+
+from __future__ import annotations
+
+from typing import Mapping, Sequence
+
+import numpy as np
+import pandas as pd
+
+from ._result import PMB, Alert, Result, data_hash, utcnow
+from ._version import __version__
+
+__all__ = ["evm", "plan", "earned_schedule"]
+
+
+def plan(periods: Sequence[float], pv: Sequence[float]) -> PMB:
+    """Freeze a time-phased planned value curve into a PMB."""
+    return PMB(
+        periods=tuple(float(x) for x in periods),
+        pv=tuple(float(x) for x in pv),
+        bac=float(pv[-1]),
+        created_at=utcnow(),
+        version=__version__,
+    )
+
+
+def earned_schedule(pmb: PMB, ev: float) -> float:
+    """Earned schedule ES(t): when the plan earned what we have earned.
+
+    Linear interpolation on the cumulative PV curve (Lipke 2003):
+    ES = t_N + (EV - PV_N) / (PV_{N+1} - PV_N) * (t_{N+1} - t_N),
+    where N is the last baseline period with PV_N <= EV.
+    """
+    t = np.asarray(pmb.periods, dtype=float)
+    pv = np.asarray(pmb.pv, dtype=float)
+    if ev <= pv[0]:
+        return float(t[0])
+    if ev >= pv[-1]:
+        return float(t[-1])
+    n = int(np.searchsorted(pv, ev, side="right") - 1)
+    if pv[n + 1] == pv[n]:
+        return float(t[n + 1])
+    return float(t[n] + (ev - pv[n]) / (pv[n + 1] - pv[n]) * (t[n + 1] - t[n]))
+
+
+def evm(
+    pmb: PMB | str,
+    ev: float,
+    ac: float,
+    at: float,
+    thresholds: Mapping[str, float] | None = None,
+) -> Result:
+    """Evaluate project status at actual time ``at`` against a frozen PMB.
+
+    Parameters
+    ----------
+    pmb : a PMB object or a path to a saved PMB JSON.
+    ev : cumulative earned value at ``at``.
+    ac : cumulative actual cost at ``at``.
+    at : actual time, in the PMB's time units.
+    thresholds : alert thresholds; defaults to CPI and SPI(t) below 0.90.
+
+    Returns a Result whose stats include the full indicator set:
+    PV, CV, SV, CPI, SPI, the EAC family, ETC, TCPI, VAC, and the
+    earned-schedule block ES, SV(t), SPI(t), IEAC(t).
+    """
+    if isinstance(pmb, str):
+        pmb = PMB.load(pmb)
+    if ev < 0 or ac < 0:
+        raise ValueError("EV and AC must be non-negative")
+    if ev > pmb.bac * (1 + 1e-9):
+        raise ValueError("EV cannot exceed BAC")
+    t = np.asarray(pmb.periods, dtype=float)
+    pv_curve = np.asarray(pmb.pv, dtype=float)
+    pv = float(np.interp(at, t, pv_curve))
+    bac, pd_ = pmb.bac, pmb.planned_duration
+
+    cv, sv = ev - ac, ev - pv
+    cpi = ev / ac if ac > 0 else np.nan
+    spi = ev / pv if pv > 0 else np.nan
+    eac_cpi = bac / cpi if cpi and not np.isnan(cpi) and cpi > 0 else np.nan
+    eac_typical = ac + (bac - ev)  # remaining work at planned efficiency
+    spi_for_blend = spi if spi and not np.isnan(spi) and spi > 0 else np.nan
+    eac_blend = (
+        ac + (bac - ev) / (cpi * spi_for_blend)
+        if cpi and spi_for_blend and cpi > 0
+        else np.nan
+    )
+    etc = eac_cpi - ac if not np.isnan(eac_cpi) else np.nan
+    tcpi_bac = (bac - ev) / (bac - ac) if bac > ac else np.inf
+    vac = bac - eac_cpi if not np.isnan(eac_cpi) else np.nan
+
+    es = earned_schedule(pmb, ev)
+    sv_t = es - at
+    spi_t = es / at if at > 0 else np.nan
+    ieac_t = pd_ / spi_t if spi_t and not np.isnan(spi_t) and spi_t > 0 else np.nan
+
+    stats = {
+        "bac": bac, "planned_duration": pd_, "at": at,
+        "pv": pv, "ev": ev, "ac": ac,
+        "cv": cv, "sv": sv, "cpi": cpi, "spi": spi,
+        "eac_cpi": eac_cpi, "eac_typical": eac_typical, "eac_cpi_spi": eac_blend,
+        "etc": etc, "tcpi_bac": tcpi_bac, "vac": vac,
+        "es": es, "sv_t": sv_t, "spi_t": spi_t, "ieac_t": ieac_t,
+        "pct_complete": ev / bac, "pct_spent": ac / bac,
+    }
+
+    thr = {"cpi": 0.90, "spi_t": 0.90, **(thresholds or {})}
+    alerts = tuple(
+        Alert(indicator=k, value=float(stats[k]), threshold=float(v),
+              note="below threshold")
+        for k, v in thr.items()
+        if k in stats and not np.isnan(stats[k]) and stats[k] < v
+    )
+
+    table = pd.DataFrame(
+        {"indicator": list(stats), "value": [stats[k] for k in stats]}
+    )
+    meta = {
+        "computed_at": utcnow(),
+        "version": __version__,
+        "input_hash": data_hash({"ev": ev, "ac": ac, "at": at, "pv": list(pmb.pv)}),
+        "pmb_created_at": pmb.created_at,
+    }
+    return Result(method="evm", params={"ev": ev, "ac": ac, "at": at},
+                  stats=stats, table=table, alerts=alerts, meta=meta)

pmcontrols/network.py

@@ -0,0 +1,224 @@
+"""Project networks: CPM and PERT.
+
+Activity-on-node networks built from plain records
+(id, duration, predecessors). The forward/backward pass follows the
+standard formulation (e.g. Render, Stair & Hanna; PMBOK):
+
+    EF = ES + t           ES = max EF of immediate predecessors
+    LS = LF - t           LF = min LS of immediate successors
+    slack = LS - ES = LF - EF
+"""
+
+from __future__ import annotations
+
+from graphlib import CycleError, TopologicalSorter
+from typing import Iterable, Mapping
+
+import numpy as np
+import pandas as pd
+
+from ._result import Result, utcnow, data_hash
+from ._version import __version__
+
+__all__ = ["cpm", "pert"]
+
+Activity = Mapping[str, object]
+
+
+def _normalize(activities: Iterable[Activity]) -> dict[str, dict]:
+    acts: dict[str, dict] = {}
+    for a in activities:
+        aid = str(a["id"])
+        if aid in acts:
+            raise ValueError(f"duplicate activity id: {aid}")
+        preds_raw = a.get("predecessors", a.get("pred", ())) or ()
+        if isinstance(preds_raw, str):
+            preds: tuple[str, ...] = tuple(
+                p.strip() for p in preds_raw.split(",") if p.strip()
+            )
+        else:
+            preds = tuple(str(p) for p in preds_raw)  # type: ignore[attr-defined]
+        acts[aid] = {"preds": preds, **{
+            k: v for k, v in a.items() if k not in ("id", "predecessors", "pred")
+        }}
+    for aid, a in acts.items():
+        for p in a["preds"]:
+            if p not in acts:
+                raise ValueError(f"activity {aid} references unknown predecessor {p!r}")
+    return acts
+
+
+def _topo_order(acts: dict[str, dict]) -> list[str]:
+    """Topological order, raising a clear error on precedence cycles."""
+    try:
+        return list(
+            TopologicalSorter({k: v["preds"] for k, v in acts.items()}).static_order()
+        )
+    except CycleError as exc:  # graphlib's message is opaque to end users
+        cycle = " -> ".join(map(str, exc.args[1])) if len(exc.args) > 1 else "?"
+        raise ValueError(f"precedence cycle in the activity network: {cycle}") from None
+
+
+def _passes(acts: dict[str, dict], dur: Mapping[str, float]) -> pd.DataFrame:
+    order = _topo_order(acts)
+    es: dict[str, float] = {}
+    ef: dict[str, float] = {}
+    for a in order:
+        es[a] = max((ef[p] for p in acts[a]["preds"]), default=0.0)
+        ef[a] = es[a] + dur[a]
+    finish = max(ef.values())
+    succs: dict[str, list[str]] = {a: [] for a in acts}
+    for a in acts:
+        for p in acts[a]["preds"]:
+            succs[p].append(a)
+    lf: dict[str, float] = {}
+    ls: dict[str, float] = {}
+    for a in reversed(order):
+        lf[a] = min((ls[s] for s in succs[a]), default=finish)
+        ls[a] = lf[a] - dur[a]
+    rows = []
+    for a in order:
+        slack = ls[a] - es[a]
+        rows.append(
+            {
+                "activity": a,
+                "duration": dur[a],
+                "es": es[a],
+                "ef": ef[a],
+                "ls": ls[a],
+                "lf": lf[a],
+                "slack": slack,
+                "critical": bool(abs(slack) < 1e-9),
+            }
+        )
+    return pd.DataFrame(rows)
+
+
+def cpm(activities: Iterable[Activity], duration: str = "duration") -> Result:
+    """Critical path analysis of a deterministic activity network.
+
+    Parameters
+    ----------
+    activities : iterable of mappings with keys ``id``, ``predecessors``
+        (list or comma-separated string; empty for start activities) and a
+        duration field.
+    duration : name of the duration field (default ``"duration"``).
+    """
+    acts = _normalize(activities)
+    dur = {a: float(v[duration]) for a, v in acts.items()}
+    if any(d < 0 for d in dur.values()):
+        raise ValueError("durations must be non-negative")
+    table = _passes(acts, dur)
+    crit = table.loc[table["critical"], "activity"].tolist()
+    stats = {
+        "project_duration": float(table["ef"].max()),
+        "n_activities": float(len(table)),
+        "n_critical": float(len(crit)),
+    }
+    meta = {
+        "computed_at": utcnow(),
+        "version": __version__,
+        "input_hash": data_hash({a: dur[a] for a in sorted(dur)}),
+        "critical_activities": crit,
+    }
+    return Result(method="cpm", params={"duration": duration},
+                  stats=stats, table=table, meta=meta)
+
+
+def pert(
+    activities: Iterable[Activity],
+    optimistic: str = "a",
+    most_likely: str = "m",
+    pessimistic: str = "b",
+    n_sim: int = 20_000,
+    seed: int | None = 0,
+) -> Result:
+    """PERT three-point analysis with Monte Carlo schedule risk.
+
+    Expected time and variance per activity follow the classical beta
+    approximation te = (a + 4m + b) / 6, var = ((b - a) / 6)^2.  The
+    analytic project estimate sums te and var along the te-critical path
+    (the textbook procedure); the Monte Carlo simulation samples each
+    activity from the PERT-beta distribution and reports the empirical
+    completion distribution and per-activity criticality indices, which
+    the analytic procedure cannot provide.
+    """
+    acts = _normalize(activities)
+    te, var, lo, hi = {}, {}, {}, {}
+    for k, v in acts.items():
+        a, m, b = float(v[optimistic]), float(v[most_likely]), float(v[pessimistic])
+        if not a <= m <= b:
+            raise ValueError(f"activity {k}: require a <= m <= b")
+        te[k] = (a + 4 * m + b) / 6.0
+        var[k] = ((b - a) / 6.0) ** 2
+        lo[k], hi[k] = a, b
+    base = _passes(acts, te)
+    base["te"] = base["activity"].map(te)
+    base["var"] = base["activity"].map(var)
+    crit = base.loc[base["critical"], "activity"].tolist()
+    mean = float(base["ef"].max())
+    sigma = float(np.sqrt(sum(var[c] for c in crit)))
+
+    rng = np.random.default_rng(seed)
+    names = list(acts)
+    samples = {}
+    for k in names:
+        a, b = lo[k], hi[k]
+        if b - a < 1e-12:
+            samples[k] = np.full(n_sim, a)
+            continue
+        # PERT-beta with alpha + beta = 6 (the classic four-sigma range).
+        alpha = 1.0 + 4.0 * (float(acts[k][most_likely]) - a) / (b - a)
+        beta = 6.0 - alpha
+        samples[k] = a + (b - a) * rng.beta(alpha, beta, n_sim)
+
+    order = _topo_order(acts)
+    ef_sim = {k: np.zeros(n_sim) for k in names}
+    for k in order:
+        preds = acts[k]["preds"]
+        es_k = np.maximum.reduce([ef_sim[p] for p in preds]) if preds else np.zeros(n_sim)
+        ef_sim[k] = es_k + samples[k]
+    finish = np.maximum.reduce([ef_sim[k] for k in names])
+
+    # Per-activity criticality index: share of simulation runs in which the
+    # activity lies on the critical path (zero slack) under sampled durations.
+    succs: dict[str, list[str]] = {name: [] for name in acts}
+    for name in acts:
+        for pred in acts[name]["preds"]:
+            succs[pred].append(name)
+    ls_sim: dict[str, np.ndarray] = {}
+    lf_sim: dict[str, np.ndarray] = {}
+    crit_idx: dict[str, float] = {}
+    for k in reversed(order):
+        lf_sim[k] = (
+            np.minimum.reduce([ls_sim[s] for s in succs[k]]) if succs[k] else finish
+        )
+        es_k = (
+            np.maximum.reduce([ef_sim[p] for p in acts[k]["preds"]])
+            if acts[k]["preds"]
+            else np.zeros(n_sim)
+        )
+        ls_sim[k] = lf_sim[k] - samples[k]
+        crit_idx[k] = float(np.mean(np.abs(ls_sim[k] - es_k) < 1e-9))
+    base["criticality_index"] = base["activity"].map(crit_idx)
+
+    stats = {
+        "expected_duration": mean,
+        "sigma_critical_path": sigma,
+        "mc_mean": float(np.mean(finish)),
+        "mc_p50": float(np.percentile(finish, 50)),
+        "mc_p80": float(np.percentile(finish, 80)),
+        "mc_p95": float(np.percentile(finish, 95)),
+    }
+    meta = {
+        "computed_at": utcnow(),
+        "version": __version__,
+        "n_sim": n_sim,
+        "seed": seed,
+        "critical_activities": crit,
+        "mc_finish_quantiles": {
+            str(q): float(np.percentile(finish, q)) for q in (5, 25, 50, 75, 95)
+        },
+    }
+    return Result(method="pert", params={"n_sim": n_sim}, stats=stats,
+                  table=base, meta=meta)

pmcontrols-0.1.0.dist-info/METADATA

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: pmcontrols
+Version: 0.1.0
+Summary: Project scheduling and earned value control for Python: CPM, PERT with Monte Carlo schedule risk, minimum-cost crashing, EVM and earned schedule, validated against published reference values.
+Author: Atakan Arikan
+License: MIT
+Project-URL: Homepage, https://github.com/arikanatakan/pmcontrols
+Project-URL: Documentation, https://arikanatakan.github.io/pmcontrols/
+Project-URL: Repository, https://github.com/arikanatakan/pmcontrols
+Project-URL: Issues, https://github.com/arikanatakan/pmcontrols/issues
+Keywords: project-management,critical-path,cpm,pert,earned-value,evm,earned-schedule,schedule-risk,crashing,project-controls,eia-748
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Manufacturing
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Office/Business :: Scheduling
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scipy>=1.10
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs-material; extra == "docs"
+Dynamic: license-file
+
+# pmcontrols
+
+[![CI](https://github.com/arikanatakan/pmcontrols/actions/workflows/ci.yml/badge.svg)](https://github.com/arikanatakan/pmcontrols/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/github/license/arikanatakan/pmcontrols)](LICENSE)
+
+Project scheduling and earned value control for Python.
+
+CPM, PERT with Monte Carlo schedule risk, minimum-cost crashing, and
+EVM/earned-schedule control — computed from the defining formulations,
+never from spreadsheet conventions, and checked against published
+reference values in the test suite.
+
+Companion to [lotsampling](https://github.com/arikanatakan/lotsampling) (acceptance
+sampling): lotsampling judges the lot, pmcontrols keeps the project honest.
+
+## Motivation
+
+Every project office computes CPI and SPI; almost all of it happens in
+Excel. R and commercial tools (Primavera, Deltek, @RISK) cover schedule
+risk and earned value; in Python the landscape is a 4 KB CPM toy and an
+abandoned ERP add-on. There is no maintained library a cost engineer or
+a project-controls researcher can `pip install` to get:
+
+- the **critical path** with full ES/EF/LS/LF/slack accounting
+- **PERT** three-point analysis plus what the textbook procedure cannot
+  give you: a Monte Carlo completion distribution and per-activity
+  **criticality indices**
+- **crashing as optimization** — the cheapest set of compressions
+  meeting a deadline, solved as the classical time/cost trade-off LP
+  rather than by manual marginal-cost inspection
+- **EVM with earned schedule** — the full indicator set (CV, SV, CPI,
+  SPI, the EAC family, TCPI, VAC) plus Lipke's time-based ES, SPI(t)
+  and duration forecast IEAC(t), which plain EVM gets wrong late in
+  projects
+
+## Quickstart
+
+```python
+import pmcontrols as pm
+
+activities = [
+    {"id": "A", "predecessors": [],         "duration": 2},
+    {"id": "B", "predecessors": [],         "duration": 3},
+    {"id": "C", "predecessors": ["A"],      "duration": 2},
+    {"id": "D", "predecessors": ["B"],      "duration": 4},
+    {"id": "E", "predecessors": ["C"],      "duration": 4},
+    {"id": "F", "predecessors": ["C"],      "duration": 3},
+    {"id": "G", "predecessors": ["D", "E"], "duration": 5},
+    {"id": "H", "predecessors": ["F", "G"], "duration": 2},
+]
+
+r = pm.cpm(activities)
+r.stats["project_duration"]        # 15.0
+r.meta["critical_activities"]      # ['A', 'C', 'E', 'G', 'H']
+r.table                            # tidy ES/EF/LS/LF/slack DataFrame
+
+# Cheapest way to finish in 13 periods (linear program):
+r = pm.crash(crash_activities, target=13)
+r.stats["total_crash_cost"]        # optimal, not greedy
+
+# Plan once, freeze, control forever:
+pm.plan(periods, pv_curve).save("pmb.json")     # commit this to git
+r = pm.evm("pmb.json", ev=30_000, ac=35_000, at=4)
+r.ok                 # False — CPI and SPI(t) below threshold
+print(r.summary())   # audit text with plain-language verdict
+r.stats["ieac_t"]    # earned-schedule duration forecast
+```
+
+`r.ok` is the automation primitive: a weekly cron job can evaluate the
+latest actuals against the frozen PMB and exit nonzero the moment cost
+or schedule efficiency breaches a threshold.
+
+## Validation philosophy
+
+Every release must reproduce, in `tests/validation_cases.json` (each
+case ships with its full derivation):
+
+1. the General Foundry reference network — complete ES/EF/LS/LF/slack
+   table, 15-period critical path, and optimal crash costs to 14 and 13
+   periods,
+2. hand-derived EVM/earned-schedule cases covering the full indicator
+   set and the ES interpolation formula,
+3. identity and property checks (slack = LS−ES = LF−EF; SPI(t) = ES/AT;
+   crash cost monotone in target; Monte Carlo means converging to
+   analytic values),
+4. (before 0.1) published PMI/Lipke earned-schedule case studies,
+   verified privately where copyright prevents redistribution.
+
+## Status
+
+0.1.0 — first public release. The API surface is small on purpose; the
+`Result`/`PMB` contract is frozen and append-only from this version on.
+
+## Roadmap
+
+| Version | Scope |
+| ------- | ----- |
+| 0.2 | Published PMI/Lipke earned-schedule case-study validation; Gantt and OC plotting (separate from the statistics) |
+| 0.3 | Resource leveling and constrained scheduling; schedule risk drivers (correlation, risk events); EVM from time-phased ledgers (DataFrame in, indicators out) |
+| 0.4 | Critical chain buffers; probabilistic crashing (crash under uncertainty); ES forecasting variants (performance factors); JOSS paper |
+
+Out of scope: Gantt-chart project *editors* (use dedicated PM tools),
+process control, acceptance sampling (see lotsampling), generic LP modeling
+(use scipy/pyomo directly).
+
+## License
+
+MIT. Written and maintained by [Atakan Arikan](https://github.com/arikanatakan),
+MSc Student at Tsinghua University and Politecnico di Milano.

pmcontrols-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+pmcontrols/__init__.py,sha256=YXhB1tbUoJl6wCy5GptZTbc7S0rNWm3dJSe3F3g2x34,928
+pmcontrols/_result.py,sha256=qPe0auuviSxq4VQ_haJVLFPFdG6qr0oQxL6om_C7I6c,5640
+pmcontrols/_version.py,sha256=kUR5RAFc7HCeiqdlX36dZOHkUI5wI6V_43RpEcD8b-0,22
+pmcontrols/crash.py,sha256=ZmuX-r3CxyKQcpokl6MTKHvRvNtZ3cK68a_ouMKVHEA,4372
+pmcontrols/evm.py,sha256=ZDZ6g30yqINQkME92umLVsLZXbFV9W0Nl-MSfdc8OL8,4895
+pmcontrols/network.py,sha256=n13VN0PpKutGWLi3cQLGWvtvMD7_I7DYrNm0Zp4UQjw,8092
+pmcontrols/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pmcontrols-0.1.0.dist-info/licenses/LICENSE,sha256=a3yEF0vGHVodoVsu7IKY7Otc_8-fuwfYXMMm9h3VoJg,1070
+pmcontrols-0.1.0.dist-info/METADATA,sha256=_l2Q535rGvcZ2QImri9w4qzUCi1PmSQxtcyH_BJ-yn8,6435
+pmcontrols-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pmcontrols-0.1.0.dist-info/top_level.txt,sha256=gK8Yoyxrm2EFREu4Is1E2IWET3GoNnvhTMUaFgib-0c,11
+pmcontrols-0.1.0.dist-info/RECORD,,

pmcontrols-0.1.0.dist-info/WHEEL

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

pmcontrols-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Atakan Arikan
+
+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.

pmcontrols-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pmcontrols