instrumentserver.params#

Functions

`paramTypeFromName`(name)
`paramTypeFromVals`(vals)

Classes

`ManagedParameter`(name[, path])	A parameter that can carry a Lock naming another parameter as its Target.
`ParameterGroup`(name[, metadata, label])	A Parameter Group: a plain container of parameters and nested Parameter Groups inside a Parameter Manager.
`ParameterManager`(name)	A virtual instrument that acts as a manager for a collection of arbitrary parameters and groups of parameters.
`ParameterTypes`(*values)

class instrumentserver.params.ManagedParameter(name: str, path: str | None = None, **kwargs: Any)[source]#

Bases: Parameter

A parameter that can carry a Lock naming another parameter as its Target.

While the Lock is locked, the parameter answers get with the Target’s value and refuses set with a ValueError naming the Target: values are pulled on get, nothing is ever pushed into a Follower (ADR-0002). Locking never touches the own cached value, so unlocking exposes the own value again. With no Lock, or with a Lock that is present but unlocked, the parameter behaves like a plain Parameter; an unlocked Lock only remembers its Target.

get_raw() → Any[source]#: Answer with the Target’s value while locked, the own cached value otherwise.

property locked: bool#: Whether a Lock is present and currently locked.

own_value() → Any[source]#: Return the own cached value, whatever state the Lock is in.

property path: str#: The parameter’s full dotted path with the instrument name, the form Locks and files use (parameter_manager.q01.x); for a standalone parameter, its plain name.

set_raw(value: Any) → None[source]#: Store the value while not locked; while locked, refuse with a ValueError naming the full dotted paths of Follower and Target.

snapshot_base(update: bool | None = True, params_to_skip_update: Sequence[str] | None = None) → Dict[str, Any][source]#

Snapshot with a lock entry while a Lock is present; while locked, the reported value is the Target’s value.

With update=True the base snapshot already asks this parameter, whose locked get answers with the Target’s value, so the Target is not read a second time. With a falsy update the Target is read directly — not its cache — so that each hop of a chain reads according to its own state (D7).

class instrumentserver.params.ParameterGroup(name: str, metadata: Mapping[Any, Any] | None = None, label: str | None = None)[source]#

Bases: InstrumentBase

A Parameter Group: a plain container of parameters and nested Parameter Groups inside a Parameter Manager.

It holds parameters and nested Parameter Groups and offers the tree helpers (dotted-path add/remove/get/set, listing, tree building), but has no file, profile, Type or Lock logic of its own. Every submodule of a Parameter Manager is a Parameter Group; only the root is the Parameter Manager, which extends the Parameter Group with those responsibilities. When a Parameter Group belongs to a Parameter Manager, its public add_parameter/remove_parameter route to the root, so ManagedParameter creation and the Lock cleanup always happen; a standalone Parameter Group behaves as a plain container.

add_parameter(name: str, **kw: Any) → None[source]#

Add a parameter.

A Parameter Group that belongs to a Parameter Manager routes the call to the root, with the path made relative to it (<group path>.<name>), so the parameter is created as a ManagedParameter that can carry a Lock (D15). A standalone Parameter Group creates a plain qcodes Parameter.

Parameters:

name – Name of the parameter. If the name contains .`s, then an element before a dot is interpreted as a submodule. Multiple dots represent nested submodules. I.e., when we supply ``foo.bar.foo2` we have a top-level submodule foo, containing a submodule bar, containing the parameter foo2. Submodules are generated on demand.
kw – Any keyword arguments will be passed on to qcodes.Instrument.add_parameter, except: - set_cmd is always set to None - parameter_class defaults to qcodes.Parameter - vals defaults to qcodes.utils.validators.Anything().

Returns:

None.

get(param_name: str) → Any[source]#

Shortcut for getting a parameter from its name.

Parameters:: param_name – The name of a parameter of this instrument.
Returns:: The current value of the parameter.

Note

This is deprecated. Call get directly on the parameter.

has_param(param_name: str) → bool[source]#

list() → List[str][source]#: Return a list of all parameters.

