hierarchy add

hierarchy add hhandle ?handle?...

h.add(?handle/ref?,...)

Add objects to a hierarchy. The handles can be ensembles, reactions, datasets, tables, networks, biologics or hierarchies. If an added object is a hierarchy, it is added as a subtree. The new objects are added at the end of the current object set in the hierarchy. It is possible to use this command to change the position of an object within a hierarchy, or to transfer it from a different hierarchy.

In addition to recognized handles, the arguments may also be identifiable reaction or structure line encodings, such as SMILES or Reaction SMILES strings. These objects are decoded with standard options, get their own handles, and immediately added to the hierarchy.

The command returns the hierarchy handle or reference.

hierarchy append

hierarchy append hhandle ?property value?...

h.append({?property:value,?...})

h.append(?property,value,?...)

Standard data manipulation command for appending property data. It is explained in more detail in the section about setting property data.

The command returns the first data value.

hierarchy assign

hierarchy assign hhandle srcproperty dstproperty

h.assign(srcproperty=,dstproperty=)

Assign property data to another property on the same hierarchy. Both properties must be associated with the hierarchy object class. This process is more efficient than going through a pair of hierarchy get/hierarchy set commands, because in most cases no string or Tcl/Python script object representations of the property data need to be created.

Both source and destination properties may be addressed with field specifications. A data conversion path must exist between the data types of the involved properties. If any data conversion fails, the command fails. For example, it is possible to assign a string property to a numeric property - but only if all property values can be successfully converted to that numeric type. The reverse example case always succeeds, out-of-memory errors and similar global events excluded.

The original property data remains valid. The command variant hierarchy rename directly exchanges the property name without any data duplication or conversion, if that is possible. In any case, the original property data is no longer present after the execution of this command variant.

The command returns the object handle for Tcl , or object reference for Python .

If the object class of the assigned property is not hierarchy, the command executes recursively on all hierarchy objects.

Examples:

hierarchy assign $hh H_IDENT H_NAME

hierarchy assign $hh E_IDENT E_NAME

hierarchy biologics

hierarchy biologics hhandle ?filterlist? ?recursive?

h.biologics(?filters=?,?recursive=?)

Return a list of the handles or references of all biologics objects in the hierarchy node which additionally pass the filter set, if one is specified.

By default, only those items directly stored on the command object are listed, but this can be changed via the boolean recursive flag. If it is set, the command additionally traverses all hierarchy objects below the current one. Recursively found objects are appended to the list without a level indication. The hierarchy node they are attached to, and from there its level H_LEVEL or other property value, can be obtained by the object’s hierarchy command.

Example:

hierarchy biologics $hhandle

hierarchy create

hierarchy create ?handle?...

Hierarchy(?handle/ref?,...)

Hierarchy.Create(?handle/ref?,...)

Create a new hierarchy object with an initial set of embedded objects.

The arguments may be handles of structure ensembles, reactions, datasets, networks, tables, or hierarchies themselves.

In addition to recognized handles, the arguments may also be identifiable reaction or structure line encodings, such as SMILES or Reaction SMILES strings. These objects are decoded with standard options, get their own handles, and immediately added to the hierarchy.

The command returns the handle or reference of the newly created hierarchy object.

hierarchy dataset

hierarchy dataset hhandle ?filterlist?

h.dataset(?filters=?)

Return the dataset handle or reference of the dataset the hierarchy is a member of. It the hierarchy is not member of a dataset, or does not pass all of the optional filters, an empty string or None for Python is returned.

This command is not the same as hierarchy datasets .

Example:

hierarchy dataset $hhandle

hierarchy datasets

hierarchy datasets hhandle ?filterlist? ?recursive?

h.biologics(?filters=?,?recursive=?)

Return a list of the handles or references of all dataset objects in the hierarchy node which additionally pass the filter set, if one is specified.

By default, only those items directly stored on the command object are listed, but this can be changed via the boolean recursive flag. If it is set, the command additionally traverses all hierarchy objects below the current one. Recursively found objects are appended to the list without a level indication. The hierarchy node they are attached to, and from there its level H_LEVEL or other property value, can be obtained by the object’s hierarchy command.

