Describe your facility#

A deployment describes its facility once, as source files under data/facility/. osprey build combines them into one facility file, build/facility.json, and writes every file a service reads from it: the channel finder’s index, the limits database, the simulator’s channel list, the knowledge graph. Nothing else in the deployment lists a channel. The machine facts can instead live in a machine repository.

This page walks the tree a fresh osprey init --preset demo writes, file by file, then the three ways records get into it: by hand, from an importer, and through a fix. What the build writes from the result is in Facility File and Its Views.

The tree#

data/facility/
  identity.yaml             who the facility is
  records/
    places.yaml             the facility's own tree of places
    devices.yaml            the devices
    channels.yaml           the control-system channels
    groups.yaml             named sets of devices
    relations.yaml          claims that two records are related
  classes.yaml              device classes the facility adds
  signals.yaml              signal roles the facility adds
  models.yaml               the simulation models and their wiring
  decks/                    the decks those models name
  limits.yaml               the write limits
  seeds.yaml                how a channel no model wires behaves when simulated
  measurement/<model>.yaml  the measurements a model allows
  scenarios/<name>.yaml     ways the simulated machine departs from its baseline
  documents.yaml            the source documents records and claims cite
  policy.yaml               how the build ranks competing claims
  fixes.yaml                corrections to records another source states
  imported/<layer>/         records an importer wrote
  knowledge/                the facility knowledge pages
  ariel/vocabulary.yml      the logbook shorthand ARIEL expands
  benchmarks/               the channel-finder benchmark queries

Every file is optional. A deployment with no data/facility/ at all builds a facility with no channel, and each file added states more. The demo preset ships all of them except signals.yaml, fixes.yaml and imported/; the hello-world preset ships identity.yaml, records/channels.yaml, limits.yaml and seeds.yaml.

Check the tree at any time, without writing anything:

osprey facility validate
osprey facility show
osprey facility show SR:MAG:HCM:01:CURRENT:SP

validate builds the tree and renders the main profile’s views in memory. It prints the errors of the first check that fails, one line each, facility: <kind>: <record kind> <id> — <detail>; fix: <remedy>; a clean tree prints its warnings the same way. show prints the identity, the record counts, the models and the views; given an id it prints that record with the layer and file each of its fields came from, the fields the build filled and the fixes applied. Both are described in full under osprey facility.

Identity#

identity.yaml holds the facility’s code and, optionally, its name and description:

code: ca
name: Example Research Facility

The code names the facility in the knowledge graph and in each served model’s status channel, <code>:SIM:<model>:STATUS. Without the file the code is the project name, folded to letters, digits and underscores. The name is what agents and panels call the facility; a facility that states none is called by the project name.

Records#

The files under records/ each hold a list of records of one kind. Every record has an id, and a record states only what its author knows: a field left out is either filled by the build or stays absent.

Places are the facility’s own tree. A place’s id is its path, SR/SECT1 under SR; level is the facility’s word for that depth. A place with a span covers a stretch of one model’s deck, from the from_marker element up to the to_marker element, or to the deck’s end without one. A device the deck puts inside it belongs to the deepest such place, unless the device states its own place in an authored record or a fix. A place only an importing layer states (place_from: imported) yields to a span that is that place or lies inside it, and stands under a span that holds it or where none holds the device; any other span holding the device contradicts it, and the build stops place-conflict. A device still without a place takes the one its located_in claims name (place_from: relation) when no claim on its key is contested and the accepted claims that are not coarse all name one place; the claim’s unit is not copied.

- id: SR/SECT1
  level: sector
  span:
    model: SR
    from_marker: SECT1
    to_marker: SECT2

Devices name a class, either one of the shared vocabulary’s classes (Quadrupole, BeamPositionMonitor, Gauge) or one the facility adds in classes.yaml. A device may state its place, a label, other names people use for it, and a position: s in metres along the deck of its model. A device a model wires takes its position from the deck.

Channels are the control-system addresses. A channel’s id is its full address, written exactly as the control system serves it; no part of the address means anything to OSPREY. What a channel is comes from its fields:

Field

Meaning

role

