simcon-toolkit 0.1.0__py3-none-any.whl

simcon_toolkit/_kit/templates/quoting/quoting/costing.py

@@ -0,0 +1,725 @@
+"""From geometry + a gating decision to a tool price and a piece price.
+
+Every number here is traceable to two places and nowhere else: the **shop files** (rates, presses,
+grades, the mold cost model) and the **simulation** (cavity pressure, fill time). Nothing is
+hard-coded that an estimator would want to argue with - if you disagree with a figure, it is in
+``shop/``, and if the estimate came out wrong, the correction goes in ``shop/lessons.md`` and
+changes the next quote.
+
+Three model choices worth knowing before you trust the output:
+
+* **Cooling time is analytic**, not simulated - the AI filling solver has no cooling phase. The
+  one-term slab solution below is the textbook estimate, cross-checkable on paper, and it is
+  multiplied by a calibration factor precisely because it is known to run optimistic on ribbed
+  parts (see ``shop/lessons.md`` L-001).
+* **Clamp force is never sized from the simulation alone.** The AI model is one cavity with no
+  runner system and under-reads absolute pressure on multi-gate parts, so the material's
+  rule-of-thumb cavity pressure is taken as a floor. Which one governed is reported.
+* **The gate count is decided on money**, not on pressure: more gates means lower pressure and
+  possibly a smaller press, against one more hot-runner nozzle per cavity and one more weld line.
+  :func:`compare_options` prices both sides and picks.
+"""
+
+from __future__ import annotations
+
+import math
+from dataclasses import asdict, dataclass, field
+
+from .geometry import PartGeometry
+from .shop import ShopContext
+from .study import GateOption
+
+
+# ==========================================================================
+# physics-ish helpers
+# ==========================================================================
+def cooling_time_s(wall_mm: float, thermal: dict, melt_K: float, mold_K: float, *, factor: float = 1.0) -> float:
+    """One-term slab solution for cooling the part centre to ejection temperature.
+
+        t = h^2 / (pi^2 * alpha) * ln( 4/pi * (T_melt - T_mold) / (T_eject - T_mold) )
+
+    with ``h`` the half wall thickness and ``alpha = lambda / (rho * cp)``. This is the estimate a
+    process engineer can redo on paper from a datasheet, which is exactly why it is used here: an
+    estimate the customer can check beats a black box. ``factor`` carries the shop's measured
+    correction (ribs and bosses cool slower than a slab).
+    """
+    alpha = float(thermal["lambda_W_mK"]) / (float(thermal["rho_kg_m3"]) * float(thermal["cp_J_kgK"]))
+    h = (wall_mm / 2.0) / 1000.0
+    eject_K, dT = float(thermal["eject_K"]), float(melt_K - mold_K)
+    ratio = (4.0 / math.pi) * dT / max(eject_K - mold_K, 1.0)
+    if ratio <= 1.0:  # mould already above ejection temperature - not a runnable process
+        return float("nan")
+    return factor * (h * h) / (math.pi**2 * alpha) * math.log(ratio)
+
+
+def clamp_force_kN(mean_cavity_pressure_bar: float, projected_area_cm2: float) -> float:
+    """F[kN] = p[bar] * A[cm2] / 100.   (1 bar = 0.1 N/mm2.)"""
+    return mean_cavity_pressure_bar * projected_area_cm2 / 100.0
+
+
+def cavity_layout(cavities: int, tooling: dict) -> tuple[int, int]:
+    """Rows x columns for the cavity grid - the shop's preferred grid, else near-square."""
+    preferred = tooling.get("layout", {}).get("preferred_grids", {})
+    if str(cavities) in preferred:
+        cols, rows = preferred[str(cavities)]
+        return int(cols), int(rows)
+    cols = int(math.ceil(math.sqrt(cavities)))
+    rows = int(math.ceil(cavities / cols))
+    return cols, rows
+
+
+# ==========================================================================
+# results
+# ==========================================================================
+@dataclass
+class CycleTime:
+    fill_s: float
+    pack_s: float
+    cool_s: float
+    handling_s: float
+    total_s: float
+    governing_wall_mm: float
+    basis: str = ""
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class MachineChoice:
+    name: str
+    clamp_kN: float
+    rate_eur_h: float
+    shot_cm3: float
+    required_clamp_kN: float
+    clamp_basis: str  # "simulation" | "material rule of thumb"
+    shot_volume_cm3: float
+    shot_utilisation: float
+    clamp_utilisation: float
+    plate_mm: tuple[float, float]
+    fits: bool
+    notes: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class ToolCost:
+    lines: list[tuple[str, float]]
+    subtotal_eur: float
+    risk_eur: float
+    margin_eur: float
+    total_eur: float
+    lead_time_weeks: float
+    plate_mm: tuple[float, float]
+    cavity_grid: tuple[int, int]
+    complexity: float
+    hot_runner: bool
+    n_nozzles: int
+    side_actions: int
+    notes: list[str] = field(default_factory=list)
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class PiecePrice:
+    parts_per_year: int
+    material_eur: float
+    machine_eur: float
+    labour_eur: float
+    secondary_eur: float
+    setup_eur: float
+    overhead_eur: float
+    margin_eur: float
+    total_eur: float
+    tool_amortisation_eur: float
+
+    def as_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass
+class Quote:
+    part_name: str
+    cavities: int
+    grade: dict
+    geo: PartGeometry
+    option: GateOption
+    cycle: CycleTime
+    machine: MachineChoice
+    tool: ToolCost
+    ladder: list[PiecePrice]
+    shot_mass_g: float
+    part_mass_g: float
+    currency: str
+    assumptions: list[str] = field(default_factory=list)
+    flags: list[str] = field(default_factory=list)
+
+    def reference_price(self) -> PiecePrice:
+        """The middle rung of the ladder - what "the price" means when someone asks for one."""
+        return self.ladder[len(self.ladder) // 2]
+
+    def total_cost_of_ownership(self, parts: int) -> float:
+        price = min(self.ladder, key=lambda p: abs(p.parts_per_year - parts))
+        return self.tool.total_eur + price.total_eur * parts
+
+    def as_dict(self) -> dict:
+        return {
+            "part_name": self.part_name,
+            "cavities": self.cavities,
+            "grade": self.grade,
+            "geometry": self.geo.as_dict(),
+            "gating": self.option.as_dict(),
+            "cycle": self.cycle.as_dict(),
+            "machine": self.machine.as_dict(),
+            "tool": self.tool.as_dict(),
+            "ladder": [p.as_dict() for p in self.ladder],
+            "shot_mass_g": round(self.shot_mass_g, 2),
+            "part_mass_g": round(self.part_mass_g, 2),
+            "currency": self.currency,
+            "assumptions": self.assumptions,
+            "flags": self.flags,
+        }
+
+    def summary(self) -> str:
+        ref = self.reference_price()
+        feed = f"{self.tool.n_nozzles} hot-runner nozzle(s)" if self.tool.hot_runner else "cold runner"
+        lines = [
+            f"  gating          {self.option.n_gates} gate(s), {self.option.max_pressure_bar:.0f} bar "
+            f"({self.option.source}), {self.option.n_welds} weld line(s) of which {self.option.n_interior_welds} interior",
+            f"  machine         {self.machine.name}  ({self.machine.required_clamp_kN:.0f} kN required, "
+            f"basis: {self.machine.clamp_basis})",
+            f"  cycle           {self.cycle.total_s:.1f} s  (fill {self.cycle.fill_s:.2f} + pack "
+            f"{self.cycle.pack_s:.1f} + cool {self.cycle.cool_s:.1f} + handling {self.cycle.handling_s:.1f})",
+            f"  shot            {self.shot_mass_g:.1f} g over {self.cavities} cavities "
+            f"({self.machine.shot_utilisation * 100:.0f}% of barrel)",
+            f"  tooling         {self.tool.total_eur:,.0f} {self.currency}   lead {self.tool.lead_time_weeks:.0f} weeks"
+            f"   ({feed}, {self.tool.side_actions} side action(s))",
+            "  piece price     " + "   ".join(f"{p.parts_per_year // 1000}k: {p.total_eur:.3f}" for p in self.ladder),
+            f"  reference       {ref.total_eur:.3f} {self.currency}/part at {ref.parts_per_year:,} pcs/year",
+        ]
+        lines += [f"  ! {f}" for f in self.flags]
+        return "\n".join(lines)
+
+
+# ==========================================================================
+# the model
+# ==========================================================================
+def _plate_size_mm(geo: PartGeometry, cavities: int, tooling: dict) -> tuple[float, float, tuple[int, int]]:
+    """Mold plate footprint from the cavity grid, part size, spacing and edge margin."""
+    layout = tooling["layout"]
+    in_plane = [i for i in range(3) if i != geo.draw_axis]
+    part_a, part_b = geo.bbox_mm[in_plane[0]], geo.bbox_mm[in_plane[1]]
+    cols, rows = cavity_layout(cavities, tooling)
+    spacing, margin = layout["cavity_spacing_mm"], layout["edge_margin_mm"]
+    a = cols * part_a + (cols - 1) * spacing + 2 * margin
+    b = rows * part_b + (rows - 1) * spacing + 2 * margin
+    a = max(a, layout["min_plate_mm"][0])
+    b = max(b, layout["min_plate_mm"][1])
+    return a, b, (cols, rows)
+
+
+def _complexity(geo: PartGeometry, side_actions: int, ctx: ShopContext) -> float:
+    """How much harder than a plain cavity this one is to cut.
+
+    Deliberately **not** built on surface-to-volume: that number is dominated by wall thinness,
+    so a trivial 1.5 mm plate scores 15 on it and would price like a ribbed housing. The shape
+    factor (surface vs. bounding-box surface) is what actually tracks feature count.
+    """
+    f = 1.0
+    if geo.nominal_wall_mm < 1.2:
+        f += 0.15
+    if geo.draw_depth_mm > 60:
+        f += 0.15
+    f += 0.25 * max(0.0, geo.shape_factor - 1.0)
+    f += 0.05 * side_actions
+    f += 0.02 * geo.through_holes  # every hole is a core pin to make, fit and vent, per cavity
+    f += float(ctx.cal("complexity_bonus"))
+    return min(f, float(ctx.tooling["cavity"]["complexity_cap"]))
+
+
+def select_machine(
+    ctx: ShopContext,
+    *,
+    required_clamp_kN: float,
+    shot_volume_cm3: float,
+    plate_mm: tuple[float, float],
+    clamp_basis: str,
+) -> MachineChoice:
+    """The smallest press that clears clamp, shot window and tie-bar opening.
+
+    The three constraints are not equally hard, and pretending they are produces the useless
+    answer "nothing fits" on perfectly ordinary parts. **Clamp and tie-bar are hard** - too little
+    tonnage means flash, and a mold that does not physically go in does not go in. The **shot
+    window is soft**: a shot below 20 % of the barrel is a melt-residence problem to be managed
+    (smaller screw, shorter dwell), not a reason to refuse the job. So the search relaxes in that
+    order and says which constraint it had to bend.
+    """
+    cfg = ctx.machines
+    max_util = float(cfg.get("max_clamp_utilisation", 0.8))
+    lo, hi = cfg.get("shot_utilisation_window", [0.2, 0.8])
+    plate = (max(plate_mm), min(plate_mm))
+    ordered = sorted(cfg["machines"], key=lambda x: (x["clamp_kN"], x["rate_eur_h"]))
+
+    def clears_hard(m: dict) -> bool:
+        tb = (max(m["tiebar_mm"]), min(m["tiebar_mm"]))
+        return required_clamp_kN <= m["clamp_kN"] * max_util and plate[0] <= tb[0] and plate[1] <= tb[1]
+
+    def build(m: dict, *, fits: bool, notes: list[str]) -> MachineChoice:
+        return MachineChoice(
+            name=m["name"] + ("" if fits else " (no exact fit)"),
+            clamp_kN=float(m["clamp_kN"]),
+            rate_eur_h=float(m["rate_eur_h"]),
+            shot_cm3=float(m["shot_cm3"]),
+            required_clamp_kN=required_clamp_kN,
+            clamp_basis=clamp_basis,
+            shot_volume_cm3=shot_volume_cm3,
+            shot_utilisation=shot_volume_cm3 / float(m["shot_cm3"]),
+            clamp_utilisation=required_clamp_kN / float(m["clamp_kN"]),
+            plate_mm=plate_mm,
+            fits=fits,
+            notes=notes,
+        )
+
+    for m in ordered:
+        if clears_hard(m) and m["shot_cm3"] * lo <= shot_volume_cm3 <= m["shot_cm3"] * hi:
+            return build(m, fits=True, notes=[])
+
+    # Relax the shot window, keeping clamp and tie-bar.
+    for m in ordered:
+        if clears_hard(m):
+            util = shot_volume_cm3 / float(m["shot_cm3"])
+            note = f"shot is {util * 100:.0f}% of the barrel (window {lo * 100:.0f}-{hi * 100:.0f}%): " + (
+                "long melt residence - specify a smaller screw or accept the degradation risk"
+                if util < lo
+                else "no cushion - the next press up is the safe answer"
+            )
+            return build(m, fits=True, notes=[note])
+
+    # Genuinely nothing: name the binding constraint so the estimator can act on it.
+    biggest = max(cfg["machines"], key=lambda x: x["clamp_kN"])
+    widest = max(cfg["machines"], key=lambda x: max(x["tiebar_mm"]))
+    notes = []
+    if required_clamp_kN > biggest["clamp_kN"] * max_util:
+        notes.append(
+            f"needs {required_clamp_kN:.0f} kN clamp - above {biggest['name']} "
+            f"({biggest['clamp_kN']} kN) at {max_util * 100:.0f}% utilisation"
+        )
+    tb = (max(widest["tiebar_mm"]), min(widest["tiebar_mm"]))
+    if plate[0] > tb[0] or plate[1] > tb[1]:
+        notes.append(f"mold plate {plate_mm[0]:.0f}x{plate_mm[1]:.0f} mm clears no press ({widest['name']} is widest)")
+    if not notes:
+        notes.append("no press satisfies clamp and tie-bar together")
+    return build(biggest, fits=False, notes=notes)
+
+
+def tool_cost(
+    ctx: ShopContext,
+    geo: PartGeometry,
+    *,
+    cavities: int,
+    gates_per_cavity: int,
+    hardened: bool,
+    finish: str = "technical",
+) -> ToolCost:
+    """The mold, line by line. The gate count enters as hot-runner nozzles."""
+    t = ctx.tooling
+    plate_a, plate_b, grid = _plate_size_mm(geo, cavities, t)
+    plate_area_cm2 = plate_a * plate_b / 100.0
+    complexity = _complexity(geo, geo.side_actions, ctx)
+    notes: list[str] = []
+
+    lines: list[tuple[str, float]] = []
+    lines.append(("Mold base + plates", t["base"]["fixed_eur"] + t["base"]["eur_per_cm2_plate"] * plate_area_cm2))
+    lines.append(("Guided ejector package", float(t["base"]["guided_ejector_eur"])))
+
+    cav = t["cavity"]
+    cavity_eur = (cav["fixed_eur_per_cavity"] + cav["eur_per_cm2_part_surface"] * geo.surface_area_cm2) * complexity
+    lines.append((f"Cavities + cores ({cavities}x, complexity {complexity:.2f})", cavity_eur * cavities))
+    if hardened:
+        lines.append(("Hardening / coating (bought in)", cav["hardened_surcharge_eur_per_cavity"] * cavities))
+
+    sa = t["side_actions"]
+    if geo.side_actions:
+        lines.append((f"Side actions ({geo.side_actions}x slide)", sa["slide_eur"] * geo.side_actions))
+
+    feed = t["feed_system"]
+    hot = cavities >= int(feed["hot_runner_from_cavities"]) or gates_per_cavity > 1
+    n_nozzles = cavities * gates_per_cavity if hot else 0
+    if hot:
+        hr = feed["hot_runner_controller_eur"] + feed["hot_runner_nozzle_eur"] * n_nozzles
+        if n_nozzles > 1:
+            hr += feed["hot_runner_manifold_eur"]
+        lines.append((f"Hot runner ({n_nozzles} nozzle(s) + manifold + controller)", hr))
+    else:
+        lines.append((f"Cold runner ({gates_per_cavity} drop(s)/cavity)", float(feed["cold_runner_eur"])))
+
+    cool = t["cooling"]
+    circuits = max(int(cool["min_circuits"]), int(math.ceil(plate_area_cm2 / cool["cm2_plate_per_circuit"])))
+    lines.append((f"Cooling ({circuits} circuits)", cool["circuit_eur"] * circuits))
+
+    ej = t["ejection"]
+    pins = max(
+        int(ej["min_pins_per_cavity"]), int(math.ceil(ej["pins_per_cavity_per_cm2_projected"] * geo.projected_area_cm2))
+    )
+    lines.append((f"Ejection ({pins} pins/cavity)", ej["fixed_eur"] + ej["pin_eur"] * pins * cavities))
+
+    fin = t["finish"]
+    finish_rate = fin.get(f"{finish}_eur_per_cm2", fin["technical_eur_per_cm2"])
+    lines.append((f"Surface finish ({finish})", finish_rate * geo.surface_area_cm2 * cavities))
+
+    eng = t["engineering"]
+    hours = (
+        eng["design_hours_base"]
+        + eng["design_hours_per_cavity"] * cavities
+        + eng["design_hours_per_side_action"] * geo.side_actions
+    )
+    lines.append((f"Design + engineering ({hours:.0f} h)", eng["design_rate_eur_h"] * hours))
+
+    smp = t["sampling"]
+    lines.append((f"Sampling ({smp['shots_included']} shots incl.)", smp["eur_per_shot"] * smp["shots_included"]))
+
+    direct = sum(v for _, v in lines)
+    pm = direct * eng["project_mgmt_pct"] / 100.0
+    lines.append((f"Project management ({eng['project_mgmt_pct']:.0f}%)", pm))
+    subtotal = direct + pm
+    risk = subtotal * t["risk_contingency_pct"] / 100.0
+    margin = (subtotal + risk) * t["margin_pct"] / 100.0
+    total = (subtotal + risk + margin) * float(ctx.cal("tooling_price_factor"))
+
+    lt = t["lead_time"]
+    weeks = (
+        lt["base_weeks"]
+        + lt["weeks_per_extra_cavity"] * max(0, cavities - 1)
+        + lt["weeks_per_side_action"] * geo.side_actions
+        + (lt["hot_runner_weeks"] if hot else 0)
+        + lt["sampling_weeks"]
+        + (cav["hardened_lead_weeks"] if hardened else 0)
+        + (fin["texturing_lead_weeks"] if finish == "textured" else 0)
+    )
+
+    limit = t["layout"]["max_plate_mm"]
+    if plate_a > limit[0] or plate_b > limit[1]:
+        notes.append(f"plate {plate_a:.0f}x{plate_b:.0f} mm exceeds the largest mold we build ({limit[0]}x{limit[1]})")
+    if complexity >= t["cavity"]["complexity_cap"]:
+        notes.append("complexity is at the cap - this is a guess, not an estimate; quote after a design review")
+
+    return ToolCost(
+        lines=lines,
+        subtotal_eur=subtotal,
+        risk_eur=risk,
+        margin_eur=margin,
+        total_eur=total,
+        lead_time_weeks=weeks,
+        plate_mm=(plate_a, plate_b),
+        cavity_grid=grid,
+        complexity=complexity,
+        hot_runner=hot,
+        n_nozzles=n_nozzles,
+        side_actions=geo.side_actions,
+        notes=notes,
+    )
+
+
+def cycle_time(
+    ctx: ShopContext,
+    geo: PartGeometry,
+    option: GateOption,
+    thermal: dict,
+    melt_K: float,
+    mold_K: float,
+    *,
+    clamp_kN: float,
+) -> CycleTime:
+    """fill + pack + cool + handling, with cooling analytic and everything else from the shop."""
+    c = ctx.cycle
+    fill = float(option.fill_time_s)
+    # Holding time is set by gate freeze, which follows the wall the melt flows through - the
+    # nominal wall, not the thickest section. Cooling below is the opposite: it is set by the
+    # slowest-cooling section, because the whole part has to be ejectable.
+    pack = float(ctx.cal("pack_time_s_per_mm_wall")) * geo.nominal_wall_mm
+    cool = cooling_time_s(geo.governing_wall_mm, thermal, melt_K, mold_K, factor=float(ctx.cal("cooling_time_factor")))
+    removal = c["part_removal_s"]["robot" if clamp_kN >= c["robot_from_clamp_kN"] else "freefall"]
+    handling = c["mold_open_close_s"] + c["ejection_s"] + removal
+    # Pack overlaps the start of cooling in reality; the convention here is that the *cooling*
+    # clock starts at the end of fill, so the cycle is fill + max(pack, cool) + handling.
+    total = (fill + max(pack, cool) + handling) * float(ctx.cal("cycle_time_factor"))
+    return CycleTime(
+        fill_s=fill,
+        pack_s=pack,
+        cool_s=cool,
+        handling_s=handling,
+        total_s=total,
+        governing_wall_mm=geo.governing_wall_mm,
+        basis=(
+            f"cooling from the one-term slab solution on the p95 wall ({geo.governing_wall_mm:.2f} mm), "
+            f"factor {ctx.cal('cooling_time_factor')}"
+        ),
+    )
+
+
+def piece_price(
+    ctx: ShopContext,
+    *,
+    parts_per_year: int,
+    part_mass_g: float,
+    runner_mass_per_part_g: float,
+    grade: dict,
+    machine: MachineChoice,
+    cycle_s: float,
+    cavities: int,
+    tool_total_eur: float,
+) -> PiecePrice:
+    """One rung of the volume ladder."""
+    com = ctx.commercial
+    mats = ctx.materials
+    oee = float(ctx.cycle.get("oee", 1.0))
+
+    price_kg = float(grade["price_eur_kg"])
+    if grade.get("stock") == "per order":
+        price_kg *= 1.0 + float(mats.get("procurement_surcharge_pct", 0)) / 100.0
+    if grade.get("dry"):
+        price_kg += float(mats.get("drying_eur_per_kg", 0.0))
+
+    scrap = float(com["scrap_pct_established"]) / 100.0
+    regrind = float(grade.get("regrind_pct", 0)) / 100.0
+    net_runner_g = runner_mass_per_part_g * (1.0 - regrind)
+    kg_per_part = (part_mass_g + net_runner_g) / 1000.0 * (1.0 + scrap)
+    # Annual tonnage buys a price break - one of only two things that move along the ladder.
+    tonnage = kg_per_part * parts_per_year
+    breaks = sorted(com.get("material_price_breaks", []), key=lambda b: b["min_kg_per_year"])
+    discount = max((b["discount_pct"] for b in breaks if tonnage >= b["min_kg_per_year"]), default=0.0)
+    material = kg_per_part * price_kg * (1.0 - discount / 100.0)
+
+    machine_h = cycle_s / 3600.0 / max(cavities, 1) / max(oee, 1e-6)
+    machine_eur = machine.rate_eur_h * machine_h
+    labour_eur = (float(com["labour_rate_eur_h"]) / float(com["machines_per_operator"])) * machine_h
+    secondary = float(com["packaging_eur_per_part"]) + float(com["qc_eur_per_part"])
+
+    # Orders per year is capped by the minimum economic batch: at 10k/year nobody sets the tool
+    # up twelve times for 800-part runs, and pretending otherwise buries the low-volume rung of
+    # the ladder under a setup cost that would never be incurred.
+    min_batch = float(com.get("min_order_parts", 1))
+    orders = max(1.0, min(float(com["orders_per_year"]), parts_per_year / max(min_batch, 1.0)))
+    setup_per_order = float(com["setup_hours_per_order"]) * machine.rate_eur_h
+    setup = setup_per_order * orders / max(parts_per_year, 1)
+
+    overhead = (material + labour_eur) * float(com["overhead_pct_on_material_and_labour"]) / 100.0
+    manufacturing = material + machine_eur + labour_eur + secondary + setup
+    margin = (manufacturing + overhead) * float(com["margin_pct"]) / 100.0
+    total = (manufacturing + overhead + margin) * float(ctx.cal("piece_price_factor"))
+
+    return PiecePrice(
+        parts_per_year=int(parts_per_year),
+        material_eur=material,
+        machine_eur=machine_eur,
+        labour_eur=labour_eur,
+        secondary_eur=secondary,
+        setup_eur=setup,
+        overhead_eur=overhead,
+        margin_eur=margin,
+        total_eur=total,
+        tool_amortisation_eur=tool_total_eur / max(int(com["amortisation_default_parts"]), 1),
+    )
+
+
+def build_quote(
+    ctx: ShopContext,
+    geo: PartGeometry,
+    option: GateOption,
+    *,
+    cavities: int,
+    grade: dict,
+    thermal: dict,
+    melt_K: float,
+    mold_K: float,
+    finish: str = "technical",
+    material_note: str = "",
+) -> Quote:
+    """Price one gating option end to end."""
+    assumptions: list[str] = []
+    if ctx.is_example:
+        assumptions.append(
+            "BUILT ON EXAMPLE SHOP DATA: the presses, rates, material prices and mould cost model "
+            "in shop/ are the shipped fictional example and have not been replaced with this "
+            "shop's own figures. This document shows the format of a quotation, not a price."
+        )
+    if material_note:
+        assumptions.append(material_note)
+    flags: list[str] = []
+    t = ctx.tooling
+
+    # -- clamp force: simulation as a lower bound, material rule of thumb as the floor --------
+    rule_bar = float(grade.get("clamp_pressure_bar", 400))
+    sim_bar = float(option.max_pressure_bar) * float(ctx.cal("sim_peak_to_mean_pressure"))
+    use_sim = bool(ctx.cal("use_simulated_clamp_pressure")) and option.source == "cloud" and math.isfinite(sim_bar)
+    mean_bar = max(sim_bar, rule_bar) if use_sim else rule_bar
+    basis = "simulation" if (use_sim and sim_bar >= rule_bar) else "material rule of thumb"
+
+    # The runner's own projected area adds to the clamp on a cold-runner tool; on a hot runner it
+    # does not (the melt channel is inside the manifold, not in the parting line).
+    hot = cavities >= int(t["feed_system"]["hot_runner_from_cavities"]) or option.n_gates > 1
+    runner_proj_cm2 = 0.0 if hot else 0.15 * geo.projected_area_cm2 * cavities
+    projected_total = geo.projected_area_cm2 * cavities + runner_proj_cm2
+    required = clamp_force_kN(mean_bar, projected_total) * float(ctx.cal("clamp_safety_factor"))
+
+    # -- shot ---------------------------------------------------------------------------------
+    density = float(grade["density_g_cm3"])
+    runner_cm3 = 0.0 if hot else float(t["feed_system"]["cold_runner_volume_cm3_per_drop"]) * cavities * option.n_gates
+    shot_cm3 = geo.volume_cm3 * cavities + runner_cm3
+    part_mass_g = geo.volume_cm3 * density
+    shot_mass_g = shot_cm3 * density
+    runner_per_part_g = (runner_cm3 * density) / max(cavities, 1)
+
+    plate_a, plate_b, _ = _plate_size_mm(geo, cavities, t)
+    machine = select_machine(
+        ctx,
+        required_clamp_kN=required,
+        shot_volume_cm3=shot_cm3,
+        plate_mm=(plate_a, plate_b),
+        clamp_basis=basis,
+    )
+
+    cycle = cycle_time(ctx, geo, option, thermal, melt_K, mold_K, clamp_kN=machine.clamp_kN)
+
+    # Hardened steel above 100k parts/year or for any glass-filled grade (abrasive).
+    ladder = ctx.volume_ladder()
+    hardened = max(ladder) > 100_000 or "GF" in str(grade.get("family", ""))
+    tool = tool_cost(ctx, geo, cavities=cavities, gates_per_cavity=option.n_gates, hardened=hardened, finish=finish)
+
+    prices = [
+        piece_price(
+            ctx,
+            parts_per_year=v,
+            part_mass_g=part_mass_g,
+            runner_mass_per_part_g=runner_per_part_g,
+            grade=grade,
+            machine=machine,
+            cycle_s=cycle.total_s,
+            cavities=cavities,
+            tool_total_eur=tool.total_eur,
+        )
+        for v in ladder
+    ]
+
+    # -- what the estimator must know ---------------------------------------------------------
+    assumptions.append(
+        f"Piece prices are quoted at {', '.join(f'{v // 1000}k' for v in ladder)} parts/year; no annual "
+        "volume was stated by the customer."
+    )
+    assumptions.append(
+        f"Cavity pressure for clamp sizing: {mean_bar:.0f} bar ({basis}). "
+        f"Simulated peak {option.max_pressure_bar:.0f} bar x {ctx.cal('sim_peak_to_mean_pressure')} = "
+        f"{sim_bar:.0f} bar mean; material rule of thumb {rule_bar:.0f} bar."
+    )
+    assumptions.append(
+        f"Cooling time {cycle.cool_s:.1f} s is analytic (one-term slab on the {geo.governing_wall_mm:.2f} mm "
+        f"p95 wall, factor {ctx.cal('cooling_time_factor')}); the filling solver models no cooling phase."
+    )
+    assumptions.append(f"{'Hardened' if hardened else 'Pre-hardened'} steel; surface finish '{finish}'.")
+    assumptions.append(f"{geo.side_actions} side action(s) taken from the geometry - verify against the drawing.")
+    if option.source != "cloud":
+        assumptions.append(
+            "No simulation was run: gating and pressure are rule-of-thumb estimates. Treat the machine "
+            "selection and the cycle as provisional."
+        )
+
+    if machine.fits:
+        flags += machine.notes
+    else:
+        flags.append("no press in the shop fits: " + "; ".join(machine.notes))
+    if option.short_shot:
+        flags.append("the simulation did not fill the part at this gating")
+    if option.n_interior_welds:
+        flags.append(
+            f"{option.n_interior_welds} weld line(s) predicted across the part (plus "
+            f"{option.n_welds - option.n_interior_welds} at the ends) - confirm none falls on a "
+            "functional or visible face"
+        )
+    elif option.n_welds:
+        flags.append(
+            f"{option.n_welds} weld line(s) predicted, all at the part ends - normally hidden, "
+            "but confirm against the drawing"
+        )
+    if not geo.watertight:
+        flags.append("STL is not watertight; volume and wall thickness are estimates")
+    flags += tool.notes
+    flags += geo.notes
+
+    return Quote(
+        part_name=geo.path.stem,
+        cavities=cavities,
+        grade=grade,
+        geo=geo,
+        option=option,
+        cycle=cycle,
+        machine=machine,
+        tool=tool,
+        ladder=prices,
+        shot_mass_g=shot_mass_g,
+        part_mass_g=part_mass_g,
+        currency=ctx.currency(),
+        assumptions=assumptions,
+        flags=flags,
+    )
+
+
+def compare_options(
+    ctx: ShopContext,
+    geo: PartGeometry,
+    options: list[GateOption],
+    *,
+    cavities: int,
+    grade: dict,
+    thermal: dict,
+    melt_K: float,
+    mold_K: float,
+    reference_parts: int | None = None,
+    finish: str = "technical",
+    material_note: str = "",
+) -> list[Quote]:
+    """Price every gating option and rank them by total cost of ownership.
+
+    This is the decision the study exists to inform, and it is a **commercial** one: a second
+    gate lowers pressure (maybe a press class cheaper, maybe a shorter fill) and costs one more
+    hot-runner nozzle per cavity plus a weld line. Neither side wins in general - which is why
+    both are priced instead of argued.
+    """
+    ladder = ctx.volume_ladder()
+    ref = reference_parts or ladder[len(ladder) // 2]
+    quotes = [
+        build_quote(
+            ctx,
+            geo,
+            o,
+            cavities=cavities,
+            grade=grade,
+            thermal=thermal,
+            melt_K=melt_K,
+            mold_K=mold_K,
+            finish=finish,
+            material_note=material_note,
+        )
+        for o in options
+    ]
+    quotes.sort(key=lambda q: (not q.machine.fits, q.option.short_shot, q.total_cost_of_ownership(ref)))
+    return quotes
+
+
+def comparison_table(quotes: list[Quote], reference_parts: int) -> str:
+    head = (
+        f"  {'gating':>8}  {'press':<24} {'cycle':>7} {'tool':>10} {'piece':>8} "
+        f"{'TCO @ ' + str(reference_parts // 1000) + 'k':>12}  interior welds"
+    )
+    rows = [head, "  " + "-" * (len(head) - 2)]
+    for q in quotes:
+        price = min(q.ladder, key=lambda p: abs(p.parts_per_year - reference_parts))
+        rows.append(
+            f"  {q.option.n_gates:>6} g  {q.machine.name:<24} {q.cycle.total_s:>6.1f}s "
+            f"{q.tool.total_eur:>10,.0f} {price.total_eur:>8.3f} "
+            f"{q.total_cost_of_ownership(reference_parts):>12,.0f}  {q.option.n_interior_welds}"
+        )
+    return "\n".join(rows)