chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/core/time_reduction_numpy.py

@@ -0,0 +1,205 @@
+"""用真实数组处理有限块时间极值、规范化时间均值及BOOL TRUE时长。
+
+push把有限CalculationSeries装成(N,)typed列，区间使用(N-1,)int64纳秒差与bool掩码。
+min/max保留原dtype；duration用TRUE掩码精确累计纳秒；mean先独立检查整数
+浮点精度，第二遍以全窗有效时长规范化权重，再推进本数组原序误差归约。
+最终单位仅finish转换一次，不读旧来源、不保存全轴，也不调用参考数值核。
+装箱和未知Interval恢复循环只处理协议；数值裁剪、掩码、权重和极值用数组。
+状态驱动累计少量标量事实；数组及误差状态预算由外层owner提前预约。
+指定step_ns只接收所选驱动真实点；时长/均值按实际交集折算，另有一份有限权重
+求和状态。接线者须预约这份状态和当前权重数组，不能沿用actual的费用冒充已计费。
+"""
+
+# 本后端只复用数组原序核与静态模型，数值不委托参考实现。
+import numpy as np
+from .integral_sum_numpy import NumpyIntegralSum
+from .models import Interval
+from .numeric_numpy import NumericArray, DTYPES, to_float_numpy
+from .types import QualityFlag as Q
+from .time_reduction import (TimeCalculationFacts, TimeReductionResult,
+                             require_time_config, require_time_series, require_time_options)
+
+from .time_reduction import MeanTimeBlock
+from .mean_weights_numpy import normalized_mean_terms
+
+
+class NumpyTimeReduction:
+    """保留单候选、精确时长计数及有限误差数组，不保留历史输入列。
+
+    mean分母为None时只处理第一遍事实，不能finish；第二遍须逐块消费同一历史。
+    原序浮点累计属于state_driver，每项误差推进与块掩码均是实际数组运算。
+    """
+
+    def __init__(self, spec, input_unit, dtype, *, selected_duration_ns=None, partial_limit=4096,
+                 step_ns=None, selected_weight_seconds=None):
+        """检查无条件时间配置并建立本数组后端状态。
+
+        参数: spec/单位/dtype为原配置；selected_duration_ns为均值全窗有效时长；
+            partial_limit为误差容量；step_ns可选周期，周期均值第二遍改用
+            selected_weight_seconds。返回: None。异常: 配置、数组分配错误传播。
+        """
+        self._unit, self._factor = require_time_config(spec, input_unit, dtype, selected_duration_ns, partial_limit,
+            step_ns=step_ns, selected_weight_seconds=selected_weight_seconds)
+        self._spec, self._input_unit, self._dtype = spec, input_unit, dtype
+        self._step_ns = step_ns
+        self._denominator = selected_duration_ns if step_ns is None else selected_weight_seconds
+        # 固定状态不随输入块数增长，输入列生命周期只限当前push。
+        self._identity = self._candidate = None
+        self._value_duration = self._selected_duration = self._terms = 0
+        self._numeric_quality = Q.NONE
+        self._sum = NumpyIntegralSum(partial_limit) if spec.operation == 'time_weighted_mean' and self._denominator is not None else None
+        self._weight_sum = NumpyIntegralSum(partial_limit) if step_ns is not None and spec.operation in ('duration', 'time_weighted_mean') else None
+
+    @property
+    def selected_weight_seconds(self):
+        """读取必要的周期累计权重。参数: 无。返回: float或不适用None。异常: 数值故障。"""
+        if self._weight_sum is None:
+            return None
+        result = self._weight_sum.finish('s')
+        if result.calculation_failed:
+            raise OverflowError('周期权重累计失败')
+        return 0.0 if result.value is None else result.value
+
+    @property
+    def selected_duration_ns(self):
+        """读取累计选择时长。参数: 无。返回: 原生int纳秒。异常: 无。"""
+        return self._selected_duration
+
+    @property
+    def value_valid_duration_ns(self):
+        """读取累计有效时长。参数: 无。返回: 原生int纳秒。异常: 无。"""
+        return self._value_duration
+
+    def push(self, series, *, valid_until_ns=None, retain_unknown_ranges=True, retain_mean_terms=False):
+        """数组计算有限块事实，并推进对应原单位数值状态。
+
+        参数: series为无条件、同dtype和原单位CalculationSeries；末点不贡献区间或样本。
+        valid_until_ns按实际时间截断；retain_unknown_ranges=False省去未知位置构造。
+        retain_mean_terms仅均值首遍返回MeanTimeBlock，其他调用返回事实。
+        返回: TimeCalculationFacts；数值权重故障与输入覆盖有效性分别记录。
+        异常: 结构、身份、容量或分配错误传播；外层异常后只能清理owner。
+        内存: 新数组都是当前(N,)或(N-1,)有限列，不修改输入，也不存入跨块状态。
+        """
+        actual = require_time_series(series, self._spec, self._input_unit, self._dtype)
+        require_time_options(series, self._step_ns, valid_until_ns, retain_unknown_ranges)
+        if type(retain_mean_terms) is not bool or retain_mean_terms and (self._spec.operation != 'time_weighted_mean' or self._denominator is not None):
+            raise ValueError('仅均值首遍可请求必要回读项')
+        if self._identity is not None and self._identity != series.binding_identity:
+            raise ValueError('时间归约不能跨绑定身份累计')
+        self._identity = series.binding_identity
+        # 装箱仅恢复typed列；无效位置0需要显式valid和quality，不能作为正常值。
+        column = NumericArray(self._dtype,
+                              np.array([value.value if value.valid else 0 for value in series.values], dtype=DTYPES[self._dtype]),
+                              np.array([value.valid for value in series.values], dtype=bool),
+                              np.array([int(value.quality) for value in series.values], dtype=np.uint16))
+        values = to_float_numpy(column) if self._spec.operation == 'time_weighted_mean' else column
+        times = np.array(series.times_ns, dtype=np.int64)
+        start, end = (actual.start_ns, actual.end_ns) if actual is not None else (0, 0)
+        # 先裁剪整数端点，仅在正交集做差，避免域外反序减法wrap。
+        left = np.maximum(times[:-1], np.int64(start))
+        right = np.minimum(times[1:], np.int64(end))
+        observed = right > left
+        deadlines = np.array([2**63-1 if item is None else item for item in valid_until_ns], dtype=np.int64) if valid_until_ns is not None else None
+        value_end = right.copy() if deadlines is None else np.minimum(right, deadlines[:-1])
+        value_end = np.maximum(left, np.where(values.valid[:-1], value_end, left))
+        durations = np.zeros(len(left), dtype=np.int64)
+        usable = observed & (value_end > left)
+        np.subtract(value_end, left, out=durations, where=usable)
+        selected = usable & values.values[:-1] if self._spec.operation == 'duration' else usable
+        # 非负时长总和不超过已校验观测跨度，int64不会wrap；全窗由Python整数累加。
+        value_duration = int(np.sum(durations[usable], dtype=np.int64))
+        selected_duration = int(np.sum(durations[selected], dtype=np.int64))
+        seconds = None
+        if self._weight_sum is not None:
+            # 只计算当前有限块；求和后列只读，后续归一化另生成数值结果。
+            seconds = durations[selected].astype(np.float64)
+            seconds /= np.diff(times)[selected]
+            seconds *= self._step_ns / 1_000_000_000
+            weight_valid = np.ones(len(seconds), dtype=bool)
+            seconds.setflags(write=False)
+            weight_valid.setflags(write=False)
+            self._weight_sum.push_values(seconds, weight_valid)
+        terms = int(np.count_nonzero(usable))
+        samples = (times >= start) & (times < end) & np.array(series.actual_value_updates, dtype=bool) & values.valid
+        if deadlines is not None:
+            samples &= times < deadlines
+        if self._spec.operation == 'duration':
+            samples &= values.values
+        # 依赖诊断覆盖正区间与实际更新点；EOF右端不凭点增加时长或样本。
+        relevant = np.concatenate((observed, np.array([False]))) | ((times >= start) & (times < end) & np.array(series.actual_value_updates, dtype=bool))
+        diagnostics = np.array([int(item) for item in series.diagnostics], dtype=np.uint16) | values.quality
+        quality = Q(int(np.bitwise_or.reduce(diagnostics[relevant], initial=np.uint16(0))))
+        if np.any(observed & values.valid[:-1] & (value_end < right)):
+            quality |= Q.STALE
+        unknown = (tuple(Interval(int(value_end[index]), int(right[index])) for index in np.flatnonzero(observed & (value_end < right)))
+                   if retain_unknown_ranges else ())
+        if self._spec.operation in ('min_time', 'max_time') and terms:
+            # 每块极值由原dtype数组归约，跨块仅保存一个精确原生候选。
+            candidate = (np.min if self._spec.operation == 'min_time' else np.max)(values.values[:-1][usable])
+            if self._candidate is not None:
+                previous = DTYPES[self._dtype].type(self._candidate)
+                candidate = (np.minimum if self._spec.operation == 'min_time' else np.maximum)(previous, candidate)
+            self._candidate = candidate.item()
+        elif self._spec.operation == 'time_weighted_mean' and self._denominator is not None:
+            chosen = values.values[:-1][usable]
+            measures = durations[usable].astype(np.float64) if self._step_ns is None else seconds
+            weighted, weight_quality = normalized_mean_terms(chosen, measures, self._denominator)
+            self._numeric_quality |= weight_quality
+            if self._numeric_quality == Q.NONE:
+                keep = np.ones(len(weighted), dtype=bool)
+                keep.setflags(write=False)
+                self._sum.push_values(weighted, keep)
+        self._value_duration += value_duration
+        self._selected_duration += selected_duration
+        self._terms += terms
+        facts = TimeCalculationFacts(self._spec, actual, value_duration, selected_duration,
+                               int(np.count_nonzero(samples)), unknown, quality, self._input_unit,
+                               self._dtype, series.binding_identity, series.source_refs, retain_unknown_ranges)
+        if retain_mean_terms:
+            selected_values = values.values[:-1][usable]
+            selected_weights = durations[usable].copy() if self._step_ns is None else seconds
+            selected_values.setflags(write=False)
+            selected_weights.setflags(write=False)
+            return MeanTimeBlock(facts, selected_values, selected_weights)
+        return facts
+
+    def finish(self):
+        """正确舍入并做一次最终转换，生成本后端数值快照。
+
+        参数: 无。返回: TimeReductionResult，不执行覆盖状态分类。
+        异常: RuntimeError为mean第一遍；ValueError为有效时长与全窗分母不符；
+            分配或取消传播，数值溢出与非零下溢写成计算失败。
+        """
+        if self._spec.operation == 'time_weighted_mean':
+            if self._denominator is None:
+                raise RuntimeError('时间均值第一遍只收事实，不能生成数值')
+            measured = self._selected_duration if self._step_ns is None else self.selected_weight_seconds
+            if measured != self._denominator:
+                raise ValueError('时间均值第二遍有效时长与整窗分母不同')
+            if self._numeric_quality != Q.NONE:
+                return TimeReductionResult(None, self._unit, True, self._numeric_quality, self._terms)
+            # 数组原序核直接执行一次输出转换；映射冻结结果不再次做数值处理。
+            number = self._sum.finish(self._unit, self._factor)
+            return TimeReductionResult(number.value, number.unit, number.calculation_failed, number.quality, self._terms)
+        if self._terms == 0:
+            return TimeReductionResult(None, self._unit, False, Q.NONE, 0)
+        # BOOL时长先保持精确整数纳秒，再最终换成秒；极值保持原native dtype。
+        value = ((float(np.divide(np.float64(self._selected_duration), np.float64(1_000_000_000)))
+                  if self._step_ns is None else self.selected_weight_seconds)
+                 if self._spec.operation == 'duration' else self._candidate)
+        quality = Q.NONE
+        if self._factor != 1 and type(value) is int:
+            converted = to_float_numpy(NumericArray(self._dtype,
+                np.array([value], dtype=DTYPES[self._dtype]), np.array([True]), np.array([0], dtype=np.uint16)))
+            if not converted.valid[0]:
+                quality |= Q(int(converted.quality[0]))
+            else:
+                value = converted.values[0].item()
+        if quality == Q.NONE and self._factor != 1:
+            original = value
+            with np.errstate(over='ignore', under='ignore', invalid='ignore'):
+                value = np.multiply(np.float64(value), np.float64(self._factor)).item()
+            if not np.isfinite(value) or value == 0 and original != 0:
+                quality |= Q.NONFINITE if not np.isfinite(value) else Q.PRECISION_LOSS
+        return TimeReductionResult(None if quality != Q.NONE else value, self._unit,
+                                   quality != Q.NONE, quality, self._terms)