setpoint, readback or none. Absent means readback.

pair

On a setpoint, the address of its readback. Absent, the build pairs the setpoint with the readback that shares its on, or its endpoint_of, or neither, and whose signal names the same quantity (gap_setpoint with gap_readback). It does so only when exactly one setpoint and one readback of that quantity share it, no stated pair names the readback, and the two agree in value_type, options and shape; else it pairs the setpoint with itself.

tolerance

On a float setpoint, how close its readback must come before a move counts as done: {absolute: <x>} in the channel’s unit or {relative: <fraction>} of its seed’s nominal. The setpoint and its readback must both state a unit.

on

The one device or place the channel belongs to, {device: <id>} or {place: <id>}. Absent, the channel belongs to nothing.

endpoint_of

The devices that share the channel, for a supply feeding several.

signal

A signal role of the shared vocabulary, such as current_setpoint or gap_readback. A facility cannot add one.

unit, description

Free text. A channel that states no description and names a signal is given one composed from its owner, its signal and its unit.

label, names

The one name a person reads for the channel, and other names in use.

tags

Free words. in_context narrows the in-context channel-finder index to the tagged channels.

value_type

float, int, bool, enum, string or waveform. Absent means float.

options

The labels of a bool or enum channel.

shape

The dimensions of a waveform channel.

precision

Optional, on float channels only: an integer from 0 to 17, the number of decimals a display shows. The simulator serves it as the channel’s display precision on both Channel Access and PVAccess, and serves a float channel that states none with 4.

former_addresses, attributes

Addresses the channel was known by, and a free map carried verbatim.

- id: SR:MAG:QF:01:CURRENT:SP
  role: setpoint
  pair: SR:MAG:QF:01:CURRENT:RB
  tolerance:
    absolute: 0.01
  unit: A
  label: focusing quadrupole current setpoint
  description: Focusing quadrupole current setpoint

Groups are named sets of devices: an id, a description in the facility’s words and the members. A group says which devices belong together; what a channel means stays on the channel. Its kind is family (the default: devices of one sort, described by the group) or section (things that belong together, such as a vacuum section). Only a family is a channel-finder Family and gives its members their purpose text.

Relations are claims, one per source, that two records are related: a type, a subject and an object, each naming one device, place or group. The build writes each claim’s standing: accepted, contested when claims state different objects and none ranks first, or superseded; and contests, the ids of the claims it disagrees with, when there are any. A claim stops the build with relation-invalid, naming the claim, on any of seven conditions:

  • an end names no device, place or group;

  • an end names more than one of them;

  • an end gives unit but names no place;

  • an end names a kind the type does not allow there;

  • basis: inferred comes without its rule;

  • a required attribute is missing;

  • the subject and object name the same end, port included.

policy.yaml ranks competing claims by the kind of document they cite, as declared in documents.yaml: relations.precedence lists kinds per relation type or as default. Between claims whose documents rank the same, a stated claim breaks the tie over an inferred one unless stated_over_inferred: false. Without a policy, competing claims stay contested.

Claims reach the knowledge graph as edges between their ends, by standing: an accepted claim is a plain edge, a contested one a separate contested edge, a superseded one no edge. Each claim is also a node carrying its source, so a query can go from an edge to the document behind it (Facility Graph Contracts).

classes.yaml adds device classes the shared vocabulary lacks, each as the child of an existing class:

- class: Undulator
  parent: Magnet
  aliases: [insertion device, ID]

signals.yaml adds signal roles the vocabulary lacks; one it already has is refused:

- name: taper_setpoint
  aliases: [gap taper]
  description: Commanded gap difference between an undulator's two ends.

Layers#

Records reach the build from several sources at once, and each source is a layer. records/, models.yaml, seeds.yaml and measurement/ are the layer authored; each directory under imported/ is the layer of that name. A layer states only the fields its source states.

The build merges the layers field by field: per record and per field it takes the one value any layer states. Two layers stating different values for one field stop the build with layer-conflict, naming the record. A set fix settles it (see Fixes). A group’s members are the exception: the group carries every member any layer states, and layers that state different members get a members-disagree warning naming which source states which member, until they agree or a set fix names members. A place’s or device’s scheme_names are joined too, so a layer can add a name to a record another layer states; one name in one scheme that two layers state with different content is still a layer-conflict.

