The pi Command

The pi command is the generic command used to manipulate π systems. The syntax of this command follows the standard schema of command/subcommand/majorhandle/minorlabel .

Pseudo π system labels first , last and random are special values, which select the first π system in the π system list, the last, or a random π system.

Examples:

pi get $ehandle 1 P_ATOMS

This is the list of officially supported subcommands:

pi append

pi 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.

Example:

pi append $ehandle 1 P_NAME “_uvactive”

pi atoms

pi atoms ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of the atom in the π system. This is explained in more detail in the section about object cross-references.

Example:

pi atoms $ehandle 1 carbon

returns the labels of the carbon atoms in the π system.

pi bonds

pi bonds ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of the bonds the π system contains. This is explained in more detail in the section about object cross-references. Technically, a π system contains atoms, not bonds. This command lists all bonds which exist between atoms in the π system. Bonds involving only a single atom in a π system are excluded.

Examples:

pi bonds $ehandle 1
pi bonds $ehandle 1 {1 doublebond triplebond} count

The first example returns all labels of the bonds π system 1 contains. The second example returns the number of double or triple bonds in the π system.

pi create

pi create ehandle ?atom?...

Define a new π system from an atom set. A new π system is always created, even if one with the same atoms already exists. No check on the presence of π electrons is performed. Before the command is executed, the default π system set is automatically instantiated if it was not yet computed. Adding a new π system invalidates properties which are sensitive to π system changes.

The command returns the label of the new π system.

pi defined

pi defined ehandle label property

This command checks whether a property is defined for the π system. 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.

pi delete

pi delete ehandle ?label?...

This command removes π systems from the ensemble π system list and destroys them. A pi property invalidation event is generated and thus the command may indirectly change the ensemble data.

This command is rarely used. π systems are usually generated and destroyed automatically.

The command returns the number of deleted items.

pi dget

pi 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 pi get command. The difference between pi get and pi dget is that the latter does not attempt computation of property data, but rather initializes the property values to the default and returns that default if the data is not yet available. For data already present, pi get and pi dget are equivalent.

pi exists

pi exists ehandle label ?filterlist?

Check whether this π system exists. Optionally, a filter list can be supplied to check for the presence of specific features. The command returns 0 if the π system does not exist, or fails the filter, and 1 in case of successful testing.

Example:

pi exists $ehandle 99

pi expr

pi expr ehandle label expression

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

pi fill

pi 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.

pi filter

pi filter ehandle label filterlist

Check whether a π system passes a filter list. The return value is 1 for success and 0 for failure.

Example:

pi filter $ehandle 1 [list carbon doublebond]

checks whether the π system contains one or more carbon atoms and one or more double bonds. The double bond does not need to contain a carbon atom.

pi get

pi 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.

pi groups

pi groups ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of the groups the π system overlaps with. This is explained in more detail in the section about object cross-references. An overlap between a π system and a group is established when there are common atoms which are contained in both objects.

Example:

pi groups $ehandle 1

pi index

pi index ehandle label

Get the index of the π system. The index is the position in the π system list of the ensemble. The first position is index 0.

Example:

pi index $ehandle 99

pi jget

pi jget ehandle label propertylist ?filterset? ?parameterlist?

This is a variant of pi get which returns the result data as a JSON formatted string instead of Tcl interpreter objects.

pi jnew

pi jnew ehandle label propertylist ?filterset? ?parameterlist?

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

pi jshow

pi jshow ehandle label propertylist ?filterset? ?parameterlist?

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

pi local

pi 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.

pi match

pi match ehandle label ss_ehandle ?ss_label? ?matchflags? ?ignoreflags? ?atommapvar? ?bondmapvar? ?molmapvar?

Check whether the selected π system matches a substructure. Only the first substructure π system, or the π system 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 π system. Both the atoms in the π system 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.

Examples:

pi match [ens create C=CCC=N] 1 C=C
pi match [ens create C=CCC=N] 1 N=C
pi match [ens create C=CCC=N] 2 C=C
pi match [ens create C=CCC=N] 2 N=C

The first and last commands match, the second and third do not.

pi mol

pi mol ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of the molecules the π system is contained in. This is explained in more detail in the section about object cross-references.

pi new

pi 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.

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

pi nget

pi 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 pi get command. The difference between pi get and pi nget is that the latter returns numeric data, even if symbolic names for the values are available.

pi pi

pi pi ehandle label

Standard cross-referencing command to obtain the label of the π system as stored in property P_LABEL . This is explained in more detail in the section about object cross-references.

Example:

pi pi $ehandle #0

returns the label of the first π system of the ensemble π system list.

pi rings

pi rings ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of the rings the π system is associated with. This is explained in more detail in the section about object cross-references. Rings which only partially overlap with the π system are included.

Examples:

pi rings $ehandle 1
pi rings $ehandle 1 [list heterocycle aroring]

The first example returns the labels of all rings the π system overlaps with. If the π system 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.

pi ringsystems

pi ringsystems ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of the ring systems the π system is associated with. This is explained in more detail in the section about object cross-references. Ring systems which only partially overlap with the π system are included.

pi set

pi set ehandle label property value ?property value?..

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

pi show

pi 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 pi get command. The difference between pi get and pi 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, pi get and pi show are equivalent.

pi sigmas

pi sigmas ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of the σ systems the π system overlaps with. This is explained in more detail in the section about object cross-references.

Examples:

pi 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.

pi sqldget

pi 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 pi get command. The differences between pi get and pi 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.

pi sqlget

pi 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 pi get command. The difference between pi get and pi sqlget is that the SQL command variant formats the data as SQL values rather than for Tcl script processing.

pi sqlnew

pi 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 pi get command. The differences between pi get and pi 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.

pi sqlshow

pi 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 pi get command. The differences between pi get and pi 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.

pi subcommands

pi subcommands

Lists all subcommands of the pi command. Note that this command does not require an ensemble handle, or a label.

pi surfaces

pi surfaces ehandle label ?filterset? ?filtermode?

Standard cross-referencing command to obtain the labels of surface patches the π system is associated with. This is explained in more detail in the section about object cross-references.

Example:

pi 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 π system.