chronaxis/core/time_reduction_reference.py

@@ -0,0 +1,203 @@
+"""独立用标量处理有限块时间极值、规范化时间均值和BOOL TRUE时长。
+
+push接收原单位CalculationSeries，返回该块的覆盖、更新、未知及来源事实。
+min/max保留原整数；duration精确累计纳秒；mean第一遍只查有效性，第二遍
+使用已知全窗有效时长计算每项x*(dt/D)，并由本参考后端原序误差核归约。
+最终单位只在finish转换一次，不先求块均值或块面积、不保存全窗列。
+指定step_ns时只接收所选驱动真实记录对，按实际交集折算周期；时长/均值额外
+使用一份有界权重求和状态，不把浮点权重冒充实际纳秒覆盖。外层须为其预付费用。
+本纯核只依赖标准库与参考算法，不执行I/O、资源预约或关闭；有限临时列表、
+误差状态及返回事实必须由外层owner预先计费，推进异常后外层须放弃该状态。
+"""
+
+# 参考核不导入NumPy；复用同后端已验证的原序误差状态，不复用数组算法。
+from math import isfinite
+from .integral_sum_reference import ReferenceIntegralSum
+from .models import Interval
+from .numeric import ScalarValue, to_float_reference
+from .types import QualityFlag as Q
+from .time_reduction import (TimeCalculationFacts, TimeReductionResult,
+                             require_time_config, require_time_series, require_time_options)
+from .record_intervals import clipped_record_seconds
+
+from .time_reduction import MeanTimeBlock
+from .mean_weights_reference import normalized_mean_terms
+
+
+class ReferenceTimeReduction:
+    """保留有限数值状态，第一遍与第二遍的mean实例不能混用。
+
+    极值只保留一个原生候选，actual时长只保留整数；周期权重与均值误差项
+    分别受partial_limit限制，原调用方的费用估算不能直接沿用到新周期模式。
+    finish为不破坏状态的快照，未指定均值全窗分母时禁止生成候选数值。
+    """
+
+    def __init__(self, spec, input_unit, dtype, *, selected_duration_ns=None, partial_limit=4096,
+                 step_ns=None, selected_weight_seconds=None):
+        """检查明确配置，再建立本后端有限状态。
+
+        参数: spec/单位/dtype为原输入；selected_duration_ns为均值第二遍整窗有效时长；
+            partial_limit为误差容量；step_ns可选周期；周期均值第二遍使用
+            selected_weight_seconds。返回: None。异常: 配置或分配错误原样传播。
+        """
+        self._unit, self._factor = require_time_config(spec, input_unit, dtype, selected_duration_ns, partial_limit,
+            step_ns=step_ns, selected_weight_seconds=selected_weight_seconds)
+        self._spec, self._input_unit, self._dtype = spec, input_unit, dtype
+        self._step_ns = step_ns
+        self._denominator = selected_duration_ns if step_ns is None else selected_weight_seconds
+        # 常量状态不随着输入块数增长；输入身份在第一块确认后禁止变化。
+        self._identity = self._candidate = None
+        self._value_duration = self._selected_duration = self._terms = 0
+        self._numeric_quality = Q.NONE
+        self._sum = ReferenceIntegralSum(partial_limit) if spec.operation == 'time_weighted_mean' and self._denominator is not None else None
+        # 只在周期时长/均值确实需要时保存有限权重误差项；不存逐条时间或输入。
+        self._weight_sum = ReferenceIntegralSum(partial_limit) if step_ns is not None and spec.operation in ('duration', 'time_weighted_mean') else None
+
+    @property
+    def selected_weight_seconds(self):
+        """读取周期模式的必要累计权重。参数: 无。返回: float或不适用None。异常: 数值故障。"""
+        if self._weight_sum is None:
+            return None
+        result = self._weight_sum.finish('s')
+        if result.calculation_failed:
+            raise OverflowError('周期权重累计失败')
+        return 0.0 if result.value is None else result.value
+
+    @property
+    def selected_duration_ns(self):
+        """读取累计已选时长。参数: 无。返回: 原生int纳秒。异常: 无。"""
+        return self._selected_duration
+
+    @property
+    def value_valid_duration_ns(self):
+        """读取累计有效时长。参数: 无。返回: 原生int纳秒。异常: 无。"""
+        return self._value_duration
+
+    def push(self, series, *, valid_until_ns=None, retain_unknown_ranges=True, retain_mean_terms=False):
+        """独立消费有限块并返回事实，不跨块保存输入列。
+
+        参数: series为同dtype/原单位的无条件CalculationSeries，末点不参与正区间或样本。
+        valid_until_ns按实际时间截断；retain_unknown_ranges=False省去未知位置构造。
+        retain_mean_terms仅均值首遍返回MeanTimeBlock，其他调用返回事实。
+        返回: TimeCalculationFacts；mean权重故障另记数值失败，不改变有效覆盖。
+            step_ns模式只接受驱动真实点，不把合成TTL/窗口点当新周期。
+        异常: 结构、身份、容量或分配错误原样传播；外层不得继续使用异常前缀。
+        """
+        actual = require_time_series(series, self._spec, self._input_unit, self._dtype)
+        require_time_options(series, self._step_ns, valid_until_ns, retain_unknown_ranges)
+        if type(retain_mean_terms) is not bool or retain_mean_terms and (self._spec.operation != 'time_weighted_mean' or self._denominator is not None):
+            raise ValueError('仅均值首遍可请求必要回读项')
+        if self._identity is not None and self._identity != series.binding_identity:
+            raise ValueError('时间归约不能跨绑定身份累计')
+        self._identity = series.binding_identity
+        # 仅mean需要浮点精度门槛，极值不把大整数无声转成浮点数。
+        values = tuple(to_float_reference(value) for value in series.values) if self._spec.operation == 'time_weighted_mean' else series.values
+        start = actual.start_ns if actual is not None else 0
+        end = actual.end_ns if actual is not None else 0
+        value_duration = selected_duration = samples = terms = 0
+        unknown, weighted = [], []
+        period_weights = [] if self._weight_sum is not None else None
+        mean_values = [] if self._spec.operation == 'time_weighted_mean' and (self._denominator is not None or retain_mean_terms) else None
+        mean_weights = [] if mean_values is not None else None
+        quality, weight_quality = Q.NONE, Q.NONE
+        # 逐正区间独立计算整数裁剪差与有效性，完全不调用NumPy。
+        for index in range(len(series.times_ns) - 1):
+            left, right = max(series.times_ns[index], start), min(series.times_ns[index + 1], end)
+            if left >= right:
+                continue
+            value = values[index]
+            quality |= series.diagnostics[index] | value.quality
+            deadline = None if valid_until_ns is None else valid_until_ns[index]
+            value_end = max(left, min(right, deadline)) if deadline is not None else right
+            if not value.valid:
+                value_end = left
+            if value_end < right:
+                if retain_unknown_ranges:
+                    unknown.append(Interval(value_end, right))
+                if value.valid:
+                    quality |= Q.STALE
+            if value_end <= left:
+                continue
+            dt = value_end - left
+            value_duration += dt
+            terms += 1
+            # FALSE是有效主BOOL，仍提供零时长证据；只有TRUE增加选择时长。
+            selected_duration += dt if self._spec.operation != 'duration' or value.value else 0
+            measure = dt
+            if period_weights is not None and (self._spec.operation != 'duration' or value.value):
+                measure = clipped_record_seconds(series.times_ns[index], series.times_ns[index + 1],
+                                                 Interval(left, value_end), step_ns=self._step_ns)
+                period_weights.append(measure)
+            if self._spec.operation in ('min_time', 'max_time'):
+                if self._candidate is None:
+                    self._candidate = value.value
+                elif self._spec.operation == 'min_time':
+                    self._candidate = min(self._candidate, value.value)
+                else:
+                    self._candidate = max(self._candidate, value.value)
+            elif mean_values is not None:
+                mean_values.append(value.value)
+                mean_weights.append(measure)
+        # 真实更新的点诊断与计数独立于保持区间，不把右端重复计算。
+        for index, time in enumerate(series.times_ns):
+            if not start <= time < end or not series.actual_value_updates[index]:
+                continue
+            value = values[index]
+            quality |= series.diagnostics[index] | value.quality
+            deadline = None if valid_until_ns is None else valid_until_ns[index]
+            if value.valid and (deadline is None or time < deadline) and (self._spec.operation != 'duration' or value.value):
+                samples += 1
+        # 原序状态只接受正常权重项；任一权重失败使整次均值失败，覆盖仍完整保留。
+        if self._denominator is not None:
+            weighted, weight_quality = normalized_mean_terms(mean_values, mean_weights, self._denominator)
+        self._numeric_quality |= weight_quality
+        if period_weights is not None:
+            self._weight_sum.push_values(tuple(period_weights), (True,) * len(period_weights))
+        if self._sum is not None and self._numeric_quality == Q.NONE:
+            self._sum.push_values(tuple(weighted), (True,) * len(weighted))
+        self._value_duration += value_duration
+        self._selected_duration += selected_duration
+        self._terms += terms
+        facts = TimeCalculationFacts(self._spec, actual, value_duration, selected_duration, samples,
+                               tuple(unknown), quality, self._input_unit, self._dtype,
+                               series.binding_identity, series.source_refs, retain_unknown_ranges)
+        return MeanTimeBlock(facts, tuple(mean_values), tuple(mean_weights)) if retain_mean_terms else facts
+
+    def finish(self):
+        """仅完整调用者确认后生成数值快照，最终转换一次。
+
+        参数: 无。返回: TimeReductionResult，覆盖分类由外层负责。
+        异常: RuntimeError为mean第一遍；ValueError为第二遍有效时长与分母不符；
+            配置/分配错误传播，数值范围错误按calculation_failed返回。
+        """
+        if self._spec.operation == 'time_weighted_mean':
+            if self._denominator is None:
+                raise RuntimeError('时间均值第一遍只收事实，不能生成数值')
+            measured = self._selected_duration if self._step_ns is None else self.selected_weight_seconds
+            if measured != self._denominator:
+                raise ValueError('时间均值第二遍有效时长与整窗分母不同')
+            if self._numeric_quality != Q.NONE:
+                return TimeReductionResult(None, self._unit, True, self._numeric_quality, self._terms)
+            # 本参考原序核finish直接执行一次转换；输出映射不再乘因子。
+            number = self._sum.finish(self._unit, self._factor)
+            return TimeReductionResult(number.value, number.unit, number.calculation_failed, number.quality, self._terms)
+        # 没有有效正区间不能借sum空输入产生正常零。
+        if self._terms == 0:
+            return TimeReductionResult(None, self._unit, False, Q.NONE, 0)
+        value = ((self._selected_duration / 1_000_000_000 if self._step_ns is None else self.selected_weight_seconds)
+                 if self._spec.operation == 'duration' else self._candidate)
+        quality = Q.NONE
+        # 非1倍率的整数极值先校验精确float表示，再转换；倍率1保持原生整数。
+        if self._factor != 1 and type(value) is int:
+            converted = to_float_reference(ScalarValue(value, self._dtype))
+            if not converted.valid:
+                quality |= converted.quality
+            else:
+                value = converted.value
+        if quality == Q.NONE:
+            original = value
+            value = value * self._factor if self._factor != 1 else value
+            if type(value) is float and (not isfinite(value) or value == 0 and original != 0):
+                quality |= Q.NONFINITE if not isfinite(value) else Q.PRECISION_LOSS
+        return TimeReductionResult(None if quality != Q.NONE else value, self._unit,
+                                   quality != Q.NONE, quality, self._terms)

