p4p control, display and alarm fields complete

Author: MatInGit

docs/source/config.rst

@@ -62,7 +62,8 @@ Each interface type has its own ``config`` block. Refer to the
 :doc:`interfaces` guide for details on:
 
 - ``p4p`` / ``p4p_server`` — EPICS PVA variables with ``proto``, ``name``,
-  ``type``, ``default`` fields
+  ``type``, ``default`` fields, plus optional alarm metadata
+  (``compute_alarm``, ``display``, ``control``, ``valueAlarm``)
 - ``k2eg`` — Kafka-to-EPICS gateway variables
 - ``fastapi_server`` — REST API with ``host``, ``port``, ``start_server``,
   ``input_queue_max``, ``output_queue_max``, ``cors_origins``, and typed
@@ -80,4 +81,4 @@ Model modules
 ~~~~~~~~~~~~~
 Model config specifies a ``type`` (e.g. ``LocalModelGetter``,
 ``MLflowModelGetter``) and ``args`` for the model getter class. See the
-README for full examples.
+README for full examples.

docs/source/interfaces.rst

@@ -21,6 +21,89 @@ The ``p4p`` interface connects to an external EPICS server. The ``p4p_server``
 interface hosts its own p4p server for the specified PVs. Both share the same
 YAML configuration format. See the README for sample YAML.
 
+EPICS Variable Fields
+~~~~~~~~~~~~~~~~~~~~~
+
+.. list-table::
+   :header-rows: 1
+   :widths: 18 10 15 57
+
+   * - Field
+     - Type
+     - Default
+     - Description
+   * - ``proto``
+     - string
+     - **required**
+     - Protocol (currently ``pva``)
+   * - ``name``
+     - string
+     - **required**
+     - PV name
+   * - ``mode``
+     - string
+     - ``"inout"``
+     - ``in``, ``out``, or ``inout``
+   * - ``type``
+     - string
+     - ``"scalar"``
+     - ``scalar``, ``waveform``, ``array``, ``image``
+   * - ``default``
+     - any
+     - ``0.0`` / zeros
+     - Initial value (not supported for ``image`` type)
+   * - ``length``
+     - int
+     - ``10``
+     - Array/waveform length when no default is provided
+   * - ``image_size``
+     - dict
+     - —
+     - Required for ``image`` type: ``{"x": int, "y": int}``
+   * - ``compute_alarm``
+     - bool
+     - ``false``
+     - Enable scalar alarm computation from ``valueAlarm`` limits
+   * - ``display``
+     - dict
+     - —
+     - Optional NTScalar display metadata
+   * - ``control``
+     - dict
+     - —
+     - Optional NTScalar control metadata
+   * - ``valueAlarm``
+     - dict
+     - —
+     - Optional NTScalar alarm limit metadata
+
+Alarm Behavior
+~~~~~~~~~~~~~~
+
+- Computation is scalar-only and active when ``compute_alarm: true``.
+- ``compute_alarm: true`` requires:
+  ``valueAlarm.active: true`` and limits
+  ``lowAlarmLimit``, ``lowWarningLimit``, ``highWarningLimit``, ``highAlarmLimit``.
+- Missing severities use defaults:
+  ``lowAlarmSeverity=2``, ``lowWarningSeverity=1``,
+  ``highWarningSeverity=1``, ``highAlarmSeverity=2``.
+- Status mapping follows EPICS ``menuAlarmStat``:
+  ``NO_ALARM=0``, ``HIHI=3``, ``HIGH=4``, ``LOLO=5``, ``LOW=6``.
+- Explicit ``alarm`` payload overrides computed alarm.
+- Non-scalars do not compute alarms, but explicit ``alarm`` payloads are accepted.
+
+Model Alarm Override
+~~~~~~~~~~~~~~~~~~~~
+
+Models can publish structured output with explicit alarm fields (for example
+``{"PV": {"value": 1.0, "alarm": {...}}}``), and ``ModelObserver`` preserves
+that structure when publishing downstream.
+
+See example:
+
+- ``examples/base/local/deployment_config_p4p_alarm.yaml``
+- ``examples/base/local/model_definition_alarm_override.py``
+
 k2eg Interface
 --------------
 Built on SLAC's `k2eg <https://github.com/slaclab/k2eg>`_, this interface gets
