Expressions

Expressions combine previously defined signals, for example voltage * current for power or current > 5 for a condition. Define the input signals first; with DBC inputs, the program can infer their types and units. Write formulas in fields such as derived.<name>.expr, calculations[].expr, and rules[].condition.

The language resembles a restricted subset of Python. A numeric expression produces values; a condition produces true, false, or unknown. An enum mapping such as 7: running lets you write mode == "running"; use a string to compare the label. To compare the retained integer code, use enum_code(mode) == 7; a numeric state signal can use state == 7 directly. See integer states and enum codes for the code requirements.

Complete minimal and extended examples

expression-minimal.yaml defines 400 V and 10 A over 0–4 s and returns a maximum derived power of 4000 W. expression-extended.yaml adds current > 5 and voltage > 300, requiring 2 s of continuous agreement. It confirms at 2 s and, with the default onset-based range, integrates the full 0–4 s interval to 16000 J.

Prepare sources and signals

The shared electrical-base.yaml reads synthetic ASC data through a DBC and analyzes its observed range. The following signal definitions illustrate the names used on this page. They are already in the base configuration: do not append a second signals section. The 20 s validity is chosen for these sparse teaching records, not as a production recommendation.

signals:                   # Names available to expressions.
  - name: temperature      # Analysis name for the DBC temperature signal.
    field:                 # Locate the original signal.
      frame_id: '0x11d'    # CAN message identifier.
      signal: Temperature  # Signal name in the DBC.
    valid_for: 20s         # Validity for the sparse synthetic example.
  - name: voltage          # Voltage alias.
    field:                 # Original CAN signal.
      frame_id: '0x11f'    # CAN message identifier.
      signal: Voltage      # Signal name in the DBC.
    valid_for: 20s         # Validity for this example.
  - name: current          # Current alias.
    field:                 # Original CAN signal.
      frame_id: '0x114'    # CAN message identifier.
      signal: Current      # Signal name in the DBC.
    valid_for: 20s         # Validity for this example.
  - name: mode             # State alias.
    field:                 # Original CAN signal.
      frame_id: '0x118'    # CAN message identifier.
      signal: Mode         # Signal name in the DBC.
    valid_for: 20s         # Validity for this example.
  - name: request          # Boolean request alias.
    field:                 # Original CAN signal.
      frame_id: '0x11a'    # CAN message identifier.
      signal: Request      # Signal name in the DBC.
    choices:               # Explicit code-to-boolean mapping.
      - [0, false]         # Inactive.
      - [1, true]          # Active.
    valid_for: 20s         # Validity for this example.
  - name: response         # Boolean response alias.
    field:                 # Original CAN signal.
      frame_id: '0x11b'    # CAN message identifier.
      signal: Response     # Signal name in the DBC.
    choices:               # Explicit code-to-boolean mapping.
      - [0, false]         # Inactive.
      - [1, true]          # Active.
    valid_for: 20s         # Validity for this example.

Configuration fragment: power, activity, and energy

For that base file, replace the root-level derived, rules, and calculations sections with this fragment. Do not nest them under signals or append duplicate root keys.

derived:                                      # Reusable calculated signals, keyed by name.
  power:                                      # Name used by later expressions.
    expr: voltage * current                   # V multiplied by A produces W.
rules:                                        # Event detection rules.
  - name: working                             # Rule name.
    condition: current > 5 and voltage > 300  # Both conditions must be true.
    duration_comparison: ">="                 # Include the threshold; use > for strictly longer.
    minimum_duration: 2s                      # Require two continuous seconds.
    rule_type: condition_duration             # Detect sustained conditions.
calculations:                                 # Requested results.
  - name: energy                              # Calculation name.
    expr: power                               # Reuse the derived signal.
    operation: integral                       # Integrate W over time to obtain J.
    scope:                                    # Restrict the calculation range.
      rule: working                           # Calculate over this rule's activity.

If a formula is used only once, write it directly in that calculation's expr. A named derived signal is useful when several rules or calculations reuse it.

Derived signal fields

derived is a mapping from a name to an object, not a list. For example, the full expression path is derived.power.expr; power is the chosen name. Do not add a second name inside that object. Derived and original signal names share a namespace; duplicate names and cyclic dependencies are invalid. Omission or {} means no derived signals; null is invalid.

Derived signals have no independent dtype or valid_for: their types and validity follow their inputs. Undefined names, cycles, incompatible types, and incompatible units fail configuration validation. Runtime failures such as division by zero make the affected value invalid and record a reason.

Literals, names, and parentheses