The importers are osprey facility import mml, osprey facility import list and osprey facility import relations.

A Middle Layer export#

osprey facility import mml reads a MATLAB Middle Layer export into data/facility/imported/mml/. From the export to a served model it is five steps; each is described in Import a Middle Layer export.

  1. Export. osprey facility import mml --print-exporter > mml_export.m prints the exporter. Run it in MATLAB once per sub-machine.

  2. Draft the mapping. The first run of osprey facility import mml <stem>.ao.json writes imported/mml/mapping.yaml and stops with import mml: mapping-draft. The mapping holds every decision the export does not state.

  3. Review the mapping. Replace every null. Four top-level blocks are required: models (what each exported system is called as a model), section_order, families and directions (whether each field is read or write). Each family states its aliases, description, provenance, channels and fields, and may state a class, its devices, a rename and the branch a new class extends. Three top-level blocks are optional: facility (the identity the first import seeds), branches (device classes the mapping adds, each with its parent) and judgments. Where the export leaves a family’s shape open, judgments: carries one slot per question: a channel row beyond the family’s devices (drop, device or {field: <name>}), a device no channel binds (drop or keep), and a channel shared across devices (keep_all or an owning device).

  4. Wire the model. Each model’s wiring block in the mapping lists the families the model drives or reads. Per family it names the element_field, the family field the model wires; engine, the deck attribute, index or axis the field acts on; and calibration, linear or table. From it the import writes one wiring record per address into imported/mml/models.yaml, and the deck it serves, its wired elements renamed, into imported/mml/decks/<model>.json; osprey build copies both into the simulator view the simulator serves.

  5. Accept. Run osprey facility validate. For each model whose export carried a response matrix it compares that matrix with the one the imported model computes and prints one response check <model>: … line. A failing check exits 1. A passing one is the acceptance: the calibrations, nominals and element bindings of the imported model agree with the machine the export was sampled on.

The record files under imported/mml/ belong to the import and are rewritten by every run; mapping.yaml is yours and is only drafted when absent. The import also creates limits.yaml, seeds.yaml, identity.yaml, measurement/<model>.yaml and scenarios/readout.yaml when they do not exist, and never rewrites them afterwards. It creates classes.yaml when absent; when the file exists, the import appends only the classes it lacks and leaves its rows as written. It replaces a bundled facility, saying so in one line, and refuses only hand-written records of the kinds it writes, naming each file. That refusal guards the first import: once an imported layer exists, records you write by hand beside it stay through every later import, and the build combines them with the layers.

A channel list#

osprey facility import list FILE reads a CSV of channel addresses into data/facility/imported/list/. A header row names address and any of role, pair, device, place, unit, description, tags, s and model; a file with no address column holds one address per line.

channels.csv#
address,role,pair,device,s,unit,description
SR:MAG:QF:01:CURRENT:SP,setpoint,SR:MAG:QF:01:CURRENT:RB,QF01,1.5,A,Focusing quadrupole current
SR:MAG:QF:01:CURRENT:RB,,,QF01,1.5,A,Focusing quadrupole current readback

The files under imported/list/ belong to the import and are replaced by each run, so they are never edited by hand: a correction goes into the CSV or into fixes.yaml. Each device a row gives an s is written to imported/list/devices.yaml; a model column names the model whose deck s is measured along. A run whose list states no s leaves no devices.yaml, and a device the list then names needs a record of its own, such as an add fix, or the build stops with reference-missing. The list import runs the same step as every format: it replaces a bundled facility and refuses only hand-written channel and device lists, so it still positions a list against your own deck, models and places.

Relation tables#

osprey facility import relations TABLE --layer NAME reads relation claims, from a cable schedule or a rack list, into data/facility/imported/<NAME>/. TABLE holds the claims; three optional tables hold what the claims lean on. Each is UTF-8 CSV with a header row naming its columns in any order; an empty cell is absent.

Table

Option

Required columns

Optional columns

claims

TABLE

