"""Starter implementation for the Module 10 sensor-inversion capstone.""" from __future__ import annotations import argparse import json import platform import struct import subprocess import sys from dataclasses import asdict, dataclass from decimal import Decimal from pathlib import Path DeclaredNumber = str | Decimal | float @dataclass(frozen=True) class SensorCase: """Declared inputs and decision requirements for the teaching case.""" # Strings preserve the decimal tokens supplied by the scientific case. y1: DeclaredNumber = "1.0000000" y2: DeclaredNumber = "1.0000004" separation: DeclaredNumber = "1e-6" reading_bound: DeclaredNumber = "5e-8" threshold_mg_per_l: float = 0.61 required_accuracy_mg_per_l: float = 0.01 @dataclass(frozen=True) class ConcentrationEnvelope: """Deterministic output bounds induced by bounded sensor readings.""" c_a_min: float c_a_max: float c_b_min: float c_b_max: float total_min: float total_max: float def binary32(value: float) -> float: """Round a Python float to IEEE 754 binary32 and return it as a float.""" return struct.unpack("!f", struct.pack("!f", value))[0] def as_float(value: DeclaredNumber) -> float: """Convert a declared input for a binary floating-point calculation.""" return float(value) def as_declared_decimal(value: DeclaredNumber) -> Decimal: """Return a Decimal without silently treating a binary float as declared.""" if isinstance(value, Decimal): return value if isinstance(value, str): return Decimal(value) raise TypeError( "decimal reference inputs must be declared as strings or Decimal" ) def solve_binary32(case: SensorCase) -> tuple[float, float]: """Solve the stored binary32 system with rounding after each operation.""" one = binary32(1.0) stored_y1 = binary32(as_float(case.y1)) stored_y2 = binary32(as_float(case.y2)) stored_coefficient = binary32(1.0 + as_float(case.separation)) stored_separation = binary32(stored_coefficient - one) if stored_separation == 0.0: raise ValueError("sensor separation is zero after binary32 storage") difference = binary32(stored_y2 - stored_y1) c_b = binary32(difference / stored_separation) c_a = binary32(stored_y1 - c_b) return c_a, c_b def solve_binary64(case: SensorCase) -> tuple[float, float]: """Solve the nominal system using Python's binary64 arithmetic.""" # TODO 1: convert declared inputs with as_float, solve for c_B from # y2 - y1, then use y1 = c_A + c_B. raise NotImplementedError("implement the binary64 nominal solve") def decimal_reference(case: SensorCase) -> tuple[Decimal, Decimal]: """Solve the declared decimal inputs with 50-digit Decimal arithmetic.""" # TODO 2: use as_declared_decimal for each input and solve the same system. raise NotImplementedError("implement the exact-decimal nominal reference") def residual_inf_norm( case: SensorCase, concentrations: tuple[float, float] ) -> float: """Return the maximum absolute residual in normalized response units.""" c_a, c_b = concentrations y1 = as_float(case.y1) y2 = as_float(case.y2) separation = as_float(case.separation) residual_1 = c_a + c_b - y1 residual_2 = c_a + (1.0 + separation) * c_b - y2 return max(abs(residual_1), abs(residual_2)) def condition_number_2(separation: DeclaredNumber) -> float: """Return the matrix 2-norm condition number without a small subtraction.""" # TODO 3: convert separation with as_float, then derive a stable expression # from the eigenvalues of A.T A. # Hint: det(A.T A) = separation**2, so do not obtain the smaller # eigenvalue by subtracting two nearly equal numbers. raise NotImplementedError("implement the matrix condition number") def concentration_envelope(case: SensorCase) -> ConcentrationEnvelope: """Propagate deterministic reading bounds by evaluating all four corners.""" # TODO 4: use as_declared_decimal and solve with Decimal arithmetic at # every (y1, y2) bound corner. raise NotImplementedError("implement deterministic input-bound propagation") def classify_value(c_a: float, threshold: float) -> str: """Classify a nominal value for the strict c_A > threshold question.""" return "yes" if c_a > threshold else "no" def classify_interval(lower: float, upper: float, threshold: float) -> str: """Classify a strict threshold over a deterministic admissible interval.""" # TODO 5: return yes, no, or indeterminate for the complete interval. raise NotImplementedError("implement the interval decision") def controlled_separation_sweep() -> list[dict[str, object]]: """Return a known-solution control while changing only sensor separation.""" rows: list[dict[str, object]] = [] for separation_text in ("1e-1", "1e-2", "1e-4", "1e-6"): separation = Decimal(separation_text) y2 = Decimal("1.0") + Decimal("0.4") * separation control = SensorCase(y2=str(y2), separation=separation_text) binary32_solution = solve_binary32(control) rows.append( { "separation": separation_text, "matrix_2_norm_condition_number": condition_number_2( separation_text ), "binary32_c_a_mg_per_l": binary32_solution[0], "binary32_forward_error_c_a_mg_per_l": abs( binary32_solution[0] - 0.6 ), } ) return rows def source_revision() -> dict[str, object]: """Capture the repository revision without recording a machine-local path.""" repository = Path(__file__).resolve().parents[3] try: revision = subprocess.run( ["git", "rev-parse", "--short", "HEAD"], cwd=repository, check=True, capture_output=True, text=True, timeout=2, ).stdout.strip() dirty_tree = bool( subprocess.run( ["git", "status", "--porcelain"], cwd=repository, check=True, capture_output=True, text=True, timeout=2, ).stdout.strip() ) except (FileNotFoundError, subprocess.SubprocessError): return {"commit": "unavailable", "dirty_tree": "unavailable"} return {"commit": revision, "dirty_tree": dirty_tree} def build_evidence_record(case: SensorCase) -> dict[str, object]: """Assemble the evidence needed for the decision-facing statement.""" binary32_solution = solve_binary32(case) binary64_solution = solve_binary64(case) reference = decimal_reference(case) envelope = concentration_envelope(case) reference_float = (float(reference[0]), float(reference[1])) binary32_error = abs(binary32_solution[0] - reference_float[0]) binary64_error = abs(binary64_solution[0] - reference_float[0]) required_accuracy = case.required_accuracy_mg_per_l return { "claim": ( "decide whether c_A is strictly greater than " f"{case.threshold_mg_per_l} mg/L" ), "case": { "y1": str(case.y1), "y2": str(case.y2), "separation": str(case.separation), "reading_bound": str(case.reading_bound), "threshold_mg_per_l": case.threshold_mg_per_l, "required_accuracy_mg_per_l": case.required_accuracy_mg_per_l, }, "units": { "concentrations": "mg/L", "readings": "normalized response units", }, "reference": { "kind": "50-digit Decimal solution of the declared decimal inputs", "c_a_mg_per_l": str(reference[0]), "c_b_mg_per_l": str(reference[1]), }, "precision_variation": { "binary32": { "c_a_mg_per_l": binary32_solution[0], "c_b_mg_per_l": binary32_solution[1], "nominal_decision": classify_value( binary32_solution[0], case.threshold_mg_per_l ), "forward_error_c_a_mg_per_l": binary32_error, "required_accuracy_mg_per_l": required_accuracy, "accuracy_requirement_passed": ( binary32_error <= required_accuracy ), "residual_inf_norm_response_units": residual_inf_norm( case, binary32_solution ), }, "binary64": { "c_a_mg_per_l": binary64_solution[0], "c_b_mg_per_l": binary64_solution[1], "nominal_decision": classify_value( binary64_solution[0], case.threshold_mg_per_l ), "forward_error_c_a_mg_per_l": binary64_error, "required_accuracy_mg_per_l": required_accuracy, "accuracy_requirement_passed": ( binary64_error <= required_accuracy ), "residual_inf_norm_response_units": residual_inf_norm( case, binary64_solution ), }, }, "conditioning": { "matrix_2_norm_condition_number": condition_number_2( case.separation ) }, "controlled_separation_sweep": controlled_separation_sweep(), "deterministic_input_envelope": asdict(envelope), "supported_decision": classify_interval( envelope.c_a_min, envelope.c_a_max, case.threshold_mg_per_l, ), "limitations": [ "the deterministic reading bounds are not probabilities", "the linear sensor model and calibration are assumed, not validated", "only the emulated binary32 and current Python binary64 paths were tested", ], "source_revision": source_revision(), "runtime": { "python_version": platform.python_version(), "python_implementation": platform.python_implementation(), "operating_system": platform.system(), "os_release": platform.release(), "machine": platform.machine(), "float_radix": sys.float_info.radix, "float_mantissa_bits": sys.float_info.mant_dig, }, } def reliability_statement(case: SensorCase) -> str: """Return a concise statement supported by the assembled evidence.""" # TODO 6: write a statement comparing both precision errors with the # required accuracy, then give the conditioning, input envelope, supported # decision, and limitations. raise NotImplementedError("write the qualified reliability statement") def print_baseline(case: SensorCase) -> None: """Print the suspicious supplied result without revealing the diagnosis.""" binary32_solution = solve_binary32(case) print( "scientific question: is " f"c_A > {case.threshold_mg_per_l:.2f} mg/L?" ) print(f"required absolute accuracy: {case.required_accuracy_mg_per_l:.2f} mg/L") print("stored precision: binary32") print(f"c_A: {binary32_solution[0]:.9f} mg/L") print(f"c_B: {binary32_solution[1]:.9f} mg/L") print(f"decision: {classify_value(binary32_solution[0], case.threshold_mg_per_l)}") print( "residual infinity norm: " f"{residual_inf_norm(case, binary32_solution):.3e} response units" ) def print_report(case: SensorCase) -> None: """Print the complete evidence record and learner-written conclusion.""" print(json.dumps(build_evidence_record(case), indent=2, sort_keys=True)) print("\nqualified reliability statement\n") print(reliability_statement(case)) def main() -> None: parser = argparse.ArgumentParser(description=__doc__) parser.add_argument( "--report", action="store_true", help="print the complete evidence record instead of only the baseline", ) arguments = parser.parse_args() case = SensorCase() if arguments.report: print_report(case) else: print_baseline(case) if __name__ == "__main__": main()