sierra.core.experiment.definition#

Functionality for reading, writing, etc., experiment definitions.

Format-specific bits handled at a lower level via plugin; this is generic functionality for experiment definitions.

Classes#

`AttrChange`	Specification for a change to an existing expdef attribute.
`AttrChangeSet`	Data structure for `AttrChange` objects.
`BaseExpDef`	Base class for experiment definitions.
`ElementAdd`	Specification for adding a new expdef tag.
`ElementAddList`	Data structure for `ElementAdd` objects.
`ElementRm`	Specification for removal of an existing expdef tag.
`ElementRmList`	Data structure for `ElementRm` objects.
`NullMod`	Specification for a null-change (no change) to an existing expdef.
`WriterConfig`	Config for writing `BaseExpDef`.

Module Contents#

class sierra.core.experiment.definition.AttrChange(path: str, attr: str, value: str | int | float)[source]#: Specification for a change to an existing expdef attribute.

class sierra.core.experiment.definition.AttrChangeSet(*args: AttrChange | NullMod)[source]#

Data structure for AttrChange objects.

The order in which attributes are changed doesn't matter from the standpoint of correctness (i.e., different orders won't cause crashes).

static unpickle(fpath: pathlib.Path) → AttrChangeSet[source]#

Unpickle changes.

You don't know how many there are, so go until you get an exception.

class sierra.core.experiment.definition.BaseExpDef(input_fpath: pathlib.Path, write_config: WriterConfig | None = None)[source]#

Base class for experiment definitions.

abstract attr_add(path: str, attr: str, value: str | int | float, noprint: bool = False) → bool[source]#

Add the specified attribute to the element matching the specified path.

Only the FIRST element matching the specified path searching from the tree root is modified.

Parameters:

path -- An expression uniquely identifying the element containing the attribute to add. The element must exist or an error will be raised.
attr -- An expression uniquely identifying the attribute to change within the enclosing element.
value -- The value to set the attribute to.

abstract attr_change(path: str, attr: str, value: str | int | float, noprint: bool = False) → bool[source]#

Change the specified attribute of the element at the specified path.

Only the attribute of the FIRST element matching the specified path is changed.

Parameters:

path -- An expression uniquely identifying the element containing the attribute to change. The element must exist or an error will be raised.
attr -- An expression uniquely identify the attribute to change within the enclosing element.
value -- The value to set the attribute to.

abstract attr_get(path: str, attr: str) → str | int | float | None[source]#

Retrieve the specified attribute of the element at the specified path.

If it does not exist, None is returned.

abstract element_add(path: str, tag: str, attr: sierra.core.types.StrDict | None = None, allow_dup: bool = True, noprint: bool = False) → bool[source]#: Add tag name as a child element of enclosing parent.

abstract element_change(path: str, tag: str, value: str) → bool[source]#

Change the specified tag of the element matching the specified path.

Parameters:

path -- An expression uniquely identifying the element containing the tag to change. The element must exist or an error will be raised.
tag -- An expression uniquely identifying the tag to change within the enclosing element.
value -- The value to set the tag to.

abstract element_remove(path: str, tag: str, noprint: bool = False) → bool[source]#

Remove the specified child tag in the enclosing parent.

If more than one tag matches, only one is removed. If the path does not exist, nothing is done.

Parameters:

path -- An expression uniquely identifying the element containing the tag to remove. The element must exist or an error will be raised.
tag -- An expression uniquely identifying the tag to remove within the enclosing element.

abstract element_remove_all(path: str, tag: str, noprint: bool = False) → bool[source]#

Remove the specified child tag(s) in the enclosing parent.

If more than one tag matches in the parent, all matching child tags are removed.

Parameters:

path -- An expression uniquely identifying the element containing the tag(s) to remove. The element must exist or an error will be raised.
tag -- An expression uniquely identifying the tag to remove within the enclosing element.

abstract flatten(keys: list[str]) → None[source]#

Replace the specified filepath attributes with their contents.

Filepaths are interpreted relative to the directory in which the original experiment definition template resides, and assumed to be defined as such.

abstract has_attr(path: str, attr: str) → bool[source]#: Determine if the attribute uniquely identified by path exists.

abstract has_element(path: str) → bool[source]#: Determine if the element uniquely identified by path exists.

abstract n_mods() → tuple[int, int][source]#: Get the # (adds, changes) as a tuple.

abstract write(base_opath: pathlib.Path) → None[source]#: Write the definition stored in the object to the filesystem.

class sierra.core.experiment.definition.ElementAdd(path: str, tag: str, attr: sierra.core.types.StrDict, allow_dup: bool, as_root: bool = False)[source]#

Specification for adding a new expdef tag.

The tag may be added idempotently, or duplicates can be allowed.

class sierra.core.experiment.definition.ElementAddList(*args: ElementAdd)[source]#

Data structure for ElementAdd objects.

The order in which tags are added matters (i.e., if you add dependent tags in the wrong order you will get an exception), hence the list representation.

static unpickle(fpath: pathlib.Path) → ElementAddList | None[source]#

Unpickle modifications.

You don't know how many there are, so go until you get an exception.

class sierra.core.experiment.definition.ElementRm(path: str, tag: str)[source]#: Specification for removal of an existing expdef tag.

class sierra.core.experiment.definition.ElementRmList(*args: ElementRm)[source]#

Data structure for ElementRm objects.

The order in which tags are removed matters (i.e., if you remove dependent tags in the wrong order you will get an exception), hence the list representation.

class sierra.core.experiment.definition.NullMod[source]#: Specification for a null-change (no change) to an existing expdef.

class sierra.core.experiment.definition.WriterConfig(values: list[dict])[source]#

Config for writing BaseExpDef.

Different parts of the AST can be written to multiple files, as configured.

The order of operations for the applying the config should be:

Extraction of subtree

Renaming subtree root

Adding new children

Adding grafts

Attributes: values: Dict with the following possible key, value pairs:

src_parent - The parent of the root of the AST specifying a sub-tree to write out as a child of new_children_parent, or None to write out entire AST. This key is required. If None omitted then then tree rooted at src_tag is written out. Otherwise, the subtree rooted at <src_parent>/<src_tag> is written out instead.

src_tag - Unique query path expression for the child element within src_parent to write out; that is this tag is the root of the sub-tree within the experiment definition to write out. This key is required.

rename_to - String to rename the root of the AST written out. This key is optional, and should be processed after {src_parent, src_tag}.

new_children_parent - Unique query path expression for the parent element to create new child elements under via new_children. This key is optional; can be omitted or set to None.

new_children - Ordered List of ElementAdd objects to use to create new child elements under new_children_parent. Must form a tree with a single root when added in order.

opath_leaf - Additional bits added to whatever the opath file stem that is set for the BaseExpDef instance. This key is optional. Can be used to add an extension; this is helpful because some engines require input files to have a certain extension, and SIERRA strips out the extension passed to --expdef-template used as the bases for creating experiments.

child_grafts_parent - Unique query path expression for the parent element to for grafting elements under via child_grafts. This path expression is relative to <src_tag> due to ordering. This key is optional; can be omitted or set to None.

child_grafts - Additional bits of the current AST to add under child_grafts_parent in the written out experiment definition, specified as a list of query path strings. This key is optional.