diff --git a/docs/decisions.md b/docs/decisions.md index 5a586fa..049582f 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -16,3 +16,8 @@ 4. Big-money recommendations (e.g. BHP go/no-go, roughly 100k AIC): independent second opinion on the numbers. - If a bigger-model spawn is refused, tell the player and ask them to run the review. - Routine tool building is not reviewed by a bigger model. + +## 2026-10-09 Drop "ROI/day %" terminology +- `profit/day รท new_capex` (what tools were calling "ROI/day X%") is just 1/payback_days rewritten as a percentage. It is NOT a compoundable rate of return - there's no reinvestment mechanism, and every opportunity here is capacity/market-limited (saturation), so it can't be extrapolated or annualized like an interest rate. +- Report **payback in days** as the primary number everywhere. A "%/day" figure, if shown at all, must be labelled as simple/non-compounding and never compared to a real yield/interest rate. +- Applies to `tools/whatif.py`, `tools/simulate.py`, `tools/scan.py`, `tools/persistence.py`, `tools/history.py`, and anything built after this that reports a return on a one-time building cost. diff --git a/plans/chains/nike_deimos_lst.yaml b/plans/chains/nike_deimos_lst.yaml index bebb3ff..94328d5 100644 --- a/plans/chains/nike_deimos_lst.yaml +++ b/plans/chains/nike_deimos_lst.yaml @@ -1,8 +1,9 @@ # Multi-base chain: Nike mines LST, ships it to Deimos, Deimos turns it (+ market AL) into BSE. -# trip_cost/cargo are placeholders (see tools/network.py) until a real fuel model exists. +# trip_cost omitted below: tools/network.py computes it from the real fuel model (puga.shipping) +# since Nike<->Deimos is a direct-jump route. cargo is still a placeholder (ship hold size). name: "Nike LST -> Deimos PP2 (BSE)" bases: nike: {plan: plans/examples/nike_lst_ext.yaml, cm_free: true} # founded via the faction expansion contract's kit deimos: plans/examples/deimos_pp2_bse.yaml transfers: - - {material: LST, src: nike, dst: deimos, trip_cost: 9250, cargo: 500} + - {material: LST, src: nike, dst: deimos, cargo: 500} diff --git a/puga/network.py b/puga/network.py index d95de4c..5fc74b1 100644 --- a/puga/network.py +++ b/puga/network.py @@ -8,6 +8,15 @@ the transferred quantity (base A "sells" it, base B "buys" it, at the same price combined total needs only ONE correction: the real freight cost of physically moving it, which isn't in either base's isolated numbers. Leftover surplus (more produced than a partner needs) is still validly sold at market by the producing base; leftover deficit is still validly bought. + +CAVEAT: the "cancel out" claim only holds when the price basis prices buy and sell sides of a +ticker identically (true for `uni30`, the default in tools/network.py). Under `--basis real` +(or any basis with a genuine bid/ask spread), each base's own `simulate()` correctly books its +flows at the real sell (bid/vwap) or buy (ask) price - but for the `moved` quantity, that's not +what actually happens: it moves at no transaction price at all, not at both a real sale AND a +real purchase. Summing the two bases' independent numbers and subtracting only freight therefore +UNDERSTATES the true combined profit by the bid-ask spread on the moved quantity - a real gap, +not symmetric cancellation, under any basis with a spread. Not corrected here. """ from dataclasses import dataclass, field from . import fio @@ -33,7 +42,9 @@ class Transfer: material: str src: str # producing base's name (key in the `bases` dict) dst: str # consuming base's name - trip_cost: float = 9250.0 # AIC per round trip; PLACEHOLDER until a real route/fuel model exists + trip_cost: float = 9250.0 # AIC per round trip; tools/network.py fills this from puga.shipping.round_trip_cost() + # when src/dst are a direct-jump route and no explicit value is given in the chain + # YAML - this default is the fallback for gateway routes/transfers without one cargo: float = 500.0 # t or m3 per trip diff --git a/tools/network.py b/tools/network.py index 2657346..88ce683 100755 --- a/tools/network.py +++ b/tools/network.py @@ -9,7 +9,7 @@ import argparse, sys from pathlib import Path import yaml sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) -from puga import ROOT, config, market, prunplanner as pp +from puga import ROOT, config, market, prunplanner as pp, shipping from puga.network import BaseNode, Transfer, combine sys.path.insert(0, str(Path(__file__).resolve().parent)) @@ -56,18 +56,35 @@ def main(): built["CM"] = 1 bases[key] = BaseNode(key, plan, recipes, blds, planet["resources"], planet["fertility"], price, faction, perm, built) - transfers = [Transfer(**t) for t in net.get("transfers", [])] + sf_px = (snap.get(("SF", a.cx)) or market.Quote("SF", a.cx)).ask or 0 + ff_px = (snap.get(("FF", a.cx)) or market.Quote("FF", a.cx)).ask or 0 + transfers, cost_notes = [], [] + for raw in net.get("transfers", []): + t = dict(raw) + if "trip_cost" not in t and t["src"] in bases and t["dst"] in bases: + real = shipping.round_trip_cost(bases[t["src"]].plan["planet_natural_id"], bases[t["dst"]].plan["planet_natural_id"], + sf_px, ff_px) + if real is not None: + t["trip_cost"] = real + cost_notes.append(f" {t['material']} {t['src']}->{t['dst']}: real round-trip cost {real:,.0f} AIC (puga.shipping)") + else: + cost_notes.append(f" {t['material']} {t['src']}->{t['dst']}: no direct-jump route (gateway?) - using placeholder {Transfer.__dataclass_fields__['trip_cost'].default:,.0f} AIC, check SFC in-game") + transfers.append(Transfer(**t)) r = combine(bases, transfers) print(f"{net.get('name', a.spec)} ({a.basis} prices)\n") for key, res in r["results"].items(): line = f"[{key}] area {res['area']:.0f} profit/day {res['profit']:,.0f} new capex {res['new_capex']:,.0f}" if res["new_capex"] > 0: - line += f" ({100*res['profit']/res['new_capex']:.1f}%/day)" + line += f" (payback {res['new_capex']/res['profit']:.1f} d)" print(line) for b in res["buildings"]: print(f" {b['amount']:2} x {b['building']:4} eff {b['efficiency']*100:6.1f}%") + if cost_notes: + print("\nFREIGHT COST") + print("\n".join(cost_notes)) + print("\nTRANSFERS") for t in r["ledger"]: note = f"SHORTFALL {t['shortfall']:.1f}/d bought at market by {t['dst']}" if t["shortfall"] > 0.01 else \ @@ -77,13 +94,16 @@ def main(): total_new_capex = sum(res["new_capex"] for res in r["results"].values()) print(f"\nCOMBINED profit/day {r['total_profit']:,.0f} new capex {total_new_capex:,.0f}" - + (f" {100*r['total_profit']/total_new_capex:.1f}%/day" if total_new_capex > 0 else "")) + + (f" payback {total_new_capex/r['total_profit']:.1f} d" if total_new_capex > 0 else "")) print("CAUTION: a base's 'profit/day' here is its WHOLE plan (existing buildings included), not just the new " - "addition, so its %/day overstates the marginal return where new_capex is small relative to an existing " - "base. For the true marginal ROI, also simulate the base's plan WITHOUT the new building/transfer and " - "diff the profit; see docs/library.md.") - print("NOTE: trip_cost/cargo are placeholders (default 9250 AIC, 500 t/m3, same as the AI1 route) until a real " - "inter-base fuel model exists (docs/roadmap.md tools/route.py) -- check SFC in-game for the real cost.") + "addition, so its payback here understates the marginal payback where new_capex is small relative to an " + "existing base. For the true marginal payback, also simulate the base's plan WITHOUT the new " + "building/transfer and diff the profit; see docs/library.md.") + print("NOTE: trip_cost is computed from the real fuel model (puga.shipping, max sliders) for direct-jump routes " + "between two bases in this chain (see FREIGHT COST above); a gateway route, or a transfer with an " + "explicit trip_cost in the YAML, uses that value instead (9250 AIC if neither applies). cargo defaults " + "to 500 t/m3 (the account's ship hold size, confirmed via FIO) - override per-transfer if a different " + "ship is used.") if __name__ == "__main__": diff --git a/tools/scan.py b/tools/scan.py index 5211203..16916d6 100755 --- a/tools/scan.py +++ b/tools/scan.py @@ -1,9 +1,10 @@ #!/usr/bin/env python3 """Depth-aware single-step recipe scan at one exchange (saturation model v1, see docs/saturation-design.md). -For each recipe: buildings the market can absorb (N*), and ROI/day at N=1 and N* using a patient sell price -(not top-of-book) and ask-walked inputs. Excludes thin markets by default. +For each recipe: buildings the market can absorb (N*), and payback/yield at N=1 and N* using a patient sell +price (not top-of-book) and ask-walked inputs. Excludes thin markets by default. yld/d is profit/day over +capex as a %, NOT a compoundable rate - it's 1/payback; see docs/decisions.md's "Drop ROI/day %" entry. - tools/scan.py # AI1, all tiers, top 30 by ROI at N* + tools/scan.py # AI1, all tiers, top 30 by yield at N* tools/scan.py --cogc METALLURGY --tier S # e.g. a Metallurgy-COGC base, up to settlers tools/scan.py --sort total --min-n 3 # rank by absorbable profit/day """ @@ -35,7 +36,7 @@ def main(): ap.add_argument("--deprec", type=float, default=0, help="demolish-later mode: building value decays linearly to 0 over this many days (game: ~60); subtracts capex/deprec per day") ap.add_argument("--input", help="only recipes consuming this ticker as an input, e.g. --input AL for recipes built on top of your own AL chain") ap.add_argument("--planet", help="planet natural id: adds extraction (EXT/COL/RIG) from its resources, uses its fertility and active COGC; new base (not in state) => no HQ, permits+1") - ap.add_argument("--own", type=int, default=1, help="how many buildings WE would run; ROI is measured at this size (default 1). --min-n is only a market-size filter") + ap.add_argument("--own", type=int, default=1, help="how many buildings WE would run; yield/payback is measured at this size (default 1). --min-n is only a market-size filter") ap.add_argument("--skip", default="", help="tiers left unstaffed, e.g. technician (no housing/wages; efficiency = staffed headcount share)") ap.add_argument("--experts", default="", help="expert counts, e.g. METALLURGY=2 (bonus x1.0306..1.284 for 1..5)") ap.add_argument("--hq", action="store_true", help="corp HQ bonus x1.1") @@ -256,10 +257,11 @@ def main(): import json Path(a.json).write_text(json.dumps(rows)) print(f"# {a.cx} tier<={a.tier or 'any'} cogc={a.cogc or '-'} faction={faction or '-'} ({pu}/{pt} permits) min-n>={a.min_n} sorted by {a.sort}") - print("# ROI/day is for OUR size (--own buildings, default 1) incl. our own price impact; market = buildings the market could absorb (--min-n filters on it, nothing else). Net of freight. Patient asks near VWAP, inputs ask-walked; all estimates") - print(f"{'ROI/d':>6} {'own':>3} {'market':>6} {'lim':4} {'profit/d':>11} {'capex':>9} {'eff':>4} {'bld':4} {'staff':5} {'t/d':>5} {'frt/d':>6} {'h':>5} recipe") + print("# yld/d is profit/day / capex as a %, for OUR size (--own buildings, default 1) incl. our own price impact; this is NOT a compoundable rate (1/payback, see docs/decisions.md) - pback is the number to actually reason about. market = buildings the market could absorb (--min-n filters on it, nothing else). Net of freight. Patient asks near VWAP, inputs ask-walked; all estimates") + print(f"{'yld/d':>6} {'pback':>6} {'own':>3} {'market':>6} {'lim':4} {'profit/d':>11} {'capex':>9} {'eff':>4} {'bld':4} {'staff':5} {'t/d':>5} {'frt/d':>6} {'h':>5} recipe") for r in rows[:a.top]: - print(f"{r['roiN']:6.1f} {r['n']:3d} {r['n_lim']:6.1f} {r['lim']:4} {r['total']:11.0f} {r['capex']:9.0f} {r['eff']*100:4.0f} {r['bld']:4} {r['staff']:5} {r['tons']:5.0f} {r['frt']:6.0f} " + pback = f"{100/r['roiN']:6.1f}" if r['roiN'] > 0 else " inf" + print(f"{r['roiN']:6.1f} {pback} {r['n']:3d} {r['n_lim']:6.1f} {r['lim']:4} {r['total']:11.0f} {r['capex']:9.0f} {r['eff']*100:4.0f} {r['bld']:4} {r['staff']:5} {r['tons']:5.0f} {r['frt']:6.0f} " f"{r['h']:5.1f} {r['rec']}{' [thin]' if r['thin'] else ''}") diff --git a/tools/simulate.py b/tools/simulate.py index 548f80b..a2ba238 100755 --- a/tools/simulate.py +++ b/tools/simulate.py @@ -70,7 +70,7 @@ def main(): print(f"{plan['plan_name']} {plan['planet_natural_id']} COGC {plan.get('plan_cogc')} prices: {a.cx} {a.basis}") print(f"Area {r['area']:.0f}/500 Profit/day {r['profit']:,.0f} gross {r['gross']:,.0f} degradation {r['degradation']:,.0f} plan cost {r['plan_cost']:,.0f} ROI {r['roi_days'] and round(r['roi_days'], 2)} d") nc = r["new_capex"] - print(f"NEW CAPEX = planned minus already built ({built or 'nothing built'}): {nc:,.0f} -> payback {nc / r['profit']:.2f} d = {100 * r['profit'] / nc:.1f}%/day" if r["profit"] > 0 and nc > 0 else ("NEW CAPEX: nothing to build" if nc <= 0 else "NEW CAPEX: profit <= 0")) + print(f"NEW CAPEX = planned minus already built ({built or 'nothing built'}): {nc:,.0f} -> payback {nc / r['profit']:.2f} d" if r["profit"] > 0 and nc > 0 else ("NEW CAPEX: nothing to build" if nc <= 0 else "NEW CAPEX: profit <= 0")) print("\nWORKFORCE need supply open eff%") for t, w in r["workforce"].items(): if w["need"] or w["supply"]: diff --git a/tools/whatif.py b/tools/whatif.py index 024f1dc..c1671ab 100644 --- a/tools/whatif.py +++ b/tools/whatif.py @@ -14,7 +14,7 @@ from collections import Counter from pathlib import Path import yaml sys.path.insert(0, str(Path(__file__).resolve().parent.parent)) -from puga import config, fio, market, prunplanner as pp +from puga import config, contracts, fio, market, prunplanner as pp, shipping from puga.simulate import simulate sys.path.insert(0, str(Path(__file__).resolve().parent)) @@ -88,6 +88,40 @@ def reclaim_value(ticker: str, qty: int, built_count: int, cx: str): return {"value": value, "items": items} +def trip_tonnage(flows: dict, mats: dict): + """Total t/m3 the base needs to haul IN (net importers) and ship OUT (net exporters) per day - + same accounting scan.py already uses for its own trip-cost estimate (max of the four, since + imports and exports share the same round trips).""" + w_in = w_out = v_in = v_out = 0.0 + for t, f in flows.items(): + net = f["inp"] - f["out"] + m = mats.get(t) + if not m or abs(net) < 1e-6: + continue + if net > 0: + w_in += net * m["Weight"]; v_in += net * m["Volume"] + else: + w_out += -net * m["Weight"]; v_out += -net * m["Volume"] + return w_in, w_out, v_in, v_out + + +def marginal_freight(r_b, r_a, planet_id, cx, sf_price, ff_price, mats): + """AIC/day freight for the EXTRA trips this addition requires - not the base's whole freight + bill. If the addition's materials fit in slack the base's existing traffic already has (the + common case for a small addition), this comes out to ~0: real freight cost only kicks in once + net t/m3 crosses into needing another round trip. Returns (freight_aic_per_day, note).""" + origin = shipping.cx_system(cx) + if origin is None: + return 0.0, f"no station found for CX {cx!r} - freight not modelled" + rt = shipping.round_trip_cost(origin, planet_id, sf_price, ff_price) + if rt is None: + return 0.0, "no priceable route (gateway without a measured LOCK fee?) - freight not modelled" + trips_b = max(trip_tonnage(r_b["flows"], mats)) / contracts.SHIP_CARGO + trips_a = max(trip_tonnage(r_a["flows"], mats)) / contracts.SHIP_CARGO + extra_trips = trips_a - trips_b + return extra_trips * rt, f"{extra_trips:+.3f} extra round trips/day x {rt:,.0f} AIC/trip" + + def run(spec, recipes, blds, price, faction, perm, built): plan = plan_push.build_payload(spec, recipes, {b["building_ticker"] for b in blds}) planet = pp._g(f"/data/planet/{plan['planet_natural_id']}/", 3600) @@ -151,6 +185,12 @@ def main(): d_profit = r_a["profit"] - r_b["profit"] d_capex = r_a["new_capex"] - r_b["new_capex"] + mats = {m["Ticker"]: m for m in fio.materials()} + sf_px = (snap.get(("SF", a.cx)) or market.Quote("SF", a.cx)).ask or 0 + ff_px = (snap.get(("FF", a.cx)) or market.Quote("FF", a.cx)).ask or 0 + freight, freight_note = marginal_freight(r_b, r_a, planet_id, a.cx, sf_px, ff_px, mats) + d_profit -= freight + before_counts = Counter(b["building"] for b in before_spec.get("buildings", []) for _ in range(b["amount"])) after_counts = Counter(b["building"] for b in after_spec.get("buildings", []) for _ in range(b["amount"])) reclaim_total = 0.0 @@ -166,8 +206,9 @@ def main(): print(f"BEFORE profit/day {r_b['profit']:,.0f} new_capex {r_b['new_capex']:,.0f}") print(f"AFTER profit/day {r_a['profit']:,.0f} new_capex {r_a['new_capex']:,.0f}") + print(f"FREIGHT {freight:+,.0f} AIC/day marginal ({freight_note})") if reclaim_lines: - print(f"\nRECLAIMED MATERIALS (demolishing what's removed, sell value, real FIO data):") + print("\nRECLAIMED MATERIALS (demolishing what's removed, sell value, real FIO data):") for line in reclaim_lines: print(line) print(f" total: {reclaim_total:,.0f} AIC") @@ -175,7 +216,7 @@ def main(): net_label = f" net cash GAINED {-net_capex:,.0f}" if net_capex < 0 and reclaim_total else (f" net new capex {net_capex:,.0f}" if reclaim_total else "") print(f"\nMARGINAL profit/day {d_profit:,.0f} new_capex {d_capex:,.0f}" + net_label, end="") if net_capex > 0 and d_profit > 0: - print(f" ROI/day {100*d_profit/net_capex:.2f}% payback {net_capex/d_profit:.1f} d") + print(f" payback {net_capex/d_profit:.1f} d (simple, non-compounding - a one-time capex paying itself off; not a reinvestable rate, see docs/decisions.md)") elif net_capex <= 0 and d_profit > 0: print(" (no net new capex after reclaim)" if reclaim_total else " (no new capex)") else: