Independent batch analyses

For separate vehicles or unrelated trials, create an analysis configuration for each trial and run them together. Each job has its own signal state, alarm timers, response queue, and output directory.

Use a separate batch file with chronaxis batch run or load_batch_plan / run_batch. Its root process_count: 4 permits up to four independent jobs at once. With two jobs, at most two analysis workers start. Omission still means 1; the program does not automatically use every CPU.

List different configurations in jobs, or apply one template to multiple independent inputs; these forms are mutually exclusive. Each child uses execution.process_count: 1 and default file_merge: concatenate. The outer batch supplies parallelism; a child does not start another file-worker pool.

Put volumes from the same charge in one source's paths and use continuous-file multiprocessing. An alarm active at the end of volume one continues into volume two in a continuous analysis; independent batch jobs do not share that state. execution.batch_rows separately sets samples per batch, not jobs or worker processes.

Complete batch configuration

Fields such as batch_version, jobs, and process_count belong at the batch file's root. jobs[].plan belongs to a job item. This file is not embedded in an analysis configuration.

batch-minimal.yaml uses the single-process child batch/energy.yaml. Its batch limit is four, but one job needs at most one worker and produces 38 J. batch-extended.yaml adds batch/voltage.yaml. With a limit of four, these two jobs can run together and produce 38 J and 13 V·s. The recordings remain independent. Keep the bundled examples' batch and data subdirectories, and run from the examples directory.

batch_version: 1              # Independent batch configuration version
jobs:                         # Independent analysis tasks
  - plan: batch/energy.yaml   # Independent energy analysis; child uses one process
  - plan: batch/voltage.yaml  # Independent voltage analysis; path relative to this batch file
process_count: 4              # Up to four independent workers; these two jobs need at most two

python -m chronaxis batch run batch-extended.yaml --output batch-output

Open this run's batch report returned by the command. Check both entries in jobs, then follow each job's output locations. Verify 38 J for energy and 13 V·s for voltage integration; their different units mean these values do not form one total.

Omit job names, fail_fast, and backend settings unless you need to change their defaults. Use jobs[].name to customize output-directory names.

Names start with an ASCII letter or underscore, followed by letters, digits or underscores. Python keywords (for, class) and expression function names (abs, isclose) are prohibited. trial_a is valid; trial-a and a/b are not. Names must also be valid directory names on the platform, excluding Windows device names such as CON and NUL.

Input paths inside a child analysis remain relative to that analysis file: a/analysis.yaml referencing data.csv reads a/data.csv, not a file next to the batch configuration.

Apply one template to a directory

From the supplied examples directory, the pattern below matches only data/can/quickstart.asc, producing one job. It does not match files under quickstart-parts. With your own input set, the job count follows the actual matches.

If each input file is an independent trial with the same signals and analysis, reuse one configuration. template, inputs, and optional source are root fields and replace the jobs form.

batch_version: 1                  # Independent batch configuration version
template: batch/energy.yaml       # Single-process template applied independently to each input
inputs: data/can/quickstart*.asc  # Match independent inputs in this directory, without recursion
process_count: 4                  # Up to four independent workers; supplied files match one job

Change the directory or pattern to your BLF files, or supply a directory containing mixed supported formats.

Names are job_1, job_2, etc. Only the selected source's paths change; other sources remain as declared. State and outputs are independent, so a value or alarm from file2.csv cannot continue into file10.csv. Use one source's paths for continuous volumes.

CLI and Python

python -m chronaxis batch run batch-extended.yaml --output batch-output --process-count 4

The override is optional: CLI/API override → batch file → default 1. Batch CLI has no --backend; set it in the batch file. Single-analysis run has that option. The output directory can be reused. Job directories and the batch report use this batch's timestamp suffix.

from chronaxis import load_batch_plan, run_batch

def main():
    plan = load_batch_plan("batch-extended.yaml")
    report = run_batch(plan, "batch-output", process_count=4)
    try:
        print(report.worker_process_count)
        print(report.to_dict())
    finally:
        report.close()

if __name__ == "__main__":
    main()