In YAML, condition: mode == "charge" is a string containing an expression. The quotes around charge belong to that expression. YAML quoting the entire field is a separate layer.

Analysis aliases start with an ASCII letter or underscore, followed by ASCII letters, digits, or underscores. Chinese characters, dots, and spaces are not allowed in these aliases. Python keywords and function names reserved by the selected configuration version cannot be aliases. All built-in function names listed below are reserved. Original CSV headers and DBC signal names can contain other characters: bind them to a legal analysis alias.

Arithmetic

For dimensionless x = 6.0 and y = 2, these are the supported operators:

Arithmetic requires numeric operands; boolean and enum signals are not numeric operands. Integer division also returns float64. Division by zero and numeric overflow produce invalid results, not ordinary zero values.

Comparisons

Numeric values support ==, !=, <, <=, >, and >=. Boolean and enum operands support only == and !=; enum comparisons must use the same enum domain. Chained comparisons such as 0 <= x < 10 combine the comparisons with and. A single = is invalid, as is an undeclared enum label.

Boolean combinations and unknown values

Use and, or, and not on boolean conditions. Numeric values are not implicitly treated as booleans. Operators &, |, ~, &&, ||, and ! are not substitutes.

not Unknown remains unknown. Quality and error information is still recorded: a decisive boolean result does not hide undefined names or turn an invalid numeric value into zero.

Supported functions

Set config_version: 4 (an integer) to use automatic conversion between registered units and the functions below. The current development version accepts configuration version 4 only.

For sample statistics, each actual update of the selected signal counts. Switching branches also counts. Refreshing a switch without changing its state does not add a sample, nor does updating only the inactive signal. Simultaneous updates form one group. Use where to select a value and calculations[].condition to decide whether a period participates in a calculation.

Complete built-in function reference

Parameters are positional unless shown as keywords: the tolerances of isclose and the options of lookup are keyword arguments. Inputs such as x, a, and b can be declared signals or valid expressions. Quote unit and table literals; "mV" is not a signal name. Invalid declarations fail loading/validation. Invalid data at one update produces an invalid result with a quality reason.

For example, where(enabled, power, missing_name) fails validation even if enabled is always true. minimum(v_in_V, v_in_mV, 1) cannot decide whether 1 means V or mV; write quantity(1,"V"). A bare constant inherits a declared scale only when that scale is unambiguous.

Integer flags, enum codes and casts (version 4)

Use these expressions in derived.<name>.expr, rules[].condition or calculations[].expr. For a state declared as int64 or uint64, state == 0x1 works directly without an enum mapping. With an enum, mode == "charge" compares labels; enum_code(mode) == 0x1 compares the retained integer code instead.

Bit functions require unit 1 int64/uint64 input. For flags=6 (binary 110), bit_test(flags,0) is False and bit_extract(flags,1,2) is 3. Signed integers use 64-bit two’s complement. In-memory enums require code_dtype and original codes when using enum_code; DBC enums obtain the code type from the signal definition. Invalid records remain invalid.

Casts retain physical meaning and use canonical units by default. For example, 1500 mV becomes 1.5 V and cannot be represented exactly as an integer. To request integer millivolts, write to_int64(to_unit(voltage, "mV")).

abs(x): absolute value

abs(x) takes exactly one positional numeric argument. It does not accept keywords such as abs(x=current). Taking the absolute value of the minimum int64 value overflows and is invalid.

isclose(a, b, atol=..., rtol=...): tolerance comparison

isclose(a, b, atol=..., rtol=...) takes exactly two positional arguments and requires both tolerance keywords. Tolerances must be finite, nonnegative numeric literals; they cannot be signals or expressions such as 1/10.

For example, isclose(voltage, 400, atol=0.1, rtol=0) allows an absolute difference of 0.1 V. A bare comparison constant first inherits the other input's declared unit. Both values then convert to canonical units; atol is expressed directly in that canonical unit, and rtol is dimensionless. The test is:

abs(a - b) <= atol + rtol * abs(b)

With voltage declared in mV and equal to 500.0, isclose(voltage,501,atol=0.1,rtol=0) compares 0.5 V and 0.501 V using a 0.1 V tolerance: True. To allow 0.1 mV, use atol=0.0001 (V): False. The equivalent V input uses isclose(voltage,0.501,atol=0.0001,rtol=0) and also gives False. Neither quantity nor a signal/expression is accepted for atol. Using to_unit(...,"mV") does not prevent comparison from normalizing to V.

