chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/execution/record_point_buffer.py

@@ -0,0 +1,101 @@
+"""共享有限驱动点的接收与失效处理，不执行数值统计或创建历史。
+
+积分和时间统计沿用同一同刻/递增/条件门槛，具体owner负责预付缓冲费用并实现_flush。
+该内部基类不能独立构造使用；没有独立预算或第二份输入缓冲。
+"""
+
+from ..core.numeric import ScalarValue
+from ..core.types import SignalDType as D
+from ..results.errors import ResultClosedError
+from ..timebase.conversion import require_int64_ns
+
+
+class RecordPointBuffer:
+    """复用一份有限点缓冲，子类初始化字段并拥有数值状态及关闭过程。"""
+
+    def _require_open(self):
+        """失败/清理/关闭后拒绝读取与推进。参数: 无。返回: None。异常: ResultClosedError。"""
+        if self._closed or self._closing or self._failed:
+            raise ResultClosedError('记录流统计已关闭、失败或正在清理')
+
+    def consume(self, rows, *, conditions=None, condition_valid_until_ns=None, actual_value_updates=None):
+        """接收已按所选驱动求值的有限点，不先截掉窗口两侧记录。
+
+        参数: rows为不超过batch_intervals+1的tuple，每项(time_ns, ScalarValue)，
+            或附第三项实际有效截止valid_until_ns；到截止即失效，None表示本点无额外截止。
+            conditioned时另传同长conditions及可选实际条件截止tuple；TRUE/FALSE/UNKNOWN分开处理。
+            actual_value_updates仅样本统计/选择使用，明确区分真实值更新与条件更新，不提供时保持原五字段缓冲。
+        返回: None。异常: 类型、时间倒退/同刻、预算/取消；任何错误后不交付前缀结果。
+        约束: 上游处理同刻、条件及TTL；无效值必须传入，不能跳过后连接有效值。
+        """
+        self._require_open()
+        if self._finished:
+            raise ResultClosedError('记录流统计已结束，不能继续追加')
+        item = value = None
+        try:
+            if type(rows) is not tuple or len(rows) > self._limit + 1:
+                raise ValueError('驱动点需要不超批上限的tuple')
+            if actual_value_updates is not None and (type(actual_value_updates) is not tuple
+                    or len(actual_value_updates)!=len(rows) or any(type(flag) is not bool for flag in actual_value_updates)):
+                raise ValueError('真实更新标志需要同长bool tuple')
+            if self._conditioned:
+                if type(conditions) is not tuple or len(conditions) != len(rows):
+                    raise ValueError('条件统计需要同长BOOL条件tuple')
+                if condition_valid_until_ns is not None and (type(condition_valid_until_ns) is not tuple
+                        or len(condition_valid_until_ns) != len(rows)):
+                    raise ValueError('条件截止需要同长tuple')
+            elif conditions is not None or condition_valid_until_ns is not None:
+                raise ValueError('无条件统计不能隐式接入条件')
+            for index, item in enumerate(rows):
+                if type(item) is not tuple or len(item) not in (2, 3):
+                    raise TypeError('驱动点需要时间、数值及可选实际有效截止')
+                time, value = item[:2]
+                deadline = item[2] if len(item) == 3 else None
+                if deadline is not None:
+                    deadline = require_int64_ns(deadline, 'record_calculation.valid_until_ns')
+                time = require_int64_ns(time, 'record_calculation.time_ns')
+                if not isinstance(value, ScalarValue) or value.dtype is not self._dtype:
+                    raise TypeError('驱动点数值与声明dtype不同')
+                if self._last_time is not None and time <= self._last_time:
+                    raise ValueError('驱动点必须严格递增；同刻更新应先按既有政策归组')
+                condition = conditions[index] if self._conditioned else None
+                condition_deadline = None if condition_valid_until_ns is None else condition_valid_until_ns[index]
+                if self._conditioned and (not isinstance(condition, ScalarValue) or condition.dtype is not D.BOOL):
+                    raise TypeError('统计选择条件需要BOOL ScalarValue')
+                if condition_deadline is not None:
+                    condition_deadline = require_int64_ns(condition_deadline, 'record_calculation.condition_valid_until_ns')
+                # 只保计算必需的冻结数值与实际时间，不留下原消息或来源对象。
+                self._rows.append((time, value, deadline, condition, condition_deadline)
+                    +(() if actual_value_updates is None else (actual_value_updates[index],)))
+                self._last_time = time
+                if len(self._rows) == self._limit + 1:
+                    self._flush()
+        except BaseException:
+            self._failed = True
+            raise
+        finally:
+            rows = item = value = conditions = condition = condition_valid_until_ns = None
+
+    def expire_at(self, time_ns, *, condition=False):
+        """依赖中途失效时截断最后待结算驱动点，不新增驱动点或补计周期。
+
+        参数: time_ns为已按序处理的失效实际时刻；condition=True只截断选择条件。返回: None。
+        异常: 非法/回退时间或对象关闭失败；调用方必须在下一驱动点进入前通知。
+        """
+        self._require_open()
+        if self._finished:
+            raise ResultClosedError('记录流统计已结束，不能修改有效截止')
+        try:
+            if type(condition) is not bool or condition and not self._conditioned:
+                raise ValueError('条件失效通知只能用于条件统计')
+            time = require_int64_ns(time_ns, 'record_calculation.expire_at')
+            if self._last_time is not None and time < self._last_time:
+                raise ValueError('失效通知不能回退到已处理驱动点之前')
+            if self._rows:
+                index = 4 if condition else 2
+                previous = self._rows[-1]
+                deadline = previous[index]
+                self._rows[-1] = previous[:index] + (time if deadline is None else min(time, deadline),) + previous[index+1:]
+        except BaseException:
+            self._failed = True
+            raise

