Mixed Precision Engine: Examples

Each example is a verified run of a guided tour script from the shipped python/examples/ bundle (see PROGRESSION.md for the full 01→06 sequence). Run the guided tour first: it narrates the scenario, explains each metric, and shows when to trust the result. Use the production one-liner when wiring the same API call into your pipeline.

Beta release. Products in this catalog other than the SolvSRK family and SolvScout / SolvTune are beta — suitable for trials and evaluation; APIs and packaging may change before GA. Do not deploy beta builds in production programs without a signed agreement with Resonix. Activate a trial license before running examples — see Install and Licensing.

Journeys

Example 1: Journey 01 — First contact

Version, license, simplest successful call. Every support ticket starts with the package version. The C engine is machine-locked. license_valid() tells you whether this machine can run the gated functions (reduce/analyze/certify/RF).

Walkthrough:

1. What you are doing — mixed_precision decides, per field, the narrowest floating-point dtype that still meets a caller-supplied error tolerance. This journey just confirms the wheel loads, shows your license state, and runs the single smallest call the engine offers: analyze_field.

2. Version — Every support ticket starts with the package version.

   • version: 0.3.0

3. License — The C engine is machine-locked. license_valid() tells you whether this machine can run the gated functions (reduce/analyze/certify/RF).

   • license_valid: True

4. Simplest call: analyze_field — Given an array and a relative tolerance, analyze_field returns a recommendation: the target dtype, the worst-case error that dtype incurs, and whether the reduction is 'safe' (error <= tolerance).

   • n_values: 1000
   • tolerance: 0.001
   • target_dtype: float16
   • max_relative_error: 4.689e-04
   • safe: True
   • est_compression: 4.00x — float64 -> float16: the engine says this smooth ramp survives at 1e-3 with room to spare.

Guided tour output (from a verified run):

Version, license, simplest successful call

-- Act 1 - What you are doing --
  -> mixed_precision decides, per field, the narrowest floating-point dtype that still meets a caller-supplied error tolerance. This journey just confirms the wheel loads, shows your license state, and runs the single smallest call the engine offers: analyze_field.

-- Act 2 - Version --
  -> Every support ticket starts with the package version.
  version: 0.3.0

-- Act 3 - License --
  -> The C engine is machine-locked. license_valid() tells you whether this machine can run the gated functions (reduce/analyze/certify/RF).
  license_valid: True

-- Act 4 - Simplest call: analyze_field --
  -> Given an array and a relative tolerance, analyze_field returns a recommendation: the target dtype, the worst-case error that dtype incurs, and whether the reduction is 'safe' (error <= tolerance).
  n_values: 1000
  tolerance: 0.001
  target_dtype: float16
  max_relative_error: 4.689e-04
  safe: True
  est_compression: 4.00x
  -> float64 -> float16: the engine says this smooth ramp survives at 1e-3 with room to spare.

-- Run complete --
  version: 0.3.0
  target_dtype: float16
  next_journey: 02_reduce_dataset.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/01_first_contact.py
 
# Production one-liner — same API call you ship:
python -c "import mixed_precision as mp; print(mp.__version__, mp.license_valid())"

Example 2: Journey 02 — Reduce a dataset

Per-field dtype selection under a tolerance budget. reduce_dataset(fields, tolerances) returns a ReducedDataset: the reduced arrays, per-field metadata (the recommendation), and the byte totals. The byte totals reflect only the dtype reduction (lossless codecs come later in Journey 04). Fields that cannot be narrowed safely stay float64 - the engine never trades correctness for size.

Walkthrough:

1. The problem — You have a telemetry table where every column is stored as float64 out of habit. Most columns do not need 52 bits of mantissa. reduce_dataset analyzes each field independently and casts it to the narrowest dtype that still honors that field's tolerance.

2. Reduce — reduce_dataset(fields, tolerances) returns a ReducedDataset: the reduced arrays, per-field metadata (the recommendation), and the byte totals.

   • temperature_c: float16 (tol=1e-02, err=4.75e-04, safe=True)
   • pressure_kpa: float32 (tol=1e-04, err=3.76e-08, safe=True)
   • counter: float64 (tol=0e+00, err=0.00e+00, safe=True)
   • wide_dynamic: float32 (tol=1e-03, err=5.87e-08, safe=True)