parameter(name: str) → ParameterBase[source]#

Get a parameter object from the manager.

Parameters:: name – the full name
Returns:: the parameter

remove_empty_submodules() → None[source]#: Delete all empty submodules in the instrument.

remove_parameter(param_name: str, cleanup: bool = True) → None[source]#

Remove a parameter.

A Parameter Group that belongs to a Parameter Manager routes the call to the root, with the path made relative to it, so the root’s Lock cleanup happens before the deletion (D3, D15). A standalone Parameter Group deletes directly.

Parameters:

param_name – Name of the parameter; dotted names traverse nested Parameter Groups.
cleanup – Whether to remove emptied submodules afterwards.

set(param_name: str, value: Any) → Any[source]#

Shortcut for setting a parameter from its name and new value.

Parameters:

param_name – The name of a parameter of this instrument.
value – The new value to set.

Note

This is deprecated. Call set directly on the parameter.

to_tree() → Dict[source]#

class instrumentserver.params.ParameterManager(name: str)[source]#

Bases: Broadcaster, ParameterGroup

A virtual instrument that acts as a manager for a collection of arbitrary parameters and groups of parameters.

Allows extra-easy on-the-fly addition/removal of new parameters.

The Parameter Manager is the root of the parameter tree. It extends the Parameter Group with file, profile, Lock, and Type logic; its submodules are plain Parameter Groups.

It implements the Broadcaster contract, so the Server can register itself as a broadcast sink when the Parameter Manager joins the Station. Every Lock method that changes a Lock emits one pm-lock-update Broadcast per affected Follower (D10), and remove_parameter emits them for the Locks that deleting a Target drops. Every Type-editing method emits pm-type-update with the edited Type’s fresh PMTypeBluePrint (D22), and the parameters the Type edits and add_instance() create as side effects are re-emitted as parameter-creation Broadcasts (ADR-0003); direct add_parameter calls keep being announced by the Server, so nothing is announced twice. Declaring a Type Lock with lock_type_parameter() and removing it with unlock_type_parameter() do both: they emit the pm-lock-update Broadcasts of the Locks the declaration creates and the pm-type-update of the edited Type, and every new Instance gets the existing Type Locks of its Type at creation (D17). Removing a parameter that is the stored Target of Type Locks drops the Locks pointing at it and clears those Type Locks, emitting one pm-type-update per affected Type (D18).

For the parameter manager to recognize other profiles in disk, the profile filename needs to start with ‘parameter_manager-’ and end with ‘.json’ with the name of the profile in the middle. For example, ‘parameter_manager-qubit1.json’ represents the profile qubit1

add_instance(type_name: str, name: str) → None[source]#

Create the Instance name of the Type type_name (D14): every effective parameter path of the Type that is missing under name — together with the Parameter Groups on the way — is created with the entry’s default value and unit through the ordinary add_parameter() path, and every parameter that exists at a target path already is kept untouched, with its own value and unit. name is a dotted submodule path relative to this Parameter Manager ("q01" or "q01.readout"), so nested Instances are allowed. After a successful call name carries the whole effective set with the units the Type declares, so it is an Instance in instances_of() — unless the Type is empty: an empty Type has no Instances (D12), creates nothing and raises nothing, and the submodule is not created for it.

Raises ValueError — creating nothing — naming every offending path when no such Type exists, when name is empty or has an empty segment, when name starts with the reserved Globals name _globals (D18), when a parameter already exists at an effective path with a unit different from the one the Type declares (the unit-conflict scan runs over every effective path before anything is created, D14), or when a target path cannot be created because a segment of name or of the target is an existing parameter, or the final segment of a target is an existing Parameter Group.

After the Instance is created it emits one parameter-creation Broadcast per parameter it created, in creation order, followed by one pm-lock-update Broadcast per Type Lock it applied to the new Instance (D17, D22, ADR-0003); the call edits no Type, so it emits no pm-type-update. A failed validation emits nothing. As a new Instance, name gets the existing Type Locks of this Type and of every Type nesting it applied to its parameters at their locked effective entries — a parameter the call kept (D14) included, since a Lock changes neither its own value nor its unit. A kept parameter that already carries a Lock on another Target, a stored Target that no longer exists and a Lock that would close a cycle are skipped, collected into one logger.warning; the creation itself still succeeds. Submodules that were Instances before the call are untouched.

