plesty.lib.experiment.manifest

What an experiment module declares about itself, for a caller that runs it.

A device answers describe and a console builds its panel from the reply, holding no per-device GUI code. An experiment is not a server and answers nothing, so the same knowledge has to leave it another way: python -m <module> --manifest prints this document as JSON, and a caller reads the run command, the configuration the experiment takes, and the environment it needs without importing the module or guessing from --help.

The configuration schema is not a new vocabulary. It is {group: [parameter, ...]} — the very document a device’s describe carries under parameters, each entry a to_dict(). So controls_for() turns an experiment’s configuration into controls exactly as it turns a device’s, and nothing that renders one has to learn the other.

A configuration key that is not a scalar — a list of measurement targets, an open-ended mapping of fit options — is declared with dtype="yaml". There is no widget that edits an arbitrary document, and inventing one would be a form that quietly rejects what the experiment accepts; a renderer shows those as text.

from plesty.lib.device.params import ConfigParameter
from plesty.lib.experiment import EnvVar, Manifest

manifest = Manifest(
    module="plesty.pol_pl",
    title="Polarization PL",
    schema={
        "hwp": [
            ConfigParameter("start_deg", default=0.0, dtype=float, unit="deg",
                            min_value=0.0, max_value=360.0,
                            description="First half-wave-plate angle."),
        ],
    },
    environment=[EnvVar("HWP_ADDRESS", "ZMQ address of the rotation stage.")],
)
manifest.to_dict()["schema"]["hwp"][0]["unit"]  # → 'deg'

Attributes

`YAML_DTYPE`
`DEFAULT_GROUP`

Exceptions

ManifestError

Raised when a manifest document is malformed or incomplete.

Classes

`EnvVar`	One environment variable the run reads.
`Option`	One extra command-line option the module adds to the standard set.
`Manifest`	What one experiment module declares about running it.

Functions