chronaxis/execution/record_rule_timeline.py

@@ -0,0 +1,344 @@
+"""用最新必要信号在线推进一条规则，不保存输入历史或第二时间轴。
+
+只暂留一个完整条件组，等下一组或真实EOF确定其是否为末点。实际模式调度
+必要TTL和规则截止；记录周期模式只在选定驱动更新时增加等待量。输出直接
+交调用方结果消费者，输入/共享状态和结果仓不归本对象所有。
+"""
+
+from dataclasses import replace
+from ..core.temporal import ConditionTick, TemporalRule
+from ..core.types import Truth as T, QualityFlag as Q
+from ..results.errors import ResultClosedError
+from ..results.spool import _reserve_owned_ram, _release_owned_ram, _cleanup_owner
+from .driver_expression import DriverExpression
+from .temporal_buffer import BudgetedTemporalDetector
+from .history import _metadata_bytes
+from .record_alarm_duration import RecordAlarmDuration
+from .record_delta_condition import RecordDeltaCondition
+
+
+class RecordRuleTimeline:
+    """拥有规则表达式、检测器和一个待定条件组；原始组由父会话原子提交。"""
+
+    def __init__(self,plan,request,state,budget,step_ns,driver,observation_ends,consumer,step_consumer=None):
+        """建立有限声明，不读来源，也不把请求域当作已观测范围。
+
+        参数: plan/request同计划规则、state共享最新值、budget共享预算、step_ns
+            为None或周期，driver为所选别名，observation_ends借用EOF终点，consumer接事件。
+        返回: 新owner。异常: 原构造错误附record_rule_cleanup_owner。
+        """
+        self._plan,self._request,self._state,self._budget=plan,request,state,budget
+        self._step,self._driver,self._ends,self._consumer=step_ns,driver,observation_ends,consumer
+        self._step_consumer=step_consumer
+        self._held_cost=self._fixed_cost=0
+        self._expressions=[]
+        self._detector=self._pending_owner=self._batch=None
+        self._alarm=self._delta=None
+        self._delta_emitted=False
+        # 常量大小的业务概况，不保留条件轨迹；关闭仍由原固定预算负责。
+        self._seen_true=self._seen_false=self._seen_unknown=False
+        self._event_count=0
+        self._pending=None
+        self._next_expiry=self._last_driver=None
+        self._start=None
+        self._end=plan.dataset.domain.end_ns
+        self._full_domain=not plan.dataset.domain_explicit
+        self._closed=self._closing=self._failed=self._finished=False
+        try:
+            _reserve_owned_ram(self,131584+32*_metadata_bytes(request),'_fixed_cost')
+            for expression in request.expressions:
+                try:
+                    owner=DriverExpression(expression,state,None,backend=plan.execution.backend,
+                        derived=tuple(item.definition for item in plan.derived),observation_ends=observation_ends)
+                except BaseException as error:
+                    self._pending_owner=getattr(error,'driver_expression_cleanup_owner',None)
+                    raise
+                self._expressions.append(owner)
+            if request.rule_type=='window_delta':
+                try:
+                    self._delta=RecordDeltaCondition(budget,request.window_delta,
+                        request.condition.root.dtype,plan.execution.backend,step_ns)
+                except BaseException as error:
+                    self._delta=getattr(error,'record_delta_cleanup_owner',None)
+                    raise
+            self.sources=frozenset(state.definitions[name].source for name in
+                set(request.dependencies)|({driver} if driver else set()))
+            if not self.sources:
+                self.sources=frozenset(source.name for source in plan.sources)
+            if request.stability is not None and request.stability.track_duration:
+                try:
+                    self._alarm=RecordAlarmDuration(budget,step_ns,plan.execution.backend,plan.dataset.domain)
+                except BaseException as error:
+                    self._alarm=getattr(error,'record_alarm_cleanup_owner',None)
+                    raise
+        except BaseException as error:
+            _cleanup_owner(self,error,'record_rule_cleanup_owner','在线规则构造')
+            raise
+
+    def extend_observation(self, end_ns):
+        """更新单遍读取已见的末端；最后条件组仍等待后继或EOF。参数: 实际末端。返回: None。异常: 回退。"""
+        if not self._full_domain or self._finished:
+            return
+        self._end=end_ns
+        if self._detector is not None:
+            self._detector.extend_observed_end(end_ns)
+        if self._alarm is not None:
+            self._alarm._window=self._plan.dataset.domain
+
+    def _open(self):
+        """拒绝失效实例。参数: 无。返回: None。异常: ResultClosedError。"""
+        if self._closed or self._closing or self._failed:
+            raise ResultClosedError('在线规则已关闭或失败')
+
+    def begin(self,observed_start):
+        """用实际观察起点建立检测器，空来源由父跳过。
+
+        参数: observed_start实际首端。返回: None。异常: 构造/范围错误附可清理owner。
+        """
+        self._open()
+        if self._start is not None:
+            raise ValueError('在线规则不能重复开始')
+        start=max(observed_start,self._plan.dataset.domain.start_ns)
+        if start>self._end:
+            self._finished=True
+            return
+        request=self._request
+        rule=TemporalRule(request.rule_id,self._plan.dataset.dataset_id,self._plan.dataset.session_id,
+            request.temporal_rule_type,request.minimum_duration_ns or 0,request.emit_initial,request.window_duration_ns or 0,
+            duration_comparison=request.duration_comparison)
+        try:
+            self._detector=BudgetedTemporalDetector(self._budget,rule,start,self._end,
+                backend=self._plan.execution.backend,
+                stability=replace(request.stability,track_duration=False) if self._alarm is not None else request.stability,
+                start_end=request.start_end,
+                record_clock=self._step is not None)
+            self._start=start
+        except BaseException as error:
+            self._detector=getattr(error,'temporal_detector_cleanup_owner',None)
+            self._failed=True
+            error.record_rule_cleanup_owner=self
+            raise
+
+    def _snapshot(self,time_ns,actual,terminal=False):
+        """收齐进出条件的点/右侧值，保一个必要组。参数: 实际时间/更新/EOF。返回: None。异常: 求值原错。"""
+        ticks=[]
+        deadlines=[]
+        actual_names={name for name in self._request.dependencies if
+            self._state.get(name) is not None and self._state.get(name).time_ns==time_ns} if actual else set()
+        selected=self._state.get(self._driver) if self._driver else None
+        is_driver=actual and selected is not None and selected.time_ns==time_ns
+        for expression in self._expressions:
+            point,_=expression.evaluate_at(time_ns,continuous=False)
+            right,deadline=expression.evaluate_at(time_ns)
+            if self._delta is not None:
+                point,right=self._delta.update(time_ns,point,right,deadline,driver=is_driver)
+                deadline=self._delta.next_deadline
+            point_state=T.TRUE if point.valid and point.value else T.FALSE if point.valid else T.UNKNOWN
+            right_state=T.TRUE if right.valid and right.value else T.FALSE if right.valid else T.UNKNOWN
+            point_quality=Q.NONE if point.valid else point.quality
+            quality=Q.NONE if right.valid else right.quality
+            observed_end=any(self._ends.get(source)==time_ns for source in self.sources)
+            updated=self._delta is not None or bool(actual_names & set(expression._static.dependencies))
+            ticks.append(ConditionTick(time_ns,T.UNKNOWN if terminal else right_state,
+                quality|Q.MISSING if terminal else quality,actual_update=updated,
+                observation_end=observed_end,terminal=terminal,point_state=point_state,point_quality=point_quality,
+                actual_unknown=updated and not point.valid,diagnostic_quality=point.quality|right.quality))
+            if deadline is not None:
+                deadlines.append(deadline)
+        advance=None
+        is_driver=False
+        if self._step is not None:
+            selected=self._state.get(self._driver)
+            is_driver=actual and selected is not None and selected.time_ns==time_ns
+            advance=self._step if is_driver and self._last_driver is not None else 0
+            if is_driver:
+                self._last_driver=time_ns
+        self._pending=(tuple(ticks),advance,is_driver)
+        self._next_expiry=min(deadlines) if deadlines else None
+
+    def _commit(self):
+        """交付一个完整条件组和增量事件，消费失败不返回前缀。参数: 无。返回: None。异常: 原错。"""
+        ticks,advance,driver=self._pending
+        self._batch=self._detector.push((ticks[0],),None if len(ticks)==1 else (ticks[1],),
+            advances=None if advance is None else (advance,))
+        events=self._batch.events
+        if self._delta is not None and self._request.retrigger=='once':
+            if self._delta_emitted:
+                events=()
+            elif events:
+                self._delta_emitted=True
+        # 真实末点可以说明当时条件，但EOF人为补出的UNKNOWN不算数据缺口。
+        tick=ticks[0]
+        truths=(tick.point_state,) if tick.terminal else (tick.state,tick.point_state)
+        self._seen_true |= T.TRUE in truths
+        self._seen_false |= T.FALSE in truths
+        self._seen_unknown |= any(T.UNKNOWN in ((item.point_state,) if item.terminal
+                                  else (item.state,item.point_state)) for item in ticks)
+        self._event_count += len(events)
+        primary=None
+        try:
+            if self._alarm is not None:
+                state=T.UNKNOWN if ticks[0].terminal else self._detector._detector.state
+                self._alarm.consume(ticks[0].time_ns,state)
+            if self._step_consumer is not None:
+                self._step_consumer(self._request.rule_id,ticks[0],events)
+            for event in events:
+                self._consumer(event)
+        except BaseException as error:
+            primary=error
+            raise
+        finally:
+            event=ticks=None
+            try:
+                self._batch.close()
+                self._batch=None
+            except BaseException as cleanup:
+                if primary is None:
+                    raise
+                primary.add_note('规则输出批清理失败：'+type(cleanup).__name__)
+        self._pending=None
+
+    def _drain_before(self,time_ns):
+        """只推进已经由后续观测证明存在的区间。参数: 下个实际边界。返回: None。异常: 原推进错。"""
+        if self._pending is None and self._detector._detector.last_time is None and self._start<time_ns:
+            self._snapshot(self._start,False)
+        while True:
+            if self._pending is not None:
+                if self._pending[0][0].time_ns>=time_ns:
+                    return
+                self._commit()
+            next_times=[value for value in (self._next_expiry,self._detector.next_deadline_ns) if value is not None]
+            if not next_times or min(next_times)>=time_ns:
+                return
+            self._snapshot(min(next_times),False)
+
+    def before_group(self,time_ns):
+        """父提交新组前处理旧状态上的TTL和实际等待。参数: 新组时间。返回: None。异常: 原错。"""
+        self._open()
+        if self._finished or self._start is None or time_ns<self._start:
+            return
+        try:
+            if time_ns>self._end:
+                self.finish(self._end)
+            else:
+                self._drain_before(time_ns)
+        except BaseException as error:
+            self._failed=True
+            error.record_rule_cleanup_owner=self
+            raise
+
+    def after_group(self,time_ns):
+        """父原子提交后保存新条件组；实际终点在同刻更新之后结算。
+
+        参数: 新组时间。返回: None。异常: 原求值/事件错误，失败只能关闭。
+        """
+        self._open()
+        if self._finished or self._start is None or time_ns<self._start:
+            return
+        try:
+            terminal=time_ns==self._end and not self._full_domain
+            self._snapshot(time_ns,True,terminal=terminal)
+            if terminal:
+                self._commit()
+                self._batch=self._detector.finish()
+                self._batch.close();self._batch=None
+                self._finished=True
+        except BaseException as error:
+            self._failed=True
+            error.record_rule_cleanup_owner=self
+            raise
+
+    def clock_group(self,group):
+        """待定旧条件已经交付后，接收报警累计所需的完整驱动对。
+
+        参数: 新的真实同刻组。返回: None。异常: 累计顺序/预算错误。
+        不改变事件坐标，也不把请求域外样本算入报警；只借它们确定裁剪分母。
+        """
+        if self._alarm is not None and self._step is not None and any(s.name==self._driver for s in group.samples):
+            self._alarm.driver(group.time_ns)
+
+    def finish(self,observed_end):
+        """所有必要来源EOF后按真实末端封口，不外推到请求结束。
+
+        参数: observed_end必要来源联合末端。返回: None。异常: 原错，未完成不发布结果。
+        """
+        self._open()
+        if self._finished or self._start is None:
+            return
+        try:
+            end=min(observed_end,self._end)
+            if end<self._start:
+                self._finished=True
+                return
+            self._detector.set_observed_end(end)
+            self._end=end
+            self._drain_before(end)
+            if self._pending is not None and self._pending[0][0].time_ns==end:
+                ticks,advance,driver=self._pending
+                self._pending=(tuple(replace(t,terminal=True,state=T.UNKNOWN,quality=t.quality|Q.MISSING) for t in ticks),advance,driver)
+            else:
+                self._snapshot(end,False,terminal=True)
+            self._commit()
+            self._batch=self._detector.finish()
+            self._batch.close();self._batch=None
+            self._finished=True
+        except BaseException as error:
+            self._failed=True
+            error.record_rule_cleanup_owner=self
+            raise
+
+    def outcome(self):
+        """冻结规则结果原因，不读取输入。参数: 无。返回: RuleOutcome。异常: 未完成或已关闭。
+
+        有事件时始终保留计数；缺信号和UNKNOWN不被解释成条件为假。
+        """
+        self._open()
+        if not self._finished and self._start is not None:
+            raise ValueError('规则未结束，不能报告结果概况')
+        from ..results.analysis_outcome import RuleOutcome
+        missing=tuple(name for name in self._request.dependencies if self._state.get(name) is None)
+        # 已产生的事件与未观测/未知事实并存；无事件时才用数据充分性解释原因。
+        if self._event_count:
+            status='events_found'
+        elif self._start is None or missing:
+            status='no_observation'
+        elif self._seen_unknown:
+            status='insufficient_data'
+        elif self._request.rule_type=='condition_duration' and self._seen_true:
+            status='duration_not_met'
+        elif not self._seen_true:
+            status='condition_not_met'
+        else:
+            status='no_event'
+        return RuleOutcome(self._request.rule_id,status,self._event_count,self._seen_unknown,missing)
+
+    @property
+    def duration_result(self):
+        """借出明确请求的最终累计；空来源返回无观测。参数: 无。返回: tuple或None。异常: 未完成错误。"""
+        if self._alarm is None:
+            return None
+        if not self._finished and self._start is not None:
+            raise ValueError('报警尚未完成')
+        return self._alarm.finish()
+
+    @property
+    def closed(self):
+        """返回资源关闭状态。参数: 无。返回: bool。异常: 无。"""
+        return self._closed
+
+    def close(self):
+        """释放自有批、表达式和检测器，保留失败槽供重试。参数: 无。返回: None。异常: 原关闭错。"""
+        if self._closed:
+            return
+        self._closing=True
+        for slot in ('_batch','_pending_owner','_detector','_alarm','_delta'):
+            owner=getattr(self,slot)
+            if owner is not None:
+                owner.close()
+                setattr(self,slot,None)
+        for index,owner in enumerate(self._expressions):
+            if owner is not None:
+                owner.close();self._expressions[index]=None
+        self._pending=self._consumer=self._step_consumer=self._state=self._plan=self._ends=None
+        _release_owned_ram(self,self._fixed_cost,'_fixed_cost')
+        self._closed=True