Omitting API process_count, or passing None, uses the plan. A positive integer overrides only this run. BatchPlan(..., process_count=4) and BatchRunner(process_count=4) have the same meaning. Ordinary analysis separately uses execution.process_count and the AnalysisRunner override to read files from one continuous session; the main process maintains the calculation state. See continuous multiprocessing.

With jobs, load_batch_plan reads the batch file; each child's plan and input are read when it starts. With template, loading reads the template, expands inputs, and compiles independent plans; DBC metadata may be read to infer signal definitions, but business frames are not scanned yet.

run_batch writes a timestamped batch report; its actual path is report.report_path. Lower-level BatchRunner.run() returns an object; call write_batch_report() explicitly when using that entry. Detailed signatures: batch API, BatchRunner, models (Chinese implementation reference).

Windows starts workers with spawn, which imports the script again. Keep startup inside if __name__ == "__main__": and run a saved .py file so workers do not dispatch the batch again. On Linux, process cleanup also depends on the capabilities described in Installation; a Python version alone does not establish support.

Actual workers are at most min(process_count, number of jobs). Empty or pre-cancelled batches launch none; a limit of four with two jobs launches two workers. The scheduler is additional. ASC/BLF concatenation runs inside each analysis worker without an extra pure-BLF reader subprocess. Requested BLF exports can still create additional workers, so the operating-system process total need not equal the task-worker count. Workers are reused, but signal and event state are not carried between jobs.

The report stores the effective limit as process_count, actual count as worker_process_count, and each job's process ID as jobs[].worker_pid (null for unstarted jobs). Several jobs may share a reused PID. Reports retain declaration order, not completion order.

Device label on the batch report

CLI reads CHRONAXIS_DEVICE_LABEL, strips surrounding whitespace, and defaults to pending for an unset/blank value. The user supplies the actual device convention; the program does not inspect hardware. In PowerShell, $env:CHRONAXIS_DEVICE_LABEL = "home" affects the current process and its children.

Python does not automatically read this variable: pass run_batch(plan, "batch-output", device_label="home") if needed; omission gives pending. This labels the batch summary, not each child's metadata.device_label. See exports for ordinary analysis and independent-export requirements. Keep pending when no device provenance is needed; it is not a business signal.

Failure, cancellation, and resources

output_dir is populated only after results are written. If writing succeeds but closing fails, the job is still failed, with its output path retained.

Suppose A and B are running and C is waiting. If A fails, B continues; C starts when fail_fast=false, but does not start when true. API cancel_event or Ctrl+C similarly stops new launches and retains completed outputs. Cancellation waits for dispatched jobs to finish writing and closing rather than killing them immediately.

Ordinary task failures follow fail_fast. Unexpected worker exit is a scheduling failure: stop dispatch, preserve completed output, and clean up that worker's CAN reader processes. Python infrastructure exceptions carry batch_report, whose close() can be retried.

If Ctrl+C occurs while a worker is being created and that worker cannot finish cleanup, the original KeyboardInterrupt is re-raised and may carry both batch_report and batch_worker_cleanup_owner. Use the report to inspect completed jobs and retry the cleanup it manages. A worker whose constructor did not finish may not appear in the report's job entries; call close() on an available batch_worker_cleanup_owner as well. Ctrl+C with cleanup already completed still follows the normal cancellation-report path.

If cleanup continues failing, that worker stops accepting jobs and the report marks cleanup_pending=true. Resources remain owned by that process. Correct the file-use/environment problem and call report.close() to retry remotely. If every worker is waiting for cleanup, unstarted jobs become cancelled, not completed. Published JSON records the state when written; the live report's to_dict() reflects later cleanup retries.

Exit codes: 0 for all successful, 1 for job or file-operation failure (such as a non-directory or unwritable output path), 2 for invalid batch configuration/arguments, and 130 for cancellation. Failure takes precedence over cancellation and returns 1.

Each job has its own analysis memory/disk limits. Two jobs allowing 256 MiB each do not impose a 256 MiB total-process limit; Python and decoders add overhead. First verify one job, then choose process_count using actual resources and measurements.

Batch files do not support imports; child analyses may each import definitions with paths based on their declaration files. config origins BATCH lists child or template paths, not each child's full origins. See shared definitions.