type, subject, object

subject_kind, object_kind (device, place or group; empty means device), subject_port, object_port, object_unit, attrs (key=value pairs separated by ;), basis, rule, subject_class, object_class

names

--names

thing, name, scheme

basis, rule

places

--places

place

within, basis, rule

members

--members

group, member

member_kind, group_kind (family or section)

Every table also takes the citation columns document, version, state, locator and imported (an ISO date). basis: inferred needs a rule. Against the demo preset, these three tables put both booster focusing quadrupoles on one new supply in a new rack:

cables.csv#
type,subject,object,object_kind,object_class,document,version,locator
powered_by,BR/QF01,BR/QF-PS,,PowerSupply,PS-LIST,C,p. 4
powered_by,BR/QF02,BR/QF-PS,,,PS-LIST,C,p. 4
located_in,BR/QF-PS,RK01,place,,PS-LIST,C,p. 2
racks.csv#
place,within,document,version
RK01,BR,PS-LIST,C
names.csv#
thing,name,scheme,document
BR/QF-PS,PS-QF-B,cable-schedule,PS-LIST
osprey facility import relations cables.csv --layer cables --places racks.csv --names names.csv

Each end and name resolves against the whole facility except the layer being replaced. The rules:

  • Stubs. A device end the facility lacks is created as a stub only when its row states subject_class or object_class, a class of the facility or the shared vocabulary; one row’s class holds for every row naming that device. --stub-unknown stubs a class-less end as Unidentified, and the build reports such stubs with relation-stub. Without either, the row is refused, so a misspelt name stops the import. Place and group ends are never stubbed.

  • Places. within names an authored place or one the places table creates, never one another imported layer creates, so where a layer puts a place does not depend on import order. A place’s id is its path, BR/RK01 above, so one name may repeat under several parents. The build reports a place created top-level with no citation with place-unplaced.

  • Members. The members table creates a group no other source has. A row naming a member another source’s group lacks adds it: the layer then states that group too, with every member its rows name.

  • Names. The names table names any device or place. For one the authored file or another layer states, the layer writes a record carrying only the id and the names, and the build joins them with the names the other sources state. A name for a group is refused: a group has no scheme_names.

  • Ids. A claim’s id is <NAME>/<type>/<hash>. The hash covers the type, both ends (in either order for a symmetric type), the ports, the type’s key attribute and the cited document, never its version, locator or imported date: a new revision of the schedule keeps every id. A symmetric row written reversed, or a repeated row, is one claim; one fact cited from two documents is two claims. The import never stamps a date of its own.

The layer is replaced whole: relations.yaml, devices.yaml (the stubs), places.yaml and groups.yaml, each written only when it holds a record, and a byte copy of each table. A file of the previous run this one does not write is removed. Nothing outside imported/<NAME>/ changes: unlike the other importers, it neither replaces a bundled facility nor refuses hand-written records. A refused row prints one source-invalid line, every refusal is reported and the import writes nothing. The layer name matches [a-z0-9][a-z0-9_-]* and is not authored, list or mml.

Fixes#

fixes.yaml corrects a record another source states, without editing that source. Each fix names a record and gives the reason. These two correct the channel list above:

schema: osprey.facility.fixes/1
fixes:
  - op: set
    kind: channel
    id: SR:MAG:QF:01:CURRENT:SP
    fields: {description: Focusing quadrupole current setpoint}
    was: {description: {list: Focusing quadrupole current}}
    why: The list's description leaves out that this is the setpoint.
  - op: add
    kind: device
    id: QF02
    record: {class: Quadrupole}
    why: Missing from the list.

set replaces the fields it names, each whole; add adds a record; drop removes one. kind is place, device, channel, wiring, group, model or relation. A set states under was the value each layer held when the fix was written. When was is missing, or a later import changes that value, the build stops with fix-stale and prints the corrected fix to paste in its place, so a fix never silently outlives the fact it corrected. The result does not depend on the order of the fixes.

osprey facility show <id> lists the fixes applied to a record.

Limits#

limits.yaml holds the write limits, one record per channel. The demo preset ships this one:

