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 |
|---|---|
|
|
|
On a setpoint, the address of its readback. Absent, the build pairs the
setpoint with the readback that shares its |
|
On a float setpoint, how close its readback must come before a move
counts as done: |
|
The one device or place the channel belongs to, |
|
The devices that share the channel, for a supply feeding several. |
|
A signal role of the shared vocabulary, such as |
|
Free text. A channel that states no description and names a signal is given one composed from its owner, its signal and its unit. |
|
The one name a person reads for the channel, and other names in use. |
|
Free words. |
|
|
|
The labels of a |
|
The dimensions of a |
|
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. |
|
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
unitbut names no place;an end names a kind the type does not allow there;
basis: inferredcomes without itsrule;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.
Export.
osprey facility import mml --print-exporter > mml_export.mprints the exporter. Run it in MATLAB once per sub-machine.Draft the mapping. The first run of
osprey facility import mml <stem>.ao.jsonwritesimported/mml/mapping.yamland stops withimport mml: mapping-draft. The mapping holds every decision the export does not state.Review the mapping. Replace every
null. Four top-level blocks are required:models(what each exported system is called as a model),section_order,familiesanddirections(whether each field isreadorwrite). Each family states itsaliases,description,provenance,channelsandfields, and may state aclass, itsdevices, arenameand thebrancha new class extends. Three top-level blocks are optional:facility(the identity the first import seeds),branches(device classes the mapping adds, each with itsparent) andjudgments. Where the export leaves a family’s shape open,judgments:carries one slot per question: a channel row beyond the family’s devices (drop,deviceor{field: <name>}), a device no channel binds (droporkeep), and a channel shared across devices (keep_allor an owning device).Wire the model. Each model’s
wiringblock in the mapping lists the families the model drives or reads. Per family it names theelement_field, the family field the model wires;engine, the deck attribute, index or axis the field acts on; andcalibration,linearortable. From it the import writes one wiring record per address intoimported/mml/models.yaml, and the deck it serves, its wired elements renamed, intoimported/mml/decks/<model>.json;osprey buildcopies both into the simulator view the simulator serves.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 oneresponse 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.
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 |
|
|
|
names |
|
|
|
places |
|
|
|
members |
|
|
|
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:
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
place,within,document,version
RK01,BR,PS-LIST,C
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_classorobject_class, a class of the facility or the shared vocabulary; one row’s class holds for every row naming that device.--stub-unknownstubs a class-less end asUnidentified, and the build reports such stubs withrelation-stub. Without either, the row is refused, so a misspelt name stops the import. Place and group ends are never stubbed.Places.
withinnames 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/RK01above, so one name may repeat under several parents. The build reports a place created top-level with no citation withplace-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 orimporteddate: 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:
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:
pulsesits on a channel that is not a waveform, or itsdriveris not an unwired float channel, or itsenableis not an unwired bool channel;gatesits 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; orgateddoes not fit the channel’s type as above;gateinputs form a cycle (agated bybgated bya).
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:
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 |
|---|---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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,showand the importers.