chronaxis/core/types.py

@@ -0,0 +1,105 @@
+"""定义信号类型、时间坐标、三值条件和质量原因，供模型及计算层共用。
+
+模型接收明确的枚举成员；质量原因以固定的整数位保存，允许组合已知位，
+拒绝未知位。Truth区分条件成立、不成立和无法确定三种结果，禁止直接转为
+Python布尔值。SignalDType声明值类型，TimeType区分相对坐标与UTC绝对坐标。
+本模块只依赖标准库，不读取数据或文件，不持有会话状态；SourceType当前
+只描述内存输入。
+"""
+
+# 严格位边界防止未知质量位被误认为已校验策略。
+from enum import Enum, FlagBoundary, IntFlag
+
+
+class Truth(Enum):
+    """保存条件成立、不成立或无法确定的三种结果。
+
+    TRUE和FALSE表示已有充分证据；UNKNOWN表示缺失、过期或无法有效求值。
+    成员不可变，任何成员都禁止隐式转为Python布尔值，调用者须明确处理三种结果。
+    """
+
+    TRUE = "true"  # 已知且条件成立。
+    FALSE = "false"  # 已知且条件不成立。
+    UNKNOWN = "unknown"  # 缺失、过期或无法有效求值。
+
+    def __bool__(self) -> bool:
+        """阻止三个枚举成员被Python统一当作True。
+
+        参数: 无额外参数；当前三值结果。
+        返回: 无正常返回；须显式比较Truth成员。
+        异常: TypeError；三值逻辑尚未由普通Python bool表达。
+        """
+        # 对TRUE/FALSE也统一拒绝，避免逻辑分支误用枚举默认真值。
+        raise TypeError("Truth不能隐式转bool，请显式处理TRUE/FALSE/UNKNOWN")
+
+
+class QualityFlag(IntFlag, boundary=FlagBoundary.STRICT):
+    """用固定整数位保存样本无效或质量受限的原因。
+
+    多个原因可以组合；基础策略拒绝所有非零位。NONE表示没有记录原因，
+    仍需结合valid判断有效性。最高位为256，数组至少需要16位保存全部标志；
+    构造时拒绝负值和未知位。
+    """
+
+    NONE = 0  # 没有已记录原因，不证明来源能力完整。
+    MISSING = 1  # 缺少所需观测。
+    STALE = 2  # 观测超过有效期。
+    DECODE_ERROR = 4  # 来源解析或解码失败。
+    NONFINITE = 8  # 数值NaN或无穷。
+    OUT_OF_RANGE = 16  # 超过明确业务范围。
+    ESTIMATED = 32  # 显式估计值，首版基础策略也禁止。
+    OVERFLOW = 64  # 定宽运算上溢或下溢，回绕结果不能作为有效值。
+    PRECISION_LOSS = 128  # 不能精确表示的数值转换。
+    DOMAIN_ERROR = 256  # 除零等值域错误。
+
+    @classmethod
+    def _missing_(cls, value):
+        """检查候选质量位值，再由标准库构造合法的位组合。
+
+        参数:
+            value: 没有对应单一成员的候选位值；合法组合必须是非负整数。
+        返回:
+            QualityFlag或None: 合法组合由IntFlag构造；其他输入遵循标准库协议。
+        异常:
+            ValueError: 候选值为负数、包含未知位或不能构造为合法质量值。
+        """
+        # STRICT仍会归一化负值；须在该标准库过程之前显式拒绝。
+        if isinstance(value, int) and value < 0:
+            # -512不能被隐藏为NONE，非法原因不进入有效模型。
+            raise ValueError("quality mask必须非负")
+        # 非负已知组合沿用标准位构造，未知正位由STRICT拒绝。
+        return super()._missing_(value)
+
+
+class SignalDType(Enum):
+    """声明信号值的逻辑类型，供模型和数值运算检查使用。
+
+    整数明确分为int64和uint64，浮点使用float64。bool独立于整数，enum使用
+    显式标签域；类型不会根据Python继承关系或NumPy自动类型提升推断。
+    """
+
+    INT64 = "int64"  # 有符号64位整数。
+    UINT64 = "uint64"  # 无符号64位整数。
+    FLOAT64 = "float64"  # 有限双精度浮点，不隐式转大整数。
+    BOOL = "bool"  # 明确布尔值，不按任意数值的Python真值判断。
+    ENUM = "enum"  # 显式枚举标签，不参与一般数值运算。
+
+
+class TimeType(Enum):
+    """区分相对来源坐标和UTC绝对坐标，保留显式起点依据。
+
+    不读取机器时区，不自动把相对0当作UTC epoch。
+    """
+
+    RELATIVE = "relative"  # 需要来源声明origin。
+    ABSOLUTE = "absolute"  # 已规范化UTC epoch纳秒。
+
+
+class SourceType(Enum):
+    """标明当前内存模型接受的数据来源种类。
+
+    MEMORY表示调用者直接提供已转换为纳秒的内存行。本枚举没有可变注册表，
+    不会因为声明一个外部来源名称就自动读取或解码该来源。
+    """
+
+    MEMORY = "memory"  # 已声明纳秒的内存行，不执行旧读写或解码。

