lume-pva-apg

lume-pva-apg serves EPICS PVs based on a LUMEModel subclass and its supported variables. It is a distribution of lume-pva maintained as a staging area for changes intended to land upstream; see Relationship to lume-pva below.

Features:

• Model outputs served over PVAccess (PVA) and/or ChannelAccess (CA).
  • PVA PVs support a subset of the EPICS NormativeTypes metadata.
  • CA PVs support a subset of the standard EPICS CA meta, such as alarms, display limits and control limits.
• Model inputs served as writable PVs over PVA and/or CA.

Installation

The core distribution is pure-Python and carries no EPICS transport, so it installs from wheels on every platform without triggering a native build. Serving requires at least one transport extra:

pip install 'lume-pva-apg[ca,pva]'   # both transports
pip install 'lume-pva-apg[pva]'      # PVAccess only

The pva extra is required for any serving at all: the value layer in lume_pva_apg.variables is expressed in p4p types and is used by the CA path too. A CA-only install is therefore not currently possible. Importing a module whose transport is absent raises an ImportError naming the extra to install.

pcaspy>=0.8.1 is a floor rather than an exact pin. On 0.8.0 the asynchronous write path passes a casClientInfo where a casCtx is required, which raises inside the SWIG director and terminates the server process; a client issuing a put with callback is told the write succeeded while the value never lands. 0.8.1 fixes it, and the fix depends on a binding 0.8.0 does not compile, so it cannot be worked around from Python. 0.8.1 publishes no linux/aarch64 wheel, so the bound is left open: arm64 consumers must stay free to build from sdist or to take a later release that restores the wheel.

Basic Usage

from lume_pva_apg.runner import Runner

myModel = MyLUMEModel()
r = Runner(model=myModel)
r.run()

Operational Description

Model Outputs

Model outputs can be served over PVA and/or CA. If the output is solely an output, it will be configured as a read-only PV.

Model Inputs

Model inputs are served by the Runner class and can be interacted with using pvput, caput or other CA/PVA tools on the command line.

Like model outputs, inputs can be served over CA or PVA, depending on the Runner configuration.

The Write Path

A write to an input PV is queued, applied to the model on the next simulation cycle, and only then acknowledged: a caput -c or a PVA put with wait=True stays blocked until the cycle that consumed it has finished. Three properties of what happens in between are selectable, and each defaults to the behaviour the runner has always had.

echo_unconfirmed_writes (default True) decides whether an input PV may advertise a value the model has not accepted. By default the requested value is published immediately on PVA, and recorded on CA whether or not the cycle succeeded, so a client reading back an input after a failed cycle can see a value the model never took. Set it to False and the echo waits for the model to accept the write, and is withheld entirely if the model refuses it, leaving the PV on the last value that actually landed.

alarm_on_refused_write (default False) raises WRITE_ALARM/INVALID_ALARM on the CA PV when the model refuses a write. Channel Access put-completion carries no failure channel — it can only ever report success — so an alarm is the only way to tell a CA client its write did not land. PVAccess reports the failure through the put itself and needs no equivalent.

clamp_writes (default False) clamps a written value into the variable's value_range before handing it to the model. LUMEModel.set does not enforce value_range, so by default an out-of-range write reaches the model unchanged and it is the model's job to reject it. The clamp is applied where the write enters the server, so the value echoed back to the client is the same value the model was given.

update_rate is the length in seconds of the window during which arriving writes are batched into a single model.set(). Set it to zero and the window is skipped: every queued write drives a model.set() of its own, so one client's write is never merged into another's.

Control PVs

The runner exposes a control PV of its own:

• {prefix}RESET: any write requests model.reset() and publishes the reset state to output PVs.

The control PV is served over PVA, and is also available over CA when protocol includes "ca".

Set control_pvs to False and the runner serves the model's variables and nothing else. Use it when the runner shares its prefix with another server, or when the surrounding deployment offers reset through a channel of its own, so the runner claims no name the model did not ask for.

prefix is passed to the constructor of the Runner class and defines a prefix to prepend to the start of PV names.

Extension Points

A consumer that needs to serve more than the model describes can subclass Runner rather than fork it. Each seam below defaults to what the base class has always done.

_extend_pvdb() returns additional pcaspy database entries. They are keyed by base PV name, exactly as the runner's own are — prefix is applied by the server, not by the caller. It is called once, after the model's variables and the control PVs are in the database and before the server is created, and only when protocol includes "ca". Merging refuses to shadow a name already there, so a contributed PV can never silently replace one the model owns.

ca_driver_cls is the driver class instantiated to serve that database, constructed with the runner as its only argument. The stock driver resolves a reason through the model's variables and refuses anything it cannot find, so a subclass contributing PVs of its own supplies a driver that knows how to write them and delegates the rest to super(). Reads need no override: the pcaspy default reads back through getParam.

_post_outputs(out_values, ts) is the run loop's publishing step, given the values model.get returned and the timestamp to stamp them with. Overriding it lets a subclass publish elsewhere, publish more, or publish nothing. Raising from it fails the cycle exactly as raising inline did: the model is rolled back to its cached state and every waiting put completes with the error.

class CoHostedRunner(Runner):
    class Driver(Runner.CaDriver):
        def write(self, reason, value):
            if reason == "STATUS":
                self.setParam(reason, value)
                self.updatePV(reason)
                return True
            return super().write(reason, value)

    ca_driver_cls = Driver

    def _extend_pvdb(self):
        return {"STATUS": {"type": "int", "value": 0}}

    def _post_outputs(self, out_values, ts):
        self.ca_driver.setParam("STATUS", len(out_values))
        super()._post_outputs(out_values, ts)

Configuration

Runner.generate_config() can be used to generate a dict describing the default configuration for the model. You can either edit this on the fly, or serialize it and edit it by hand later.

print(Runner.generate_config(model=myModel))

An example configuration:

{
    'prefix': 'MY_PV_PREFIX:',
    'update_rate': 0.1, # Update period under which PVs will be batched together into one model.set(). Set to 0 to disable the window.
    'protocol': ['ca', 'pva'], # Serve this as both CA and PVA (the default)
    'echo_unconfirmed_writes': True, # Echo a written value before the model has accepted it
    'alarm_on_refused_write': False, # Alarm the CA PV when the model refuses a write
    'clamp_writes': False, # Clamp a written value into the variable's value_range
    'control_pvs': True, # Serve the runner's own {prefix}RESET control PV
    'variables': {
        'input_a': {
            'name': 'input_a',
            'pv': 'input_a_pv',
            'mode': 'rw', # 'rw' means we can read and write this PV
            'precision': 3, # Optional, float scalars only: display precision (0..17), CA `prec` and PVA `display.precision`
            'description': 'Input A' # Optional, scalar/str/bool/enum only: PVA `display.description`; defaults to the variable's own description (lume-base >= 0.6)
        },
        'output_b': {
            'name': 'output_b',
            'pv': 'output_b_pv',
            'mode': 'ro' # 'ro' means the PV is read-only
        }
    }
}

Consumer contract

A deployment that configures the runner, supplies its model, or subclasses it relies on the names and rules below. They are stable across patch releases; anything not listed here is an implementation detail.

Configuration keys.

• config["variables"][name]["precision"]: optional. Must be an int (not a bool) in 0..17, and is allowed only on a float scalar variable — a ScalarVariable that is not an IntVariable. Int, bool, string, enum, array and Torch variables reject it. A configured precision reaches CA as prec and PVA as display.precision; a float without one keeps its previous display fields, display.format included.
• config["variables"][name]["description"]: optional. Must be a str, and is allowed on scalar, int, string, bool and enum variables; array and Torch variables reject it. Without one, the variable's own description is used where the installed lume-base has it (0.6 and later). It reaches PVA as display.description; an empty string means no description. The model's variable is never modified.
• config["tick_interval_s"]: optional. Absent or None means no periodic passes. Otherwise it must be an int or float (not a bool), finite and greater than zero, in seconds.

Every violation raises ValueError from the Runner constructor, naming the variable and the key. A variable's value_range always comes from the model's Variable: a value_range key in the config entry is ignored.

The output_severity hook. A model may define

def output_severity(self, names: list[str]) -> dict[str, dict[str, str]]:
    return {"some_output": {"condition": "udf"}}

It is called once per pass, on the run-loop thread, before anything is published, with the names of the outputs that pass publishes. Each name it reports "udf" is published as (INVALID, UDF) on both transports until a later pass stops reporting it. Only requested names are evaluated: keys outside names are ignored, so a model may report on outputs the pass does not publish. For a requested name, anything other than {"condition": "udf"} — an unknown condition, a non-dict entry, a reply that is not a dict — raises ValueError, nothing is published, and the pass fails as any failed pass does (the model rolls back and every waiting put completes with the error).

Reporting a name undefined does not excuse its value. model.get validates every output against its variable before publishing starts, so an undefined output must still return a type-valid value: a float may be NaN, and an enum's value must be one of its options. An invalid value fails the pass.

Alarm-aware _generate_value. _generate_value(name, value, ts) applies the UDF alarm to any name currently undefined, so a subclass publishing through it — its own echo, an extra post — carries the model's latest verdict without further work. _pack_value builds the same Value without that overlay. One race remains: a _generate_value called off the run-loop thread for a name, between the moment a pass records its new verdict and the moment that pass publishes the name, may carry the previous verdict. The next pass that publishes the name corrects it, which with tick_interval_s set happens within one tick.

Periodic-pass signals. Every queued item carries item["tick"]: False for a write or reset, True for a periodic pass. Read it as item.get("tick", False), since items a subclass builds may lack the key. During a pass, self._pass_is_tick is true only when every item of the batch was a tick and the batch carries no input values and no reset; it is set before the pass's jobs run, so _cycle_output_names and _post_outputs can read it. A subclass running with update_rate of zero may equally treat "input values present" as the mark of a write pass.

Intended wire changes. Three differences a client can observe are deliberate:

1. An IntVariable is served on PVA as an NTScalar "i" (int32, the width of a CA long) rather than a double, and reads back as an integer.
2. String and bool NTScalars and NTEnums carry a display block.
3. When building a pass's outputs fails, nothing from that pass is published on either transport. Previously a CA conversion error could leave part of the pass published.

Relationship to lume-pva

This distribution exists so that changes can be exercised against a real deployment before they are proposed upstream. It is a staging area, not a long-lived divergence: each entry below is either an intended upstream pull request or a packaging consequence of publishing under a second name, and the distribution retires once the upstream ones are merged and released.

Intended upstream pull requests

Fork-local changes

Removing the remote-input mode also removed what depended on it: the remote PV mode, the remote_model_mode config key, the remote_inputs argument to generate_config, snapshot mode, and the {prefix}SNAPSHOT control PV, whose only purpose was to trigger a pull from remote inputs.

Supported Variables

Supported variable types and their metadata fields.

ScalarVariable and IntVariable

Represented as NTScalar with a double or int value field (depending on variable type).

Supported metadata:

• timestamp
• display.units
  • ScalarVariable.unit
• control.limitLow
  • ScalarVariable.value_range[0]
• control.limitHigh
  • ScalarVariable.value_range[1]
• alarm.severity and alarm.status (PVA only)
  • Set from the value's position relative to value_range: a value strictly outside it is a MAJOR alarm, a value anywhere within it — including at either limit — is no alarm.

On CA, value_range is served as the display limits (lolim/hilim) and is not served as an alarm threshold. pcaspy compares its lolo/hihi thresholds inclusively, so a range published as an alarm limit puts a value driven to either end of its own legal span into MAJOR alarm. A CA client therefore sees no range-derived alarm at all, while a PVA client still sees one for a value outside the range.

NDVariable

Represented as NTNDArray with data representation matching the numpy shape and dtype.

Supported metadata:

• timestamp

TorchScalarVariable

Requires the torch extra (pip install 'lume-pva-apg[torch]').

Represented as NTScalar with a double value field.

Supported metadata:

• timestamp

TorchNDVariable

Requires the torch extra (pip install 'lume-pva-apg[torch]').

Represented as NTNDArray with data representation matching the Tensor shape and dtype.

Supported metadata:

• timestamp

BoolVariable

Represented as NTScalar with a bool value field.

Supported metadata:

• timestamp

StrVariable

Represented as NTScalar with a str value field.

Supported metadata:

• timestamp