Facility Relations#

A relation says how two parts of the machine depend on each other: a magnet is powered by a supply, a supply sits in a rack, a monitor is read out by a chassis. OSPREY records each such statement as a claim in the facility file, never as a field on a device. This page explains that choice and follows a claim from its record to the views that read it. The record format is in Describe your facility; what the graph writes for a claim is in Facility Graph Contracts.

Relation claims: the records they come from, the standing the build gives them, the place a located_in claim projects, and the views that read either Read left to right in four columns. Column 1, the records. Relations, in records/relations.yaml: each claim names a type, a subject and an object, a basis of stated or inferred (an inferred claim names its rule), and a source citing a document, its version, its state and a locator; for example SR/QF05-PS located_in HALL/ROW3/RK07. Documents, in documents.yaml: each has an id, a title, a kind and a system, such as rack-layout and cable-schedule. Policy, in policy.yaml, is optional: a precedence of document kinds per relation type, and stated_over_inferred, true unless set false. Places and devices, in records/places.yaml and records/devices.yaml, and groups, are the ends a claim names; a device may have no place of its own. Column 2, standing. A claim whose shape breaks a rule stops the build with relation-invalid: an end naming no device, place or group, or more than one; a kind the type does not allow at that end; basis inferred without a rule; a required attribute left out; or a subject equal to its object. Sound claims, with the documents and the policy, get a standing per key: the claims on one key group by the object they state; with a policy they rank by the precedence of their document's kind, then stated before inferred. A claim is accepted when its key has one object or its group ranks strictly best, contested when the objects disagree and no group wins, and superseded when it ranks below the winner. The demo has 16 accepted and 2 contested claims. Standing raises warnings, and the build goes on: relation-contested, one per key a dispute leaves unsettled; relation-coarse, one per type, for a claim with a place end where the type allows a device, or with a key attribute, port or unit left out; and also identity-ambiguous, part-cycle and relation-stub. Column 3, projection. Accepted located_in claims give Device.place, only when the device has no place yet (an authored place, a fix, an imported place or a span comes first), no claim on its key is contested, and the accepted claims that are not coarse name exactly one place. The device then carries provenance.place_from: relation; the claim's unit is not copied. In the demo SR/BPM13-EL takes HALL/ROW3/RK08, one place with no dispute; SR/QF05-PS takes no place, because rack-layout and cable-schedule disagree, so its key is contested and warned. Column 4, views. The graph, data/graph/facility.ttl, reads every standing: an accepted claim is an edge under its type's predicate, such as poweredBy, cabledTo or locatedIn; a contested claim is an edge under the predicate's Contested twin, such as locatedInContested; a superseded claim is no edge. The claims setting, all, contested or none, chooses which claims also get a narad_sem:Claim node. basis: stated drops the inferred claims, and the locatedIn of a projected place that no stated claim backs. The views that read the projected place: facts, with its place counts and the classes of unplaced devices; the channel finder in hierarchical mode, whose levels come from the places that hold channels; and the channel finder in middle_layer mode, whose System is the top place of the device. The views that read no relations: the channel finder in in_context mode, pyaml, simulator, bluesky, limits and benchmarks; a claim changes none of them. Footer: warnings never stop the build, relation-invalid does; a disputed key projects nothing, and its warning is the report. 1 · RECORDS 2 · STANDING 3 · PROJECTION 4 · VIEWS RELATIONS records/relations.yaml claim: type, subject, object basis: stated | inferred + rule source: document, version, state, locator SR/QF05-PS located_in HALL/ROW3/RK07 DOCUMENTS documents.yaml id, title, kind, system rack-layout, cable-schedule, … POLICY · OPTIONAL policy.yaml precedence: document kinds, per relation type stated_over_inferred (true) PLACES AND DEVICES records/places.yaml, records/devices.yaml, groups the ends a claim names a device may have no place: projection (3) can give one RELATION-INVALID · BUILD STOPS an end names no kind, or two a kind the type does not allow inferred without a rule a required attribute left out subject equal to object STANDING · PER KEY claims on one key group by the object they state; with a policy they rank by document kind, then stated before inferred accepted · one object, or best contested · objects tie superseded · ranked below demo: 16 accepted, 2 contested WARNINGS · THE BUILD GOES ON relation-contested · per key a dispute leaves unsettled relation-coarse · per type a place end where a device fits; a key attribute, port or unit left out + identity-ambiguous, part-cycle, … EVERY STANDING LOCATED_IN → DEVICE.PLACE only when: · the device has no place yet (authored, fix, imported or span come first) · no claim on its key contested · the accepted claims that are not coarse name one place provenance.place_from: relation the claim's unit is not copied IN THE DEMO SR/BPM13-EL → HALL/ROW3/RK08 one place, no dispute SR/QF05-PS → no place rack-layout and cable-schedule disagree: contested, warned GRAPH · READS EVERY CLAIM data/graph/facility.ttl accepted → edge: poweredBy, cabledTo, locatedIn, … contested → …Contested twin (locatedInContested) superseded → no edge claims: all | contested | none picks narad_sem:Claim nodes basis: stated drops inferred claims, and a projected locatedIn no stated claim backs READ THE PROJECTED PLACE facts: place counts, classes of unplaced devices channel finder hierarchical: levels from channel places channel finder middle_layer: System = the device's top place READ NO RELATIONS channel finder in_context, pyaml, simulator, bluesky, limits, benchmarks a claim changes none of them Warnings never stop the build; relation-invalid does. A disputed key projects nothing: its warning is the report.

