setting_node

A tree-structured container for Settings.

The SettingNode class combines a bunch of Settings together. It may also contain other SettingNodes. Together, the contents form a tree structure that provides a useful way of grouping Settings.

As an example, we manually construct a tree of SettingNodes with some dummy Settings, but it is usually not necessary. The root node in the following examples is called 'node'.

What’s inside?

The easiest way to see the content of the node is the SettingNode.print_tree() method:

 >>> node.print_tree(levels=1)
  "root"
  ║
  ╚═ flux: "root.flux"
  ╚═ pulse: "root.pulse"

We see that the 'root' node has two children, named 'root.flux' and 'root.pulse', which themselves are also SettingNodes. This follows the typical naming convention in EXA: Subnodes include the names of their parents, separated by a dot.

 >>> node.print_tree()
  "root"
  ║
  ╠═ flux: "root.flux"
  ║   ╠─ voltage: Voltage = 1.5 V
  ║   ╚─ resistance: Resistance = None (automatic/unspecified)
  ╚═ pulse: "root.pulse"
      ╠─ amplitude: Amplitude = 1.0
      ╚─ duration: Duration = 1e-07 s

The children contain some dummy Settings, showing the keys, labels and current values.

For other ways to access the content of the node, see also SettingNode.children, SettingNode.all_settings, and SettingNode.nodes_by_type().

Get and set values

The values within the nodes can be accessed using the attribute or dictionary syntax:

>>> node.pulse.amplitude.value
1.0
>>> node['flux']['voltage'].value
1.5

The values can be changed with a simple = syntax:

>>> node.pulse.amplitude = 1.4
>>> node.pulse.amplitude.value
1.4

Note

node.setting refers to the Setting object. node.setting.value syntax refers to the data stored inside.

Basic manipulation

Adding and deleting new Settings and nodes is simple:

>>> modified = node.copy()
>>> del modified.flux # removes the node
>>> del modified.pulse.amplitude # removes the Setting
>>> modified.pulse.my_new_setting = Setting(Parameter('my name'), 33)

It is usually a good idea to make a copy of the original node, so that it won’t be modified accidentally.

To merge values of two SettingNodes, there are helpers SettingNode.merge() and SettingNode.merge_values().

The first one merges the tree structure and values of two nodes and outputs a third one as a result. None values are always replaced by a proper value if such exists. In case of conflicting nodes or values, the content of the first argument takes priority.

>>> result = SettingNode.merge(node.flux, node.pulse)
>>> result.print_tree()
 "root.flux"
 ╠─ amplitude: Amplitude = 1.4
 ╠─ duration: Duration = 1e-07 s
 ╚─ voltage: Voltage = 1.5 V

Note how the result has values from node.flux, but also settings node.pulse that do not exist in node.flux.

The SettingNode.merge_values() method is an in-place operation that only changes the values of Settings that already exist in the node, if possible:

>>> modified = node.copy()
>>> modified.flux.voltage = 222
>>> modified.flux.resistance = 333
>>> node.merge_values(modified, prioritize_other=True)
>>> node.print_tree()
 "root"
 ║
 ╠═ flux: "root.flux"
 ║   ╠─ voltage: Voltage = 222 V
 ║   ╚─ resistance: Resistance = 333 Ohm
 ╚═ pulse: "root.pulse"
     ╠─ amplitude: Amplitude = 1.4
     ╚─ duration: Duration = 1e-07 s

Sometimes, it is easier to collect values in a dictionary and set them all at once by using SettingNode.set_from_dict(). The nested structure of the dictionary should match the structure of the SettingNode. Keys that are not found in the tree are silently ignored, unless the strict flag is used.

>>> values_to_set = {'flux': {'resistance': 0.001}, 'ignored_entry': 234}
>>> node.set_from_dict(values_to_set)
>>> node.flux.print_tree()
 "root.flux"
 ╠─ voltage: Voltage = 222 V
 ╚─ resistance: Resistance = 0.001 Ohm

Full path: exa.common.data.setting_node

Classes

SettingNode

A tree-structured Setting container.

Inheritance

digraph inheritance73f9298f86 { bgcolor=transparent; rankdir=LR; size="8.0, 12.0"; "SettingNode" [URL="exa.common.data.setting_node.SettingNode.html#exa.common.data.setting_node.SettingNode",fillcolor=white,fontname="Vera Sans, DejaVu Sans, Liberation Sans, Arial, Helvetica, sans",fontsize=10,height=0.25,shape=box,style="setlinewidth(0.5),filled",target="_top",tooltip="A tree-structured :class:`.Setting` container."]; }