The group command is the generic command used to manipulate groups. The syntax of this command follows the standard schema of command/subcommand/majorhandle/minorlabel.
Pseudo group labels first , last and random are special values, which select the first group in the group list, the last, or a random group.
group get $ehandle 1 G_SIZE
This is the list of officially supported subcommands:
group add ehandle label objectlist
Add more atoms or groups as members to an existing group. A group cannot be added to itself, and the formation of cyclic dependencies is illegal. It is however possible to add an atom or group more than once to a group, and an atom or a group may be a member of an arbitrary number of groups.
Adding objects to a group triggers a groupchange property invalidation event and may thus have an influence on the validity of chemical object data.
The use of an empty object list is possible and does not change the group, nor is an invalidation event issued.
The object list syntax is the same as in the
group create
command.
The command returns the group label.
group add $ehandle $glabel 1
group add $ehandle $glabel [list “group” [group create $ehandle [list 5 7]]]
The first sample line simply adds the atom with label 1 to the group. The second line adds a newly created group with atoms 5 and 7 to the existing group as a recursive group element.
group append ehandle label property value ?property value?..
Standard data manipulation command for appending property data. It is explained in more detail in the section about setting property data.
group append $ehandle 1 G_NAME “_linker”
group atoms ehandle label ?filterset? ?filtermode?
List the labels of all atoms which are in the group. There are two different modes of operation, depending on whether the group contains at least one atom as member object.
If there is a member atom: Group member objects which are not atoms, such as bonds or recursive groups, are omitted from output, as are atoms which are only indirectly a group member via a recursive group.
Without atoms in the group, atoms which are components of the group objects are listed.
In other respects, this is a standard cross-referencing command. The usage of the filterset and filtermode parameter is explained in the section about object cross-references.
set gh [group create $ehandle [list 1 2 3]]
group atoms $ehandle $gh carbon
gets the labels of the carbon atoms in the group.
set gh [group create $ehandle [list [list „bond“ 1]]]
group atoms $ehandle $gh
while this command on a group which only contains bonds, but no atoms, reports the atom labels of the bond in the group.
group bonds ehandle label ?filterset? ?filtermode?
Retrieve the labels of bonds which are associated with a group. There are two different modes of operation, depending on whether the group contains at least one bond as member object.
If there is a member bond, Group member objects which are not bonds, such as atoms or recursive groups, are omitted from output, as are bonds which are only indirectly a group member via a recursive group.
Otherwise, a bond is considered to be associated with a group if all atoms of the bond are group members. All bond atoms must be in the same group object, i.e. indirect memberships via recursive groups are ignored. Bonds are not associated with a group if only some of their atoms are members of the group.
In other respects, this is a standard cross-referencing command. The usage of the filterset and filtermode parameter is explained in the section about object cross-references.
set gh [group create $ehandle [list 1 2 3]]
group bonds $ehandle $gh {1 doublebond triplebond}
gets the bond labels of all double and triple bonds between the group atoms.
set gh [group create $ehandle [list [list „bond“ 1]]]
group bonds $ehandle $gh
group create ehandle objectlist
Create a new group containing atoms or other minor objects, including other groups as member elements.
The object list parameter is a list of object identifiers. An object identifier is either a single-element simple identifier, in which case it is interpreted as an atom identifier (usually a label, but all other identifiers are possible), or a two-element list. If the second form is used, the list must consist of an object class name, followed by an object identifier (usually a label, but all types of minor object identifiers are possible).
Specifying a member object which cannot be resolved produces an error. However, it is no error for an atom or a group to be listed more than once as a member of a group, nor is there any restriction of how many groups an atom or other minor object can be a member. However, circular relationships are illegal, and a group cannot be a member of itself. Duplicate objects in a group are allowed and not filtered when a group is set up.
Creating a new group triggers the group and groupchange invalidation events and may thus influence the validity of chemical object data.
The creation of empty groups by supplying an empty object list is possible.
The return value of this function is the label of the new group.
set g1 [group create $ehandle {1 2 3}]
set g2 [group create $ehandle [list [list “group” $g1] 4 [list “atom” #5]]]
The first line creates a simple group with atoms 1, 2 and 3. The second line builds a recursive group which contains the first group (identified as a group reference by prefixing its label with a group object class name), the atom with label 4, and the atom with index 5 (which could have any label).
group defined ehandle label property
This command checks whether a property is defined for the group. 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
ens valid
command is used for this purpose.
group defined $ehandle 1 G_XYZ
checks whether group 1 is of a type for which G_XYZ is defined.
group delete ehandle ?label?...
group delete ehandle all
Delete a set of groups. Groups are either identified by a standard group identifier (usually a label), or the reserved word all.
If a deleted group contains as a member another group, that group is also deleted in a recursive fashion. If this behavior is not wanted, recursive groups should be explicitly unlinked from their base groups by means of the
group remove
command.
Deleting a group triggers the group and groupchange invalidation events and may thus influence the validity of chemical object data. If an empty object list is used, the command does nothing, and no invalidation event is generated.
This command returns the number of deleted groups on the first level, i.e. recursive group deletions are not counted.
group delete $ehandle all
group delete $ehandle [ens groups $ehandle xatom]
The first example deletes all groups in the ensemble. The second example deletes all those groups which contain one or more hetero atoms as members.
group dget ehandle label propertylist ?filterset? ?parameterlist?
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
group get
command. The difference between
group get
and
group 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,
group get
and
group dget
are equivalent.
group dup ehandle label ?datasethandle? ?position?
Duplicate the atoms and bonds of a group into a new ensemble. The function returns the new ensemble handle.
By default, the new ensemble is appended to the same dataset as the original ensemble, or placed outside of any dataset if the input ensemble was not a dataset member. If the optional dataset handle parameter is specified, the duplicate is directly moved to that dataset. If an empty string is passed, the duplicate is not made a dataset member, even if the input ensemble is in a dataset.
group dup $ehandle 1 [dataset create]
duplicates the group with label one and move the new single-molecule ensemble into a newly created dataset.
group exists ehandle label ?filterlist?
Check whether this group exists. Optionally, a filter list can be supplied to check for the presence of specific features. The command returns 0 if the group does not exist, or fails the filter, and 1 in case of successful testing.
group exists $ehandle 99
group expr ehandle label expression
Compute a standard SQL -style property expression for the group. This is explained in detail in the chapter on property expressions.
group fill ehandle label property value ?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.
group fill $ehandle 1 B_COLOR red
sets the color of the first bond group 1 contains or is associated with to red.
group filter ehandle label filterlist
Check whether a group passes a filter list. The return value is 1 for success and 0 for failure.
group filter $ehandle 1 [list carbon doublebond]
checks whether the group contains one or more carbon atoms and one or more double bonds. The double bond does not need to be with a carbon atom.
group get ehandle label propertylist ?filterset? ?parameterlist?
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
group get $ehandle 1 {G_SIZE A_ELEMENT}
yields a list with two elements, consisting of the group size (count of group members) as the first element and the element numbers of all atoms in the groups as a nested list as the second result list element. If the information is not yet available, an attempt is made to compute it. If the computation fails, an error results.
group get $ehandle 1 B_ORDER ringbond
gives the bond orders of all bonds of associated with the group which are ring bonds.
For the use of the optional property parameter list argument, refer to the documentation of the
ens get
command.
Variants of the group get command are group new, group dget, group nget, group show, group sqldget, group sqlget, group sqlnew and group sqlshow .
group get $ehandle 1 E_NAME
group get $ehandle 1 A_FLAGS(boxed)
group group ehandle label
Standard cross-referencing command to obtain the label of the group as stored in property
G_LABEL
. This is explained in more detail in the section about object cross-references. Note that there is also a
group groups
(plural
groups
) command which has a different function.
group group $ehandle #0
returns the label of the first group of the ensemble group list.
group groups ehandle label ?filterset? ?filtermode?
List the labels of all groups which are members of the group. Group member objects, such as atoms, which are not groups are omitted, as are groups which are only indirectly a group member via a recursive group.
In other respects, this is a standard cross-referencing command. The usage of the
filterset
and
filtermode
parameter is explained in the section about object cross-references. Note that there is also a
group group
(singular
group
) command which has a different function.
group groups $ehandle 1
gets the labels of the groups which are a (recursive) member of group 1.
group hdup ehandle label ?datasethandle? ?position?
This command provides the same functionality as
group dup
, except that it also adds a standard set of hydrogens to the new ensemble.
group index ehandle label
Get the index of the group. The index is the position in the group list of the ensemble. The first position is index 0.
group index $ehandle 99
group local ehandle label propertylist ?filterset? ?parameters?
Standard data manipulation command for reading and recalculating object data. It is explained in more detail in the section about retrieving property data.
group local $ehandle 1 A_LABEL_STEREO
Note that very few computation routines currently support the local re-computation of data - in most cases, this command falls back to a global re-computation.
group match ehandle label ss_ehandle ?ss_label? ?matchflags? ?ignoreflags? ?atommapvar? ?bondmapvar? ?molmapvar?
Check whether the selected group matches a substructure. Only the first substructure group, or the group selected by the substructure label parameter, is tested. The substructure may be part of any structure ensemble, and even be in the same ensemble as the primary command group. Both the atoms in the group and the bonds between them are checked.
The precise operation of the substructure match routine can be tuned by providing a standard set of match flags and feature ignore flags. The default match flag set has set bits for the bondorder , atomtree and bondtree comparison features, and an empty ignore set. If a flag set is specified as an empty string, the default set is used. In order to reset a flag set, an explicit none value must be used.
The command returns 1 for a successful match, 0 otherwise. If an optional atom, bond, or molecule map variable is specified, it is set to a nested list of matching substructure/structure atom, bond or molecule labels. If no match can be found, the variable is set to an empty list. In case only a bond or molecule map variable is needed, an empty string can be used to skip the unused map variable argument positions.
set ss [ens create {c1ccccc1} smarts]
set g_contains_phenyl_ring [group match $ehandle $label $ss]
group mols ehandle label ?filterset? ?filtermode?
Standard cross-referencing command to obtain the labels of the molecules the atoms in the group are a member of. This is explained in more detail in the section about object cross-references.
group mols $ehandle 1
group mols $ehandle 1 heterocycle
The first example is simple retrieval, the second line filters the molecules and lists only the labels of those molecules which contain one or more heterocycles.
group new ehandle label propertylist ?filterset? ?parameterlist?
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
group get
command. The difference between
group get
and
group new
is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.
group nget ehandle label propertylist ?filterset? ?parameterlist?
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
group get
command. The difference between
group get
and
group nget
is that the latter always returns numeric data, even if symbolic names for the values are available.
group objects ehandle label ?filterset? ?filtermode?
This is a cross-referencing command specific to groups. The standard operation of cross-referencing commands and the use of the optional parameters are explained in the object referencing section of this manual.
The difference of this command to the
group atoms, group bonds
or
group groups
commands is that this command lists all object classes present in the group. Every listed item is output as a list with two elements - the first being the object class (
atom
,
bond
or
group
), the second being the object label. This list is suitable for use in a
group create
or
group add
statement.
group create $ehandle [group objects $ehandle 1]
group pis ehandle label ?filterset? ?filtermode?
Standard cross-referencing command to obtain the labels of the π systems the group is associated with. This is explained in more detail in the section about object cross-references.
group pis $ehandle 1
π systems are a rather exotic feature and not commonly used. These are essentially descriptions of bonding interactions which use p or d orbitals, such as in standard covalent multiple bonds. A simple double bond is described with one σ system and one π system in this representation.
group remove ehandle label objectlist
Remove group elements from a group. The removed objects are not deleted from the ensemble, they simply are no longer a group member. The syntax of the object list is the same as in the
group add
and
group create
commands. The groups the objects are removed from also remain in existence.
Removing an object from a group triggers a groupchange property invalidation event and may thus have an influence on the validity of chemical object data.
The command returns the number of removed group elements.
group remove $ehandle 1 [group atoms $ehandle 1 hydrogen]
group rings ehandle label ?filterset? ?filtermode?
Standard cross-referencing command to obtain the labels of the rings the group is associated with. This is explained in more detail in the section about object cross-references. Rings which only partially overlap with the group are included.
group rings $ehandle 1
group rings $ehandle 1 [list heterocycle aroring]
The first example returns the labels of all rings the group overlaps with. If the group does not overlap with any ring, an empty list is returned. Only labels of rings in the SSSR or ESSSR set are returned, even if the currently computed ring set is larger. The second example filters the rings - only heteroaromatic rings are reported.
group ringsystems ehandle label ?filterset? ?filtermode?
Standard cross-referencing command to obtain the labels of the ring systems the group is associated with. This is explained in more detail in the section about object cross-references. Ring system which only partially overlap with the selected group are listed.
group ringsystems $ehandle 1
group ringsystems $ehandle 1 [list heterocycle aroring]
The first example returns the labels of all ring systems the group is associated with. If the group does not overlap with any ringsystem, an empty list is returned. The second example filters the ring systems - a ring system label is added to the output list only if that ring system contains one or more hetero aromats.
group set ehandle label property value ?property value?..
Standard data manipulation command for setting property data. It is explained in more detail in the section about setting property data.
group set $ehandle 1 G_CONSTRAINT [list “distance” [list 3.0 4.0]]
group show ehandle label propertylist ?filterset? ?parameterlist?
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 group get command. The difference between
group get
and
group 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,
group get
and
group show
are equivalent.
group sigmas ehandle label ?filterset? ?filtermode?
Standard cross-referencing command to obtain the labels of the σ systems the group is associated with. This is explained in more detail in the section about object cross-references. An association is assumed if any atoms of the σ system is a group member. Recursive groups are not searched.
group sigmas $ehandle 1
σ systems are a rather exotic feature and not commonly used. These are essentially descriptions of bonding interactions which use s orbitals, such as normal, covalent single bonds, or the central bond in multiple bonds. A simple double bond is described with one σ system and one π system in this representation.
group sqldget ehandle label propertylist ?filterset? ?parameterlist?
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
group get
command. The differences between
group get
and
group 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
script processing.
group sqlget ehandle label propertylist ?filterset? ?parameterlist?
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
group get
command. The difference between
group get
and
group sqlget
is that the
SQL
command variant formats the data as
SQL
values rather than for Tcl script processing.
group sqlnew ehandle label propertylist ?filterset? ?parameterlist?
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
group get
command. The differences between
group get
and
group 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
script processing.
group sqlshow ehandle label propertylist ?filterset? ?parameterlist?
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
group get
command. The differences between
group get
and
group 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
script processing.
group subcommands
Lists all subcommands of the
group
command. Note that this command does not require an ensemble handle, or a group label.
group surfaces ehandle label ?filterset? ?filtermode?
Standard cross-referencing command to obtain the labels of surface patches the group is associated with. This is explained in more detail in the section about object cross-references.
group surfaces $ehandle $label
Note that surface patches do not need to be associated with an atom, and if they are not, they are implicitly not associated with any group.