research: prepare B1 residual contract and physics branch findings

This commit is contained in:
Frank14f committed 2026-11-17 11:39:46 +08:00
1 parent f9a5b4eafe
commit 0a60f5d6fd
7 files changed
+493

No files matched your search

+46
View File
@@ -0,0 +1,46 @@
"""Array-only residual interface; no I/O, model, labels, or clock fitting policy.
The caller supplies a frozen, training-only clock. It also fixes the F precision
in the reviewed contract. Passing F explicitly avoids a hidden extra feature.
"""
import numpy as np
def prior(cdf, clock):
f = np.asarray(cdf)
if f.ndim != 1 or f.dtype.kind != 'f' or not len(f):
raise ValueError('Expected nonempty floating-point CDF vector')
if not np.isfinite(f).all() or np.any(f < 0) or np.any(f > 1):
raise ValueError('CDF outside [0,1] or nonfinite')
if not np.isscalar(clock) or not np.isfinite(clock) or clock <= 0:
raise ValueError('Clock must be a finite positive frozen scalar')
return np.asarray(f, dtype=np.float64)*float(clock)
def residual_target(target_star, cdf, clock, *, fit_dtype):
y = np.asarray(target_star, dtype=np.float64)
base = prior(cdf, clock)
if y.shape != base.shape or not np.isfinite(y).all() or np.any(y < 0):
raise ValueError('Invalid original normalized arrival target')
dtype = np.dtype(fit_dtype)
if dtype not in (np.dtype('float32'), np.dtype('float64')):
raise ValueError('Fit precision must be explicitly float32 or float64')
out = np.asarray(y-base, dtype=dtype)
if not np.isfinite(out).all():
raise ValueError('Residual overflow at fit precision')
# Negative residuals are valid. Never clip or impose a positivity loss here.
return out
def decode_seconds(predicted_residual, cdf, clock, t_set):
residual = np.asarray(predicted_residual, dtype=np.float64)
base = prior(cdf, clock)
if residual.shape != base.shape or not np.isfinite(residual).all():
raise ValueError('Invalid predicted residual')
if not np.isscalar(t_set) or not np.isfinite(t_set) or t_set <= 0:
raise ValueError('Invalid pre-solve seconds scale')
out = (base+residual)*float(t_set)
if not np.isfinite(out).all():
raise ValueError('Decoded prediction overflow')
# Keep negative predictions visible to scoring/diagnostics; no silent clamp.
return out
+38
View File
@@ -0,0 +1,38 @@
"""Synthetic interface checks only; no model fit or project data access."""
import unittest
import numpy as np
from phase2_residual_math import prior, residual_target, decode_seconds
class ResidualInterfaceTests(unittest.TestCase):
def test_negative_residual_and_exact_reconstruction(self):
f = np.array([0., .25, .75]); y = np.array([0., .125, .5])
r = residual_target(y, f, 2., fit_dtype='float64')
self.assertTrue(np.any(r < 0))
np.testing.assert_array_equal(decode_seconds(r, f, 2., 4.), y*4.)
def test_zero_residual_is_prior(self):
f = np.array([0., .25, .5], dtype=np.float32)
np.testing.assert_array_equal(decode_seconds(np.zeros(3), f, 1.5, 2.), np.asarray(f, dtype=np.float64)*3.)
def test_no_posthoc_clamp(self):
y = decode_seconds(np.array([-1., 2.]), np.array([0., 1.]), 1., 1.)
np.testing.assert_array_equal(y, [-1., 3.])
def test_bad_shapes_and_inputs(self):
for f in [np.array([]), np.array([np.nan]), np.array([-0.1]), np.array([1.1]), np.zeros((2, 1))]:
with self.assertRaises(ValueError): prior(f, 1.)
for clock in [0., -1., float('nan'), float('inf')]:
with self.assertRaises(ValueError): prior(np.array([.5]), clock)
with self.assertRaises(ValueError): residual_target(np.array([1., 2.]), np.array([.5]), 1., fit_dtype='float32')
with self.assertRaises(ValueError): decode_seconds(np.array([0.]), np.array([.5]), 1., 0.)
def test_permutation_equivariance(self):
f = np.array([0., .1, .1, .7]); y = np.array([0., .05, .2, .8]); order = np.array([2, 0, 3, 1])
a = residual_target(y, f, .9, fit_dtype='float32')
b = residual_target(y[order], f[order], .9, fit_dtype='float32')
np.testing.assert_array_equal(a[order], b)
if __name__ == '__main__':
unittest.main()