SettingNode

SettingNode#

Module: exa.common.data.setting_node

class SettingNode(name, settings=None, subtrees=None, *, path='', align_name=True, generate_paths=None)#

Bases: BaseModel

A tree-structured Setting container.

Each child of the node is a Setting, or another SettingNode. Iterating over the node returns all children, recursively. Settings can be accessed by dictionary syntax or attribute syntax:

>>> from exa.common.data.parameter import Parameter
>>> from exa.common.data.setting_node import SettingNode
>>> p1 = Parameter("voltage", "Voltage")
>>> f1 = Parameter("frequency", "Frequency")
>>> sub = SettingNode("sub", frequency=f1)
>>> settings = SettingNode('name', voltage=p1)
>>> settings.voltage.parameter is p1
True
>>> settings['voltage'].parameter is p1
True
>>> settings.voltage.value is None
True
>>> settings.voltage = 7  # updates to Setting(p1, 7)
>>> settings.voltage.value
7
>>> settings["sub.frequency"] = 8
>>> settings["sub.frequency"].value
8

Parameters:

name (str) – Name of the node.
settings (dict[str, Any] | None) – Dict of setting path fraqment names (usually the same as the setting name) to the settings. Mostly used when deserialising and otherwise left empty.
subtrees (dict[str, Any] | None) – Dict of child node path fraqment names (usually the same as the child node name) to the settings. Mostly used when deserialising and otherwise left empty.
path (str) – Optionally give a path for the node, by default empty.
align_name (bool) – Whether to align node.name = node.path in this node and all of its child nodes, by default True.
generate_paths (bool | None) – If set True, all subnodes will get their paths autogenerated correctly. Only set to False if the subnodes already have correct paths set (e.g. when deserialising).
kwargs – The children given as keyword arguments. Each argument must be a Setting, Parameter, or a SettingNode. The keywords are used as the names of the nodes. Parameters will be cast into Settings with the value None.

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

Attributes

`all_settings`	Yields all `Setting` instances inside this node, recursively.
`child_nodes`	ItemsView of immediate child nodes of this node.
`child_settings`	ItemsView of settings of this node.
`children`	Dictionary of immediate child nodes of this node.
`model_config`	Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].
`name`
`settings`
`subtrees`
`path`
`align_name`

Methods

`add_for_path`	Add nodes to `self` while creating the missing nodes in-between.
`diff`	Recursive diff between two SettingNodes.
`fast_construct`	Fast construction alternative to __init__ from trusted serialized dict using model_construct.
`find_by_name`	Find first occurrence of Setting or SettingNode by name, by iterating recursively through all children.
`get_default_implementation_name`	Get the default implementation name for a given gate and locus.
`get_gate_node_for_locus`	Get the gate calibration sub-node for the locus given as a parameter if it exists in the settings tree.
`get_gate_properties_for_locus`	Get the gate characterization sub-node for the locus given as a parameter if it exists in the settings tree.
`get_locus_node_paths_for`	Get all the gate locus node paths for a given `gate`.
`get_node_for_path`	Return the node corresponding to the given path.
`get_parent_of`	Get the first SettingNode that has a Setting named name.
`merge`	Recursively combine the tree structures and values of two SettingNodes.
`merge_values`	Recursively combine the values from another `SettingNode` to this one.
`model_copy`	Copy the model.
`nodes_by_type`	Yields all nodes, filtered by given node_types.
`print_tree`	Print a tree representation of the contents of this node.
`prune`	Recursively delete all branches from this SettingNode that are not found in `other`.
`set_from_dict`	Recursively set values to Settings, taking values from a dictionary that has similar tree structure.
`set_shots`	Set `playlist_repeats` and `averaging_bins` under `self.controllers.options`.
`set_source`	Set source recursively to all Settings in `self`.
`setting_with_path_name`	Get a copy of a setting with its name replaced with the path name.
`transform_node_types`	Reduce any subclass of SettingNode and it's contents into instances of cls.
`update_setting`	Update an existing Setting in this tree.

classmethod fast_construct(name, settings=None, subtrees=None, *, path='', align_name=True, generate_paths=False, **kwargs)#

Fast construction alternative to __init__ from trusted serialized dict using model_construct.

This is the “middle ground” between __init__ (full validation and normalization) and BaseModel.model_construct (no normalization).

The key purpose is performance: when loading large trees (e.g. tens of thousands of settings) that were already validated before being written to the database, re-running Pydantic validation and index construction in __init__ is unnecessary and expensive. fast_construct lets us reuse that trusted data as-is and skip the extra work.