Parameters:

type_name – Name of the Type.
name – Dotted submodule path of the Instance, relative to this Parameter Manager.

add_nested_type(type_name: str, submodule: str, nested_type: str) → None[source]#

Require the Nested Type nested_type at the submodule submodule of the Type type_name (D11), and write the nested Type’s effective parameter set under that submodule into every Instance of type_name — and of every Type nesting it — that lacks the parameters, with each entry’s default value and unit (D13).

Raises ValueError — leaving the registry and the parameter tree untouched — naming every offending name or path when a Type does not exist, when submodule is empty, has an empty segment or starts with the reserved Globals name _globals (D18), when the submodule already requires a Nested Type, when the nesting would close a cycle (type_name == nested_type included), when the resulting effective parameter set of type_name or of any Type nesting it would contain a path twice, or when a target path cannot be created because an intermediate segment is an existing parameter, the final segment is an existing Parameter Group, or another target of the same edit is a strict segment-prefix of it.

After the edit succeeds it emits one parameter-creation Broadcast per parameter it created, in creation order, followed by one pm-lock-update Broadcast per Type Lock it applied to a new Instance and one pm-type-update Broadcast per affected Type — the edited Type first, then every Type nesting it, whose effective parameter set the nested entries extend (D17, D22, ADR-0003); a failed validation emits nothing. A new Instance — a submodule that is an Instance after the edit but was not one before — gets the existing Type Locks of its Type applied to its parameters at the Type’s locked effective entries, parameters the edit kept included; the Nested Type’s own chain joins the Types whose Type Locks are applied, since nesting it completes the submodules at its position into Instances of it; skips are collected into one logger.warning and the edit still succeeds.

Parameters:

type_name – Name of the outer Type.
submodule – Name of the submodule that requires the Nested Type.
nested_type – Name of the Nested Type.

add_parameter(name: str, **kw: Any) → None[source]#

Add a parameter, created as a ManagedParameter.

Same dotted-name semantics as ParameterGroup.add_parameter(), which this method calls; only the parameter class differs, so that the Parameter Manager’s parameters can carry a Lock. The created parameter’s path is set to its full dotted path with the instrument name (parameter_manager.q01.x), the form Locks and files use.

Raises ValueError naming the offending path, creating nothing, when name is the reserved Globals name _globals or starts with it (D18): the Globals submodule holds only the default Targets of Type Locks, and its parameters are created on demand by _ensure_global_target(), not through the public API. Since a Parameter Group routes its add_parameter to the root (D15), this check covers calls made on any Parameter Group of this Parameter Manager as well.

Parameters:

name – Name of the parameter; see ParameterGroup.add_parameter().
kw – Any keyword arguments will be passed on to qcodes.Instrument.add_parameter, as in ParameterGroup.add_parameter().

Returns:

None.

add_type(name: str) → None[source]#

Create an empty Type named name in the Type registry.

Raises ValueError naming the name when it is the reserved Globals name _globals or when a Type with that name exists already; nothing is changed then. A fresh Type has no entries and no Nested Types, so it has no Instances until entries are added. Emits one pm-type-update Broadcast carrying the new Type’s PMTypeBluePrint after it is created (D22); a failed validation emits nothing.

Parameters:: name – Name of the Type.

add_type_parameter(type_name: str, path: str, default: Any = None, unit: str = '') → None[source]#

Add an entry to the Type type_name (D11) and create the parameter at path — with the entry’s default value and unit — in every Instance of the Type that lacks it, and in every Instance of a Type whose effective parameter set contains type_name through nesting (D13). Parameters that already exist at a target path are left alone, whatever their unit; the missing Parameter Groups along a target path are created.

