chronaxis 0.1.0.dev0__py3-none-any.whl

chronaxis/guide/en/semantics.md

@@ -0,0 +1,70 @@
+<a id="先决定什么能算再生成配置"></a>
+# Establish what can be calculated before generating configuration
+
+| Task | Facts to establish | How to decide |
+|---|---|---|
+| Identify inputs | BLF/ASC logs, DBC, channel, message, and signal; actual CSV headers and time units. | Joint analysis of different clocks needs a common origin, offset, or other explicit synchronization evidence. Both files starting at zero is insufficient. |
+| Bind names | Locate the original input field. `name` is its analysis name; `semantic_id` is optional business metadata. | If `BMS_I` is bound as `pack_current` with semantic ID `battery.current`, write `pack_current > 5`. A dotted semantic ID is not an object attribute. Require an explicit choice when multiple candidates match. |
+| Units and direction | Existing DBC conversion, physical unit, positive direction, and measurement point. | Converting decoded 2000 mA to 2 A needs only the additional unit conversion. Unit labels and `sign_convention` do not change values. There is no public `direction_factor`; same-unit `scale=-1` is not a general sign-flip mechanism. |
+| State codes | The business meaning of each code. | Whether 2 means charging depends on the equipment. Preserve numeric types for a user-supplied comparison such as `state == 0x2`. Use Boolean/enumeration mappings only when true/false or named states are needed. Unknown mapping codes do not mean nonzero=true. Without definitions, identify the missing facts rather than claiming a production-ready charging detector. |
+| Validity | `valid_for` is a positive duration. An explicit value wins; otherwise use three times this signal's `period`, obtaining a DBC message period at runtime where applicable. Do not guess without a basis. Explicit null is not omission. | With an update at 0 and `period=100ms`, the value remains valid at 0.299 s and becomes unknown at 0.300 s. An invalid update at 0.2 s makes it unknown from 0.2 s. Validity does not set a sample rate or create records. |
+| Conditions and statistics | Requested range, observed range, selected data, and `partial_policy`. | A fully observed, known-false condition may yield zero conditional integral. Minimum/maximum/mean of an empty selection are null. No observations or all-unknown input must not become a normal zero. Explain partial values together with `status`, `reason`, and `quality`. |
+| Events and segments | Two activities can merge into one surrounding segment without making their gap an activity. | `segments.parent_event_ids` may reference several `events.event_id` values in the same run. Link calculations using `scope` and `parent_id`, not row number or rule name alone. |
+| Timing and output | Batch size changes execution chunks only. Unknown response differs from decidable timeout. Actual-time integration differs from per-message accumulation. | Inspect dependencies, intervals, output units, and requested ranges in `explain`. `coverage_status` exists only for applicable result types and thresholds; it is not a numerical coverage ratio. Do not invent a `coverage` field. |
+| Business presets | Charging, for example, needs `mode`/`current` and `voltage` when energy is requested. Direction, units, and measurement point must meet role requirements. | Missing facts or two matching candidates do not authorize choosing the first. Explicit bindings still undergo role validation. Example thresholds and codes do not transfer automatically to another vehicle. |
+
+<a id="从报告定位错误"></a>
+## Diagnose using actual reports
+
+Record the user's required signals, conditions, scope, and outputs first. Request JSON from `validate`. For a constructed plan, inspect `valid`, `execution_ready`, `errors`, `warnings`, and `capability_status`. For loading failure, use the actual fields supplied in the single `error`, such as `code`, `source`, `path`, `line`, `column`, `message`, and `hint`. In `explain`, the validation report is under `validation`, with dependencies under `nodes` and `input_requirements`. Environment, I/O, or argument errors may produce only a nonzero exit code and stderr; missing JSON does not mean success.
+
+For example, string `config_version: "3"` is rejected. Change only that value to integer 3, preserve the calculation, and recheck. Do not remove a filter, extend validity, ignore unknown data, or reverse a sign to “fix” a diagnostic. If two correction rounds still fail, report the real error and unresolved facts rather than fabricate runnable output.
+
+```text
+python -m chronaxis config origins ../examples/analysis-imports.yaml --fields --format json
+python -m chronaxis config resolve ../examples/analysis-imports.yaml --defaults --format json
+python -m chronaxis validate ../examples/input-csv-minimal.yaml --format json
+python -m chronaxis explain ../examples/input-csv-minimal.yaml --format json
+```
+
+`origins` identifies the declaration supplying a field. `resolve` shows expanded configuration and defaults that can currently be determined; it must not invent a fixed period awaiting DBC lookup. `load_analysis_plan` resolves paths relative to the defining file; `AnalysisPlan.from_dict` takes an already expanded dictionary. Validation does not establish actual observation coverage, real units, or correct results. Deliver the version, inputs, key assumptions, checks actually performed, and unverified conditions.
+
+<a id="持续门槛与积分起点"></a>
+## Duration thresholds and integration starts
+
+For `condition_duration`, `minimum_duration: 60s` means reaching 60 seconds by default. For “more than 60 seconds,” add `duration_comparison: ">"`, not 60.1 seconds. Default `selection_origin: onset` includes the entire qualifying interval. Select `confirmed` only when the user asks to start after confirmation. An exactly 60-second activity produces an event in the default mode and no event in strict mode. Time precision is 1 ns. Actual-time strict comparison can confirm at threshold plus 1 ns; fixed/DBC mode waits for the next driving message that takes accumulated duration strictly past the threshold.
+
+<a id="资源不足时保留原任务"></a>
+## Preserve the task when resources are insufficient
+
+Sample minimum, maximum, and mean use chunked reductions within the shared memory budget; their result does not depend on chunk size. Do not add unrequested statistics for debugging. For a budget error, first inspect the named calculation, workspace, or read buffer instead of attributing every failure to machine RAM. If even the smallest statistical chunk does not fit, execution fails explicitly. Reducing read batches changes processing chunks, not conditions, validity, or retained input. Increase budgets only with an actual resource basis. Managed budget estimates and process RSS are different quantities.
+
+<a id="can通道连续文件与检查范围"></a>
+## CAN channels, continuous files, and check scope
+
+DBC mapping keys, explicit signal channels, per-message selectors, and raw-frame resampling channels all start at 1 in public configuration. Channel 1 in ASC is channel 1 in configuration; do not subtract 1. Signal/selector `channel` can be omitted when the source channel is unambiguous. The program converts internal zero-based numbering. For raw CSV, `reader.channel_origin` still describes whether the input column itself starts at 0 or 1. Migrate old zero-based configuration rather than editing the original log.
+
+Configuration paths are relative to the file containing that field, including shared definitions. Dictionary APIs use `base_dir`, defaulting to the current directory. `chronaxis explain PLAN --format json` shows plan information; `chronaxis config resolve PLAN --format json` shows expanded configuration. Files within one source are continuous in listed order, retaining candidate state across boundaries. Directory matching uses natural order. Sharing a folder does not prove sharing a session: use batch tasks for independent experiments, and do not invent offsets to concatenate them.
+
+ASC checks timestamp order only for required channels/IDs by default. The source's earliest and latest frame times are still collected during that same read. Required records moving backwards remain errors; full checks or raw-frame export require the whole source to be ordered. Do not add a separate full-file scan followed by automatic cleaning. A small difference of microseconds does not authorize changing the input.
+
+<a id="默认可读结果"></a>
+## Default readable results
+
+Omitting `outputs.tables` selects `readable_csv`: Chinese filenames and headers, exact seconds, and one row containing the metrics for each event or window. Discover actual files through `run_manifest.json.outputs`; do not hard-code `events.csv` or `calculations.csv`. Explicit `outputs.tables: csv` or `jsonl` selects the original interchange format and integer nanoseconds. Only the selected table format is produced.
+
+Readable tables retain calculation names and units. Empty cells are not zero. Each metric independently reports `完整` (complete), `部分有效` (partial), or `无法确定` (indeterminate), with its reason. Inspect interval status separately from metric status. Global `has_unknown` does not invalidate a complete calculation within a known interval. For no events, inspect manifest `result_messages`; do not create a false zero-energy result. Preserve the original analysis time coordinates without inventing dates or shifting to zero. Do not duplicate seconds and nanoseconds. Python iterators such as `iter_events` and `iter_calculations` continue to return original typed rows.
+
+<a id="独立批量的进程数"></a>
+## Process count for independent batch tasks
+
+Root-level batch `process_count` is a positive integer, default 1, limiting analysis worker processes. It excludes the scheduler and CAN reader subprocesses. `run_batch(plan, output, process_count=4)` and CLI `--process-count 4` override it. Only the Python API accepts `None` to inherit the plan; configuration rejects null and Booleans. Call from a Python script inside `if __name__ == "__main__":`. Ordinary `AnalysisRunner` has no such parameter. Continuous `paths` in one session are not split into independent processes.
+
+Each task has its own budgets and output. Cancellation prevents tasks that have not started; in-flight tasks finish and close. `report.close()` can retry remote cleanup. Unstarted tasks and worker crashes are not successes. Legacy `workers`, `max_workers`, and `--workers` are rejected.
+
+<a id="迁移数值与后端核对"></a>
+## Migrated numbers and backend comparisons
+
+Historical INI seconds accept scientific notation. Import preserves compact representation and checks representable durations; do not expand huge exponents for display. A rejection report is not a successfully generated analysis plan. Both backends must agree on event boundaries, statuses, and diagnostics. Compare floating-point metrics using their unit and agreed error tolerance, without requiring bitwise equality or attributing event/quality differences to rounding.
+
+Ordinary scalar calculations, including sample statistics, can return `coverage_status` when `minimum_coverage > 0`. It records the threshold decision, not a ratio, and does not change the equal weighting of `sample_mean`. Initial-edge `emit_initial` concerns the first known state, not an arbitrary first `True` anywhere in the analysis. A requested endpoint can produce a point event only when it is actually observed and satisfies the rule.