chronaxis/core/units.py

@@ -0,0 +1,81 @@
+"""检查信号声明的线性单位转换是否与已知单位关系一致。
+
+输入为原单位、目标单位、scale、offset和方向因子；输出verified或unverified。
+已知单位用精确分数核对倍率，未知单位保留未校验状态。本模块检查转换声明，
+不转换样本值，也不推断物理方向。仅依赖标准库，没有文件操作或会话状态；
+温度和复杂量纲不在当前单位表中。
+"""
+
+# 分数用于校验声明系数，避免0.001的二进制近似误报配置冲突。
+from fractions import Fraction
+from math import isfinite
+# 单位表不可由调用者原地修改，否则已编译转换身份会失去依据。
+from types import MappingProxyType
+
+# 每项为物理类别及相对于该类别基准的精确倍率；不据名称推测方向。
+UNIT_TABLE = MappingProxyType({"1": ("dimensionless", Fraction(1)), "V": ("voltage", Fraction(1)),
+              "mV": ("voltage", Fraction(1, 1000)), "A": ("current", Fraction(1)),
+              "mA": ("current", Fraction(1, 1000)), "W": ("power", Fraction(1)),
+              "kW": ("power", Fraction(1000)), "J": ("energy", Fraction(1)),
+              "Wh": ("energy", Fraction(3600)), "kWh": ("energy", Fraction(3600000)),
+              "s": ("time", Fraction(1)), "ms": ("time", Fraction(1, 1000)),
+              "Ah": ("charge", Fraction(3600)), "A·s": ("charge", Fraction(1))})
+
+
+def require_number(value: int | float, field: str) -> int | float:
+    """要求有限原生数值，拒绝bool及未经声明的隐式标量转换。
+
+    参数: value为原生int或有限float；field用于诊断位置。
+    返回: 原数值，不改变整数精度。
+    异常: TypeError为其他类型；ValueError为非有限float。
+    """
+    # bool不能作为工程转换系数或范围端点。
+    if type(value) not in (int, float):
+        # 配置层负责显式解析，不从任意对象取数值。
+        raise TypeError(f"{field}必须为原生int或float")
+    # 无界int本身有限，不能先转float造成伪溢出。
+    if type(value) is float and not isfinite(value):
+        # 非有限系数会污染全部输入，在执行前拒绝。
+        raise ValueError(f"{field}必须有限")
+    # 返回原值供精确配置和后续数值层使用。
+    return value
+
+
+def validate_conversion(input_unit: str, unit: str, scale: int | float,
+                        offset: int | float, direction_factor: int) -> str:
+    """核对已知单位的转换系数，无法识别单位时返回unverified。
+
+    参数:
+        input_unit (str): 已校验的非空原单位标签。
+        unit (str): 已校验的非空目标单位标签。
+        scale (int | float): 显式倍率，必须已经包含direction_factor。
+        offset (int | float): 显式偏移；已知单位的当前转换只接受0。
+        direction_factor (int): 已声明的1或-1，表示方向保持或反转。
+    返回:
+        str: 已知单位关系通过时为verified，任一单位未知时为unverified。
+        函数不会补全系数、推断方向或执行样本转换。
+    异常:
+        ValueError: 已知单位量纲不兼容，倍率不符合单位关系，或偏移不为0。
+    """
+    # 未知标签只能按显式声明使用，不能宣称量纲校验成功。
+    if input_unit not in UNIT_TABLE or unit not in UNIT_TABLE:
+        # 同名未知标签也不冒充已知单位。
+        return "unverified"
+    # 同维度单位才存在首版线性单位换算。
+    input_dimension, input_factor = UNIT_TABLE[input_unit]
+    # 目标倍率与输入同样使用精确分数。
+    output_dimension, output_factor = UNIT_TABLE[unit]
+    # 不把电压等不同物理量以一个scale伪装成相同。
+    if input_dimension != output_dimension:
+        # 编译前明确拒绝单位冲突。
+        raise ValueError(f"已知单位不兼容：{input_unit}→{unit}")
+    # 用户声明的scale须已经包含显式方向因子。
+    expected = input_factor / output_factor * direction_factor
+    # 十进制精确倍率或精确倍率唯一的float64舍入值均合法，不放宽任意容差。
+    matches = Fraction(str(scale)) == expected or (type(scale) is float and scale == float(expected))
+    # 非终止倍率如J→Wh允许标准float64表示；实际样本仍由数值层检查精度损失和质量原因。
+    if not matches or offset != 0:
+        # 不自动修正错误系数或再次施加DBC缩放。
+        raise ValueError(f"已知单位转换需要scale={expected}、offset=0")
+    # 这里只证明单位关系，尚不证明预设角色或样本数值有效。
+    return "verified"