Raises ValueError — leaving the registry and the parameter tree untouched — naming every offending path when no such Type exists, when path is empty or has an empty segment, when path is already in the Type’s effective parameter set (naming the Type that defines it), when prefix + path is already in the effective parameter set of a Type nesting this one — naming every colliding path and the Type whose effective set holds it, since the duplicated path would break every query on that Type — or when a target path cannot be created because an intermediate segment is an existing parameter, the final segment is an existing Parameter Group, or another target of the same edit is a strict segment-prefix of it.

After the edit succeeds it emits one parameter-creation Broadcast per parameter it created, in creation order, followed by one pm-lock-update Broadcast per Type Lock it applied to a new Instance and one pm-type-update Broadcast per affected Type — the edited Type first, then every Type nesting it, whose effective parameter set the new entry extends (D17, D22, ADR-0003); a failed validation emits nothing. A new Instance — a submodule that is an Instance of an affected Type after the edit but was not one before — gets the existing Type Locks of that Type applied to its parameters at the Type’s locked effective entries, parameters the edit kept included; skips are collected into one logger.warning and the edit still succeeds.

Parameters:

type_name – Name of the Type.
path – Relative parameter path of the entry.
default – Default value the created parameters start with.
unit – Unit of the entry and the created parameters.

static cleanProfileName(name: str) → str[source]#: When passed the full file name of a parameter_manager profile, return only the middle string representing the profile’s name.

static createFromParamDict(paramDict: Dict[str, Any], name: str) → ParameterManager[source]#

Create a new ParameterManager instance from a paramDict.

Parameters:

paramDict – The paramDict object.
name – Name of the instrument in the paramDict (each entry in the paramDict starts with <instrumentName>.[…]).

Returns:

New ParameterManager instance.

classmethod does_profile_exist(profiles: List[str], target: str) → bool[source]#

followers_of(name: str) → List[str][source]#: Paths (relative to this Parameter Manager) of every Follower whose Lock points at the parameter at name, locked and unlocked alike. Raises ValueError naming the path when the parameter does not exist.

fromFile(filePath: str | None = None, deleteMissing: bool = True) → None[source]#

Load parameters, Types and Locks from a parameter json file (see serialize).

If the filepath starts with ‘parameter_manager-’ and ends with ‘.json’, selectedProfile is changed to the filename.

Parameters:

filePath – Path to the json file. If None it looks in the instrument current location directory for a file called “parametermanager_parameters.json”.
deleteMissing – If True, delete parameters currently in the ParameterManager that are not listed in the file.

fromParamDict(paramDict: Dict[str, Any], deleteMissing: bool = True) → None[source]#

Load parameters, Types and Locks from a parameter dictionary (see serialize).

A dictionary without a top-level version key is the legacy flat parameter map and loads exactly as before: parameters only, and the Types and Locks of this Parameter Manager are untouched by the legacy reader.

A version-2 profile document (the document toParamDict() writes, plan decision D19) is validated as a whole before anything is loaded (plan decision D20). The schema is checked with serialize.validateParameterManagerV2(); every remaining problem is collected into one ValueError naming all of them (rule 3): every file key must belong to this Parameter Manager (the full-path form with the instrument name), every Type name must be valid (non-empty, not the reserved Globals name _globals), every Nested Type must name a Type of the document, the document’s Types must form no Nested Type cycle and hold no effective parameter path twice, every lock Target and every non-null Type Lock Target must be a parameters key of the document, and no lock may be a self-lock or close a cycle among the document’s Locks (walking Targets regardless of locked/unlocked state, D7). A refused document changes nothing and emits nothing. Any other version value raises ValueError naming it.

After the validation the document loads in order (D20): first the Locks of every parameter it lists go away, so setting a stored own value on a currently locked Follower cannot raise (D6); then the parameters with the semantics the reader always had (an existing one is set to its stored own value and unit, a missing one is created — one under the Globals submodule through the internal creation path _create_managed_parameter(), since the public add_parameter() refuses the Globals name (D18) — and deleteMissing=True removes the parameters the document does not list, dropping their Locks and Type Locks exactly like remove_parameter() does); then the Types, written straight into the registry as definitions — with deleteMissing=True, every Type the document does not define is removed — with no Instance side effects (D20): no parameter is created for an Instance and no Type Lock is applied on load, so a partial Instance stays partial and an Instance’s Locks come only from the document’s lock entries; then the Locks, each set directly to the stored full-form Target and stored locked state (like lock() creates it after the cycle check, not through a lock()/unlock() pair). A parameter the document lists without a lock entry ends with no Lock; parameters it does not list keep theirs when deleteMissing=False.