chronaxis/execution/record_sample.py

@@ -0,0 +1,46 @@
+"""记录流只保一份逻辑值；枚举单独保必要整数码，公共来源定义共享引用。"""
+from dataclasses import dataclass
+from ..core.models import SourceRef,SignalSample
+from ..core.numeric import ScalarValue
+from ..core.types import SignalDType as D
+
+@dataclass(frozen=True,slots=True)
+class RecordSample:
+    """一次规范更新；没有批次副本、原文或普通值的第二份物理表示。"""
+    name: str
+    time_ns: int
+    sequence: int
+    value: ScalarValue
+    unit: str
+    source_ref: SourceRef
+    enum_code: int | None = None
+
+    def __post_init__(self):
+        """检查必要样本及枚举码含义。参数: 字段。返回: None。异常: 类型/值矛盾。"""
+        if type(self.value) is not ScalarValue or type(self.unit) is not str:
+            raise TypeError('记录样本需要规范值和单位')
+        SignalSample(self.name,self.time_ns,self.value.value,self.value.valid,self.value.quality,self.source_ref,self.sequence)
+        if self.value.dtype is D.ENUM:
+            if type(self.enum_code) is not int:
+                raise TypeError('枚举需要保留整数码')
+            if self.value.valid and (not 0<=self.enum_code<len(self.value.labels) or self.value.labels[self.enum_code]!=self.value.value):
+                raise ValueError('枚举码与标签不符')
+        elif self.enum_code is not None:
+            raise ValueError('普通值不保存第二份物理码')
+
+    @property
+    def array_value(self):
+        """按需取得数组值；无效值只返回类型占位。参数: 无。返回: 标量。异常: 无。"""
+        if self.value.dtype is D.ENUM:return self.enum_code
+        if self.value.valid:return self.value.value
+        return False if self.value.dtype is D.BOOL else 0. if self.value.dtype is D.FLOAT64 else 0
+
+    @property
+    def original_present(self):
+        """本样本不保存原文。参数: 无。返回: False。异常: 无。"""
+        return False
+
+    @property
+    def original_value(self):
+        """本样本无额外原值。参数: 无。返回: None。异常: 无。"""
+        return None