3. The payoff — The byte totals reflect only the dtype reduction (lossless codecs come later in Journey 04). Fields that cannot be narrowed safely stay float64 - the engine never trades correctness for size.

   • original_bytes: 128000
   • reduced_bytes: 72000
   • compression_ratio: 1.78x

Guided tour output (from a verified run):

Per-field dtype selection under a tolerance budget

-- Act 1 - The problem --
  -> You have a telemetry table where every column is stored as float64 out of habit. Most columns do not need 52 bits of mantissa. reduce_dataset analyzes each field independently and casts it to the narrowest dtype that still honors that field's tolerance.

-- Act 2 - Reduce --
  -> reduce_dataset(fields, tolerances) returns a ReducedDataset: the reduced arrays, per-field metadata (the recommendation), and the byte totals.
  temperature_c: float16  (tol=1e-02, err=4.75e-04, safe=True)
  pressure_kpa: float32  (tol=1e-04, err=3.76e-08, safe=True)
  counter: float64  (tol=0e+00, err=0.00e+00, safe=True)
  wide_dynamic: float32  (tol=1e-03, err=5.87e-08, safe=True)

-- Act 3 - The payoff --
  -> The byte totals reflect only the dtype reduction (lossless codecs come later in Journey 04). Fields that cannot be narrowed safely stay float64 - the engine never trades correctness for size.
  original_bytes: 128000
  reduced_bytes: 72000
  compression_ratio: 1.78x

-- Run complete --
  fields: 4
  compression_ratio: 1.78x
  next_journey: 03_roundtrip_verify.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/02_reduce_dataset.py
 
# Production one-liner — same API call you ship:
python -c "import numpy as np, mixed_precision as mp; print(mp.reduce_dataset({'x': np.linspace(0,1,1000)}, {'x': 1e-3}).compression_ratio)"

Example 3: Journey 03 — Roundtrip + verify tolerance

Prove the reduced data still meets the promised error bound. Cast each field to its recommended dtype. measure_dataset_error compares the original float64 against the reduced field cast back to float64. It reports max abs/rel error, RMSE, PSNR, and a within_tolerance flag per field.

Walkthrough:

1. Why verify — A compression ratio means nothing if the data no longer meets your error budget. mixed_precision separates the claim (analyze_field) from the proof (measure the reconstructed error). This journey does both and asserts they agree.

2. Reduce — Cast each field to its recommended dtype.

   • smooth: float16 (safe=True)
   • noisy: float16 (safe=True)

3. Measure the reconstructed error — measure_dataset_error compares the original float64 against the reduced field cast back to float64. It reports max abs/rel error, RMSE, PSNR, and a within_tolerance flag per field.

   • smooth: max_rel=4.882e-04 (tol=1e-03) psnr=77.9 dB within_tol=True
   • noisy: max_rel=4.814e-04 (tol=1e-02) psnr=85.5 dB within_tol=True

4. The single-array shortcut — verify_roundtrip is the C-backed one-shot check for a single array: reduce, reconstruct, and confirm the max relative error stays under tol.

   • verify_roundtrip_smooth: True — All fields within tolerance: True

Guided tour output (from a verified run):

Prove the reduced data still meets the promised error bound

-- Act 1 - Why verify --
  -> A compression ratio means nothing if the data no longer meets your error budget. mixed_precision separates the claim (analyze_field) from the proof (measure the reconstructed error). This journey does both and asserts they agree.

-- Act 2 - Reduce --
  -> Cast each field to its recommended dtype.
  smooth: float16 (safe=True)
  noisy: float16 (safe=True)

-- Act 3 - Measure the reconstructed error --
  -> measure_dataset_error compares the original float64 against the reduced field cast back to float64. It reports max abs/rel error, RMSE, PSNR, and a within_tolerance flag per field.
  smooth: max_rel=4.882e-04 (tol=1e-03)  psnr=77.9 dB  within_tol=True
  noisy: max_rel=4.814e-04 (tol=1e-02)  psnr=85.5 dB  within_tol=True

-- Act 4 - The single-array shortcut --
  -> verify_roundtrip is the C-backed one-shot check for a single array: reduce, reconstruct, and confirm the max relative error stays under tol.
  verify_roundtrip_smooth: True
  -> All fields within tolerance: True