The Broadcasts go out once, after the whole load succeeded (D22, D10): one pm-type-update per Type the document wrote, then one with a None payload per Type removed, then one pm-lock-update per Lock that ended different from before the load (None when it was removed), in tree order. The load emits nothing for the parameter values it sets, and it re-emits no parameter-creation/parameter-deletion Broadcasts for the parameters it creates and removes: the Server’s literal-name detection does not see them either, so a GUI watching this Parameter Manager must refresh its structure after a profile load.

Parameters:

paramDict – Parameter dictionary — a legacy flat map or a version-2 profile document.
deleteMissing – If True, delete parameters currently in the ParameterManager that are not listed in the file, and remove the Types the file does not define.

static fullProfileName(name: str) → str[source]#: Adds ‘parameter_manager-’ to the beginning of name and adds ‘.json’ at the end.

getWorkingDirectory()[source]#

get_lock(name: str) → PMLockBluePrint | None[source]#: The Lock of the parameter at name (dotted path relative to this Parameter Manager) as a PMLockBluePrint whose Target is the full dotted path, or None when it carries no Lock. Raises ValueError naming the path when the parameter does not exist.

get_type(name: str) → PMTypeBluePrint[source]#: The Type name as a PMTypeBluePrint: its own entries as {path: {default, unit, target}}, its Nested Types as {submodule: type}, and the computed effective parameter set as {path: {unit, from_type}}. Raises ValueError naming the name when no such Type exists, and like _effective_parameters() when its Nested Types cycle or its effective set contains a path twice.

instances_of(type_name: str) → List[str][source]#

Paths (relative to this Parameter Manager) of every Instance of the Type type_name (D12): every Parameter Group at any depth that carries every path of the Type’s effective set with the unit the Type declares; values are irrelevant. The root is never an Instance, the Globals submodule _globals and everything under it are excluded, and an empty Type has no Instances (ADR-0001). Matching is computed on demand; this query changes no state.

Raises ValueError naming the name when no such Type exists, and like _effective_parameters() when its Nested Types cycle or its effective set contains a path twice.

Parameters:: type_name – Name of the Type.
Returns:: Paths of the Instances, in tree order.

list_locks() → Dict[str, PMLockBluePrint][source]#: All Locks in this Parameter Manager, locked and unlocked alike (D5), as a mapping from the Follower’s path (relative to this Parameter Manager) to its PMLockBluePrint.

list_profiles() → List[str][source]#: Returns a list of all profiles.

list_types() → List[str][source]#: Names of every Type in the Type registry.

lock(name: str, target: str) → None[source]#

Lock the parameter at name to the parameter at target (dotted paths relative to this Parameter Manager).

Creates the Lock, or re-targets it when one exists already, and locks it: while locked, name answers get with the Target’s value and refuses set (ADR-0002). The Target must be a parameter of this same Parameter Manager (D8). Raises ValueError naming every offending path when a path does not exist (both paths are checked before one error is raised), the Follower cannot carry a Lock, the Lock would be a self-lock, or it would close a cycle (walking Targets regardless of locked/unlocked state, D7). On success emits one pm-lock-update Broadcast naming the Follower with its new Lock (D10); a failed validation emits nothing.

Parameters:

name – path of the Follower.
target – path of the Target.

lock_type_parameter(type_name: str, path: str, target: str | None = None) → List[str][source]#

Declare the Type Lock of the entry path of the Type type_name (D17): the Target is stored on the entry — the parameter at target when given, the Globals parameter _globals.<type_name>.<path> otherwise — and an ordinary, locked Lock on that Target is put on the entry’s parameter in every current Instance of the Type. The default Globals Target is created on demand with the entry’s default value and unit, through _ensure_global_target().