This is not the same as the hierarchy dataset command.

Example:

hierarchy datasets $hhandle

hierarchy defined

hierarchy defined hhandle property

h.defined(property)

This command checks whether a property is defined for the hierarchy. This is explained in more detail in the section about property validity checking. Note that this is not a check for the presence of property data! The hierarchy valid command is used for this purpose.

hierarchy delete

hierarchy delete ?hhandle/hhandlelist/all?...

h.delete()

Hierarchy.Delete(“all”)

Hierarchy.Delete(?href/hrefsequence/hhandle?,...)

Delete hierarchy objects. The special parameter all may be used to delete all hierarchies currently registered in the application. Alternatively, any number of hierarchy handles may be specified for specific object deletions.

The command returns the number of deleted hierarchies.

Example:

hierarchy delete all

hierarchy delete $hhandle

hierarchy dget

hierarchy dget hhandle propertylist ?filterset? ?parameterdict?

h.dget(property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the network get command. The difference between hierarchy get and hierarchy dget is that the latter does not attempt computation of property data, but rather initializes the property values to the default and return that default if the data is not yet available. For data already present, hierarchy get and hierarchy dget are equivalent.

hierarchy dup

hierarchy dup hhandle ?dataset? ?position?

h.dup(?target=?,?position=?)

Duplicate a hierarchy with all objects in them and all attached data on the hierarchy object proper and its contained objects.

The duplicate hierarchy is placed into the same dataset as the source, if it is a member of a dataset. Specifying an explicitly empty dataset argument (or None for Python ) places the duplicate outside any dataset, regardless of the dataset membership of the source hierarchy.

If the duplicate is moved to a dataset, it is appended to the dataset end by default. This happens also if the position parameter is explicitly specified as end or an empty string. Otherwise, the hierarchy is inserted at the given position, starting with 0. If the requested position is larger than the current size of the dataset, the hierarchy is appended.

Example:

hierarchy dup $hhandle

The command returns a new hierarchy handle or reference.

hierarchy ens

hierarchy ens hhandle ?filterlist? ?recursive?

h.ens(?filters=?,?recursive=?)

Return a list of the handles or references of all structure ensemble objects in the hierarchy node which additionally pass the filter set, if one is specified.

By default, only those items directly stored on the command object are listed, but this can be changed via the boolean recursive flag. If it is set, the command additionally traverses all hierarchy objects below the current one. Recursively found objects are appended to the list without a level indication. The hierarchy node they are attached to, and from there its level H_LEVEL or other property value, can be obtained by the object’s hierarchy command.

Example:

hierarchy ens $hhandle

hierarchy exists

hierarchy exists hhandle ?filterlist?

h.exists(?filters=?)

Hierarchy.Exists(href,?filters=?)

Check whether a hierarchy handle or reference is valid. The command returns boolean 0 or 1. Optionally, the hierarchy may be filtered by a standard filter list, and if it does not pass the filter, it is reported as not valid.

Example:

hierarchy exists $hhandle

hierarchy expr

hierarchy expr hhandle expression

h.expr(expression)

Compute a standard SQL -style property expression for the hierarchy. This is explained in detail in the chapter on property expressions.

hierarchy fill

hierarchy fill hhandle ?property value?...

h.fill({?property:value,...})

h.fill(?property,value?,...)

Standard data manipulation command for setting data, ignoring possible mismatches between the lengths of the lists of objects associated with the property and the value list. It is explained in more detail in the section about setting property data.

hierarchy filter

hierarchy filter hhandle filterlist

h.filter(filters=)

Check whether the hierarchy passes a filter list. The return value is boolean 1 for success and 0 for failure.

hierarchy get

hierarchy get hhandle propertylist ?filterset? ?parameterdict?

hierarchy get hhandle attribute

h.get(property=,?filters=?,?parameters=?)

h.get(attribute)

h[property/attribute]

h.property/attribute

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

Examples:

hierarchy get $hhandle {H_IDENT H_NAME}

yields the ID and name of the hierarchy as a list. If the information is not available, an attempt is made to compute it. If the computation fails, an error results.

For the use of the optional property parameter list argument, refer to the documentation of the ens get command.

Variants of the hierarchy get command are hierarchy new, hierarchy dget, hierarchy jget, hierarchy jnew, hierarchy jshow, hierarchy nget, hierarchy show, hierarchy sqldget, hierarchy sqlget, hierarchy sqlnew, and hierarchy sqlshow .

In addition to property data, a hierarchy object possesses a few attributes, which can be retrieved with the get command (but not by its related sister subcommands like dget , sqlget , etc.). Some of them are also modifiable via hierarchy set. These attributes are:

• coords
  If the toolkit was compiled with factory support, these are the coordinates of the object icon on its workbench, encoded as integer pair. This attribute can be changed.
• deletable
  Flag indicating whether the object can be deleted with a standard hierarchy delete command. This attribute is read-only. Objects which are, for example, property data values cannot be deleted by standard means.
• failures
  If the property computation failure cache is active, return a list of all properties which have failed computation for this object after the last structural change. This attribute is read-only.
• footer
  If the toolkit was compiled with factory support, this is the footer of the object icon on a workbench. This attribute can be changed.
• gflags
  If the toolkit was compiled with factory support, this is the currently set object icon rendering flag collection.
• header
  If the toolkit was compiled with factory support, this is the header of the object icon on a workbench. This attribute can be changed.
• hidden
  Flag indicating whether the object is hidden. This is not the same as the invisible state. This attribute is intended to be used for rendering selections. This attribute can be changed.
• incomplete
  Boolean status flag indicating an aborted input operation during the read of the object from file, which returned the structure intact but without the complete set of associated data. An aborted input may be either be the result of an explicitly set input control flag, or by encountering property data which could not be decoded. This attribute is read-only.
• invisible
  Flag indicating whether the object is invisible. This is not the same as the hidden state. An invisible object is no longer accessible via its handle. This is usually the case for objects which are scheduled for deletion, but still have lingering pointer references. This attribute is read-only.
• javaobject
  If the toolkit was compiled with JNI support, this attribute reports the memory address of the JNI wrapper class instance, if it exists.
• modcount
  Object data modification count. This attribute is read-only.
• mutexcount
  The number of recursive mutex locks held for this object. Only supported on Linux.
• pyobject
  If the toolkit was compiled with Python support, this attribute reports the memory address of the Python wrapper class instance, if it exists. This attribute is read-only.
• pyrefcount
  If the toolkit was compiled with Python support, this attribute reports the reference count of the Python wrapper class instance, if it exists. This attribute is read-only.
• refcount
  If the Tcl interpreter is using native Cactvs objects instead of string-based major object handles and integer-based minor object labels to identify toolkit objects, this returns the number of Tcl object references active for this object. This attribute is read-only.
• scoped
  A boolean object visibility control flag. If set, and global control flag ::cactvs(object_scope) is also set, the object is visible only in the Tcl interpreter which set the scope flag and thus claimed it. Object list commands executed in other interpreters omit this object, and attempts to decode its handle in other interpreters will fail. The most common use of this feature is the hiding of persistent chemistry objects in scripted property computation functions.
• selected
  Flag indicating whether the object is selected. This attribute can be changed.
• tooltip
  If the toolkit was compiled with factory support, this is the tooltip of the object icon on a workbench. This attribute can be changed.
• uuid
  An automatically generated UUID globally identifying the object. This attribute is read-only, different for every object, and not dependent on its contents.
• x
  If the toolkit was compiled with factory support, this is the x coordinate of the object icon on its workbench. This attribute can be changed.
• y
  If the toolkit was compiled with factory support, this is the y coordinate of the object icon on its workbench.This attribute can be changed.

hierarchy getparam

hierarchy getparam hhandle property ?key? ?default?

h.getparam(property=,?key=?,?default=?)

Retrieve a named computation parameter from valid property data. If the key is not present in the parameter list, an empty string is returned ( None for Python ). If the default argument is supplied, that value is returned in case the key is not found.

If the key parameter is omitted, a complete set of the parameters used for computation of the property value is returned in dictionary format.

This command does not attempt to compute property data. If the specified property is not present, an error results.

hierarchy hdup

hierarchy hdup hhandle ?dataset? ?position?

h.hdup(?target=?,?position=?)

Duplicate a hierarchy with all objects in them and all attached data on the hierarchy object proper and its contained objects. Additionally, hydrogen addition is performed on all objects which support this operation.

The duplicate hierarchy is placed into the same dataset as the source, if it is a member of a dataset. Specifying an explicitly empty dataset argument (or None for Python ) places the duplicate outside any dataset, regardless of the dataset membership of the source hierarchy.

If the duplicate is moved to a dataset, it is appended to the dataset end by default. This happens also if the position parameter is explicitly specified as end or an empty string. Otherwise, the hierarchy is inserted at the given position, starting with 0. If the requested position is larger than the current size of the dataset, the hierarchy is appended.

Example:

hierarchy hdup $hhandle

The command returns a new hierarchy handle or reference.

hierarchy hierarchies

hierarchy hierarchies hhandle ?filterlist? ?recursive?

h.hierarchies(?filters=?,?recursive=?)

Return a list of the handles or references of all hierarchy objects in the hierarchy node which additionally pass the filter set, if one is specified.

By default, only those items directly stored on the command object are listed, but this can be changed via the boolean recursive flag. If it is set, the command additionally traverses all hierarchy objects below the current one. Recursively found objects are appended to the list without a level indication. The hierarchy node they are attached to, and from there its level H_LEVEL or other property value, can be obtained by the object’s hierarchy command.

This command is not the same as the hierarchy hierarchy command.

Example:

hierarchy hierachies $hhandle

hierarchy hierarchy

hierarchy hierarchy hhandle ?filterlist? ?root?

h.hierarchy(?filters=?,?root=?)

Return the hierarchy handle or reference of the hierarchy the command object is part of. If the command object is the root node, or does not pass all of the optional filters, an empty string or None for Python is returned. By default, the hierarchy object which directly contains the command object is returned. If the root flag is set, the root hierarchy object is reported instead, which is the same only if the hierarchy has only a single level.

This is not the same as the hierarchy hierarchies command.

Example:

hierarchy hierarchy $hhandle

hierarchy index

hierarchy index hhandle

h.index()

Get the position of the hierarchy in the object list of its dataset. If the object is not member of a dataset, -1 is returned.

hierarchy jget

hierarchy jget hhandle propertylist ?filterset? ?parameterdict?

h.jget(property=,?filters=?,?parameters=?)

This is a variant of hierarchy get which returns the result data as a JSON formatted string instead of Tcl or Python interpreter objects. The command is usable only for property data, not attribute retrieval.

hierarchy jnew

hierarchy jnew hhandle propertylist ?filterset? ?parameterdict?

h.jnew(property=,?filters=?,?parameters=?)

This is a variant of hierarchy new which returns the result data as a JSON formatted string instead of Tcl or Python interpreter objects.

hierarchy jshow

hierarchy jshow hhandle propertylist ?filterset? ?parameterdict?

h.jshow(property=,?filters=?,?parameters=?)

This is a variant of hierarchy show which returns the result data as a JSON formatted string instead of Tcl or Python interpreter objects.

hierarchy list

hierarchy list ?filterlist?

Hierarchy.List(?filters=?)

This command returns a list of the hierarchy handles currently registered in the application. This list may optionally be filtered by a standard filter list.

hierarchy lock

hierarchy lock hhandle propertylist/hierarchy/all ?compute?

h.lock(property=,?compute=?)

Lock property data of the hierarchy object, meaning that it is no longer subject to the standard data consistency manager control. The data consistency manager deletes specific property data if anything is done to the hierarchy which would invalidate the information. Property data remains locked until is it explicitly unlocked.

The property data to lock can be selected by providing a list of the following identifiers:

• Property names
  Valid property instances on the hierarchy object are locked. If the boolean compute flag is set, an attempt is made to compute the property if it is not yet present. Otherwise, a request to lock non-existent data is silently ignored. It is not possible to lock individual property fields.
• all
  All valid hierarchy properties are locked. The compute flag is ignored.
• hierarchy
  This is an object class identifier. All property data which is controlled by the hierarchy major object and attached to the specified object class is locked. Since hierarchies do not contain minor objects, this identifier is equivalent to all .

The lock can be released by a hierarchy unlock command.

The return value is the original hierarchy handle or reference.

hierarchy max

hierarchy max hhandle propertylist ?filterset?

h.max(property=,?filters=?)

Get the maximum value of one or more properties in from the elements in the hierarchy. The property argument may be any property attached to hierarchy members, or minor objects thereof. If the filterset argument is specified, the maximum value is searched only for objects which pass the filter set.

hierarchy metadata

hierarchy metadata hhandle property ?field ?value??

h.metadata(property=,?field=?,?value=?)

Obtain property metadata information, or set it. The handling of property metadata is explained in more detail in its own introductory section. The related commands hierarchy setparam and hierarchy getparam can be used for convenient manipulation of specific keys in the computation parameter field. Metadata can only be read from or set on valid property data.

hierarchy min

hierarchy min hhandle propertylist ?filterset?

h.min(property=,?filters=?)

Get the minimum value of one or more properties in from the elements in the hierarchy. The property argument may be any property attached to hierarchy members, or minor objects thereof. If the filterset argument is specified, the maximum value is searched only for objects which pass the filter set.

hierarchy move

hierarchy move hhandle ?datasethandle|remotehandle? ?position?

h.move(?target=?,?position=?)

Make the hierarchy a member of a dataset, or remove it from a dataset. If the dataset handle or reference parameter is omitted, or is an empty string, or None for Python , the object is removed from its current dataset. The dataset handle or reference may be the name of a remote dataset for moving objects over a network connection.

If a target dataset handle or reference is specified, the object is added to the dataset, if allowed by the acceptance bits of the dataset, and removed from any dataset it was member of before the execution of the command. By default the object is added to the end of the dataset object list, but the final optional parameter allows the specification of a dataset object list index. The first position is index zero. If the parameter value end is used, or the index is bigger than the current number of dataset objects minus one, the hierarchy is appended as per the default. It is legal to use this command for moving objects within the same dataset.

Another special position value is random or rnd . This value moves to the object to a random position in the dataset. Using this mode with remote datasets is currently not supported.

By default, datasets do not accept hierarchies as objects. This must be explicitly enabled by modifying the acceptance bits, as for example in

dataset append $dhandle accepts hierarchy

The dataset handle cannot be a transient dataset.

The return value of the command is the dataset of the object prior to the move operation. It is either a dataset handle/reference, or an empty string ( Tcl ) or None ( Python ) if it was not member of a dataset.

hierarchy mutex

hierarchy mutex hhandle mode

h.mutex(mode)

Manipulate the object mutex. During the execution of a script command, the mutex of the major object(s) associated with the command are automatically locked and unlocked, so that the operation of the command is thread-safe. This applies to builds that support multi-threading, either by allowing multiple parallel script interpreters in separate threads or by supporting helper threads for the acceleration of command execution or background information processing.

This command locks major objects for a period of time that exceeds a single command. A lock on the object can only be released from the same interpreter thread that set the lock. Any other threaded interpreters, or auxiliary threads, block until a mutex release command has been executed when accessing a locked command object. This command supports the following modes:

• lock
  Increase the recursive mutex lock count on the object. The command returns the current lock count after the command, excluding the transient single-command lock.
• reset
  Release all persistent locks on the object, if they exist.
• test
  Return the current persistent lock count on the object. This excludes the transient per-command lock.
• unlock
  Decrease the recursive lock count on the object. The command returns the current lock count after the command, excluding the transient single-command lock. Unlocking an object which has not been persistently locked results in an error.

There is no trylock command variant because the command already needs to be able to acquire a transient object mutex lock for its execution.

The command returns the current lock count.

hierarchy need

hierarchy need hhandle propertylist ?mode? ?parameterdict?

h.need(property=,?mode=?,?parameters=?)

Standard command for the computation of property data, without immediate retrieval of results. This command is explained in more detail in the section about retrieving property data.

The return value is the original hierarchy handle or reference.

hierarchy networks

hierarchy networks hhandle ?filterlist? ?recursive?

h.networks(?filters=?,?recursive=?)

Return a list of the handles or references of all network objects in the hierarchy node which additionally pass the filter set, if one is specified.

By default, only those items directly stored on the command object are listed, but this can be changed via the boolean recursive flag. If it is set, the command additionally traverses all hierarchy objects below the current one. Recursively found objects are appended to the list without a level indication. The hierarchy node they are attached to, and from there its level H_LEVEL or other property value, can be obtained by the object’s hierarchy command.

Example:

hierarchy networks $hhandle

hierarchy new

hierarchy new hhandle propertylist ?filterset? ?parameterdict?

h.new(property=,?mode=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the hierarchy get command. The difference between hierarchy get and hierarchy new is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.

hierarchy nget

hierarchy nget hhandle propertylist ?filterset? ?parameterdict?

h.nget(property=,?mode=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the hierarchy get command. The difference between hierarchy get and hierarchy nget is that the latter always returns numeric data, even if symbolic names for the values are available.

hierarchy nnew

hierarchy nnew hhandle propertylist ?filterset? ?parameterdict?

h.nnew(property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data and attributes. It is explained in more detail in the section about retrieving property data.

For examples, see the hierarchy get command. The difference between hierarchy get and hierarchy nnew is that the latter always returns numeric data, even if symbolic names for the values are available, and that property data re-computation is enforced.

hierarchy objects

hierarchy objects hhandle ?filterlist? ?recursive?

h.objects(?filters=?,?recursive=?)

Return a list of the handles or references of all objects in the hierarchy node which pass the filter set, if one is specified. Lower hierarchy node objects are not listed.

By default, only those items directly stored on the command object are listed, but this can be changed via the boolean recursive flag. If it is set, the command additionally traverses all hierarchy objects below the current one. Recursively found objects are appended to the list without a level indication. The hierarchy node they are attached to, and from there its level H_LEVEL or other property value, can be obtained by the object’s hierarchy command.

Example:

hierarchy objects $hhandle

hierarchy pack

hierarchy pack hhandle ?maxsize? ?requestprops? ?suppressedprops? ?compressionlib?

h.pack(?maxsize=?,?requestprops=?,?suppressedprops=?,?compressionlib=?)

Pack the hierarchy object into a base64-encoded compressed serialized object string. This string does not contain any non-printable characters and is a full dump of the internal state of the object, omitting only property data that was declared to be so easily re-computed that a dump is not worthwhile. The objects in the hierarchy and their property data are part of the dump. Further object relationships, such as datasets the object might be a member in are not saved.

The maximum size of the object string (default -1, meaning unlimited size) can be configured by the optional maxsize parameter. The size is specified in bytes. If the pack string would be longer than the maximum size, an error results.

The other optional property parameter lists allow to request a specific property set to be part of the package, even if it normally would not be included, and to explicitly omit properties from the dump. No property computation is performed, and suppressed properties are not purged from the hierarchy.

Hierarchies can be restored from a packed object string by the hierarchy unpack command.

The hierarchy object and its contained objects remain in existence after using this command.

The default compression library is zlib . Other useful variants include lzo and gzip (and there are other internal types), but these may not be available on all builds due to license issues, and you need to specify the compression library when a dataset is unpacked. It is generally recommended to stay with zlib .

The return value of this command is the packed string.

In Python , hierarchy objects support the standard pickle / unpickle protocol.

Example:

set dbstring [hierarchy pack $hhandle]

hierarchy properties

hierarchy properties hhandle ?pattern? ?noempty?

h.properties(?pattern=?,?noempty=?)

Generate a list of the names of all properties attached to the hierarchy object. Optionally, the list may be filtered by a string match pattern.

If the noempty flag is set, only properties where at least one data element is not the property default value are output. By default, the filter pattern is an empty string, and the noempty flag is not set.

The command may be abbreviated to props instead of the full name properties .

hierarchy purge

hierarchy purge hhandle propertylist/hierarchy/specialname ?emptyonly?

h.purge(properties=,?emptyonly?)

Delete property data from the hierarchy. If a property marked for deletion is not present on an object, it is silently ignored. If the hierarchy is not a dataset member, a request for the deletion of dataset properties is also ignored.

If the object class name hierarchy is used instead of a specific property name, all hierarchy property data ( H_ prefix) is deleted from the object.

The optional boolean flag emptyonly can be used to restrict the deletion to those properties where all the values for a property associated with a major object (such as on all atoms in an ensemble for atom properties, or just the single ensemble property value for ensemble properties) are set to the default property value.

The return value is the original object handle or reference.

hierarchy reactions

hierarchy reactions hhandle ?filterlist? ?recursive?

h.reactions(?filters=?,?recursive=?)

Return a list of the handles or references of all reaction objects in the hierarchy node which additionally pass the filter set, if one is specified.

By default, only those items directly stored on the command object are listed, but this can be changed via the boolean recursive flag. If it is set, the command additionally traverses all hierarchy objects below the current one. Recursively found objects are appended to the list without a level indication. The hierarchy node they are attached to, and from there its level H_LEVEL or other property value, can be obtained by the object’s hierarchy command.

Example:

hierarchy reactions $hhandle

hierarchy ref

Hierarchy.Ref(identifier)

Python only method to get a hierarchy reference from a handle or another identifier. For hierarchies, other recognized identifiers are hierarchy references, integers encoding the numeric part of the handle string, or the UUID of the hierarchy object.

hierarchy remove

hierarchy remove hhandle ?objhandle?...

h.remove(?oref/ohandle?,...)

Remove objects from the hierarchy. The object arguments must be a member of the command hierarchy object.

The command returns the original handle or reference.

hierarchy rename

hierarchy rename hhandle srcproperty dstproperty

h.rename(srcproperty=,dstproperty=)

This is a variant of the hierarchy assign command. Please refer the command description in that paragraph.

hierarchy set

hierarchy set hhandle ?property value?...

h.set(property,value,...)

h.set({property:value,...})

h.property = value

h[property] = value

Standard data manipulation command. It is explained in more detail in the section about setting property data.

hierarchy setparam

hierarchy setparam hhandle property ?key value?...

hierarchy setparam hhandle property dictionary

h.setparam(property,?key,value?...)

h.setparam(property,dict)

Set or update a property computation parameter in the metadata parameter list of a valid property. This command is described in the section about retrieving property data. The current settings of the computation parameters in the property definition are not changed.

The return value is the updated property computation parameter dictionary.

hierarchy show

hierarchy show hhandle propertylist ?filterset? ?parameterdict?

h.show(property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the hierarchy get command. The difference between hierarchy get and hierarchy show is that the latter does not attempt computation of property data, but raises an error if the data is not present and valid. For data already present, hierarchy get and hierarchy show are equivalent.

hierarchy sqldget

hierarchy sqldget hhandle propertylist ?filterset? ?parameterdict?

h.sqldget(property=,?mode=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the hierarchy get command. The differences between hierarchy get and hiedrarchy sqldget are that the latter does not attempt computation of property data, but initializes the property value to the default and returns that default, if the data is not present and valid; and that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

hierarchy sqlget

hierarchy sqlget hhandle propertylist ?filterset? ?parameterdict?

h.sqldget(property=,?mode=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the hierarchy get command. The difference between hierarchy get and hierarchy sqlget is that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

hierarchy sqlnew

hierarchy sqlnew hhandle propertylist ?filterset? ?parameterdict?

h.sqlnew(property=,?mode=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the hierarchy get command. The differences between hierarchy get and hierarchy sqlnew are that the latter forces re-computation of the property data, and that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

hierarchy sqlshow

hierarchy sqlshow hhandle propertylist ?filterset? ?parameterdict?

h.sqlshow(property=,?mode=?,?parameters=?)

Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.

For examples, see the hierarchy get command. The differences between hierarchy get and hierarchy sqlshow are that the latter does not attempt computation of property data, but raises an error if the data is not present and valid, and that the SQL command variant formats the data as SQL values rather than for Tcl or Python script processing.

hierarchy subcommands

hierarchy subcommands

dir(Hierarchy)

Lists all subcommands of the hierarchy command. Note that this command does not require a hierarchy handle.

hierarchy tables

hierarchy tables hhandle ?filterlist? ?recursive?

h.tables(?filters=?,?recursive=?)

Return a list of the handles or references of all table objects in the hierarchy node which additionally pass the filter set, if one is specified.

By default, only those items directly stored on the command object are listed, but this can be changed via the boolean recursive flag. If it is set, the command additionally traverses all hierarchy objects below the current one. Recursively found objects are appended to the list without a level indication. The hierarchy node they are attached to, and from there its level H_LEVEL or other property value, can be obtained by the object’s hierarchy command.

Example:

hierarchy tables $hhandle

hierarchy transfer

hierarchy transfer hhandle propertylist ?targethandle? ?targetpropertylist?

h.transfer(properties=,?target=?,?targetproperties=?)

Copy property data from one hierarchy to another hierarchy or other major object, without going through an intermediate scripting language object representation, or dissociate property data from the hierarchy. If a property in the argument property list is not already valid on the source reaction, an attempt is made to compute it.

If a target property list is given, the data from the source is stored as content of a different property on the target. For this, the data types of the properties must be compatible, and the object class of the target property that of the target object. No attempt is made to convert data of mismatched types. In case of multiple properties, the source property list and the target property list are stepped through in parallel. If there is no target property list, or it is shorter than the source list, unmatched entries are stored as original property values, and this implies that the object class of the source and target objects are the same.

If no target object is specified, or it is spelled as an empty string or Python None , the visible effect of the command is the same as a simple hierarchy get , i.e. the result is the property data value or value list. The property data is then deleted from the source object. In case the data type of the deleted property was a major object (i.e. an ensemble, reaction, table, dataset or network), it is only unlinked from the source object, but not destroyed. This means that the object handles returned by the command can henceforth the used as independent objects. They can be deleted by a normal object deletion command, and are no longer managed by the source object.

hierarchy unlock

hierarchy unlock hhandle propertylist/hierarchy/all

h.unlock(property=)

Unlock property data for the reaction, meaning that they are again under the control of the standard data consistency manager.

The property data to unlock can be selected by providing a list of the following identifiers:

• Property names or references
  Valid property instances on the hierarchy are unlocked. Non-existent data is silently ignored. It is not possible to unlock individual property fields.
• all
  All valid hierarchy properties are unlocked.
• hierarchy
  This is an object class identifier. All property data which is controlled by the hierarchy major object and attached to the specified object class is unlocked. Since hierarchies do not contain minor objects, this identifier is equivalent to all .

Property data locks are obtained by the hierarchy lock command.

The return value is the original hierarchy handle or reference.

hierarchy unpack

hierarchy unpack packstring ?compressionlib?

Hierarchy.Unpack(data=,?compressionlib=?)

Unpack a base64-encoded serialized object string which was created by a hierarchy pack command. The return value of this function is the handle or reference of the newly created hierarchy object, which is an exact duplicate of the packed original hierarchy.

The default compression library is zlib . For more options, see reaction pack .

Example:

set packdata [hierarchy pack [hierarchy create C=O>>CO]]

set hhandle [hierarchy unpack $packdata]

hierarchy valid

hierarchy valid hhandle propertylist

h.valid(property/propertysequence)

Returns a list of boolean values indicating whether values for the named properties are currently set for the hierarchy. No attempt at computation is made. For Python , where single-item lists are syntactically not the same as a single value, the return value is a single boolean if the argument was a string or a property reference, and only a single property was decoded.

hierarchy has is an alias to this command.

hierarchy verify

hierarchy verify hhandle property

h.verify(property)

Verify the values of the specified property on the hierarchy. The property data must be valid, and a hierarchy property. If the data can be found, it is checked against all constraints defined for the property, and, if such a function has been defined, is tested with the value verification function of the property.

If all tests are passed, the return value is boolean 1, 0 if the data could be found but fails the tests, and an error condition otherwise.