@@ -246,4 +329,4 @@ Completed jobs can be retrieved via ``GET /jobs/next`` (FIFO dequeue) or
    Proper job tracking will be integrated via trace propagation across the
    message broker. Each job's ``job_id`` will be carried through the full
    pipeline in struct metadata, enabling accurate matching of results to jobs
-   even under concurrent load.
+   even under concurrent load.

examples/base/local/deployment_config_p4p_alarm.yaml

@@ -0,0 +1,127 @@
+deployment:
+  type: "continuous"
+  rate: .1 #seconds
+
+modules:
+  p4p_server:
+    name: "p4p_server"
+    type: "interface.p4p_server"
+    pub:
+      - "in_interface"
+    sub:
+      - "get_all"
+      - "model_out"
+    module_args: None
+    config:
+      EPICS_PVA_NAME_SERVERS: "localhost:5075"
+      variables:
+        # scalar inputs
+        ML:LOCAL:TEST_B:
+          proto: pva
+          name: ML:LOCAL:TEST_B
+          type: scalar
+          default: 0.0
+          compute_alarm: true
+          display:
+            description: "Model input B"
+            units: "arb"
+            format: "%.3f"
+            limitLow: -20.0
+            limitHigh: 20.0
+          control:
+            limitLow: -10.0
+            limitHigh: 10.0
+            minStep: 0.1
+          valueAlarm:
+            active: true
+            lowAlarmLimit: -8.0
+            lowWarningLimit: -5.0
+            highWarningLimit: 5.0
+            highAlarmLimit: 8.0
+
+        ML:LOCAL:TEST_A:
+          proto: pva
+          name: ML:LOCAL:TEST_A
+          type: scalar
+          default: 0.0
+          compute_alarm: true
+          display:
+            description: "Model input A"
+            units: "arb"
+            format: "%.3f"
+            limitLow: -20.0
+            limitHigh: 20.0
+          control:
+            limitLow: -10.0
+            limitHigh: 10.0
+            minStep: 0.1
+          valueAlarm:
+            active: true
+            lowAlarmLimit: -8.0
+            lowWarningLimit: -5.0
+            highWarningLimit: 5.0
+            highAlarmLimit: 8.0
+
+        # scalar output with computed alarm
+        ML:LOCAL:TEST_S:
+          proto: pva
+          name: ML:LOCAL:TEST_S
+          type: scalar
+          default: 0.0
+          compute_alarm: true
+          display:
+            description: "Model output S"
+            units: "arb"
+            format: "%.3f"
+            limitLow: -200.0
+            limitHigh: 200.0
+          control:
+            limitLow: -120.0
+            limitHigh: 120.0
+            minStep: 0.1
+          valueAlarm:
+            active: true
+            lowAlarmLimit: -100.0
+            lowWarningLimit: -60.0
+            highWarningLimit: 60.0
+            highAlarmLimit: 100.0
+
+        # non-scalar PV: no computed alarms, but explicit alarm payloads are forwarded
+        ML:LOCAL:TEST_WF:
+          proto: pva
+          name: ML:LOCAL:TEST_WF
+          type: waveform
+          length: 8
+          default: [0, 1, 2, 3, 4, 5, 6, 7]
+
+  input_transformer:
+    name: "input_transformer"
+    type: "transformer.SimpleTransformer"
+    pub: "in_transformer"
+    sub: "in_interface"
+    module_args: None
+    config:
+      symbols:
+        - "ML:LOCAL:TEST_B"
+        - "ML:LOCAL:TEST_A"
+      variables:
+        x:
+          formula: "ML:LOCAL:TEST_A"
+        y:
+          formula: "ML:LOCAL:TEST_B"
+
+  model:
+    name: "model"
+    type: "model.SimpleModel"
+    pub: "model_out"
+    sub: "in_transformer"
+    module_args: None
+    config:
+      type: "LocalModelGetter"
+      args:
+        # This model emits an explicit alarm payload for ML:LOCAL:TEST_S.
+        model_path: "examples/base/local/model_definition_alarm_override.py"
+        model_factory_class: "ModelFactory"
+      variables:
+        max:
+          type: "scalar"

