api581-engine 0.1.4__py3-none-any.whl

api581/brittle.py

@@ -0,0 +1,205 @@
+"""Part 2 §§20,22,23 brittle-fracture and embrittlement calculations.
+
+SI tables are used as printed, except Table 20.3 where the unambiguous US
+table is converted to SI explicitly. Material qualification is caller supplied.
+"""
+from bisect import bisect_left
+import math
+from typing import Annotated, Literal
+from pydantic import Field, StrictBool
+from .core import Model, Positive, Fraction, calculation, ensure
+
+Finite = Annotated[float, Field(strict=True, allow_inf_nan=False)]
+Interpolation = Literal["exact", "linear"]
+KSI_PA = 6894757.293168
+
+# Rows: CET - Tref, K (= Celsius difference). Columns: printed SI thickness, mm.
+DELTA_K = (56, 44, 33, 22, 11, 0, -11, -22, -33, -44, -56)
+THICKNESS_MM = (6.4, 12.7, 25.4, 38.1, 50.8, 63.5, 76.2, 88.9, 101.6)
+NON_PWHT = (
+    (0,0,0,0,0,0,.9,1.1,1.2),
+    (0,0,0,.8,1.1,2,2,4,6),
+    (0,0,1,2,4,9,19,36,60),
+    (0,.7,2,9,29,69,133,224,338),
+    (.1,1.3,10,49,143,296,500,741,1008),
+    (.9,3,39,175,424,759,1142,1545,1950),
+    (1.2,7,109,405,850,1366,1897,2415,2903),
+    (2,16,220,697,1317,1969,2596,3176,3703),
+    (2,30,350,988,1740,2479,3160,3769,4310),
+    (3,46,474,1239,2080,2873,3581,4203,4746),
+    (4,61,579,1436,2336,3160,3883,4509,5000),
+)
+PWHT = (
+    (0,0,0,0,0,0,0,0,0),
+    (0,0,0,0,0,0,0,0,.2),
+    (0,0,0,0,0,.5,.9,1.1,1.3),
+    (0,0,0,.5,1.1,1.3,2,3,4),
+    (0,0,.6,1.2,2,4,7,13,23),
+    (0,0,1.1,2,6,14,29,53,88),
+    (0,.4,2,5,17,41,83,144,224),
+    (0,.9,3,12,38,90,171,281,416),
+    (0,1.1,5,22,68,153,277,436,623),
+    (0,1.2,7,34,102,219,382,582,810),
+    (0,1.3,9,46,133,277,472,704,962),
+)
+
+
+def _weights(nodes, value, mode):
+    """Ascending grid; snap only floating-point roundoff at printed nodes."""
+    for i, node in enumerate(nodes):
+        if math.isclose(value, node, rel_tol=1e-12, abs_tol=1e-9):
+            return ((i, 1.0),)
+    ensure(nodes[0] < value < nodes[-1], "Input outside tabulated domain; extrapolation is not supported")
+    ensure(mode == "linear", "Input is not a printed table node; explicitly select linear interpolation", "interpolation_required")
+    upper = bisect_left(nodes, value)
+    weight = (value - nodes[upper-1]) / (nodes[upper] - nodes[upper-1])
+    return ((upper-1, 1-weight), (upper, weight))
+
+
+def _lookup(nodes, values, value, mode):
+    return sum(values[i] * weight for i, weight in _weights(nodes, value, mode))
+
+
+class BrittleReference(Model):
+    material_group: Literal["carbon_steel", "low_alloy_steel"]
+    minimum_yield_strength_pa: Positive
+    exemption_curve: Literal["A", "B", "C", "D"]
+    interpolation: Interpolation
+
+
+@calculation("damage/brittle-reference-temperature", "Brittle fracture reference temperature", BrittleReference,
+             ["Part 2 §20.6.3 STEP 3; Table 20.3; PDF p268"],
+             limitations=["Caller qualifies material and assigns ASME exemption curve. Uses the printed US Table 20.3 (ksi, F), explicitly converted to Pa and K; not rounded SI Table 20.3M. Linear interpolation is a caller-selected engineering interpolation; no extrapolation."])
+def brittle_reference(x):
+    base = ((104,97,91,86,81,78,74,71,68,66,63) if x.material_group == "carbon_steel"
+            else (124,115,107,101,96,92,88,85,81,79,76,73,71,69,67,65,63,62,60,58,57,56,54,53,52,51))
+    yield_nodes = tuple(range(30, 30 + 2*len(base), 2))
+    offset = {"A":0, "B":38, "C":76, "D":102}[x.exemption_curve]
+    temp_f = _lookup(yield_nodes, tuple(v-offset for v in base), x.minimum_yield_strength_pa/KSI_PA, x.interpolation)
+    return {"reference_temperature_k": (temp_f-32)*5/9+273.15, "table_basis": "20.3_US_converted_to_SI"}
+
+
+class BrittleService(Model):
+    component_thickness_m: Positive
+    nominal_uncorroded_thickness_m: Positive
+    equipment_type: Literal["pressure_vessel", "piping"]
+    p1_or_p3_steel: StrictBool
+    design_temperature_k: Positive
+    construction_code_satisfied: StrictBool
+    stable_conditions_no_more_severe_future: StrictBool
+    cet_at_mawp_k: Positive
+    cyclic_fatigue_or_vibration_design_service: StrictBool
+    environmental_cracking: StrictBool
+    shock_chilling: StrictBool
+
+
+@calculation("damage/brittle-service-factor", "Brittle fracture service-experience adjustment", BrittleService,
+             ["Part 2 §20.6.3 STEP 6; eq (2.86); PDF pp264-265"],
+             limitations=["Owner qualifies code compliance, operating history and service exclusions. Thin-component criterion is an independent OR; all eight service criteria are otherwise required. Printed SI thresholds are used."])
+def brittle_service(x):
+    checks = {
+        "p1_p3_and_design_temperature": x.p1_or_p3_steel and x.design_temperature_k <= 616.15,
+        "construction_code": x.construction_code_satisfied,
+        "stable_service": x.stable_conditions_no_more_severe_future,
+        "cet_at_mawp": x.cet_at_mawp_k >= (244.15 if x.equipment_type == "pressure_vessel" else 169.15),
+        "nominal_thickness": x.nominal_uncorroded_thickness_m <= .0508,
+        "no_cyclic_service": not x.cyclic_fatigue_or_vibration_design_service,
+        "no_environmental_cracking": not x.environmental_cracking,
+        "no_shock_chilling": not x.shock_chilling,
+    }
+    thin = x.component_thickness_m <= .0127
+    return {"service_experience_factor": .01 if thin or all(checks.values()) else 1,
+            "thin_component_credit": thin, "service_criteria": checks}
+
+
+class BrittleBase(Model):
+    component_thickness_m: Positive
+    cet_minus_reference_k: Finite
+    post_weld_heat_treated: StrictBool
+    interpolation: Interpolation
+
+
+@calculation("damage/brittle-base", "Brittle fracture base damage table", BrittleBase,
+             ["Part 2 Tables 20.4M,20.5M; PDF pp270-271"],
+             limitations=["Printed SI grid: thickness 6.4-101.6 mm and CET-Tref -56 to 56 K. Linear mode is caller-selected bilinear interpolation of DF, not log DF. No extrapolation or service credit applied here."])
+def brittle_base(x):
+    table = PWHT if x.post_weld_heat_treated else NON_PWHT
+    rows = _weights(tuple(reversed(DELTA_K)), x.cet_minus_reference_k, x.interpolation)
+    cols = _weights(THICKNESS_MM, x.component_thickness_m*1000, x.interpolation)
+    value = sum(table[len(DELTA_K)-1-r][c]*rw*cw for r,rw in rows for c,cw in cols)
+    return {"base_damage_factor": value, "table": "20.5M" if x.post_weld_heat_treated else "20.4M"}
+
+
+class BrittleFracture(Model):
+    reference: BrittleReference
+    service: BrittleService
+    critical_exposure_temperature_k: Positive
+    post_weld_heat_treated: StrictBool
+    interpolation: Interpolation
+
+
+@calculation("damage/brittle-fracture", "Brittle fracture reference/base/service calculation", BrittleFracture,
+             ["Part 2 §20.6.3; Tables 20.3,20.4M,20.5M; eq (2.86)"],
+             limitations=["Caller establishes applicability, ASME curve and CET (including credited controls) per API 579. No inspection credit. Uses US reference-temperature table converted to SI plus printed SI base-DF tables. Caller selects interpolation separately for yield and base-DF grids; no extrapolation."])
+def brittle_fracture(x):
+    reference = brittle_reference(x.reference)
+    delta = x.critical_exposure_temperature_k-reference["reference_temperature_k"]
+    base = brittle_base(BrittleBase(component_thickness_m=x.service.component_thickness_m,
+        cet_minus_reference_k=delta, post_weld_heat_treated=x.post_weld_heat_treated, interpolation=x.interpolation))
+    service = brittle_service(x.service)
+    return {**reference, **base, **service, "cet_minus_reference_k": delta,
+            "damage_factor": base["base_damage_factor"]*service["service_experience_factor"]}
+
+
+class Embrittlement885(Model):
+    minimum_evaluation_temperature_k: Positive
+    reference_temperature_k: Positive = 301.15
+    interpolation: Interpolation
+
+
+@calculation("damage/embrittlement-885f", "885 F embrittlement damage factor", Embrittlement885,
+             ["Part 2 §22.6.3; Table 22.3; PDF pp279-280"],
+             limitations=["Qualified susceptible ferritic material and evaluation temperature supplied by caller; no inspection credit. Default reference is printed 28 C (301.15 K), which is not the exact conversion of printed 80 F. Uses printed SI delta-temperature rows. Above +56 K DF=0; at +56 K DF=2. Below -56 K rejected. Linear interpolation is an explicit caller choice."])
+def embrittlement_885(x):
+    delta = x.minimum_evaluation_temperature_k-x.reference_temperature_k
+    # Preserve the explicit open-ended row; never interpolate across its discontinuity.
+    if delta > 56 and not math.isclose(delta, 56, rel_tol=0, abs_tol=1e-9):
+        factor = 0.0
+    else:
+        factor = _lookup(tuple(reversed(DELTA_K)), (1381,1216,1022,806,581,371,200,87,30,8,2), delta, x.interpolation)
+    return {"reference_temperature_k": x.reference_temperature_k, "minimum_minus_reference_k": delta,
+            "damage_factor": factor}
+
+
+class SigmaContent(Model):
+    sigma_fraction: Fraction
+
+
+@calculation("damage/sigma-content", "Sigma-phase content category", SigmaContent,
+             ["Part 2 Table 23.1; PDF p284"],
+             limitations=["Content >1% is tabulated: low >1 to <5%, medium >=5 to <10%, high >=10%. At or below 1% the printed categories are unresolved and rejected; no assumed zero DF."])
+def sigma_content(x):
+    ensure(x.sigma_fraction > .01, "Sigma content at or below 1% has no unique category in Table 23.1", "unresolved_applicability")
+    return {"sigma_category": "low" if x.sigma_fraction < .05 else ("medium" if x.sigma_fraction < .1 else "high")}
+
+
+SIGMA_TEMP_C = (-46,-18,10,38,66,93,204,316,427,538,649)
+SIGMA_FACTORS = {
+    "low": (1.1,1,.9,.6,.3,.1,0,0,0,0,0),
+    "medium": (34,20,11,7,5,3,1.3,.9,.2,0,0),
+    "high": (4196,4196,4196,4196,3871,3202,1333,481,160,53,18),
+}
+
+
+class SigmaDamage(Model):
+    evaluation_temperature_k: Positive
+    sigma_category: Literal["low", "medium", "high"]
+    interpolation: Interpolation
+
+
+@calculation("damage/sigma-embrittlement", "Sigma-phase embrittlement damage factor", SigmaDamage,
+             ["Part 2 §23.6.3; Table 23.3; PDF pp283,285"],
+             limitations=["Qualified sigmatized austenitic stainless steel and content category supplied. No automatic exposure-to-sigma kinetics model or inspection credit. Printed SI evaluation-temperature grid -46 to 649 C; no extrapolation. Linear interpolation is caller-selected."])
+def sigma_damage(x):
+    return {"damage_factor": _lookup(SIGMA_TEMP_C, SIGMA_FACTORS[x.sigma_category], x.evaluation_temperature_k-273.15, x.interpolation),
+            "sigma_category": x.sigma_category}