limits.yaml#
records:
# Symmetric range: the corrector current stays within [-12, 12].
- address: SR:MAG:HCM:01:CURRENT:SP
  min_value: -12.0
  max_value: 12.0
# Range plus largest single step: the cavity frequency in MHz.
- address: SR:RF:CAVITY:01:FREQUENCY:SP
  min_value: 500.0
  max_value: 500.8
  max_step: 0.01
# Blocked outright: no write reaches this setpoint.
- address: SR:VAC:ION-PUMP:01:VOLTAGE:SP
  writable: false
# Every other corrector: within [-12, 12] in SR, where the supplies clamp, and [-10, 10] elsewhere.
- {address: BTS:MAG:HCM:01:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:HCM:02:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:HCM:03:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:HCM:04:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:HCM:05:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:HCM:06:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:HCM:07:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:HCM:08:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:HCM:09:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:VCM:01:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:VCM:02:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:VCM:03:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:VCM:04:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:VCM:05:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:VCM:06:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:VCM:07:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:VCM:08:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: BTS:MAG:VCM:09:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: GTL:MAG:HCM:01:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: GTL:MAG:HCM:02:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: GTL:MAG:HCM:03:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: GTL:MAG:HCM:04:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: GTL:MAG:VCM:01:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: GTL:MAG:VCM:02:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: GTL:MAG:VCM:03:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: GTL:MAG:VCM:04:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LINE:MAG:HCM:01:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LINE:MAG:HCM:02:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LINE:MAG:HCM:03:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LINE:MAG:HCM:04:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LINE:MAG:VCM:01:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LINE:MAG:VCM:02:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LINE:MAG:VCM:03:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LINE:MAG:VCM:04:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LN:MAG:HCM:01:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LN:MAG:HCM:02:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LN:MAG:VCM:01:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LN:MAG:VCM:02:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LTB:MAG:HCM:01:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LTB:MAG:HCM:02:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LTB:MAG:VCM:01:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LTB:MAG:VCM:02:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LTB:MAG:VCM:03:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LTB:MAG:VCM:04:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LTB:MAG:VCM:05:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LTB:MAG:VCM:06:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: LTB:MAG:VCM:07:CURRENT:SP, min_value: -10.0, max_value: 10.0}
- {address: SR:MAG:HCM:02:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:03:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:04:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:05:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:06:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:07:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:08:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:09:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:10:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:11:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:12:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:13:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:14:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:15:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:16:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:17:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:18:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:19:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:20:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:21:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:22:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:23:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:24:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:25:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:26:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:27:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:28:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:29:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:30:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:31:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:32:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:33:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:34:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:35:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:36:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:37:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:38:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:39:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:40:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:41:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:42:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:43:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:44:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:45:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:46:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:47:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:48:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:49:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:50:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:51:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:52:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:53:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:54:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:55:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:56:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:57:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:58:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:59:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:60:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:61:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:62:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:63:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:64:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:65:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:66:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:67:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:68:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:69:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:70:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:71:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:HCM:72:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:01:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:02:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:03:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:04:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:05:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:06:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:07:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:08:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:09:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:10:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:11:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:12:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:13:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:14:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:15:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:16:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:17:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:18:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:19:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:20:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:21:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:22:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:23:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:24:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:25:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:26:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:27:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:28:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:29:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:30:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:31:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:32:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:33:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:34:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:35:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:36:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:37:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:38:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:39:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:40:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:41:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:42:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:43:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:44:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:45:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:46:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:47:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:48:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:49:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:50:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:51:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:52:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:53:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:54:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:55:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:56:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:57:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:58:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:59:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:60:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:61:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:62:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:63:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:64:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:65:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:66:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:67:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:68:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:69:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:70:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:71:CURRENT:SP, min_value: -12.0, max_value: 12.0}
- {address: SR:MAG:VCM:72:CURRENT:SP, min_value: -12.0, max_value: 12.0}

A setpoint record with both min_value and max_value is writable within them; max_step bounds a single change; writable: false blocks every write; confirm: false turns off the re-read after a write.