This must only be used with already validated / trusted data (DB rows, internal API payloads, etc.). It intentionally skips Pydantic validation and coercion, so untrusted input should always go through the normal constructor instead.

Parameters:

name (str)
settings (dict[str, Any] | None)
subtrees (dict[str, Any] | None)
path (str)
align_name (bool)
generate_paths (bool)
kwargs (Any)

Return type:

SettingNode

model_copy(*, update=None, deep=True)#

Copy the model.

deep=True and no update → use fast tree clone (_fast_deep_copy).
deep=False and no update → return self (no copy).
Any update → fall back to Pydantic’s model_copy for correct update handling.

Parameters:

update (Mapping[str, Any] | None)
deep (bool)

Return type:

Self

nodes_by_type(node_types=None, recursive=False)#

Yields all nodes, filtered by given node_types.

Used to find and iterate over nodes of specific types.

Parameters:

node_types (type | tuple[type, ...] | None) – when iterating over the tree, yields only instances that match this type or any of the types in the tuple. By default, yields Settings and SettingNodes.
recursive (bool) – If True, the search is carried recursively. If False, the search is limited to immediate child nodes.

Returns:

Iterator that yields the filtered nodes.

Return type:

Iterator

update_setting(setting)#

Update an existing Setting in this tree.

Parameters:: setting (Setting) – Setting that will replace an existing Setting with the same name. Or if the setting is an element-wise setting (i.e. it has a non-empty value of setting.element_indices), the corresponding element will be updated in the collection.
Raises:: UnknownSettingError – If no setting is found in the children of this tree.
Return type:: None

property all_settings: Generator[Setting]#: Yields all Setting instances inside this node, recursively.

property children: dict[str, Setting | SettingNode]#: Dictionary of immediate child nodes of this node.

property child_settings: ItemsView[str, Setting]#: ItemsView of settings of this node.

property child_nodes: ItemsView[str, SettingNode]#: ItemsView of immediate child nodes of this node.

get_parent_of(name)#

Get the first SettingNode that has a Setting named name.

Parameters:: name (str) – Name of the setting to look for.
Returns:: A SettingNode that has a child name.
Return type:: SettingNode

find_by_name(name)#

Find first occurrence of Setting or SettingNode by name, by iterating recursively through all children.

Parameters:: name (str) – Name of the Setting or SettingNode to look for.
Returns:: First found item, or None if nothing is found.
Return type:: SettingNode | Setting | None

static merge(first, second, merge_nones=False, align_name=True, deep_copy=True)#

Recursively combine the tree structures and values of two SettingNodes.

In case of conflicting nodes,values in first take priority regardless of the replaced content in second. None values are not prioritized unless merge_nones is set to True.

Parameters:

first (SettingNode) – SettingNode to merge, whose values and structure take priority
second (SettingNode) – SettingNode to merge.
merge_nones (bool) – Whether to merge also None values from first to second.
align_name (bool) – Whether to align the paths (and also names if second does not use align_name==False) when merging the nodes. Should never be set False unless the paths in first already align with what they should be in second (setting it False in such cases can improve performance).
deep_copy (bool) – Whether to deepcopy or just shallow copy all the sub-nodes. Set to False with high caution and understand the consequences.

Returns:

A new SettingNode constructed from arguments.

Return type:

SettingNode

merge_values(other, prioritize_other=False)#

Recursively combine the values from another SettingNode to this one.

The resulting tree structure the same as that of self.

Parameters:

other (SettingNode) – SettingNode to merge.
prioritize_other (bool) – If True, will prioritize values in other. If False (default), only None values in self will be replaced.

prune(other)#

Recursively delete all branches from this SettingNode that are not found in other.

Parameters:: other (SettingNode)
Return type:: None

print_tree(levels=5)#

Print a tree representation of the contents of this node.

Parameters:: levels (int) – display this many levels, starting from the root.
Return type:: None

classmethod transform_node_types(node)#

Reduce any subclass of SettingNode and it’s contents into instances of cls.

Parameters:: node (SettingNode) – node to transform.
Returns:: A new SettingNode with the same structure as the original, but where node instances are of type cls.
Return type:: SettingNode

set_from_dict(dct, strict=False, source=None)#

Recursively set values to Settings, taking values from a dictionary that has similar tree structure. Keys that are not found in self are ignored, unless strict is True.

Parameters:

dct (dict[str, Any]) – Dictionary containing the new values to use.
strict (bool) – If True, will raise error if dct contains a setting that is not found in self.
source (None | BaseModel | dict[str, Any]) – Source for the settings (this same source is applied to all settings from the dict).

Raises:

UnknownSettingError – If the condition of strict happens.

