A channel calculation derives a number from live inputs, such as a unit conversion or a level percentage. It runs synchronously in the channel-write path, so use it when the result should follow accepted input writes without waiting for a scheduled task.

Calculation Configuration

The name after channel_calculation is the output channel. Return a number to supply its value. Static input pipes establish dependencies automatically; use depends_on for additional inputs.

This example updates a percentage whenever either input changes. Create the two input channels first and use the same units for both.

channel_calculation docs_demo_level_percent:
    local capacity = |docs_demo_capacity|
    if capacity <= 0:
        return 0
    return clamp((|docs_demo_level| / capacity) * 100, 0, 100)

Zero capacity returns zero here. Choose an appropriate fallback for your application and report invalid inputs separately so the result does not hide a sensor fault.

Activate the file and update docs_demo_level or docs_demo_capacity. Inspect docs_demo_level_percent; it should remain between 0 and 100.

Calculation Lifecycle

Activation installs the calculation and its dependencies; ordinary calculations first evaluate on a subsequent target or dependency write. Event trigger calculations also evaluate once at activation.

Each calculation has its own runtime block scope, but unlike a function or a callback, its variables persist between evaluations. Assignments still run each time and can overwrite previous values. To share variables between calculations in the same file, define them at file scope and declare global inside each calculation that uses them. See Values and Scope.

Reactivating the file replaces the calculation with fresh variable state; removing its declaration and reactivating removes it. The shared removal rules explain authority cleanup and retained channels.

Calculation Execution

Calculations run synchronously: the writing code waits for calculations and reactions to finish before its write call returns. Keep them short; waits and slow functions delay that code too.

Equal-valued writes also trigger evaluation. Metadata changes, display refreshes, and telemetry packets do not.

A timed when block can qualify a condition without waiting, but time passing alone does not trigger another evaluation.

Dependencies

A dependency is an input channel whose value writes trigger the calculation. Static pipe reads register dependencies automatically; assignment targets are outputs.

Template-generated names are detected automatically after expansion. Names built from runtime variables need explicit depends_on entries. List each input that should trigger evaluation, including any selection channel, using channel keys without pipes or metadata suffixes:

channel_calculation docs_demo_selected_pressure:
    depends_on: docs_demo_left_pressure, docs_demo_right_pressure
    local side = "left"
    return |docs_demo_{side}_pressure|

Both examples work in Lua and Native C++.

Calculation Arguments

These arguments describe the write that caused evaluation:

Read named input pipes when you need particular signals. Reads use live values, not a simultaneous snapshot of every input. See Execution and Timing for control-cycle timing.

Errors and Cycles

A calculation must return a number. If it fails or produces no numeric result, behavior depends on which channel was written:

Earlier writes and other side effects remain. Direct-write fallbacks produce an ARGUS warning and console report. Use numeric values rather than numeric strings; Lua and Native C++ handle strings and missing returns differently.

A cycle occurs when calculations feed back into one already executing. DCode skips that reentry and records an error. Keep dependencies one-way; use a periodic task for iterative logic.

Reference

• Channel calculation — Declaration, invocation, and result rules.
• Explicit dependencies — Adding inputs for reevaluation.