osprey build renders the records into build/data/channel_limits.json, the file the connector’s reference monitor and the runtime’s limits check enforce on every write. That file is an output: a profile that ships its own stops the build. The file holds the records of limits.yaml and nothing else. What happens to a channel with no record is the deployment’s choice, control_system.limits_checking.mode: under exclusive the limits file is the complete list of writable channels and a channel without a record is refused; under optional a channel without a record is written with no limits. The hello-world and demo presets ship optional.

Seeds#

seeds.yaml says how a channel behaves in the simulator when no model wires it. It is keyed by address. The preset’s booster current starts at 1.2 mA with Gaussian noise:

BR:DIAG:DCCT:01:CURRENT:RB:
  nominal: 1.2
  noise:
    absolute: 0.01

nominal is the value at start; noise is Gaussian, {absolute: <sigma>} in the channel’s unit or {relative: <fraction>}; drift is {amplitude, period_s}; clamp is [low, high]; linear makes the value a weighted sum of other channels. A wired channel starts from its deck and needs no seed. The build stops with seed-invalid when a nominal, or a wired channel’s operating point, lies outside the min_value and max_value of the channel’s limits record.

pulse gives a waveform channel its trace. It names two other channels: driver, whose reading scales the trace, and enable, which switches it on. The trace’s shape is fixed in code, not in the seed; with enable off the trace is flat zero. The preset’s septum current waveform:

SR:MAG:SEPTUM:01:CURRENT:WAVEFORM:
  pulse:
    driver: SR:MAG:SEPTUM:01:CURRENT:SP
    enable: SR:MAG:SEPTUM:01:STATUS:ON

gate says what a channel does while an interlock-like input blocks it. inputs maps each input’s address to its blocking label; while any input reads its blocking label the channel takes gated, and otherwise it behaves as its other seed keys say. gated is typed by the gated channel: a factor greater than zero on a float channel (the value is scaled by it), a label on a bool or enum channel, an integer on an int channel. In the preset, the sum signal of the first beam position monitor in the gun-to-linac line drops to 1% of full beam while the gun’s heater or its high voltage is off:

GTL:DIAG:BPM:01:SUM:RB:
  nominal: 1.0
  gate:
    inputs:
      GTL:GUN:EGUN:01:HEATER_ON:RB: 'FALSE'
      GTL:GUN:EGUN:01:HV_ON:RB: 'FALSE'
    gated: 0.01

The build checks both keys and stops with value-invalid when:

  • pulse sits on a channel that is not a waveform, or its driver is not an unwired float channel, or its enable is not an unwired bool channel;

  • gate sits on a channel that is not float, int, bool or enum; an input is wired, is not a bool or enum channel, or names a label that channel does not have; or gated does not fit the channel’s type as above;

  • gate inputs form a cycle (a gated by b gated by a).

A pulse or gate input that names no channel stops the build with reference-missing.

topoff makes a float channel a stored current under top-off: it starts each period_s at ceiling and decays with the lifetime lifetime_h until the next refill. topoff_lifetime makes a channel read that lifetime, named by the channel that carries the topoff seed, so current and lifetime always agree.

SR:DIAG:DCCT:01:CURRENT:RB:
  topoff:
    ceiling: 500.0
    lifetime_h: 7.0
    period_s: 31.0
SR:DIAG:DCCT:01:LIFETIME:RB:
  topoff_lifetime:
    of: SR:DIAG:DCCT:01:CURRENT:RB

The channel holds the sawtooth’s mean, which is what its limits and the archive’s start state see. The build stops with value-invalid when topoff sits on a channel that is not float or lifetime_h or period_s is not above zero, and with seed-invalid when topoff has a nominal beside it or topoff_lifetime.of names no channel with a topoff seed. Live reads and the archive show the same sawtooth.

At run time the gate acts on the channel’s held value, after a linear sum; drift and noise are added on top and clamp applied. A gated float reads its value times the factor, so it keeps a small residual that still moves; a gated bool or enum reads the label gated; a gated int reads the integer gated. Each input is read as its own current value, its own gate included, so gates chain: an input that is itself gated blocks whenever its gate holds it at the blocking label. An input the simulator does not serve never blocks. Live reads, change notifications and the archive’s seeded history all see the same gated value.