api581/bundle.py

@@ -0,0 +1,300 @@
+"""Part 1 §8 bundle life, cost and replacement planning primitives."""
+import math
+from typing import Literal
+from pydantic import Field, StrictBool
+from .core import Model, NonNegative, Positive, Fraction, calculation, ensure
+from .pof import Weibull, weibull
+
+
+class LifeRecord(Model):
+    duration_years: NonNegative
+    failed: StrictBool
+
+
+class BundleHistory(Model):
+    shape: Positive
+    cycles: list[LifeRecord] = Field(min_length=2, max_length=10000)
+
+
+def _eta(shape, cycles):
+    failures = sum(record.failed for record in cycles)
+    ensure(failures > 0, "Zero failures give no finite point estimate of characteristic life", "insufficient_failure_data")
+    scale = max(record.duration_years for record in cycles)
+    ensure(scale > 0, "At least one positive life duration is required")
+    eta = scale*(math.fsum((record.duration_years/scale)**shape for record in cycles)/failures)**(1/shape)
+    ensure(eta > 0 and math.isfinite(eta), "Characteristic life outside numerical domain", "numerical_failure")
+    return eta, failures
+
+
+@calculation("bundle/weibayes-history", "Fixed-shape bundle Weibayes life estimate", BundleHistory,
+             ["Part 1 §8.3.4.3; eqs (1.62)-(1.63); PDF p100"],
+             limitations=["At least two matched life records and one failure required; failures and right-censored suspensions enter the powered exposure sum. Owner qualifies unchanged design/material/service and externally selected shape. Does not fit shape, perform database matching, goodness-of-fit or Fisher confidence bounds."])
+def bundle_history(x):
+    eta, failures = _eta(x.shape, x.cycles)
+    return {"shape": x.shape, "characteristic_life_years": eta,
+            "failure_count": failures, "record_count": len(x.cycles)}
+
+
+class BundleConditionUpdate(BundleHistory):
+    predicted_failure_life_years: Positive
+
+
+@calculation("bundle/condition-update", "Add inspection-predicted bundle failure point", BundleConditionUpdate,
+             ["Part 1 §8.6.4(e); eqs (1.76)-(1.77); PDF pp104-105"],
+             limitations=["Adds predicted total life as one additional failure point, including one additional failure in denominator. This is not another right-censored observation. Owner supplies qualified predicted total life; statistical confidence and additional uncertainty are separate."])
+def bundle_condition_update(x):
+    cycles = [*x.cycles, LifeRecord(duration_years=x.predicted_failure_life_years, failed=True)]
+    eta, failures = _eta(x.shape, cycles)
+    return {"shape":x.shape, "characteristic_life_years":eta, "failure_count":failures, "record_count":len(cycles)}
+
+
+class BundleThicknessLife(Model):
+    original_thickness_m: Positive
+    measured_thickness_m: Positive
+    service_duration_years: Positive
+    remaining_wall_failure_fraction: Fraction = Field(gt=0, lt=1)
+    formula_basis: Literal["printed_eq_1_72", "remaining_wall_threshold"]
+
+
+@calculation("bundle/thickness-life", "Inspection-based tube thinning and predicted life", BundleThicknessLife,
+             ["Part 1 §8.6.4(c); eqs (1.71)-(1.74); PDF pp103-104"],
+             origin="api581_equation_or_explicit_remaining_wall_interpretation",
+             limitations=["General corrosion and average tube thickness only. Printed eq (1.72) uses RWT*t_original/rate although RWT is described as remaining wall fraction; a physical threshold extrapolation uses (1-RWT)*t_original/rate. Caller must select basis explicitly. Both agree for the printed 0.5 example. Zero measured loss gives no finite extrapolated life, not a manufactured failure point."])
+def bundle_thickness_life(x):
+    ensure(x.measured_thickness_m <= x.original_thickness_m, "Measured thickness exceeds original; negative thinning is outside this model")
+    rate = (x.original_thickness_m-x.measured_thickness_m)/x.service_duration_years
+    fraction = x.remaining_wall_failure_fraction
+    threshold_reached = x.measured_thickness_m <= fraction*x.original_thickness_m
+    life = None if rate == 0 else ((fraction if x.formula_basis == "printed_eq_1_72" else 1-fraction)*x.original_thickness_m/rate)
+    return {"thinning_rate_m_year":rate, "predicted_bundle_life_years":life,
+            "remaining_life_years": None if life is None else max(0,life-x.service_duration_years),
+            "remaining_wall_threshold_reached":threshold_reached, "formula_basis":x.formula_basis}
+
+
+class BundleEstimatedLife(Model):
+    service_duration_years: NonNegative
+    estimated_remaining_life_years: NonNegative
+
+
+@calculation("bundle/estimated-life", "Predicted bundle life from estimated remaining life", BundleEstimatedLife,
+             ["Part 1 §8.6.4(d); eq (1.75); PDF p104"])
+def bundle_estimated_life(x):
+    return {"predicted_bundle_life_years": x.service_duration_years+x.estimated_remaining_life_years}
+
+
+class BundleLifeExtension(Model):
+    age_at_action_years: NonNegative
+    life_extension_factor: Fraction
+    years_since_action: NonNegative = 0
+
+
+@calculation("bundle/life-extension", "Effective bundle age after life-extension action", BundleLifeExtension,
+             ["Part 1 §8.6.5; eqs (1.79)-(1.81); PDF p105"],
+             limitations=["Owner supplies qualified LEF. Returns effective age rather than imposing a date/day-count convention. Original age is not reset by an ordinary inspection or cleaning; apply only after a qualifying life-extension action."])
+def bundle_life_extension(x):
+    adjusted = (1-x.life_extension_factor)*x.age_at_action_years
+    return {"adjusted_age_at_action_years":adjusted, "effective_age_years":adjusted+x.years_since_action,
+            "installation_shift_years": x.age_at_action_years-adjusted}
+
+
+class BundleConsequence(Model):
+    daily_production_margin: NonNegative
+    production_rate_reduction_fraction: Fraction
+    shutdown_days: NonNegative
+    environmental_cost: NonNegative
+    replacement_cost: NonNegative
+    maintenance_cost: NonNegative
+    currency: str = Field(min_length=1, max_length=20)
+    cost_basis_year: int = Field(ge=1900, le=2200, strict=True)
+
+
+@calculation("bundle/consequence", "Bundle failure or planned replacement financial consequence", BundleConsequence,
+             ["Part 1 §8.4.1; eqs (1.64)-(1.67), (1.88); PDF pp100-101,107"],
+             limitations=["All monetary inputs must share declared currency and price year. Caller explicitly chooses planned or unplanned shutdown duration and environmental cost. No silent historical environmental default or inflation assumption."])
+def bundle_consequence(x):
+    production = x.daily_production_margin*x.production_rate_reduction_fraction*x.shutdown_days
+    return {"production_loss_cost":production, "financial_consequence":production+x.environmental_cost+x.replacement_cost+x.maintenance_cost,
+            "currency":x.currency, "cost_basis_year":x.cost_basis_year}
+
+
+class BundleRisk(Model):
+    shape: Positive
+    characteristic_life_years: Positive
+    age_years: NonNegative
+    financial_consequence: NonNegative
+    currency: str = Field(min_length=1, max_length=20)
+
+
+@calculation("bundle/risk", "Bundle unreliability-weighted consequence", BundleRisk,
+             ["Part 1 §8.5; eq (1.68); PDF p101"],
+             limitations=["Weibull cumulative probability times consequence. Despite source annual-risk terminology, this product is a probability-weighted monetary amount at age, not an instantaneous annual failure-frequency risk. No confidence-bound/inspection-uncertainty shift is inferred."])
+def bundle_risk(x):
+    probability = weibull(Weibull(shape=x.shape, characteristic_life_years=x.characteristic_life_years,age_years=x.age_years))["cumulative_failure_probability"]
+    return {"cumulative_failure_probability":probability, "probability_weighted_consequence":probability*x.financial_consequence, "currency":x.currency}
+
+
+class BundleTarget(Model):
+    shape: Positive
+    characteristic_life_years: Positive
+    target_probability_weighted_consequence: NonNegative
+    financial_consequence: Positive
+
+
+@calculation("bundle/target-age", "Bundle age at owner probability-weighted risk target", BundleTarget,
+             ["Part 1 §8.6.1; eqs (1.57),(1.69)-(1.70); PDF pp97,102"],
+             limitations=["Uses an explicitly supplied target on the same probability-weighted consequence basis as bundle/risk. Target >= consequence has no finite crossing. Owner must supply any confidence-bound/uncertainty-adjusted Weibull parameters; raw parameters are not automatically treated as 90% LBC."])
+def bundle_target(x):
+    ratio = x.target_probability_weighted_consequence/x.financial_consequence
+    age = None if ratio >= 1 else x.characteristic_life_years*(-math.log1p(-ratio))**(1/x.shape)
+    return {"target_failure_probability":min(1,ratio), "target_age_years":age,
+            "status":"no_finite_crossing" if age is None else "finite_crossing"}
+
+
+class BundleDeferral(Model):
+    shape: Positive
+    characteristic_life_years: Positive
+    first_turnaround_age_years: NonNegative
+    second_turnaround_age_years: Positive
+    financial_consequence: NonNegative
+    inspection_cost: NonNegative
+    replacement_cost: NonNegative
+    maintenance_cost: NonNegative
+    hurdle_rate: NonNegative = 0
+    currency: str = Field(min_length=1, max_length=20)
+
+
+@calculation("bundle/deferral-decision", "Conditional incremental risk and inspection/replacement economics", BundleDeferral,
+             ["Part 1 §8.7.2; eqs (1.82)-(1.84); PDF p106"],
+             limitations=["Conditioned on survival to first turnaround; uses survival ratio, not the difference of unconditional CDFs. Source prose reverses action-cost inequality; explicit eqs (1.83)-(1.84) are followed: action cost*(1+ROR) < EIR. Both economic flags may be true; this is not an exclusive inspection plan."])
+def bundle_deferral(x):
+    ensure(x.second_turnaround_age_years > x.first_turnaround_age_years, "Second turnaround must follow first")
+    # Compute cumulative-hazard difference without subtracting two underflowed survivals.
+    a,b = x.first_turnaround_age_years,x.second_turnaround_age_years
+    zb = (b/x.characteristic_life_years)**x.shape
+    if a == 0:
+        difference = zb
+    else:
+        log_ratio = math.log(a)-math.log(b) if a <= b/2 else math.log1p((a-b)/b)
+        difference = zb*(-math.expm1(x.shape*log_ratio))
+    probability = -math.expm1(-difference)
+    risk = x.financial_consequence*probability
+    inspect = (x.inspection_cost+x.maintenance_cost)*(1+x.hurdle_rate)
+    replace = (x.replacement_cost+x.maintenance_cost)*(1+x.hurdle_rate)
+    return {"conditional_failure_probability":probability,"expected_incremental_risk":risk,
+            "inspection_hurdle_cost":inspect,"replacement_hurdle_cost":replace,
+            "inspection_economically_justified":inspect < risk,"replacement_economically_justified":replace < risk,
+            "currency":x.currency}
+
+
+class BundleReplacement(Model):
+    shape: Positive
+    characteristic_life_years: Positive
+    unplanned_failure_consequence: NonNegative
+    planned_replacement_consequence: Positive
+    step_days: Positive = 7
+    maximum_replacement_age_years: Positive
+    currency: str = Field(min_length=1, max_length=20)
+
+
+@calculation("bundle/replacement-optimization", "Bundle planned-replacement grid cost optimization", BundleReplacement,
+             ["Part 1 §8.7.4; eqs (1.85)-(1.93); PDF pp107-109"],
+             limitations=["Source right-endpoint failure-life integration on uniform grid; days/year=365.24. Global minimum is over supplied finite grid only, not an unbounded certified optimum. Boundary minima are flagged. No confidence bounds, cost inflation or automatic inspection effects. Grid limited to 10000 points."])
+def bundle_replacement(x):
+    step = x.step_days/365.24
+    count = math.floor(x.maximum_replacement_age_years/step)
+    ensure(1 <= count <= 10000, "Replacement grid must contain 1-10000 points")
+    fail_life, previous, samples = 0.0,0.0,[]
+    for n in range(1,count+1):
+        age = n*step
+        z = (age/x.characteristic_life_years)**x.shape
+        p,s = -math.expm1(-z),math.exp(-z)
+        fail_life += age*(p-previous)
+        life = fail_life+age*s
+        ensure(life > 0, "Estimated service life underflow", "numerical_failure")
+        cost = (x.unplanned_failure_consequence*p+x.planned_replacement_consequence*s)/(365.24*life)
+        samples.append({"replacement_age_years":age,"failure_probability":p,
+                        "expected_service_life_years":life,"total_cost_per_day":cost})
+        previous = p
+    index = min(range(len(samples)),key=lambda i:samples[i]["total_cost_per_day"])
+    best = samples[index]
+    return {"optimal_grid_age_years":best["replacement_age_years"],"minimum_cost_per_day":best["total_cost_per_day"],
+            "minimum_at_grid_boundary":index in (0,count-1),"grid_points":count,"samples":samples,"currency":x.currency}
+
+
+MATERIAL_FACTORS = {
+    "Carbon Steel":1, "C-1/2 Mo":2, "1-1/4 Cr":2, "2-1/4 Cr":2.8,
+    "5 Cr":3.2, "9 Cr":3.3, "12 Cr":3.4, "70/30 CuNi":3.5, "90/10 CuNi":3.5,
+    "Monel 400":7, "Nickel 200":8.5, "304/309/310 SS":2.6, "304L/321/347 SS":2.8,
+    "316 SS":3, "316L SS":3, "317L SS":4.2, "410/439 SS":2.8, "444 SS":3.2,
+    "904L":7, "2205 Duplex SS":3, "2304 Duplex SS":2.8, "2507 Duplex SS":4,
+    "AL6XN/254 SMO":7, "Seacure/E-Brite":6,
+    "Admiralty Brass/Aluminum Brass/Red Brass/Muntz":2.5, "Aluminum Alloy":3,
+    "Alloy 20 Cb3":6.5, "Alloy 600":9.5, "Alloy 625":11, "Alloy 800":7,
+    "Alloy 825":8, "Alloy C276":11, "Ferralium 255":7, "Bimetallic":4.5,
+    "Ceramic":1, "Plastic":1, "Titanium Gr. 2":6, "Titanium Gr. 12":10,
+    "Titanium Gr. 16":14, "Zeron 100":4, "Zirconium Alloy":15,
+}
+
+
+class BundleMaterial(Model):
+    material: str
+
+
+@calculation("bundle/material-factor", "Bundle replacement material cost factor", BundleMaterial,
+             ["Part 1 Table8.3; PDF pp119-120"],
+             limitations=["Historical generic bundle factors, not current quotations or the fixed-equipment material factors. Caller may supply a different qualified factor directly to replacement-cost."])
+def bundle_material(x):
+    ensure(x.material in MATERIAL_FACTORS, "Unsupported material; use a printed Table8.3 material label")
+    return {"material_factor":MATERIAL_FACTORS[x.material]}
+
+
+class BundleReplacementCost(Model):
+    shell_inside_diameter_m: Positive
+    tube_length_m: Positive
+    material_factor: Positive
+    reference_bundle_cost_usd: NonNegative = 22000
+    price_index_multiplier: Positive
+    output_currency_per_usd: Positive
+    output_currency: str = Field(min_length=1, max_length=20)
+    output_cost_basis_year: int = Field(strict=True, ge=1900, le=2200)
+
+
+@calculation("bundle/replacement-cost", "Volume/material-scaled bundle replacement cost", BundleReplacementCost,
+             ["Part 1 §8.4.1; eq (1.66); PDF p101"],
+             limitations=["Printed reference volume 3.016 m3 and default reference quote USD22000. Reference quote date is not inferred from edition year; caller supplies qualified price-index multiplier and FX to declared output price year/currency. This is a size/material estimate, not a vendor quote."])
+def bundle_replacement_cost(x):
+    volume = math.pi*x.shell_inside_diameter_m**2*x.tube_length_m/4
+    reference = x.reference_bundle_cost_usd*volume*x.material_factor/3.016
+    return {"bundle_volume_m3":volume,"reference_basis_cost_usd":reference,
+            "replacement_cost":reference*x.price_index_multiplier*x.output_currency_per_usd,
+            "currency":x.output_currency,"cost_basis_year":x.output_cost_basis_year}
+
+
+class BundleExtensionFactor(Model):
+    method: Literal["plug_tubes", "rotate_180", "partial_retube", "total_retube", "install_spare", "tube_ferrules"]
+    ferrules_for_localized_tube_end_damage: StrictBool = False
+
+
+@calculation("bundle/life-extension-factor", "Suggested bundle life-extension action factor", BundleExtensionFactor,
+             ["Part 1 Table8.5 Effects of Bundle Life Extension Methods; PDF p121"],
+             limitations=["This is the second table numbered8.5; inspection uncertainty is a different table. Suggested values need owner qualification. Spare factor .5 assumes unknown condition. Ferrules .75 only for localized tube-end erosion/corrosion/impingement protection."])
+def bundle_extension_factor(x):
+    ensure(x.method != "tube_ferrules" or x.ferrules_for_localized_tube_end_damage,
+           "Ferrule LEF requires qualified protection against localized tube-end damage")
+    factors={"plug_tubes":.1,"rotate_180":.5,"partial_retube":.5,"total_retube":.9,"install_spare":.5,"tube_ferrules":.75}
+    return {"life_extension_factor":factors[x.method]}
+
+
+class BundleCategories(Model):
+    cumulative_failure_probability: Fraction
+    financial_consequence_usd: NonNegative
+    consequence_basis: Literal["printed_table_USD_basis"]
+
+
+@calculation("bundle/categories", "Bundle probability and financial consequence categories", BundleCategories,
+             ["Part 1 Table8.6; PDF p121"],
+             limitations=["Uses displayed probability and financial-USD thresholds, not inconsistent DF/area footnotes. Caller explicitly declares consequence on printed USD basis; no automatic present-value inflation or FX normalization. Returns categories only; owner risk-color matrix is separate."])
+def bundle_categories(x):
+    p = 1+sum(x.cumulative_failure_probability > b for b in (.1,.2,.3,.5))
+    c = sum(x.financial_consequence_usd > b for b in (10000,50000,150000,1000000))
+    return {"probability_category":p,"consequence_category":"ABCDE"[c]}