chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/guide/tasks.json

@@ -0,0 +1,290 @@
+{
+  "device_label": "home",
+  "revision": 1,
+  "tasks": [
+    {
+      "id": "CAN",
+      "intent": "BLF / ASC 报文积分",
+      "example": "examples/analysis.yaml",
+      "requires": "日志、通道、正确DBC、功率单位和时钟。",
+      "check": "核对 J 及实际观测范围。",
+      "fields": [
+        "sources",
+        "signals",
+        "calculations"
+      ],
+      "templates": [
+        "can-blf",
+        "can-asc"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate examples/analysis.yaml --format json"
+    },
+    {
+      "id": "CONDITION_ENERGY",
+      "intent": "BLF/ASC连续分卷：多条件持续超过门槛，对整个合格区间计算能量积分，输出kWh",
+      "example": "examples/conditional-energy.yaml",
+      "requires": "原始ASC/BLF与对应DBC，目标信号/编码/单位、比较符、持续时长及积分范围。类型/单位/周期能由DBC取得时不要求重复填写。",
+      "applicable": "自定义状态和数值条件、达到或严格超过时长、从条件开始处积分、可选能量单位。示例为strict >60s、默认onset、实际时间间隔。",
+      "not_applicable": "按每条消息固定周期直接求和时，查询message_calculations字段说明；独立文件批量使用BATCH入口。",
+      "alternative": "charge_session只适用于它的严格电流>、持续>=、Wh/Ah及方向/测点契约，不因为名称包含充电就套用。",
+      "check": "60秒整无事件；跨卷61秒区间为[61,122)，4000W×61s/3600000=0.06777777777777777kWh。以parent_id关联event_id，检查status/reason，不能用60.1秒代替严格比较。",
+      "fields": [
+        "sources",
+        "signals",
+        "rules",
+        "calculations"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate examples/conditional-energy.yaml --format json"
+    },
+    {
+      "id": "CSV",
+      "intent": "功率表、实际时间积分",
+      "example": "examples/input-csv-minimal.yaml",
+      "requires": "时间列、单位、功率列和有效期。",
+      "check": "手算38 J。",
+      "fields": [
+        "sources",
+        "signals",
+        "calculations"
+      ],
+      "templates": [
+        "signal-csv"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate examples/input-csv-minimal.yaml --format json"
+    },
+    {
+      "id": "CHARGE",
+      "intent": "充电过程、电量与充电能量",
+      "example": "examples/preset-charge-energy.yaml",
+      "requires": "模式编码、电流正向、端口位置、电压、阈值与持续时间。教学例使用ASC；使用BLF时替换为自己的日志、DBC及绑定。",
+      "check": "核对每个活动起止和Wh/Ah；恰好current_min不参与，恰好minimum_duration合格，起点默认onset。先比对适用条件，不能仅凭充电关键词匹配。",
+      "fields": [
+        "presets",
+        "signals"
+      ],
+      "templates": [
+        "charge-session"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "resolve_preset_roles",
+        "build_preset"
+      ],
+      "verify": "python -m chronaxis validate examples/preset-charge-energy.yaml --format json",
+      "applicable": "模式等于指定整数编码，并且电流严格大于current_min；连续达到minimum_duration后从条件开始处统计；能量输出Wh、电量输出Ah。已确认电流正向为充电及电池包端测点。",
+      "not_applicable": "需要电流>=门槛、严格超过持续时长、直接输出kWh、不同状态组合，或无法确认预设要求的电流方向/测点时，不直接套用charge_session。",
+      "alternative": "转到CONDITION_ENERGY任务及examples/conditional-energy.yaml，用普通condition_duration规则与事件范围integral；原样保留比较符、持续时间比较和输出单位。普通U×I积分不需额外方向/测点或95%覆盖率。"
+    },
+    {
+      "id": "EVENT",
+      "intent": "持续活动、退出合并、事件关联",
+      "example": "examples/window-merged.yaml",
+      "requires": "条件、时间单位、窗口及允许间隔。",
+      "check": "事件边界保留；片段的 parent_event_ids 可以有多个。",
+      "fields": [
+        "rules",
+        "windows"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate examples/window-merged.yaml --format json"
+    },
+    {
+      "id": "ALARM",
+      "intent": "报警上下文、上升沿",
+      "example": "examples/preset-fault-context.yaml",
+      "requires": "明确定义的布尔报警及前后时间。",
+      "check": "点事件与前后文片段分别核对。",
+      "fields": [
+        "presets",
+        "windows"
+      ],
+      "templates": [
+        "fault-window"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate examples/preset-fault-context.yaml --format json"
+    },
+    {
+      "id": "PAIR",
+      "intent": "请求响应、超时、观测不足",
+      "example": "examples/sequence-outcomes.yaml",
+      "requires": "请求与响应来自可比较时钟，最小和最大延迟明确。",
+      "check": "未知观测不能当作确定未响应。",
+      "fields": [
+        "sequences",
+        "rules"
+      ],
+      "templates": [
+        "command-response"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate examples/sequence-outcomes.yaml --format json"
+    },
+    {
+      "id": "ENCODING",
+      "intent": "布尔、枚举、编码与表达式别名",
+      "example": "examples/signal-enum-minimal.yaml",
+      "requires": "设备编码表；未定义编码不能按非零为真处理。",
+      "check": "表达式仅引用绑定名，语义标识不是属性路径。",
+      "fields": [
+        "signals",
+        "derived"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate examples/signal-enum-minimal.yaml --format json"
+    },
+    {
+      "id": "UNITS",
+      "intent": "换算、单位、比例",
+      "example": "examples/signal-number-conversion.yaml",
+      "requires": "输入/输出单位、已有解码缩放和方向声明。",
+      "check": "DBC系数只用一次，单位标签本身不做换算。",
+      "fields": [
+        "signals"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate examples/signal-number-conversion.yaml --format json"
+    },
+    {
+      "id": "QUALITY",
+      "intent": "数据过期、零值、部分结果",
+      "example": "examples/quality.yaml",
+      "requires": "周期或有效期、所需观测范围、缺失策略。",
+      "check": "同时读status/reason/quality与实际值。",
+      "fields": [
+        "signals",
+        "execution",
+        "calculations"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate examples/quality.yaml --format json"
+    },
+    {
+      "id": "BATCH",
+      "intent": "独立任务批量运行",
+      "example": "examples/batch-minimal.yaml",
+      "requires": "每个计划独立输入和输出，不能共享任务状态。",
+      "check": "使用batch run；process_count为正整数，默认1，可用--process-count覆盖。查看batch_report的worker_process_count及逐任务worker_pid。连续分卷应在一个任务的paths内。",
+      "fields": [
+        "jobs",
+        "process_count"
+      ],
+      "templates": [
+        "batch"
+      ],
+      "api": [
+        "load_batch_plan",
+        "run_batch",
+        "BatchReport"
+      ],
+      "verify": "python -m chronaxis batch run examples/batch-minimal.yaml --output new-batch"
+    },
+    {
+      "id": "IMPORT",
+      "intent": "公共定义、字段来源、相对路径",
+      "example": "examples/analysis-imports.yaml",
+      "requires": "主配置与被引用公共定义都须提供。",
+      "check": "用 config origins --fields 核对来源。",
+      "fields": [
+        "imports"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan"
+      ],
+      "verify": "python -m chronaxis validate examples/analysis-imports.yaml --format json"
+    },
+    {
+      "id": "EXPORT",
+      "intent": "输出事件附近的原始报文",
+      "example": "examples/export-can-minimal.yaml",
+      "requires": "受支持的CAN来源、明确窗口和新输出目录。",
+      "check": "核对实际窗口、格式和清单。",
+      "fields": [
+        "outputs",
+        "windows"
+      ],
+      "templates": [
+        "can-export"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate examples/export-can-minimal.yaml --format json"
+    },
+    {
+      "id": "PYTHON",
+      "intent": "Python 加载、写出与关闭",
+      "example": "examples/input-csv-minimal.yaml",
+      "requires": "已安装对应版本、完整计划及新结果目录。",
+      "check": "运行 run_analysis.py；先检查再执行，逐行读后关闭。",
+      "fields": [
+        "outputs"
+      ],
+      "templates": [
+        "signal-csv"
+      ],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner",
+        "AnalysisResult"
+      ],
+      "verify": "python -m chronaxis validate examples/input-csv-minimal.yaml --format json"
+    },
+    {
+      "id": "FIX",
+      "intent": "根据诊断修正配置",
+      "example": "examples/input-csv-minimal.yaml",
+      "requires": "需要用户原意、原文件和真实诊断。",
+      "check": "修字段位置、类型或引用，不删条件或改有效期来消除错误。",
+      "fields": [
+        "config_version"
+      ],
+      "templates": [
+        "signal-csv"
+      ],
+      "api": [
+        "validate_analysis_plan",
+        "explain_analysis_plan",
+        "PlanValidationError"
+      ],
+      "verify": "python -m chronaxis validate examples/input-csv-minimal.yaml --format json"
+    }
+  ]
+}

chronaxis/guide/workflow.md

@@ -0,0 +1,38 @@
+# 从用户输入到结果
+
+|你要做的事|采用的公开入口|结果与边界|
+|---|---|---|
+|接入日志|BLF/ASC＋对应DBC；原始报文CSV需明确报文格式；已解码CSV按表头声明，内存输入用于可控数据|来源、时钟和实体范围属于输入契约。只在证据允许时联合多个来源。|
+|构建分析|单次分析用版本3的YAML/JSON；公共定义复用限一层。读取文件用 load_analysis_plan，构造字典用 AnalysisPlan.from_dict|计划检查引用、类型、单位和时钟；可按需枚举目录或读DBC元数据。原始数据中的业务含义还未验证。|
+|选择计算|用已绑定名称定义条件、派生表达式、规则、窗口和 calculations；逐消息累计另走 message_calculations|真实活动与片段可单独统计；积分方法、时间间隔与质量影响结果。|
+|使用业务预设|在完整计划的 presets 中声明角色和参数；Python 构建预设返回 PlanFragment|预设展开为普通声明，角色校验不替你确定工程阈值；片段不是完整计划。|
+|先解释再运行|validate_analysis_plan / explain_analysis_plan；AnalysisRunner.run|解释看到依赖、时间需求和预算，并非已经读取了那么多数据。run 在真实输入上计算，返回 AnalysisResult。|
+|读取或交付|在 AnalysisResult 上流式迭代，并在结束或提前退出时关游标；write 发布到新目录，最后关闭结果|关联键和质量以各结果行类型为准，空值不等于零。发布失败不能报告已交付。|
+|独立批量|load_batch_plan、run_batch 或 python -m chronaxis batch run|每个子任务独立；正常返回仍要读各项状态。不是把一个有状态会话切成多任务。|
+
+本版正式输出发布的环境证据限于 Windows / Python 3.12。支持的旧格式、通道、导出及 profile 仍有条件；缺支持时保留 validate/explain 给出的能力限制，不承诺任意旧链可用。示例里的数值是合成数据，平台、预算、速度和真实业务判断应分别验证。
+
+## 写配置前保留用户原意
+
+先把用户已给出的条件对应到配置，不要求用户重新确认已有信息。以下例子来自“状态为 `0x2`、电流至少 `10A`，连续超过 `60s` 的区间内，积分电流乘电压，结果为 `kWh`”：
+
+|需要保留的内容|配置与处理方式|
+|---|---|
+|信号与表达式|分别绑定 `BMS_ChrgSta`、`BMS_BatPackActCur`、`BMS_BatPackActVol`；计算电流乘电压，不换成其他测点的信号。|
+|每个比较符与逻辑关系|条件为 `state == 0x2 and current >= 10`，别名分别指向上述状态和电流；保留等号、包含边界的 `>=` 和“且”。|
+|连续超过60秒|使用 `condition_duration`、`minimum_duration: 60s`、`duration_comparison: ">"`。恰好60秒不合格；不能把阈值改为60.1秒，也不能只筛选每一帧而省略连续时长。|
+|积分起点与结束|“合格区间内”采用默认 `selection_origin: onset`，从条件开始成立处累计到区间结束；不擅自丢掉前60秒。只有用户明确要求从持续确认之后算，才改用 `confirmed`。|
+|单位|按DBC或已有定义核对电流为A、电压为V，计算项输出 `kWh`；不要把J或Wh的数值直接标成kWh。|
+|文件关系和计时依据|连续分卷放在同一来源，状态跨文件延续；独立任务才使用批量入口。沿用已确定的实际间隔或固定/DBC周期，不用修改文件时间代替正确配置。|
+
+别名可由配置取简短名称，但说明应给出别名对应的原信号。优先从输入、DBC、匹配的任务示例和已给出的要求取得事实；仅在仍缺少且会改变结果时确认，例如多个候选信号无法唯一匹配，或无法判断文件是连续分卷还是独立实验。支持的默认值直接采用并在必要处说明，不把每个可选字段都变成问题。
+
+普通表达式积分不要求补充业务预设才使用的电流方向、测量位置等领域元数据。用户已指定原始电流比较和乘积时，不为了给结果命名为“充电”或“放电”而另加正负号转换；只有任务确实需要这种业务解释、且现有信息不足时才确认。
+
+## 报错修复与核验范围
+
+安装失败、缺依赖、路径或字段错误只修对应原因；保持上表中的信号、条件、持续门槛、积分起点和单位。不能为使程序跑通而增加方向/测点限制、`95%`覆盖率门槛、额外最小值/最大值统计，或调整有效期、阈值和计时方式。原始时间倒退等数据错误也不能自动排序、去重、过滤或重写输入；先给出真实诊断，确需处理数据时说明处理对结果的影响。
+
+只执行本任务需要的读取、计算和交付。安装与公开入口校验通过后运行所需分析；用户未请求、计算也不需要的贡献明细、追溯、原帧副本、额外统计或重复扫描，不构造、不扫描、不保存、不输出。无事件或空结果按实际诊断解释，不自动放宽条件重跑。
+
+独立核验按本次验证目标选用，不是每次普通运行的前置要求。若使用另写的脚本，说明它是否保留原始顺序、如何处理信号有效期（TTL）、无效更新、区间边界，以及核对了哪些文件、信号和输出。例如“按时间排序并一直沿用最近电压”的脚本，与“保留原序且电压过期后无效”的正式分析不等价；不能仅凭总能量相近就称整项功能已验证。核验只覆盖积分数值时，不扩称已验证事件筛选、跨文件状态和全部质量规则；有差异先定位原因，不改业务条件去迎合核验值。

chronaxis/legacy/__init__.py

@@ -0,0 +1,46 @@
+"""公开旧CAN记录，以及按需加载的记录仓、逐次模型与贡献累计原语。
+
+输入输出和wire边界由records统一；实际进程由调用方显式创建，worker只在INIT后
+加载vendor。包导入无输入/DBC读取、logger配置或子进程副作用；不代表旧reader关闭
+缺陷已修复。单BLF公共AnalysisRunner和原始片段已在其任务中验收；独立逐次模型及累计
+只接收调用方提供的记录和已求值贡献，不证明表达式、旧ChrgInfo出口或公共
+legacy_sum来源已经接通。原语不替输入提供者补缓存、施加TTL或重新解码。
+解码记录仓只在显式构造后写入新目录，保存现有合法记录，不扩大原IPC值类型。
+"""
+
+# 只公开标准库冻结模型；不能在包入口急切导入worker的运行依赖。
+from .records import (LegacyCANField, LegacyCANRequest, LegacyDecodedFrame, LegacyRawFrame,
+    StoredRawFrame, MAX_WIRE_BYTES, PROFILE_ID, decoded_from_dict, decoded_to_dict, decode_packet,
+    encode_packet, field_from_dict, field_to_dict, frame_from_dict, frame_to_dict)
+
+__all__ = ('LegacyCANField', 'LegacyCANRequest', 'LegacyDecodedFrame', 'LegacyRawFrame',
+    'StoredRawFrame', 'MAX_WIRE_BYTES', 'PROFILE_ID', 'decoded_from_dict', 'decoded_to_dict',
+    'decode_packet', 'encode_packet', 'field_from_dict', 'field_to_dict', 'frame_from_dict', 'frame_to_dict',
+    'LegacyDecodedUpdate', 'LegacyUpdateOrder', 'LegacySkipReason', 'LegacySumContribution',
+    'LegacySumSnapshot', 'LegacySumAccumulator', 'StoredDecodedMessage', 'DecodedMessageStore',
+    'MAX_DECODED_MESSAGE_ROW_BYTES')
+
+
+def __getattr__(name):
+    """按需公开独立模型、记录仓与累计，保持原CAN worker的轻量导入。
+
+    参数: name为请求的模块属性名。返回: 已实现模型类本身，不创建输入或状态。
+    异常: AttributeError为未公开名称；模型模块导入错误原样传播。
+    副作用: 仅访问明确名称时导入其模型或累计模块，不读取日志或DBC；
+        NumPy仅在调用者实际选择数组累计后加载。
+    """
+    # 已有CAN记录保持直接导出；未知名称不触发额外导入或提供占位实现。
+    if name in ('LegacyDecodedUpdate', 'LegacyUpdateOrder'):
+        from .updates import LegacyDecodedUpdate, LegacyUpdateOrder
+        return {'LegacyDecodedUpdate': LegacyDecodedUpdate, 'LegacyUpdateOrder': LegacyUpdateOrder}[name]
+    # 累计定义只需标准库及已有预算协议，数组内核由实际执行入口另行加载。
+    if name in ('LegacySkipReason', 'LegacySumContribution', 'LegacySumSnapshot', 'LegacySumAccumulator'):
+        from .sum import LegacySkipReason, LegacySumContribution, LegacySumSnapshot, LegacySumAccumulator
+        return {'LegacySkipReason': LegacySkipReason, 'LegacySumContribution': LegacySumContribution,
+                'LegacySumSnapshot': LegacySumSnapshot, 'LegacySumAccumulator': LegacySumAccumulator}[name]
+    # 请求仓类型只加载定义；目录创建、编码写入和资源预留都由显式实例负责。
+    if name in ('StoredDecodedMessage', 'DecodedMessageStore', 'MAX_DECODED_MESSAGE_ROW_BYTES'):
+        from .message_store import StoredDecodedMessage, DecodedMessageStore, MAX_DECODED_MESSAGE_ROW_BYTES
+        return {'StoredDecodedMessage': StoredDecodedMessage, 'DecodedMessageStore': DecodedMessageStore,
+                'MAX_DECODED_MESSAGE_ROW_BYTES': MAX_DECODED_MESSAGE_ROW_BYTES}[name]
+    raise AttributeError(f'chronaxis.legacy没有公开属性{name!r}')