Claims, not slots#

A slot such as powered_by on a device holds one value. Two sources that disagree about it are two layers writing one field, and the build stops with layer-conflict: the facility cannot hold the disagreement it actually has. A slot also has nowhere to put the port, the cable number or the document the value came from, and a place or a group cannot fill one.

A claim is one record from one source, with an id of its own. It names a relation type, a subject and an object (each a device, a place or a group, with an optional port or unit), a basis (stated, or inferred with the rule that inferred it), typed attributes, and a source citing a document, its version, its state and a locator. Two claims never merge, so two sources that disagree build as two claims, and the build decides what the disagreement means.

The chain#

Records. records/relations.yaml holds the claims. documents.yaml declares the documents they cite, each with a kind (rack-layout, cable-schedule, …). policy.yaml is optional; its relations.precedence ranks document kinds per relation type or by default, and stated_over_inferred (true unless set false) ranks a stated claim before an inferred one.

Standing. A claim whose shape breaks a rule of its type stops the build with relation-invalid. Every sound claim gets a standing, decided per key: what the type allows one object for, such as the subject of located_in or the subject and port of powered_by. Claims on one key group by the object they state. One group is accepted. Several groups without a policy are contested. With a policy they rank by their document’s kind, then by basis; the strictly best group is accepted, the rest superseded, and a tie at the best stays contested. A claim on several keys keeps its worst standing. A claim that states less than the facility knows (a place end where the type allows a device, or a key attribute, port or unit left out) is coarse: accepted, but no part of the ranking. Standing raises warnings and the build goes on: relation-contested once per unsettled key, relation-coarse once per type.

Projection. Accepted located_in claims fill Device.place when the device has no place yet, no claim on its key is contested, and the accepted claims that are not coarse name exactly one place. The device then carries provenance.place_from: relation; the claim’s unit is not copied. A disputed key projects nothing, and its warning is the report.

Views. The graph view reads every standing: an accepted claim is an edge, a contested claim is an edge under the contested twin of its predicate, a superseded claim is no edge, and the facility_graph settings choose which claims also become claim nodes. The facts view and the channel finder’s hierarchical and middle-layer indexes read the projected place, not the claims. The in-context index, pyAML, simulator, Bluesky, limits and benchmark views read no relation; a claim changes none of them.

The sector-3 example#

The example facility osprey init ships carries one worked example around the storage-ring quadrupole SR/QF05 and the monitor SR/BPM13: four documents (an equipment list, a rack layout, a cable schedule and a network plan), eleven devices, the rack row HALL/ROW3 with racks RK07 and RK08, the vacuum-section group SR/VS03, and 18 claims, 16 stated and 2 inferred, and a policy.yaml. Built as it ships, 17 claims are accepted and 1 superseded, and osprey facility validate prints one warning and exits 0.

The disputed rack. qf05-ps-rack-a puts the supply SR/QF05-PS in HALL/ROW3/RK07, citing the released rack layout; qf05-ps-rack-b puts it in HALL/ROW3/RK08, citing the in-work cable schedule. The shipped policy.yaml states precedence: {located_in: [rack-layout, cable-schedule]}, so the rack layout ranks first: qf05-ps-rack-a is accepted and qf05-ps-rack-b superseded. SR/QF05-PS takes the place HALL/ROW3/RK07 with place_from: relation; the graph holds one LOCATEDIN edge for it, and the superseded claim is no edge.

The coarse cable. w-03-0240 cables port A of SR/BPM13 to the rack HALL/ROW3/RK08 rather than to a device in it. The claim is accepted and the build warns relation-coarse for cabled_to.

The inferred readout. bpm13-readout says SR/BPM13 is read out by channel CH1 of the chassis SR/BPM13-EL. No document states it; the rule bpm-electronics-in-cable-destination-rack inferred it from the cable schedule row of the coarse cable. The chassis itself takes its place HALL/ROW3/RK08 from its uncontested rack claim bpm13-el-rack.

The undecided identity. qf05-identity is an inferred same_as between SR/QF05 and SR/MAG-Q-0301, by the rule family-and-ordinal-match. same_as records an identity nobody has decided; it merges nothing. SR/MAG-Q-0301 counts as a quadrupole of its own in the facts view, the graph and the demo’s device counts.

The vacuum section. The group SR/VS03 states kind: section. It keeps its description and its members and is no family: it describes none of its members and is no channel-finder Family.

Without the policy. With policy.yaml deleted neither document ranks first: both rack claims are contested (16 accepted, 2 contested), the build also warns relation-contested, SR/QF05-PS stays unplaced, and the graph holds two LOCATEDINCONTESTED edges in place of the LOCATEDIN.

Divergence from NARAD#

The NARAD seed schema’s device record declares four relation slots: powered_by, housed_by, controller and local_system. In the seed they are optional and untyped: no target kind, no cardinality, no attributes, no source. None is carried into core.yaml, and since none is required they are not in loosenings.yaml either. Each is a relation type instead: powered_by is powered_by, housed_by is located_in for a place or part_of for a chassis, and controller is controlled_by. local_system maps to no type; where a device sits is its place.