Instance parameters that already carry a Lock on another Target are skipped: they are left untouched, named together with their Target in one logger.warning, and returned as a list of dotted paths relative to this Parameter Manager (empty when nothing was skipped). A parameter already locked to the same Target stays as it is; an unlocked Lock remembering the same Target is locked again. Declaring the Type Lock again therefore re-applies it to everyone (“lock all”); declaring it with a different Target stores the new one, and the Followers still locked to the old Target count as skipped.

Raises ValueError — before anything is touched — naming every offending path when no such Type exists, when path is not an entry of the Type itself (naming the Type that defines it when the path only reaches the effective parameter set through a Nested Type; own entries only, like set_type_parameter_default()), when an explicit target does not exist as a parameter of this Parameter Manager, and when locking one of the Instance parameters would be a self-lock, close a cycle (walking Targets regardless of locked/unlocked state, D7) or hit a parameter that cannot carry a Lock.

On success it emits the Globals parameter’s parameter-creation (when created), then one pm-lock-update per Lock it created or relocked — nothing for skipped or already-locked parameters — and finally one pm-type-update for the edited Type (D10, D22); the Types nesting it are not named, since their effective parameter set carries units and defining Types, not Targets. A failed validation emits nothing.

Parameters:

type_name – Name of the Type.
path – Relative parameter path of the Type’s own entry.
target – Path of the Target, relative to this Parameter Manager; the default Globals Target when None.

Returns:

The skipped Instance parameter paths, in tree order.

refresh_profiles() → List[str][source]#

Goes into the working directory and updates the list of profiles.

Returns:: List of profiles in the working directory

relock(name: str) → None[source]#: Lock the Lock of the parameter at name (dotted path relative to this Parameter Manager) to its remembered Target again (D5). Raises ValueError naming the paths when the parameter does not exist, carries no Lock, or when the remembered Target is gone or locking to it would close a cycle (D7); relocking an already locked Lock does nothing and logs at INFO level. On a state change emits one pm-lock-update Broadcast carrying the locked Lock (D10); the no-op path emits nothing.

remove_all_parameters() → None[source]#: Remove all parameters from the instrument.

remove_lock(name: str) → None[source]#: Remove the Lock of the parameter at name (dotted path relative to this Parameter Manager) entirely: the Target is forgotten and the parameter behaves as a plain parameter again (D5). Raises ValueError naming the path when the parameter does not exist or carries no Lock. Emits one pm-lock-update Broadcast with a None value for the Follower whose Lock was removed (D10).

remove_nested_type(type_name: str, submodule: str) → None[source]#

Remove the Nested Type required at the submodule submodule of the Type type_name (D13): the parameters of the Instances are untouched, and the submodules that no longer carry the whole shape simply stop being Instances (D1).

Raises ValueError naming the Type and the submodule when no such Type exists or the submodule requires no Nested Type; nothing is removed then. Emits one pm-type-update Broadcast per affected Type — the edited Type first, then every Type nesting it, whose effective parameter set loses the nested paths — after the Nested Type is removed (D22); a failed validation emits nothing.

Parameters:

type_name – Name of the Type.
submodule – Name of the submodule that requires the Nested Type.

remove_parameter(param_name: str, cleanup: bool = True) → None[source]#

Remove a parameter, first removing every Lock whose Target it is (ADR-0002): the Followers become plain parameters and answer get with their own values again. One pm-lock-update Broadcast with a None value is emitted per dropped Lock (D10).

When the removed parameter is the stored Target of one or more Type Locks — a Globals parameter, or any parameter an explicit Type Lock points at — the Type Lock is cleared as well (D18): every own entry of every Type whose stored Target it was gets target=None, and one pm-type-update Broadcast per affected Type, in registry order and carrying the Type’s fresh PMTypeBluePrint, is emitted after the pm-lock-update``s (D22). The Locks a cleared Type Lock had put on Instance parameters are ordinary Locks pointing at the removed parameter, so the same cleanup drops them; a parameter that is no Type Lock Target emits no ``pm-type-update.