Return type:

None

setting_with_path_name(setting)#

Get a copy of a setting with its name replaced with the path name.

Parameters:: setting (Setting)
Return type:: Setting | None

diff(other, *, path='')#

Recursive diff between two SettingNodes.

This function is meant to produce human-readable output, e.g. for debugging purposes. It returns the differences in a list of strings, each string detailing one specific difference. The diff is non-symmetric.

Parameters:

other (SettingNode) – second node to compare self to
path (str) – node path to the currently compared nodes (used in printing the results)

Returns:

differences from self to other, in depth-first order

Return type:

list[str]

get_node_for_path(path)#

Return the node corresponding to the given path.

Parameters:: path (str) – The path.
Returns:: The node at path in self.
Raises:: ValueError – If the given path cannot be found in self.
Return type:: Setting | SettingNode

add_for_path(nodes, path, override_values=None, override_source=None)#

Add nodes to self while creating the missing nodes in-between.

Whether the names and paths are aligned is determined by the attribute align_name of the current node (self). All the created missing nodes will use this same align_name value, which determines whether their names will align with their paths.

Parameters:

nodes (Iterable[Setting | Parameter | SettingNode] | dict[str, Setting | Parameter | SettingNode]) – Nodes to add as new leaves/branches of path. If of type dict, maps the keys used in self.settings or self.subtrees to the nodes themselves. If align_name=False, the key and the node name can differ, but otherwise the names will be replaced by the path anyways).
path (str) – Path in self to which nodes will be added. If the path or any part (suffix) of it is not found in self, the associated nodes will be created automatically.
override_values (dict[str, Any] | None) – Optionally override the values for the Settings corresponding to nodes. This dict should have the same structure as nodes, including matching names. NOTE: If an override’s value is None, it is ignored.
override_source (None | BaseModel | dict[str, Any]) – Optionally override the source for the Settings corresponding to nodes. All the settings will then have this same source.

Return type:

None

get_default_implementation_name(gate, locus)#

Get the default implementation name for a given gate and locus.

Takes into account the global default implementation and a possible locus specific implementation and also the symmetry properties of the gate.

NOTE: using this method requires the standard EXA settings tree structure.

Parameters:

gate (str) – The name of the gate.
locus (str | Iterable[str]) – Individual qubits, couplers, or combinations.

Returns:

The default implementation name.

Return type:

str

get_gate_node_for_locus(gate, locus, implementation=None)#

Get the gate calibration sub-node for the locus given as a parameter if it exists in the settings tree.

NOTE: using this method requires the standard EXA settings tree structure.

Parameters:

gate (str) – The gate to retrieve the settings for.
locus (str | Iterable[str]) – Individual qubits, couplers, or combinations.
implementation (str | None) – Using a custom rather than the default gate implementation.

Returns:

The settings of the specified locus and gate.

Return type:

SettingNode

get_locus_node_paths_for(gate, implementations=None)#

Get all the gate locus node paths for a given gate.

NOTE: using this method requires the standard EXA settings tree structure.

Parameters:

gate (str) – Gate name.
implementations (list[str] | None) – optionally limit the paths by these gate implementations.

Returns:

The locus node (string) paths corresponding to this gate.

Return type:

list[str]

get_gate_properties_for_locus(gate, locus, implementation=None)#

Get the gate characterization sub-node for the locus given as a parameter if it exists in the settings tree.

NOTE: using this method requires the standard EXA settings tree structure.

Parameters:

gate (str) – The gate to retrieve the settings for.
locus (str | Iterable[str]) – Individual qubits, couplers, or combinations.
implementation (str | None) – Using a custom rather than the default gate implementation.

Returns:

The settings of the specified locus and gate.

Return type:

SettingNode

set_shots(shots, averaging_bins=None)#

Set playlist_repeats and averaging_bins under self.controllers.options.

Parameters:

shots (int) – The number of shots.
averaging_bins (int | None) – The number of averaging bins. If None, the same value as in shots will be used, i.e. no averaging is done.

Return type:

None

set_source(source, ignore_nones=True, ignore_populated=False)#

Set source recursively to all Settings in self.

Parameters:

source (None | BaseModel | dict[str, Any]) – The source to set.
ignore_nones (bool) – If True, the source will not be set for Settings with None value.
ignore_populated (bool) – If True, the source will not be set for Settings that already have a source.

Return type:

None

model_config = {'extra': 'ignore', 'frozen': True, 'ser_json_inf_nan': 'constants', 'validate_assignment': True, 'validate_default': False}#: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

Inheritance

SettingNode

Contents

SettingNode#