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,
)
  • members names each group or instrument role the kind uses and how strictly: wired, exists or optional. member_sorts says what a member the pyAML view does not ship is (monitors or instrument here).

  • stepped_roles, corrector_roles and tool_keys say what a measurement steps, what correctors may name and which measurement-file keys the tool takes (corrector_delta).

  • view_section and view_files write the kind’s part of each model’s pyAML view; measure_plan is what the measure script does, as data.

  • measurement_schema, facts_writer, build_stops and settings_from_measurement are 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 build runs. 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_kind in 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 validate builds no wheel: it reads the kinds a local-path entry or a listed apps/<name>/ declares from the package’s pyproject.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

kind fixture_kind is not registered under osprey.facility.kinds by any installed package

A measurement file lists the kind, and no package installed where osprey build runs declares it. A tree that mounts no machine root and lists no application and no dependency is a machine tree on its own and prints a kind-deferred warning instead (below).

measurement kind 'fixture_kind' (package fixture-kind-deployment): the kind's package is not among the packages the project image installs

The package is installed where the build runs but not in the profile’s dependencies, so the image would not carry it.

measurement kind orm — built-in declares a kind of the same name

The package’s kind takes a name OSPREY ships.

measurement kind fixture_kind — package … declares a kind of the same name

Two installed packages declare one name.

measurement kind hooked_kind — it names hook 'on_trigger', which OSPREY does not offer

A declaration given as a mapping names a field KindDeclaration does not have.

kind <kind> needs `<slot>`, which the file does not name

A required member is missing from the measurement file.

kind_blocks.<kind>.<field>: <message>

The measurement_schema refuses the block.

… is the block of a kind the file does not list

The file holds a block for a kind missing from its kinds.

kind fixture_kind: step clean fires CLEAN:EN, which the facility does not mark command

The kind’s build_stops refused a command step on an unmarked channel.

kind <kind>'s facts writer fails on this file's block

The facts_writer raised on a block the schema admits.

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.