Register a measurement kind#
A measurement kind is a word a model’s measurement file lists under
kinds: (Describe your facility). OSPREY ships five:
orm, dispersion, trm, crm and chromaticity_monitor
(Measure with the pyAML tools). A deployment whose machine needs another adds
it from an installable package, through the same registry the five go
through, with no OSPREY change. The contract, with every declaration field, the member roles
and what the build writes, is Facility Kinds Contract.
The worked example is the package fixture-kind-deployment under
tests/facility/fixtures/fixture_kind/, which
tests/facility/test_fixture_kind_deployment.py builds end to end: the kind
fixture_kind and the engine fixture_ring it runs on.
1. Declare the kind#
A kind is one KindDeclaration from osprey.facility.kinds, the only
OSPREY module the package should import:
FIXTURE_KIND = KindDeclaration(
name=KIND,
tool=KindTool("pyaml.tuning_tools.orbit_response_matrix", "FIXTURE_KIND_RESPONSE"),
members={
"series_monitors": "wired",
"hcor": "wired",
"vcor": "wired",
"inject_request": "exists",
"inject_busy": "exists",
"clean_enable": "optional",
"beam_current": "exists",
"rf_status": "optional",
},
member_sorts={
"series_monitors": "monitors",
"inject_request": "instrument",
"inject_busy": "instrument",
"clean_enable": "instrument",
"beam_current": "instrument",
"rf_status": "instrument",
},
stepped_roles=("hcor", "vcor"),
tool_keys=("corrector_delta",),
single_pass=True,
matrix=True,
takes_by=False,
corrector_roles=("hcor", "vcor"),
view_files={CHAIN_FILE: _chain},
measure_plan={
"tool": {"attribute": KIND},
"fit": "magnet-group",
"magnets": {"members": ["hcorrectors", "vcorrectors"]},
"named": True,
"delta": "corrector_delta",
"bipolar": {"set_delta": True, "kwargs": {"corrector_names": "$names", **_SETTLE}},
"unipolar": {
"per_member": True,
"factory": "orm",
"kwargs": {
"correctors": "$names",
"deltas": "$deltas",
"set_wait_time": "$settle",
"n_avg_meas": "$n_avg_meas",
},
},
"result": "matrix",
"missing": "kind",
},
description="corrector response of the turn-series monitors",
measurement_schema=FixtureBlock,
view_section=_section,
facts_writer=facts_writer,
build_stops=build_stops,
settings_from_measurement=settings_from_measurement,
)
membersnames each group or instrument role the kind uses and how strictly:wired,existsoroptional.member_sortssays what a member the pyAML view does not ship is (monitorsorinstrumenthere).stepped_roles,corrector_rolesandtool_keyssay what a measurement steps, whatcorrectorsmay name and which measurement-file keys the tool takes (corrector_delta).view_sectionandview_fileswrite the kind’s part of each model’s pyAML view;measure_planis what the measure script does, as data.measurement_schema,facts_writer,build_stopsandsettings_from_measurementare the kind’s own block, its facts, its build stops and the engine settings it needs (below).
The full field table is The declaration in Facility Kinds Contract.
2. Register it#
The package names the declaration under the entry-point group
osprey.facility.kinds, and an engine of its own, when it has one, under
osprey.simulation.engines:
[osprey.facility.kinds]
fixture_kind = fixture_kind_deployment:FIXTURE_KIND
[osprey.simulation.engines]
fixture_ring = fixture_kind_deployment.engine
In the package’s pyproject.toml these are the
[project.entry-points."osprey.facility.kinds"] and
[project.entry-points."osprey.simulation.engines"] tables.
3. Install it in both places#
Only osprey build reads the declaration; the runtime reads what the build
wrote. The build still refuses a registered kind whose package the project
image does not install, so the package is installed twice:
Where
osprey buildruns. The build reads every declaration from the installed entry points; a package missing there leaves the kind unregistered.In the project image. List the package under the profile’s
dependencies, as an index requirement or a local path (the example keeps its source at./kinds/fixture_kindin the deployment repository). The build turns a local path into a wheel in the same deployment-package install an application’s package gets (Build Your Own App), and the image installs it.osprey facility validatebuilds no wheel: it reads the kinds a local-path entry or a listedapps/<name>/declares from the package’spyproject.toml.
4. Give the kind its block#
A kind takes settings of its own from the measurement file, under
kind_blocks.<kind>, validated by its measurement_schema, a pydantic
model:
class FixtureBlock(_Strict):
"""The kind's own measurement sub-block."""
trigger_sample: int = Field(ge=0)
settings: list[Setting] = []
steps: list[Step] = []
The example’s measurement/SR.yaml lists kinds: [trm, fixture_kind],
names groups.series_monitors and the instruments, states
corrector_delta, and holds kind_blocks.fixture_kind with a
trigger_sample, two settings and three steps. A kind with no schema
takes no block.
Only a block the schema admits reaches the kind’s build_stops,
facts_writer and settings_from_measurement. The example’s transform
asks its engine for enough turns past the trigger sample; the patch lands in
the model’s settings in the facility file and the simulator’s view.
The build writes the facts_writer output, per model, into the facts
document, where an application reads it with osprey.apps.sdk.read_facts
(What the build writes in Facility Kinds Contract).
5. Command steps#
A step that fires a command must name a channel the facility marks
command. The facility marks it, or the model’s engine does when it
describes the record, never the kind: the example’s engine marks the record it
fires, and the kind’s build_stops refuses any other address:
def build_stops(document: Mapping[str, Any], block: Any) -> Iterator[KindStop]:
"""Refuse a command step on a channel the facility does not mark ``command``."""
commands = _commands(document)
for step in (block or {}).get("steps") or []:
address = (step.get("command") or {}).get("address")
if address is not None and str(address) not in commands:
yield KindStop(
f"step {step.get('id')} fires {address}, which the facility does not mark "
f"{COMMAND}",
f"wire {address} where its engine marks it {COMMAND}, or drop the step's command",
)
The measurement’s approval prompt lists only the setpoints pyaml_measure
steps. A chain step’s command is fired by the
application’s own write tool through osprey.apps.sdk.command_write, so the
channels it fires are shown on that tool’s approval card, which the
application’s tools.approval entry describes
(Writes and approvals). A command write checks no approval itself; the
call that leads to it is its caller’s to check
(Guarded Run Contract, Command write).
What a refusal means#
Each stops osprey build, which prints the line and how to fix it.
The build says |
Meaning |
|---|---|
|
A measurement file lists the kind, and no package installed where
|
|
The package is installed where the build runs but not in the profile’s
|
|
The package’s kind takes a name OSPREY ships. |
|
Two installed packages declare one name. |
|
A declaration given as a mapping names a field |
|
A required member is missing from the measurement file. |
|
The |
|
The file holds a block for a kind missing from its |
|
The kind’s |
|
The |
A machine repository checked on its own cannot judge a kind whose package the
mounting deployment brings. With no machine: root, no apps: entry and
no dependencies entry in its profile, osprey build and osprey
facility validate print facility: kind-deferred: measurement <model> —
kind <kind> is registered by no installed package; its roles and `kind_blocks`
entry are judged where its app is mounted, write nothing for the kind, and
leave the exit code unchanged. The deployment that mounts the machine and lists
the kind’s package judges the block.