examples/base/local/model_definition_alarm_override.py

@@ -0,0 +1,57 @@
+import torch
+import os
+
+
+OUTPUT_PV = 'ML:LOCAL:TEST_S'
+
+
+class ModelFactory:
+    def __init__(self):
+        os.environ['PYTHONPATH'] = os.path.abspath(
+            os.path.join(os.path.dirname(__file__), '..', '..', '..')
+        )
+        self.model = SimpleModel()
+        model_path = 'examples/base/local/model.pth'
+        if os.path.exists(model_path):
+            self.model.load_state_dict(torch.load(model_path))
+
+    def get_model(self):
+        return self.model
+
+
+class SimpleModel(torch.nn.Module):
+    def __init__(self):
+        super(SimpleModel, self).__init__()
+        self.linear1 = torch.nn.Linear(2, 10)
+        self.linear2 = torch.nn.Linear(10, 1)
+
+    def forward(self, x):
+        x = torch.relu(self.linear1(x))
+        x = self.linear2(x)
+        return x
+
+    @staticmethod
+    def _model_alarm_for_output(value: float) -> dict:
+        # Example override policy from model side.
+        if value >= 50.0:
+            return {'severity': 2, 'status': 3, 'message': 'HIHI (model override)'}
+        if value >= 20.0:
+            return {'severity': 1, 'status': 4, 'message': 'HIGH (model override)'}
+        if value <= -50.0:
+            return {'severity': 2, 'status': 5, 'message': 'LOLO (model override)'}
+        if value <= -20.0:
+            return {'severity': 1, 'status': 6, 'message': 'LOW (model override)'}
+        return {'severity': 0, 'status': 0, 'message': ''}
+
+    def evaluate(self, x: dict) -> dict:
+        input_tensor = torch.tensor([x['x'], x['y']], dtype=torch.float32)
+        output_tensor = self.forward(input_tensor)
+        output_value = float(output_tensor.item())
+
+        return {
+            OUTPUT_PV: {
+                'value': output_value,
+                # Explicit alarm from model should override interface-computed alarm.
+                'alarm': self._model_alarm_for_output(output_value),
+            }
+        }

poly_lithic/src/interfaces/p4p_alarm_constants.py

@@ -0,0 +1,44 @@
+SUPPORTED_PV_TYPES = {'scalar', 'waveform', 'array', 'image'}
+DISPLAY_FIELDS = {'limitLow', 'limitHigh', 'description', 'format', 'units'}
+CONTROL_FIELDS = {'limitLow', 'limitHigh', 'minStep'}
+VALUE_ALARM_FIELDS = {
+    'active',
+    'lowAlarmLimit',
+    'lowWarningLimit',
+    'highWarningLimit',
+    'highAlarmLimit',
+    'lowAlarmSeverity',
+    'lowWarningSeverity',
+    'highWarningSeverity',
+    'highAlarmSeverity',
+    'hysteresis',
+}
+
+ALARM_STATUSES = {
+    'normal': 0,  # NO_ALARM
+    'highAlarm': 3,  # HIHI
+    'highWarning': 4,  # HIGH
+    'lowAlarm': 5,  # LOLO
+    'lowWarning': 6,  # LOW
+}
+
+ALARM_SEVERITY_FIELDS = (
+    'lowAlarmSeverity',
+    'lowWarningSeverity',
+    'highWarningSeverity',
+    'highAlarmSeverity',
+)
+
+DEFAULT_ALARM_SEVERITIES = {
+    'lowAlarmSeverity': 2,
+    'lowWarningSeverity': 1,
+    'highWarningSeverity': 1,
+    'highAlarmSeverity': 2,
+}
+
+ALARM_LIMIT_FIELDS = (
+    'lowAlarmLimit',
+    'lowWarningLimit',
+    'highWarningLimit',
+    'highAlarmLimit',
+)