Models and decks#

models.yaml lists the simulation models. A model has a name, the engine that runs it, the deck it runs over, the engine’s settings and a wiring list that ties channel addresses to elements of the deck:

- name: LINE
  engine: pyat
  deck: decks/LINE.json
  settings:
    pyat:
      solve: single_pass
      twiss_in:
        beta: [7.448848, 4.786082]
        alpha: [-1.333207, 0.885765]
  wiring:
  - address: LINE:DIAG:BPM:01:POSITION:X
    element: BPM01
    engine:
      axis: x
    calibration:
      curve:
        linear: {gain: 1.0, offset: 0.0}
      energy_scaling: none

The pyat settings may also carry error_elements, a list of {element: <name>, multipoles: true|false} naming deck elements no wiring record binds that a scenario may still misalign or give a multipole error; see Element errors in Virtual Accelerator.

A wiring record’s calibration converts between the channel’s hardware value and the engine’s physics value, as a linear gain and offset or a table. Channels no served model wires are served by the texture model from their seeds. Which models a deployment serves, and what a failed one looks like, is in Simulation models.

Measurement#

measurement/<model>.yaml states which measurements a model allows and what they use. The demo preset ships this one for its storage ring:

measurement/SR.yaml#
kinds:
- orm
- dispersion
- trm
- crm
- chromaticity_monitor
groups:
  bpm: SR/BPM
  hcor: SR/HCM
  vcor: SR/VCM
  quad: [SR/QF, SR/QD]
  sext: [SR/SF, SR/SD]
instruments:
  tune: SR:DIAG:TUNE:X
  rf: SR:RF:CAVITY:01:FREQUENCY:SP
n_step: 5
n_avg_meas: 1
fit_order: 2
sleep_between_step: 0.0
sleep_between_meas: 0.0
corrector_delta: 1.0e-05
quad_delta: 0.001
sextu_delta: 0.01
frequency_delta: 100.0

kinds names the allowed measurements: orm, dispersion, trm, crm and chromaticity_monitor. groups names the group, or the list of groups taken together, that plays each part (bpm, hcor, vcor, quad, sext) and instruments the channel each instrument is read or stepped on (tune, rf). Each kind needs its own members and step keys, and the build stops when the file allows a kind without them, names a member its model does not wire, or names a tune reading of one plane that no single reading of the other plane pairs with:

Kind

Groups and instruments

Keys

orm

bpm, hcor, vcor

corrector_delta

dispersion

bpm, hcor, vcor, rf

frequency_delta

trm

quad, tune

quad_delta

crm

sext, tune, rf

sextu_delta

chromaticity_monitor

tune, rf

n_step, n_avg_meas, fit_order, sleep_between_step, sleep_between_meas

A measurement OSPREY does not ship is a kind an installed package registers (Register a measurement kind). It is listed under kinds like the five, may name roles of its own under groups and instruments, and takes its own settings under kind_blocks.<kind>.

A model solved in a single pass allows only the kinds that run single pass; of the shipped ones, orm alone. A group plays one role; only hcor and vcor may name the same group. A role naming several groups is one pyAML array named after the role. The tools that run these measurements are in Measure with the pyAML tools.

Scenarios#

Each file under scenarios/ is one way the simulated machine departs from its baseline: value overrides, model and channel faults, its own motion (drivers, couplings, noise), archive history and logbook entries. The simulator activates the scenarios marked start: true when it first comes up; with such marks the profile states no simulation.default_scenarios. Writing and applying them is in Scenarios.

Knowledge#

knowledge/ is the facility knowledge bundle: the pages agents read about subsystems, devices and procedures. A page links itself to a device with the device_id key of its frontmatter; the build names a page whose id is no device of the facility and goes on. The bundle’s format is in The OKF Bundle.

Build#

osprey build runs the checks of osprey facility validate but the response check, stops at the first that fails, and then writes build/facility.json and the views into the deployment’s render and each login and image render.

See also

Facility File and Its Views

The facility file, each view the build writes from it and what reads it.

osprey facility

Every exit and message of osprey facility validate, show and the importers.