-- Run complete --
  fields_checked: 2
  all_within_tolerance: True
  next_journey: 04_recs_stream.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/03_roundtrip_verify.py
 
# Production one-liner — same API call you ship:
python -c "import numpy as np, mixed_precision as mp; x={'x': np.random.default_rng(0).standard_normal(2000)}; t={'x':1e-3}; r=mp.reduce_dataset(x,t); print(mp.all_within_tolerance(mp.measure_dataset_error(x, r.fields, t)))"

Example 4: Journey 04 — Certified RECS streaming

A contested tactical link carries multi-platform UAS telemetry. Each frame holds several float fields for many platforms. RECS (Resonix Error-bounded Certified Streaming) reduces + compresses each frame AND attaches a per-field certificate proving every reconstructed value met the bound. certify_and_encode_frame runs the semantic reduction, builds the certificate, and serializes everything to the RECS v1 wire format (32-byte header + certificate section + payload). decode_wire_frame parses the bytes a receiver would get. all_certified means every field's reconstruction stayed within the error bound - the receiver can trust the lossy payload without re-checking the raw data.

Walkthrough:

1. The scenario — A contested tactical link carries multi-platform UAS telemetry. Each frame holds several float fields for many platforms. RECS (Resonix Error-bounded Certified Streaming) reduces + compresses each frame AND attaches a per-field certificate proving every reconstructed value met the bound.

   • fields: lat_deg, lon_deg, alt_msl_m, heading_deg, ground_speed_mps, battery_soc_pct, mission_time_s
   • platforms: 50
   • codec: zstd

2. Certify + encode to wire bytes — certify_and_encode_frame runs the semantic reduction, builds the certificate, and serializes everything to the RECS v1 wire format (32-byte header + certificate section + payload).

   • wire_bytes: 830
   • error_bound: 0.001

3. Decode on the far side — decode_wire_frame parses the bytes a receiver would get. all_certified means every field's reconstruction stayed within the error bound - the receiver can trust the lossy payload without re-checking the raw data.

   • frame_index: 0
   • decoded_error_bound: 0.001
   • n_certificates: 7
   • all_certified: True
   • lat_deg: float16 max_rel=3.81e-04 violations=0/50
   • lon_deg: float16 max_rel=1.18e-05 violations=0/50
   • alt_msl_m: float16 max_rel=4.60e-04 violations=0/50
   • heading_deg: float16 max_rel=3.79e-04 violations=0/50
   • ground_speed_mps: float16 max_rel=3.79e-04 violations=0/50
   • battery_soc_pct: float16 max_rel=3.21e-04 violations=0/50
   • mission_time_s: float32 max_rel=9.16e-09 violations=0/50

Guided tour output (from a verified run):

Compress a telemetry frame, ship it, verify the certificate

-- Act 1 - The scenario --
  -> A contested tactical link carries multi-platform UAS telemetry. Each frame holds several float fields for many platforms. RECS (Resonix Error-bounded Certified Streaming) reduces + compresses each frame AND attaches a per-field certificate proving every reconstructed value met the bound.
  fields: lat_deg, lon_deg, alt_msl_m, heading_deg, ground_speed_mps, battery_soc_pct, mission_time_s
  platforms: 50
  codec: zstd

-- Act 2 - Certify + encode to wire bytes --
  -> certify_and_encode_frame runs the semantic reduction, builds the certificate, and serializes everything to the RECS v1 wire format (32-byte header + certificate section + payload).
  wire_bytes: 830
  error_bound: 0.001

-- Act 3 - Decode on the far side --
  -> decode_wire_frame parses the bytes a receiver would get. all_certified means every field's reconstruction stayed within the error bound - the receiver can trust the lossy payload without re-checking the raw data.
  frame_index: 0
  decoded_error_bound: 0.001
  n_certificates: 7
  all_certified: True
  lat_deg: float16  max_rel=3.81e-04  violations=0/50
  lon_deg: float16  max_rel=1.18e-05  violations=0/50
  alt_msl_m: float16  max_rel=4.60e-04  violations=0/50
  heading_deg: float16  max_rel=3.79e-04  violations=0/50
  ground_speed_mps: float16  max_rel=3.79e-04  violations=0/50
  battery_soc_pct: float16  max_rel=3.21e-04  violations=0/50
  mission_time_s: float32  max_rel=9.16e-09  violations=0/50