chronaxis/guide/en/tasks.json

@@ -0,0 +1,290 @@
+{
+  "device_label": "home",
+  "revision": 1,
+  "tasks": [
+    {
+      "id": "CAN",
+      "intent": "Integrate power from BLF / ASC messages",
+      "example": "../examples/analysis.yaml",
+      "requires": "Logs, channel, matching DBC, power unit, and clock.",
+      "check": "Check joules (J) and the actual observed range.",
+      "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": "Continuous BLF/ASC volumes: require multiple conditions for longer than a threshold, then integrate energy over the full qualifying interval in kWh",
+      "example": "../examples/conditional-energy.yaml",
+      "requires": "Raw ASC/BLF and matching DBC; target signals, codes, units, comparisons, continuous duration, and integration scope. Do not require types, units, or periods to be repeated when the DBC supplies them.",
+      "applicable": "Custom state and numeric conditions; inclusive or strict duration thresholds; integration from condition onset; optional energy unit. The example uses strict >60s, default onset, and actual elapsed time.",
+      "not_applicable": "For a direct sum using a fixed period per message, consult message_calculations. Use BATCH for independent files.",
+      "alternative": "charge_session applies only to its strict current > comparison, duration >= comparison, Wh/Ah outputs, and direction/measurement-point requirements. Do not choose it merely because a task mentions charging.",
+      "check": "Exactly 60 seconds produces no event. The cross-file 61-second interval is [61,122), giving 4000W*61s/3600000=0.06777777777777777kWh. Link parent_id to event_id and check status/reason. Do not replace strict comparison with 60.1 seconds.",
+      "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": "Power table integrated using actual elapsed time",
+      "example": "../examples/input-csv-minimal.yaml",
+      "requires": "Time column, units, power column, and validity period.",
+      "check": "Compare with the hand-calculated 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": "Charging activities, electric charge, and charging energy",
+      "example": "../examples/preset-charge-energy.yaml",
+      "requires": "Mode codes, positive current direction, terminal measurement point, voltage, thresholds, and duration. The teaching example uses ASC; for BLF replace the logs, DBC, and bindings with your own.",
+      "check": "Check each activity boundary and Wh/Ah result. Current exactly equal to current_min is excluded; duration exactly equal to minimum_duration qualifies. The default start is onset. Check applicability rather than matching only the word charging.",
+      "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": "Mode equals the specified integer code and current is strictly greater than current_min. After reaching minimum_duration, calculate from condition onset. Outputs are Wh for energy and Ah for electric charge. Positive current means charging, and the measurement point is the battery-pack terminal.",
+      "not_applicable": "Do not directly apply charge_session when the task needs current >= threshold, a strict duration threshold, direct kWh output, another state combination, or unconfirmed preset direction/measurement-point requirements.",
+      "alternative": "Use CONDITION_ENERGY and ../examples/conditional-energy.yaml with an ordinary condition_duration rule and event-scope integral. Preserve the comparisons, duration comparison, and output unit. Ordinary U*I integration needs no extra direction/measurement-point metadata or 95% coverage threshold."
+    },
+    {
+      "id": "EVENT",
+      "intent": "Sustained activities, exit grouping, and event relationships",
+      "example": "../examples/window-merged.yaml",
+      "requires": "Condition, time units, window, and allowed gap.",
+      "check": "Preserve event boundaries; a segment may contain multiple 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": "Alarm context and rising edges",
+      "example": "../examples/preset-fault-context.yaml",
+      "requires": "An explicitly defined Boolean alarm and before/after durations.",
+      "check": "Check point events separately from surrounding segments.",
+      "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": "Request/response pairs, timeout, and insufficient observation",
+      "example": "../examples/sequence-outcomes.yaml",
+      "requires": "Comparable request and response clocks, with explicit minimum and maximum delays.",
+      "check": "Unknown observations must not become a definite no-response outcome.",
+      "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": "Boolean and enumeration codes, and expression aliases",
+      "example": "../examples/signal-enum-minimal.yaml",
+      "requires": "Equipment code definitions; undefined codes must not use nonzero=true.",
+      "check": "Expressions reference bound names. Semantic IDs are not attribute paths.",
+      "fields": [
+        "signals",
+        "derived"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../examples/signal-enum-minimal.yaml --format json"
+    },
+    {
+      "id": "UNITS",
+      "intent": "Conversions, units, and scales",
+      "example": "../examples/signal-number-conversion.yaml",
+      "requires": "Input/output units, existing decoder scaling, and direction declarations.",
+      "check": "Apply DBC scaling once. Unit labels alone do not convert values.",
+      "fields": [
+        "signals"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../examples/signal-number-conversion.yaml --format json"
+    },
+    {
+      "id": "QUALITY",
+      "intent": "Expired data, zero values, and partial results",
+      "example": "../examples/quality.yaml",
+      "requires": "Period or validity, required observation range, and missing-data policy.",
+      "check": "Read status/reason/quality together with the value.",
+      "fields": [
+        "signals",
+        "execution",
+        "calculations"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan",
+        "AnalysisRunner"
+      ],
+      "verify": "python -m chronaxis validate ../examples/quality.yaml --format json"
+    },
+    {
+      "id": "BATCH",
+      "intent": "Run independent tasks in a batch",
+      "example": "../examples/batch-minimal.yaml",
+      "requires": "Independent input and output for each plan, without shared task state.",
+      "check": "Use batch run. process_count is a positive integer, default 1, overridable with --process-count. Inspect worker_process_count and each task worker_pid in batch_report. Continuous volumes belong in one task's 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": "Shared definitions, field origins, and relative paths",
+      "example": "../examples/analysis-imports.yaml",
+      "requires": "Both the main configuration and referenced shared-definition files.",
+      "check": "Use config origins --fields to inspect declaration origins.",
+      "fields": [
+        "imports"
+      ],
+      "templates": [],
+      "api": [
+        "load_analysis_plan"
+      ],
+      "verify": "python -m chronaxis validate ../examples/analysis-imports.yaml --format json"
+    },
+    {
+      "id": "EXPORT",
+      "intent": "Export raw messages around events",
+      "example": "../examples/export-can-minimal.yaml",
+      "requires": "A supported CAN source, explicit window, and new output directory.",
+      "check": "Check actual windows, output format, and manifest.",
+      "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": "Load, publish, and close results in Python",
+      "example": "../examples/input-csv-minimal.yaml",
+      "requires": "The matching installed version, complete plan, and new result directory.",
+      "check": "Run ../run_analysis.py. Validate before execution, read rows, and close resources.",
+      "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": "Correct configuration using diagnostics",
+      "example": "../examples/input-csv-minimal.yaml",
+      "requires": "The user's original intent, original files, and actual diagnostics.",
+      "check": "Fix field placement, types, or references. Do not remove conditions or change validity to suppress errors.",
+      "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/en/workflow.md

@@ -0,0 +1,41 @@
+<a id="从用户输入到结果"></a>
+# From the user's inputs to results
+
+| Task | Public entry point | Result and boundaries |
+|---|---|---|
+| Connect logs | BLF/ASC with the matching DBC; raw-message CSV with an explicit record format; decoded CSV with column declarations; memory input for controlled data. | Source identity, clocks, and entity scope are input requirements. Combine sources only when the available evidence supports it. |
+| Build an analysis | Version 3 YAML/JSON for a single task, with at most one level of shared definitions. Use `load_analysis_plan` for files and `AnalysisPlan.from_dict` for dictionaries. | Checks references, types, units, and clocks; may enumerate directories or read DBC metadata. This does not verify business meaning in actual records. |
+| Choose calculations | Use bound names in conditions, derived expressions, rules, windows, and `calculations`. Use `message_calculations` for per-message accumulation. | Activities and windows can have separate calculations. Integration method, interval basis, and quality affect results. |
+| Use business presets | Declare roles and parameters in a complete plan's `presets`. Python construction returns a `PlanFragment`. | Presets expand into ordinary declarations. Role validation does not determine engineering thresholds; a fragment is not a complete plan. |
+| Explain before running | `validate_analysis_plan`, `explain_analysis_plan`, then `AnalysisRunner.run`. | Explanation shows dependencies, time requirements, and budgets, not records already read. `run` calculates from real inputs and returns an `AnalysisResult`. |
+| Read or deliver results | Stream rows from `AnalysisResult`; close cursors after exhaustion or early exit. Call `write` with a new directory, then close the result. | Follow each row type's relationship keys and quality fields. Null is not zero. Failed publication is not delivery. |
+| Run independent tasks | `load_batch_plan`, `run_batch`, or `python -m chronaxis batch run`. | Each task is independent. Inspect individual statuses even after a normal return. Do not split one stateful session into independent tasks. |
+
+Evidence for final output publication in this version is limited to Windows / Python 3.12. Historical formats, channels, exports, and profiles have specific conditions. Retain capability restrictions reported by `validate`/`explain` rather than promising every historical path works. Example values are synthetic; platform behavior, budgets, speed, and real business results require their own verification.
+
+<a id="写配置前保留用户原意"></a>
+## Preserve the user's meaning before writing configuration
+
+Map the requirements already supplied by the user to configuration without asking them to reconfirm those facts. Consider: “state is `0x2`, current is at least `10A`, continuously for more than `60s`; integrate current times voltage over each qualifying interval, in `kWh`.”
+
+| Requirement to preserve | Configuration and handling |
+|---|---|
+| Signals and expression | Bind `BMS_ChrgSta`, `BMS_BatPackActCur`, and `BMS_BatPackActVol`. Calculate current times voltage; do not substitute another measurement point. |
+| Comparisons and logic | Use `state == 0x2 and current >= 10`, binding aliases to those signals. Preserve equality, inclusive `>=`, and logical AND. |
+| Continuously longer than 60 seconds | Use `condition_duration`, `minimum_duration: 60s`, and `duration_comparison: ">"`. Exactly 60 seconds does not qualify. Do not replace it with 60.1 seconds or omit continuity by merely filtering frames. |
+| Integration boundaries | “Within the qualifying interval” uses default `selection_origin: onset`, from first satisfaction to the interval end. Do not discard the first 60 seconds. Use `confirmed` only when explicitly requested. |
+| Unit | Confirm A and V from the DBC or established definitions, and request `kWh` output. Do not relabel a J or Wh value as kWh. |
+| File relationships and timing | Put continuous volumes in one source so state continues across files. Batch only independent tasks. Preserve the chosen actual, fixed, or DBC period; do not edit timestamps instead of configuring it correctly. |
+
+Aliases may be short, but explain their original signal mappings. Obtain facts from inputs, DBC metadata, matching examples, and the user's existing instructions. Ask only when a missing fact can change the result, such as an ambiguous signal match or uncertainty about whether files are continuous volumes or independent experiments. Use supported defaults and explain them where relevant; do not turn every optional field into a question.
+
+Ordinary expression integration does not require current direction or measurement-point metadata used only by a business preset. If the user specifies a raw-current comparison and product, do not add sign conversion merely to label the result “charging” or “discharging.” Ask about that interpretation only when the task actually needs it and the available information is insufficient.
+
+<a id="报错修复与核验范围"></a>
+## Fix errors within the task's scope
+
+For installation, missing dependencies, paths, or field errors, fix the actual cause while preserving the requested signals, condition, duration threshold, integration start, and unit. Do not add direction/measurement restrictions, a `95%` coverage threshold, extra minimum/maximum statistics, or change validity, thresholds, or timing just to make execution succeed. Do not automatically sort, deduplicate, filter, or rewrite input after backwards timestamps or similar data errors. Report the actual diagnostic and explain any proposed data treatment's effect on results.
+
+Read, calculate, and deliver only what the task needs. Once installation and entry-point validation pass, run the requested analysis. Contributions, tracing, raw-frame copies, additional statistics, and repeated scans that neither the user nor calculation needs must not be constructed, scanned, saved, or output. Explain empty results using their diagnostics; do not silently loosen conditions and rerun.
+
+Choose independent verification for a specific verification goal; it is not a prerequisite for every normal run. If you write a separate checker, explain whether it preserves original order, how it handles validity (TTL), invalid updates and boundaries, and which files, signals, and results it checks. A script that sorts records and holds the latest voltage forever is not equivalent to an analysis that preserves order and expires voltage. Similar total energy alone does not verify the entire feature. Checking only integration values does not establish event selection, cross-file state, or all quality rules. Investigate discrepancies rather than changing business conditions to fit a reference value.

chronaxis/guide/examples/analysis-imports.yaml

@@ -0,0 +1,22 @@
+# 合成教学配置；请连同配套输入使用，数值仅用于复现本例。
+config_version: 3                       # 声明分析文件采用的字段结构版本；当前填写整数3
+imports: [shared/definitions.yaml]      # 先加载公共定义文件；列表项为相对当前配置文件的路径
+dataset:                                # 设置本次分析名称及可选的对象、会话和时间范围
+  name: imported_energy                 # 命名本次分析数据集；名称写入结果身份字段
+calculations:                           # 列出希望获得的统计或积分结果，每项独立选择范围和算法
+  - name: energy                        # 为这项计算结果取唯一名称；结果表用它区分计算项
+    operation: integral                 # 选择计算方法；本例将有效数值乘持续时间后累计，例如功率乘秒得到能量
+    expr: power                         # 指定参与计算的数值或信号表达式；引用前面已定义的信号
+  - name: sample_average                # 为这项计算结果取唯一名称；结果表用它区分计算项
+    operation: sample_mean              # 选择计算方法；本例对范围内有效真实样本等权求平均，每个样本计一次
+    expr: power                         # 指定参与计算的数值或信号表达式；引用前面已定义的信号
+  - name: time_average                  # 为这项计算结果取唯一名称；结果表用它区分计算项
+    operation: time_weighted_mean       # 选择计算方法；本例按有效值持续时长加权求平均
+    expr: power                         # 指定参与计算的数值或信号表达式；引用前面已定义的信号
+  - name: double_energy                 # 为这项计算结果取唯一名称；结果表用它区分计算项
+    operation: integral                 # 选择计算方法；本例将有效数值乘持续时间后累计，例如功率乘秒得到能量
+    expr: double_power                  # 指定参与计算的数值或信号表达式；引用前面已定义的信号
+metadata:                               # 保存说明性信息；字段不会自动校准数据或更改计算公式
+  device_label: home                    # 记录产出设备标签；当前独立导出仅接受home/work，普通分析与批量报告规则见对应说明
+  data_kind: synthetic                  # 记录数据来源性质；synthetic表示人工构造的测试输入
+  purpose: 演示导入公共来源、信号及派生功率，并计算能量和均值    # 记录这份配置的用途；不参与条件判断或数值计算

chronaxis/guide/examples/analysis.yaml

@@ -0,0 +1,23 @@
+# 合成教学配置；请连同配套输入使用，数值仅用于复现本例。
+config_version: 3                     # 声明分析文件采用的字段结构版本；当前填写整数3
+dataset:                              # 设置本次分析名称及可选的对象、会话和时间范围
+  name: energy                        # 命名本次分析数据集；名称写入结果身份字段
+sources:                              # 列出输入来源；每项规定数据位置、格式和时间解释方式
+  - paths: data/can/quickstart.asc    # 选择输入文件、连续分卷列表或目录；相对路径基于本配置，目录按自然序读取
+    dbc_by_channel:                   # 为每个CAN通道指定解码用DBC文件；键是通道编号的字符串
+      '1': data/can/teaching.dbc      # 为这个通道指定DBC文件；路径相对当前配置文件，通道键须为字符串
+signals:                              # 把输入字段定义为有名称、类型、单位和有效期的分析信号
+  - name: power                       # 给分析信号取名称；后续表达式和计算通过此名称引用它
+    field:                            # 指定来源中的原始字段；CSV填表头，CAN填写通道/报文ID/DBC信号名
+      frame_id: '0x100'               # 选择包含信号的报文ID；从对应DBC取得，可写整数或支持的进制文本
+      signal: Power                   # 填写DBC中的信号名称，大小写须一致
+calculations:                         # 列出希望获得的统计或积分结果，每项独立选择范围和算法
+  - name: energy                      # 为这项计算结果取唯一名称；结果表用它区分计算项
+    operation: integral               # 选择计算方法；本例将有效数值乘持续时间后累计，例如功率乘秒得到能量
+    expr: power                       # 指定参与计算的数值或信号表达式；引用前面已定义的信号
+  - name: sample_average              # 为这项计算结果取唯一名称；结果表用它区分计算项
+    operation: sample_mean            # 选择计算方法；本例对范围内有效真实样本等权求平均，每个样本计一次
+    expr: power                       # 指定参与计算的数值或信号表达式；引用前面已定义的信号
+  - name: time_average                # 为这项计算结果取唯一名称；结果表用它区分计算项
+    operation: time_weighted_mean     # 选择计算方法；本例按有效值持续时长加权求平均
+    expr: power                       # 指定参与计算的数值或信号表达式；引用前面已定义的信号

chronaxis/guide/examples/batch-minimal.yaml

@@ -0,0 +1,3 @@
+batch_version: 1           # 声明独立批量任务文件的结构版本；当前填写整数1
+jobs:                      # 列出互相独立的分析任务，每项引用一份分析配置
+  - plan: analysis.yaml    # 指定该任务的分析配置文件；相对于批量配置文件所在目录

chronaxis/guide/examples/conditional-energy.yaml

@@ -0,0 +1,36 @@
+# 合成教学示例：两个条件连续超过60秒，再对整个合格区间积分。
+config_version: 3                                     # 当前配置结构版本
+dataset:                                              # 本次分析
+  name: conditional_energy                            # 结果使用这个任务名称
+sources:                                              # 两卷连续文件组成一个来源
+  - paths:                                            # 按下面的先后顺序读取，跨文件保持状态
+      - data/can/conditional-energy/part-1.asc        # 0～89秒
+      - data/can/conditional-energy/part-2.asc        # 90～123秒
+    dbc_by_channel:                                   # 用户通道从1开始；内部编号自动匹配
+      '1': data/can/conditional-energy/signals.dbc    # 相对本配置文件的位置
+signals:                                              # 唯一来源和通道可省略；类型、单位和周期由DBC取得
+  - name: state                                       # 用整数状态直接比较，无需映射成布尔或枚举
+    field:                                            # DBC中的报文与信号
+      frame_id: '0x100'                               # 十六进制报文ID
+      signal: State                                   # DBC中的状态信号
+  - name: current                                     # 电流，DBC单位A
+    field:                                            # 与状态在同一报文中
+      frame_id: '0x100'                               # 相同ID
+      signal: Current                                 # DBC中的电流信号
+  - name: voltage                                     # 电压，DBC单位V
+    field:                                            # 与状态在同一报文中
+      frame_id: '0x100'                               # 相同ID
+      signal: Voltage                                 # DBC中的电压信号
+rules:                                                # 先找合格区间
+  - name: eligible                                    # 积分通过这个名称选择区间
+    rule_type: condition_duration                     # 要求条件连续成立
+    condition: state == 0x2 and current >= 10         # 状态为2且电流至少10A
+    minimum_duration: 60s                             # 持续时长门槛
+    duration_comparison: ">"                          # 严格超过；恰好60秒不合格
+calculations:                                         # 只请求所需的能量结果
+  - name: energy_kwh                                  # 结果表中的计算项名称
+    operation: integral                               # 按实际时间积分
+    expr: current * voltage                           # A×V得到W，乘时间后转为kWh
+    scope:                                            # 选择整个合格事件区间
+      rule: eligible                                  # 默认onset，包含最初60秒
+    unit: kWh                                         # 直接输出kWh，不在外部再换算

chronaxis/guide/examples/data/activity.csv

@@ -0,0 +1,6 @@
+time,temperature,power
+0,70,10
+1,80,10
+3,80,10
+6,70,10
+7,70,10

chronaxis/guide/examples/data/can/activity.asc

@@ -0,0 +1,11 @@
+base hex timestamps absolute
+0 1 7FE Rx d 1 00
+0 1 11D Rx d 8 00 00 00 00 00 80 51 40
+0 1 100 Rx d 8 00 00 00 00 00 00 24 40
+1 1 11D Rx d 8 00 00 00 00 00 00 54 40
+1 1 100 Rx d 8 00 00 00 00 00 00 24 40
+3 1 11D Rx d 8 00 00 00 00 00 00 54 40
+3 1 100 Rx d 8 00 00 00 00 00 00 24 40
+6 1 11D Rx d 8 00 00 00 00 00 80 51 40
+6 1 100 Rx d 8 00 00 00 00 00 00 24 40
+7 1 7FE Rx d 1 00

chronaxis/guide/examples/data/can/calculation-minimal.asc

@@ -0,0 +1,6 @@
+base hex timestamps absolute
+0 1 7FE Rx d 1 00
+0 1 100 Rx d 8 00 00 00 00 00 00 00 00
+1 1 100 Rx d 8 00 00 00 00 00 00 24 40
+4 1 100 Rx d 8 00 00 00 00 00 00 00 00
+5 1 7FE Rx d 1 00

chronaxis/guide/examples/data/can/conditional-energy/part-1.asc

@@ -0,0 +1,92 @@
+base hex timestamps absolute
+// Synthetic teaching data; device_label: home; not a vehicle measurement.
+0 1 100 Rx d 5 02 64 00 A0 0F
+1 1 100 Rx d 5 02 64 00 A0 0F
+2 1 100 Rx d 5 02 64 00 A0 0F
+3 1 100 Rx d 5 02 64 00 A0 0F
+4 1 100 Rx d 5 02 64 00 A0 0F
+5 1 100 Rx d 5 02 64 00 A0 0F
+6 1 100 Rx d 5 02 64 00 A0 0F
+7 1 100 Rx d 5 02 64 00 A0 0F
+8 1 100 Rx d 5 02 64 00 A0 0F
+9 1 100 Rx d 5 02 64 00 A0 0F
+10 1 100 Rx d 5 02 64 00 A0 0F
+11 1 100 Rx d 5 02 64 00 A0 0F
+12 1 100 Rx d 5 02 64 00 A0 0F
+13 1 100 Rx d 5 02 64 00 A0 0F
+14 1 100 Rx d 5 02 64 00 A0 0F
+15 1 100 Rx d 5 02 64 00 A0 0F
+16 1 100 Rx d 5 02 64 00 A0 0F
+17 1 100 Rx d 5 02 64 00 A0 0F
+18 1 100 Rx d 5 02 64 00 A0 0F
+19 1 100 Rx d 5 02 64 00 A0 0F
+20 1 100 Rx d 5 02 64 00 A0 0F
+21 1 100 Rx d 5 02 64 00 A0 0F
+22 1 100 Rx d 5 02 64 00 A0 0F
+23 1 100 Rx d 5 02 64 00 A0 0F
+24 1 100 Rx d 5 02 64 00 A0 0F
+25 1 100 Rx d 5 02 64 00 A0 0F
+26 1 100 Rx d 5 02 64 00 A0 0F
+27 1 100 Rx d 5 02 64 00 A0 0F
+28 1 100 Rx d 5 02 64 00 A0 0F
+29 1 100 Rx d 5 02 64 00 A0 0F
+30 1 100 Rx d 5 02 64 00 A0 0F
+31 1 100 Rx d 5 02 64 00 A0 0F
+32 1 100 Rx d 5 02 64 00 A0 0F
+33 1 100 Rx d 5 02 64 00 A0 0F
+34 1 100 Rx d 5 02 64 00 A0 0F
+35 1 100 Rx d 5 02 64 00 A0 0F
+36 1 100 Rx d 5 02 64 00 A0 0F
+37 1 100 Rx d 5 02 64 00 A0 0F
+38 1 100 Rx d 5 02 64 00 A0 0F
+39 1 100 Rx d 5 02 64 00 A0 0F
+40 1 100 Rx d 5 02 64 00 A0 0F
+41 1 100 Rx d 5 02 64 00 A0 0F
+42 1 100 Rx d 5 02 64 00 A0 0F
+43 1 100 Rx d 5 02 64 00 A0 0F
+44 1 100 Rx d 5 02 64 00 A0 0F
+45 1 100 Rx d 5 02 64 00 A0 0F
+46 1 100 Rx d 5 02 64 00 A0 0F
+47 1 100 Rx d 5 02 64 00 A0 0F
+48 1 100 Rx d 5 02 64 00 A0 0F
+49 1 100 Rx d 5 02 64 00 A0 0F
+50 1 100 Rx d 5 02 64 00 A0 0F
+51 1 100 Rx d 5 02 64 00 A0 0F
+52 1 100 Rx d 5 02 64 00 A0 0F
+53 1 100 Rx d 5 02 64 00 A0 0F
+54 1 100 Rx d 5 02 64 00 A0 0F
+55 1 100 Rx d 5 02 64 00 A0 0F
+56 1 100 Rx d 5 02 64 00 A0 0F
+57 1 100 Rx d 5 02 64 00 A0 0F
+58 1 100 Rx d 5 02 64 00 A0 0F
+59 1 100 Rx d 5 02 64 00 A0 0F
+60 1 100 Rx d 5 00 64 00 A0 0F
+61 1 100 Rx d 5 02 64 00 A0 0F
+62 1 100 Rx d 5 02 64 00 A0 0F
+63 1 100 Rx d 5 02 64 00 A0 0F
+64 1 100 Rx d 5 02 64 00 A0 0F
+65 1 100 Rx d 5 02 64 00 A0 0F
+66 1 100 Rx d 5 02 64 00 A0 0F
+67 1 100 Rx d 5 02 64 00 A0 0F
+68 1 100 Rx d 5 02 64 00 A0 0F
+69 1 100 Rx d 5 02 64 00 A0 0F
+70 1 100 Rx d 5 02 64 00 A0 0F
+71 1 100 Rx d 5 02 64 00 A0 0F
+72 1 100 Rx d 5 02 64 00 A0 0F
+73 1 100 Rx d 5 02 64 00 A0 0F
+74 1 100 Rx d 5 02 64 00 A0 0F
+75 1 100 Rx d 5 02 64 00 A0 0F
+76 1 100 Rx d 5 02 64 00 A0 0F
+77 1 100 Rx d 5 02 64 00 A0 0F
+78 1 100 Rx d 5 02 64 00 A0 0F
+79 1 100 Rx d 5 02 64 00 A0 0F
+80 1 100 Rx d 5 02 64 00 A0 0F
+81 1 100 Rx d 5 02 64 00 A0 0F
+82 1 100 Rx d 5 02 64 00 A0 0F
+83 1 100 Rx d 5 02 64 00 A0 0F
+84 1 100 Rx d 5 02 64 00 A0 0F
+85 1 100 Rx d 5 02 64 00 A0 0F
+86 1 100 Rx d 5 02 64 00 A0 0F
+87 1 100 Rx d 5 02 64 00 A0 0F
+88 1 100 Rx d 5 02 64 00 A0 0F
+89 1 100 Rx d 5 02 64 00 A0 0F