With a=102, b=100, atol=0, and rtol=0.02, it returns true. The relative term uses b, so the operation is not necessarily symmetric. An invalid operand makes the condition unknown.

One-dimensional lookup and interpolation

Root lookups defines calibration points supplied by the user. Expression lookup maps an input coordinate to an output. Obtain the relationship from equipment specifications, measurements, or confirmed data; it is not a built-in voltage-to-power law.

Input coordinates must be exactly representable as float64. Linear-mode outputs must also convert exactly to float64. Step modes can retain int64/uint64 values. If any output is floating point, every output must convert exactly to float64. A negative integer and a positive integer above the int64 maximum cannot share one integer table.

Call lookup(x, "curve", mode="linear", bounds="invalid") with exactly two positional arguments. The optional mode and bounds arguments are keyword-only string literals.

Unknown tables, unregistered/incompatible units, repeated coordinates, excessive points, dynamic table names, and invalid options fail validation. Missing data, precision loss, and out-of-range values under the default policy are invalid at runtime. The complete calibration-curve configuration includes ASC input, DBC bindings, and the point table.

Example: voltage to calibrated power

Use the ASC calibration example with its data/joint.asc and data/joint.dbc. Run python -m chronaxis run lookup-power.yaml --output result. The table maps 3 V to 10 W and 11 V to 50 W. At 7 V, lookup(voltage,'curve') interpolates to 30 W; mode='previous' selects 10 W and mode='next' selects 50 W. Out-of-range input is invalid unless you request bounds='clamp' to use the nearest endpoint.

From 0 s up to, but excluding, 3 s the three readings are 3, 7 and 3 V. They give 10, 30 and 10 W, so the session result rated_power is about 16.67 W: the sample mean of the three power values.

Use mod, bit_test or bit_extract for integer operations. For a flag word of 6 (binary 110), bit_test(flags,0) is false and bit_extract(flags,1,2) is 3. Use to_int64, to_uint64 and to_float64 for explicit conversions. Values that cannot be represented exactly are invalid; fractional values are not silently truncated.

Operator precedence

From highest to lowest: parentheses and function calls; unary +/-; *//; +/-; comparisons; not; and; or. Arithmetic operators at the same precedence evaluate left to right. For x=6 and y=2, x + y * 2 is 10, while (x + y) * 2 is 16. Use parentheses whenever grouping would otherwise be hard to read.

Units

A literal in current > 5 uses the current signal's unit, for example 5 A. Likewise, voltage + 1 adds 1 V. Multiplication or division by a bare scalar, such as current * 2 or current / 2, retains A.

Supported unit combinations include V × A → W, W × s → J, A × s → A·s, their commutative multiplication forms, and V / V → dimensionless. Version 4 converts compatible registered units: 500 mV + 2 V gives 2.5 V; V divided by A gives Ohm. A supplied scale or offset describes the whole conversion; the unit factor is not applied again. Subtracting two temperatures yields a temperature difference. Convert Celsius explicitly to K before multiplying.

For a custom unknown unit combination, you may explicitly label the derived result, but the unit relationship remains unverified: the program has not verified that physical relationship. A label does not prove compatibility.

Canonical units

Canonical units are the common calculation scales. Output units can be selected separately; isclose.atol follows this table.

Compound names prefer registered W and J, such as W/s for a power rate, 1/W for reciprocal power and 1/J for reciprocal energy. These names can be parsed again as units. A shorter name does not replace numeric conversion: mA×V retains its factor of one thousandth, N*m remains torque rather than J, and absolute temperatures remain distinct from temperature differences.

Types and integer precision

Arithmetic between signals requires compatible types. A float64 signal and an int64 signal cannot simply be multiplied; make their input types consistent, or in version 4 use explicit conversions such as to_float64, described below. Version 4 unit conversion may also promote integers to float64. Python functions float() and int() are not supported. A numeric literal, such as integer 2 multiplied by a float64 signal, is handled as a literal and is allowed.

Comparisons between int64 and uint64 signals use exact integer comparisons. Comparing a float64 signal with an integer signal requires consistent input types. A comparison literal can lie outside the signal's range: for example, 9223372036854775808 is greater than every int64 value. An integer literal used in arithmetic must fit the required numeric range.

Configuration errors and runtime invalid values

Undefined names, incompatible units, and unsupported functions are configuration errors. Missing input values, runtime division by zero, and overflow invalidate the affected value and retain the reason. See concepts and execution for quality, missing data, and result handling.

Unsupported syntax and alternatives

The runnable expression checks verify actual results on both calculation backends. They demonstrate the supported expression language, not general Python execution.