qimpy.TreeNode

class TreeNode(**kwargs)

Bases: object

Base class of objects in tree for construction and checkpointing. Provides functionality to set-up tree heirarchy based on input dicts, such as from YAML files, and to output to checkpoints such as in HDF5 files preserving the same tree structure.

__init__(**kwargs)

Methods

__init__

add_child

Construct child object self.`attr_name` of type cls.

add_child_one_of

Invoke add_child on one of several child options in args.

save_checkpoint

Save self and all children in hierarchy to cp_path.

Attributes

child_names

Names of attributes with child objects.
class ChildOptions(attr_version_name, cls, params, **kwargs)

Bases: object

Arguments to qimpy.TreeNode.add_child. Used to specify multiple option lists in qimpy.TreeNode.add_child_one_of.

Parameters:

  • attr_version_name (str) –

  • cls (Type[TreeNodeType]) –

  • params (TreeNodeType | dict | None) –

add_child(attr_name, cls, params, checkpoint_in, attr_version_name='', **kwargs)

Construct child object self.`attr_name` of type cls. Specifically, construct object from params and kwargs if params is a dict, and just from kwargs if params is None. During construction, object and its children will load data from checkpoint_in, if it contains a loaded checkpoint file. Any ‘-’ in the keys of params are replaced with ‘_’ for convenience. Otherwise check that params is already of type cls, and if not, raise an error clearly stating the types attr_name can be.

Optionally, attr_version_name overrides attr_name used in the error, which may be useful when the same attr_name could be initialized by several versions eg. kpoints in Electrons could be k-mesh (Kmesh) or k-path (Kmesh). For such cases, use add_child_one_of instead, which wraps add_child and handles the selection of which version of the child to use.

Finally, this routine supports a special case when params is str. In this case, params becomes a dict mapping that str to {}. This is a useful shortcut for a child which has one of many sub-objects. The str specifies the name of the sub-object with default parameters. The full dict version must be used instead to specify non-default values. Typically, the child will use add_child_one_of for its initialization. This is convenient to simplify syntax for geometry, thermostat etc.

Parameters:

  • attr_name (str) –

  • cls (Type[TreeNodeType]) –

  • params (TreeNodeType | dict | str | None) –

  • checkpoint_in (CheckpointPath) –

  • attr_version_name (str) –

Return type:

None

add_child_one_of(attr_name, checkpoint_in, *args, have_default)

Invoke add_child on one of several child options in args. At most one of the child options should have a params that is not None. If have_default, create child with the first class and default params. Otherwise, at least one of the child options should have a non-None params.

If loading from checkpoint_in, this will search for attribute named attr_name in the checkpoint and use that to select the child if none are specified. If parameters for a different child are specified, that takes precedence and checkpoint_in will be suppressed for that child’s initialization (as the data within would be incompatible).

Parameters:
Return type:

None

final save_checkpoint(cp_path, context)

Save self and all children in hierarchy to cp_path. Here, context helps identify why/when this checkpoint is being called, e.g. at a geometry step, or at the end of the simulation. Override _save_checkpoint to implement the save functionality.

Parameters:
Return type:

None

child_names: list[str]

Names of attributes with child objects.