Same signature and deletion behaviour as ParameterGroup.remove_parameter(); the path is relative to this Parameter Manager. The deletion itself emits nothing here: the Server announces a direct remove_parameter call with a parameter-deletion Broadcast (ADR-0003).

remove_type(name: str) → None[source]#

Remove the Type name from the Type registry.

The parameters of Instances are untouched (D13). Raises ValueError when no such Type exists, and — naming every Type that nests it — while any other Type still requires name as a Nested Type; nothing is removed then. Emits exactly one pm-type-update Broadcast with a None payload after the Type is removed (D22): nobody nests it, so no other Type is affected; a failed validation emits nothing.

Parameters:: name – Name of the Type.

remove_type_parameter(type_name: str, path: str) → None[source]#

Remove the entry at path from the Type type_name’s own entries (D13): the parameters of the Instances are untouched, and the submodules that no longer carry the whole shape simply stop being Instances (D1).

Raises ValueError naming the path when no such Type exists, when path is not an entry of the Type itself — naming the Type that defines it, when the path only reaches the effective parameter set through a Nested Type — and when it is in no effective set at all. Nothing is removed then. Emits one pm-type-update Broadcast per affected Type — the edited Type first, then every Type nesting it, whose effective parameter set loses the path — after the entry is removed (D22); a failed validation emits nothing.

Parameters:

type_name – Name of the Type.
path – Relative parameter path of the entry.

selectedProfile#: default location and name of the parameters save file.

set_type_parameter_default(type_name: str, path: str, value: Any) → None[source]#

Set the default value of the Type type_name’s own entry at path (D13): the parameters the Instances already carry keep their values, and only parameters created later start with the new default.

Raises ValueError naming the path under the same conditions as remove_type_parameter(); nothing is changed then. Emits one pm-type-update Broadcast carrying the edited Type’s fresh blueprint after the default is set (D22); no Broadcast names a nesting Type, since a Type’s effective parameter set carries units and defining Types, not defaults, so their blueprints are unchanged. A failed validation emits nothing.

Parameters:

type_name – Name of the Type.
path – Relative parameter path of the entry.
value – The entry’s new default value.

set_type_parameter_unit(type_name: str, path: str, unit: str) → None[source]#

Set the unit of the Type type_name’s own entry at path and propagate it to that parameter in every Instance of the Type and of every Type whose effective parameter set contains type_name through nesting (D13); the target of a propagation is one of the Instance’s parameters by construction, and a parameter already carrying the new unit is simply set again.

Raises ValueError naming the path under the same conditions as remove_type_parameter(); nothing is changed then. Emits one pm-type-update Broadcast per affected Type — the edited Type first, then every Type nesting it, whose effective parameter set carries the changed unit — after the unit is set and propagated (D22); a failed validation emits nothing.

Parameters:

type_name – Name of the Type.
path – Relative parameter path of the entry.
unit – The entry’s and the Instances’ new unit.

switch_to_profile(profile: str) → None[source]#: Switches to the passed profile (D20): the current profile is saved first (the version-2 profile document toFile() writes), then every parameter, Type and Lock is cleared (_clear_all()), then the new profile is loaded (fromFile(), a legacy flat map or a version-2 document). Raises ValueError — saving, clearing and loading nothing — when the profile does not exist.

toFile(filePath: str | None = None, name: str | None = None) → None[source]#

Save parameters from the instrument into a json file. The file holds the version-2 profile document toParamDict() returns (plan decision D19), dumped with indent=2, sort_keys=True. If the file being saved is a profile file (starts with ‘parameter_manager-’ and ends with ‘.json’), the selectedProfile is changed to the filename.

Parameters:

filePath – Path to the json file. If None it looks in the instrument current working directory for a file called “parameter_manager-<name_of_this_instrument>.json”.
name – If the filePath passed is a directory, The name of the file that it will create follows the convention of “parameter_manager-<name>.json”. If none it will name it the name of the instrument.