`_parameter`(→ plesty.lib.device.params.ConfigParameter)	Rebuild one configuration parameter from a printed manifest.
`group_of`(→ tuple[str, str])	Split a configuration key into its group and parameter name.
`yaml_parameter`(→ plesty.lib.device.params.ConfigParameter)	Declare a configuration key whose value is a document, not a scalar.
`env_vars`(→ tuple[EnvVar, Ellipsis])	Build required environment declarations.
`iter_parameters`(→ Iterable[tuple[str, ...)	Yield every `(group, parameter)` pair of a schema, groups in order.

Module Contents

plesty.lib.experiment.manifest.YAML_DTYPE = 'yaml'

plesty.lib.experiment.manifest.DEFAULT_GROUP = 'default'

exception plesty.lib.experiment.manifest.ManifestError

Bases: ValueError

Raised when a manifest document is malformed or incomplete.

Initialize self. See help(type(self)) for accurate signature.

class plesty.lib.experiment.manifest.EnvVar

One environment variable the run reads.

Variables:

name – The variable, as the process environment spells it.
description – What it is for, shown beside the field that sets it.
required – Whether a run without it fails. An optional variable has a working default inside the experiment; a required one does not, and a caller can refuse to start rather than abort mid-plan.

name: str

description: str = ''

required: bool = True

to_dict() → dict[str, Any]

Return the variable as JSON primitives.

Return type:: dict[str, Any]

classmethod from_dict(raw: Mapping[str, Any]) → EnvVar

Rebuild a variable from to_dict() output.

Parameters:: raw (Mapping[str, Any]) – The mapping to read.
Raises:: ManifestError – If name is missing or empty.
Return type:: EnvVar

class plesty.lib.experiment.manifest.Option

One extra command-line option the module adds to the standard set.

Variables:

flag – The option as it is typed, --prominence.
description – What it does — the option’s own help text.
dtype – Declared type name of its value; "bool" for a flag that takes none.
sets – The configuration key the option overrides, written as a renderer addresses it (analysis.fit_options.prominence), or None when it changes something other than the configuration.

flag: str

description: str = ''

dtype: str = 'str'

sets: str | None = None

to_dict() → dict[str, Any]

Return the option as JSON primitives.

Return type:: dict[str, Any]

classmethod from_dict(raw: Mapping[str, Any]) → Option

Rebuild an option from to_dict() output.

Parameters:: raw (Mapping[str, Any]) – The mapping to read.
Raises:: ManifestError – If flag is missing or empty.
Return type:: Option

class plesty.lib.experiment.manifest.Manifest

What one experiment module declares about running it.

Variables:

module – Import path served with python -m, plesty.pol_pl.
title – Human title, shown wherever the experiment is named.
schema – Configuration parameters by group. The ungrouped ones belong to DEFAULT_GROUP, as they do on a device.
environment – Variables the run reads from the environment or .env.
options – Extra command-line options beyond the standard set.
config – Default configuration file, relative to the checkout.
run_root – Where runs land when nothing overrides it.
viz – Import path of the module’s viewer (python -m <viz> monitor), or None when it ships none.
chooses_devices – Whether python -m <module> --devices --config <file> names the devices of setup.yaml a run of that configuration uses; without it every device is served (#62).

module: str

title: str

schema: Mapping[str, Sequence[plesty.lib.device.params.ConfigParameter]]

environment: Sequence[EnvVar] = ()

options: Sequence[Option] = ()

config: str = 'config/default.yaml'

run_root: str = 'runs'

viz: str | None = None

chooses_devices: bool = False

__post_init__() → None

Validate what a caller cannot recover from.

Raises:: ManifestError – If the module is unnamed, or a parameter is declared twice in one group.
Return type:: None

to_dict() → dict[str, Any]

Return the whole manifest as JSON primitives.

This is what --manifest prints: everything a caller needs to offer the experiment’s settings and start it, and nothing about how the experiment reaches its instruments.

Returns:: A mapping with module, title, config, run_root, viz, schema (grouped, as a device’s describe holds its parameters), environment, options and chooses_devices.
Return type:: dict[str, Any]

classmethod from_dict(raw: Mapping[str, Any]) → Manifest

Rebuild a manifest from a printed document.

The parameters come back as ConfigParameter objects carrying the declared type name rather than the type — the name is what crossed the wire, and what a renderer works from.

Parameters:: raw (Mapping[str, Any]) – A to_dict() document, as read back from --manifest.
Returns:: The manifest.
Raises:: ManifestError – If a required field is missing or malformed.
Return type:: Manifest

keys() → set[str]

Return every configuration key, written as a caller addresses it.

A grouped key is group.parameter; an ungrouped one is its bare name. This is the set a checker compares against the keys a shipped configuration file sets — a schema nobody keeps current is worse than none, because a console renders it as fact.

Returns:: The declared keys.
Return type:: set[str]

defaults() → dict[str, Any]

Return the declared defaults, shaped like the configuration file.

Groups become nested mappings and ungrouped parameters stay at the top level, so the result can be written out as a starting configuration. A parameter that declares no default is left out rather than written as null — an absent key takes the experiment’s own default, while a null overrides it with nothing.

Returns:: The configuration the defaults describe.
Return type:: dict[str, Any]

unknown_keys(config: Mapping[str, Any]) → list[str]

Return the keys config sets that the schema does not declare.

Only the two levels the schema describes are examined — a top-level scalar and a group’s members. What lies inside a yaml parameter is the experiment’s business and is not walked into.

Parameters:: config (Mapping[str, Any]) – A loaded configuration document.
Returns:: The undeclared keys, sorted, addressed as keys() writes them.
Return type:: list[str]

plesty.lib.experiment.manifest._parameter(group: Any, raw: Any) → plesty.lib.device.params.ConfigParameter

Rebuild one configuration parameter from a printed manifest.

Parameters:

group (Any) – The group it was printed under, for the error message.
raw (Any) – The parameter mapping.

Returns:

The parameter, its dtype the declared type name.

Raises:

ManifestError – If the entry is not a mapping, or has no name.

Return type:

plesty.lib.device.params.ConfigParameter

plesty.lib.experiment.manifest.group_of(key: str) → tuple[str, str]

Split a configuration key into its group and parameter name.

Parameters:: key (str) – group.parameter, or a bare name for an ungrouped parameter.
Returns:: The group (DEFAULT_GROUP when the key carries none) and the parameter name.
Return type:: tuple[str, str]

plesty.lib.experiment.manifest.yaml_parameter(name: str, description: str, default: Any = None) → plesty.lib.device.params.ConfigParameter

Declare a configuration key whose value is a document, not a scalar.

Parameters:

name (str) – The key.
description (str) – What it holds.
default (Any) – The default document, if it has one.

Returns:

The parameter, typed YAML_DTYPE.

Return type:

plesty.lib.device.params.ConfigParameter

plesty.lib.experiment.manifest.env_vars(*names: str, **described: str) → tuple[EnvVar, Ellipsis]

Build required environment declarations.

Parameters:

*names (str) – Variables with no description of their own.
**described (str) – Variable name to description.

Returns:

One EnvVar per name, in the order given.

Return type:

tuple[EnvVar, Ellipsis]

plesty.lib.experiment.manifest.iter_parameters(schema: Mapping[str, Sequence[plesty.lib.device.params.ConfigParameter]]) → Iterable[tuple[str, plesty.lib.device.params.ConfigParameter]]

Yield every (group, parameter) pair of a schema, groups in order.

Parameters:: schema (Mapping[str, Sequence[plesty.lib.device.params.ConfigParameter]]) – The configuration schema.
Yields:: The group name and one of its parameters.
Return type:: Iterable[tuple[str, plesty.lib.device.params.ConfigParameter]]