-- Run complete --
  wire_bytes: 830
  all_certified: True
  next_journey: 05_rf_product.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/04_recs_stream.py
 
# Production one-liner — same API call you ship:
python -c "import mixed_precision as mp; from mixed_precision.streaming.uas_telemetry import collect_uas_stream, UASStreamConfig; f=collect_uas_stream(UASStreamConfig(n_ticks=1))[0]; blob=mp.certify_and_encode_frame(f, {}, default_tolerance=1e-3, codec='none'); print(len(blob), mp.decode_wire_frame(blob).all_certified)"

Example 5: Journey 05 — RF product SKU (Low SWaP CFAR)

Shipped Low SWaP CFAR cell: fp64 FFT / fp16 filter / fp32 CFAR. Dropping the filter MAC to fp16 cuts compute/energy on the heaviest stage. The product config exists because, at these settings, detection probability (Pd) and false-alarm rate (Pfa) are preserved versus an all-fp64 reference. pd_preserved / pfa_preserved are the ship gates: True means the fp16 filter path kept detection performance inside tolerance of the fp64 reference on this cell. That is the whole value proposition - cheaper math, same answers.

Walkthrough:

1. From primitive to product — Journeys 01-04 used the general reduction engine. run_rf_product is a packaged SKU: a fixed, evidence-backed mixed-precision radar detection pipeline. It runs a matched-filter + CFAR detector where the filter MAC is computed in fp16 while the FFT stays fp64 and the CFAR stays fp32.

2. The claim being demonstrated — Dropping the filter MAC to fp16 cuts compute/energy on the heaviest stage. The product config exists because, at these settings, detection probability (Pd) and false-alarm rate (Pfa) are preserved versus an all-fp64 reference.

   • pipeline_config: fft=fp64|filt=fp16|det=fp32|mac=fp16_naive
   • detect_mode: cfar
   • filter_mac_mode: fp16_naive
   • survived: True
   • pd_ref: 1.0
   • pd_test: 1.0
   • pd_delta: 0.0
   • pd_preserved: True
   • pfa_test: 0.0
   • pfa_preserved: True
   • peak_power_loss_db: 0.0063

3. How to read this — pd_preserved / pfa_preserved are the ship gates: True means the fp16 filter path kept detection performance inside tolerance of the fp64 reference on this cell. That is the whole value proposition - cheaper math, same answers.

Guided tour output (from a verified run):

Shipped Low SWaP CFAR cell: fp64 FFT / fp16 filter / fp32 CFAR

-- Act 1 - From primitive to product --
  -> Journeys 01-04 used the general reduction engine. run_rf_product is a packaged SKU: a fixed, evidence-backed mixed-precision radar detection pipeline. It runs a matched-filter + CFAR detector where the filter MAC is computed in fp16 while the FFT stays fp64 and the CFAR stays fp32.

-- Act 2 - The claim being demonstrated --
  -> Dropping the filter MAC to fp16 cuts compute/energy on the heaviest stage. The product config exists because, at these settings, detection probability (Pd) and false-alarm rate (Pfa) are preserved versus an all-fp64 reference.
  pipeline_config: fft=fp64|filt=fp16|det=fp32|mac=fp16_naive
  detect_mode: cfar
  filter_mac_mode: fp16_naive
  survived: True
  pd_ref: 1.0
  pd_test: 1.0
  pd_delta: 0.0
  pd_preserved: True
  pfa_test: 0.0
  pfa_preserved: True
  peak_power_loss_db: 0.0063

-- Act 3 - How to read this --
  -> pd_preserved / pfa_preserved are the ship gates: True means the fp16 filter path kept detection performance inside tolerance of the fp64 reference on this cell. That is the whole value proposition - cheaper math, same answers.

-- Run complete --
  detect_mode: cfar
  pd_preserved: True
  next_journey: 06_limits.py

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/05_rf_product.py
 