toParamDict(simpleFormat: bool = False, includeMeta: List[str] = ['unit']) → Dict[str, Any][source]#

Return the state of this Parameter Manager as a version-2 profile document (plan decision D19): {"version": 2, "parameters": {...}, "types": {...}}.

parameters maps every parameter’s full dotted path (with the instrument name, like the legacy flat files) to a dict holding the parameter’s own value — ManagedParameter.own_value() for the parameters that can carry a Lock, so a locked Follower saves its own value and never the Target’s (ADR-0002), the cached snapshot value for any plain Parameter — the metadata includeMeta selects (unit by default; Globals parameters are saved like any other, D18), and, only on a parameter that carries a Lock in either state, a lock entry {"target": <full dotted Target path>, "locked": <bool>}.

types maps every Type of the Type registry to its own entries as {path: {"default": ..., "unit": ..., "target": ...}} — the stored full-form Target of the entry’s Type Lock, or None — and its Nested Types as {submodule: type}; with no Types it is {}.

The values are read from the qcodes snapshot with update=False (the cache, never get), like the legacy writer this replaces.

simpleFormat is kept for signature compatibility but has no effect: a version-2 document always stores the per-parameter dict. includeMeta still selects the per-parameter metadata besides value.

Parameters:

simpleFormat – Ignored (kept for signature compatibility).
includeMeta – List of parameter attributes to include besides value. All keys occurring in snapshots are valid.

Returns:

The version-2 profile document.

toggle_lock(name: str) → None[source]#: Toggle the Lock of the parameter at name (dotted path relative to this Parameter Manager): locked becomes unlocked and unlocked becomes locked again (D5). Raises ValueError naming the path when the parameter does not exist or carries no Lock, and like relock() when locking back would close a cycle. Emits one pm-lock-update Broadcast through unlock() / relock(), which carry out the change (D10).

types_of(path: str) → List[str][source]#

Names of the Types claiming the parameter at path (a dotted path relative to this Parameter Manager), innermost first (D16): the Type whose Instance is the deepest submodule above the parameter wins, then the one with the largest effective set, with any remaining tie broken by Type name. A Type claims the parameter when an Instance of it above the parameter — some submodule the parameter lives under — carries the parameter’s path relative to that Instance in its effective set. Parameters under the Globals submodule _globals are claimed by nothing, since matching excludes _globals (D12). Matching is computed on demand; this query changes no state.

Raises ValueError naming the path when no parameter exists there.

Parameters:: path – Path of the parameter.
Returns:: Claiming Type names, innermost first.

unlock(name: str) → None[source]#: Unlock the Lock of the parameter at name (dotted path relative to this Parameter Manager): it keeps remembering its Target but answers get with its own value again (D5). Raises ValueError naming the path when the parameter does not exist or carries no Lock; unlocking an already unlocked Lock does nothing and logs at INFO level. On a state change emits one pm-lock-update Broadcast carrying the unlocked Lock (D10); the no-op path emits nothing.

unlock_type_parameter(type_name: str, path: str) → None[source]#

Remove the Type Lock of the entry path of the Type type_name (D17): only the rule goes — the entry’s stored Target is cleared and one pm-type-update Broadcast naming the Type goes out — while the Locks the declaration put on the Instance parameters stay until they are removed individually with remove_lock(). Instances that stop matching keep their Locks either way.

Raises ValueError naming the Type and the path when no such Type exists or path is not an entry of the Type itself; nothing is changed then. An entry that carries no Type Lock is a no-op logged at INFO level that emits nothing (like unlock() and relock()).

Parameters:

type_name – Name of the Type.
path – Relative parameter path of the Type’s own entry.

property workingDirectory: Path#

class instrumentserver.params.ParameterTypes(*values)[source]#

Bases: Enum

any = 1#

bool = 5#

complex = 6#

integer = 3#

numeric = 2#

string = 4#

instrumentserver.params.paramTypeFromName(name: str) → ParameterTypes | None[source]#

instrumentserver.params.paramTypeFromVals(vals: Validator | None) → ParameterTypes | None[source]#