chronaxis/execution/record_sample_series.py

@@ -0,0 +1,29 @@
+"""把一小批实际记录及有效截止交给既有样本统计/选择核。
+
+只在当前批插入必要的失效边界，不保存另一条时间轴；这些边界的真实更新标志为False。
+半开范围及共享右端由原CalculationSeries/CalculationDefinition处理，不把保持值当作新样本。
+"""
+from ..core.calculations import CalculationSeries
+from ..core.models import Interval
+from ..core.numeric import ScalarValue
+from ..core.types import QualityFlag as Q
+
+
+def sample_series(rows,unit,conditioned):
+    """构造有界核输入。参数: 至少两点的内部行/单位/条件开关。返回: CalculationSeries。异常: 类型/时间错误。"""
+    times=[];values=[];conditions=[];updates=[]
+    for index,row in enumerate(rows):
+        time,value,deadline,condition,condition_end=row[:5]
+        end=rows[index+1][0] if index+1<len(rows) else time
+        # 每对最多两个不同过期点；不插入计算所选固定周期的虚构时刻。
+        points=(time,*sorted({d for d in (deadline,condition_end) if d is not None and time<d<end}))
+        for point in points:
+            times.append(point)
+            values.append(ScalarValue(None,value.dtype,False,value.quality|Q.STALE,value.labels)
+                if deadline is not None and point>=deadline and point<end else value)
+            if conditioned:
+                conditions.append(ScalarValue(None,condition.dtype,False,condition.quality|Q.STALE,condition.labels)
+                    if condition_end is not None and point>=condition_end and point<end else condition)
+            updates.append(bool(row[5]) if point==time and len(row)>5 else False)
+    return CalculationSeries(Interval(times[0],times[-1]),tuple(times),tuple(values),tuple(updates),unit,
+        conditions=tuple(conditions) if conditioned else None)