# Production one-liner — same API call you ship:
python -c "import mixed_precision as mp; r=mp.run_rf_product(snr_db=10.0, n_samples=512, n_trials=8, seed=99, filter_mac_mode='fp16_naive'); print(r['survived'], r['detect_mode'])"

Example 6: Journey 06 — Limits / when not to use

The honest failure edges - and how the engine refuses. A field spanning 1e-9 to 1e9 needs float64's exponent range. At a tight relative tolerance, the engine keeps it at float64 (safe reduction impossible). Ask for 1e-15 relative accuracy and only float64 qualifies. The engine reports the smallest dtype that still meets the bound - here, float64.

Walkthrough:

1. Why this journey exists — The engine's value is that it REFUSES unsafe reductions. It never silently trades correctness for size. Here are the cases where it keeps fields at float64 - and where you should not expect compression at all.

2. Wide dynamic range — A field spanning 1e-9 to 1e9 needs float64's exponent range. At a tight relative tolerance, the engine keeps it at float64 (safe reduction impossible).

   • target_dtype: float32
   • safe: True
   • max_relative_error: 2.828e-08

3. Tolerance too tight for any narrower dtype — Ask for 1e-15 relative accuracy and only float64 qualifies. The engine reports the smallest dtype that still meets the bound - here, float64.

   • target_dtype: float64
   • safe: True

4. Contrast: naive truncation is NOT what we do — naive_truncate casts without analysis and without a license gate - it is a baseline for benchmarks, not a product path. It will happily destroy your data. Compare the reconstructed error to a proper analyze_field decision.

   • naive_dtype: float16
   • naive_max_relative_error: inf
   • naive_within_tolerance: False — Naive fp16 on wide-dynamic data blows the tolerance; the engine's analyze_field kept it at float64 for exactly this reason.

5. Rules of thumb — Use it: smooth/bounded telemetry, sensor windows, RECS streaming, the RF SKU. Skip it: cryptographic/exact integers, tiny arrays (overhead > gain), fields where you need >7 significant digits everywhere.

Guided tour output (from a verified run):

The honest failure edges - and how the engine refuses

-- Act 1 - Why this journey exists --
  -> The engine's value is that it REFUSES unsafe reductions. It never silently trades correctness for size. Here are the cases where it keeps fields at float64 - and where you should not expect compression at all.

-- Act 2 - Wide dynamic range --
  -> A field spanning 1e-9 to 1e9 needs float64's exponent range. At a tight relative tolerance, the engine keeps it at float64 (safe reduction impossible).
  target_dtype: float32
  safe: True
  max_relative_error: 2.828e-08

-- Act 3 - Tolerance too tight for any narrower dtype --
  -> Ask for 1e-15 relative accuracy and only float64 qualifies. The engine reports the smallest dtype that still meets the bound - here, float64.
  target_dtype: float64
  safe: True

-- Act 4 - Contrast: naive truncation is NOT what we do --
  -> naive_truncate casts without analysis and without a license gate - it is a baseline for benchmarks, not a product path. It will happily destroy your data. Compare the reconstructed error to a proper analyze_field decision.
  naive_dtype: float16
  naive_max_relative_error: inf
  naive_within_tolerance: False
  -> Naive fp16 on wide-dynamic data blows the tolerance; the engine's analyze_field kept it at float64 for exactly this reason.

-- Act 5 - Rules of thumb --
  -> Use it: smooth/bounded telemetry, sensor windows, RECS streaming, the RF SKU. Skip it: cryptographic/exact integers, tiny arrays (overhead > gain), fields where you need >7 significant digits everywhere.

-- Run complete --
  wide_dtype: float32
  tight_dtype: float64
  next_journey: (suite complete - see PROGRESSION.md)

cd python
# Guided tour — narrated scenario walkthrough (recommended first run):
python examples/journeys/06_limits.py
 
# Production one-liner — same API call you ship:
python -c "import numpy as np, mixed_precision as mp; print(mp.analyze_field(np.array([1e-9, 1e9]), 1e-6).target_dtype)"

Example bundle

Every journey is a domain scenario with narrated acts — run the guided tour first to see what each number means, then copy the production one-liner into your pipeline.

Guided journeys

Run from the python/ directory after install and license activation. Set MIXED_PRECISION_QUIET=1 only when you want silent CLI runs (no narration).