Calculated agent

type is calc, with no protocol. The body takes only measurements and alarms — commands or interlocks are rejected. Measurements keep the usual name, equipment, type, store, and tags; alarms are written exactly as for any other agent, digital and discrete delay included:

{
  "plant-calc": {
    "type": "calc",
    "measurements": [
      {
        "name": "total_flow",
        "equipment": "plant",
        "type": "analogical",
        "store": true,
        "driver": {
          "type": "analogical",
          "inputs": { "a": "pump1::flow", "b": "pump2::flow" },
          "expr": { "add": ["a", "b"] }
        }
      },
      {
        "name": "pumps_running",
        "equipment": "plant",
        "type": "discrete",
        "driver": {
          "type": "discrete",
          "inputs": { "a": "pump1::flow", "b": "pump2::flow" },
          "expr": { "add": [{ "gt": ["a", 0.5] }, { "gt": ["b", 0.5] }] }
        }
      }
    ],
    "alarms": [
      {
        "name": "total_flow_high",
        "area": "plant",
        "type": "analog",
        "meas": "plant::total_flow",
        "conditions": {
          "high": { "value": 8, "severity": "medium", "deadband": 0.5 }
        }
      }
    ]
  }
}

Next to the signal type (and an optional conversion, as everywhere), the driver holds three fields:

• inputs — local names mapped to the equipment::name of each measurement read. The expression only ever uses the local names.
• expr — the value expression.
• quality — optional quality expression, covered below.

An expression is a JSON tree: a bare number is a constant, a bare string is the current value of an input, and an object with one key is an operator applied to its children — {"add": ["a", "b"]}. Every value is a number while it's calculated; the result is converted to the measurement's type at the end, so a discrete point like pumps_running above simply sums two comparisons. The published schema checks each operator name and how many children it takes:

• Arithmetic — add and mul (two or more children), sub (one child negates, two subtract), div, rem, pow, neg, abs.
• Functions — sqrt, exp, ln, log10, floor, ceil, round (half away from zero), sign, and clamp — [x, low, high].
• Aggregates — min, max, sum, avg — one or more children.
• Comparison — gt, ge, lt, le — exact, [a, b]. eq and ne take a third child, an absolute precision: [a, b, 0] compares exactly (right for discrete values), [a, b, 0.01] treats analog values within that band as equal.
• Logic — and, or, not, and if with required cond, then, and else.
• Input metadata — {"quality": "a"} — 1 when input a is good, 0 when bad. {"timestamp": "a"} — its sample time in Unix seconds.

A condition is true when its value is finite and non-zero; comparisons and logic return 1 or 0. if, and, and or only evaluate the children they need.

Without a quality expression, the output is bad whenever any input is bad. Set one to choose for yourself: the output is good when that expression comes out finite and non-zero. Together with quality inside expr, that gives a value that survives one bad input — the sum while both pumps are good, whichever is good otherwise, and bad only when both are:

{
  "name": "flow_fallback",
  "equipment": "plant",
  "type": "analogical",
  "driver": {
    "type": "analogical",
    "inputs": { "a": "pump1::flow", "b": "pump2::flow" },
    "expr": {
      "if": {
        "cond": { "and": [{ "quality": "a" }, { "quality": "b" }] },
        "then": { "add": ["a", "b"] },
        "else": {
          "if": { "cond": { "quality": "a" }, "then": "a", "else": "b" }
        }
      }
    },
    "quality": { "or": [{ "quality": "a" }, { "quality": "b" }] }
  }
}

A failed evaluation — division by zero, a non-finite result, or a domain error such as sqrt of a negative number or ln of zero — publishes the point bad, with its last good value (or 0 if it never had one). The quality expression isn't consulted then.

A point can read another point of the same agent. The intermediate is published like any other measurement, and the agent evaluates them in dependency order in the same pass. A point that reads itself, or a cycle between points, is rejected:

{
  "name": "total_flow_m3h",
  "equipment": "plant",
  "type": "analogical",
  "driver": {
    "type": "analogical",
    "inputs": { "t": "plant::total_flow" },
    "expr": { "mul": ["t", 3.6] }
  }
}