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.
pi get $ehandle 1 P_ATOMS
This is the list of officially supported subcommands:
pi append ehandle label ?property value?...
p.append({?property:value,?...})
p.append(?property,value,?...)
Standard data manipulation command for appending property data. It is explained in more detail in the section about setting property data.
pi append $ehandle 1 P_NAME “_uvactive”
pi atoms ehandle label ?filterset? ?filtermode?
p.atoms(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the atom in the π system. This is explained in more detail in the section about object cross-references.
pi atoms $ehandle 1 carbon
pi bonds ehandle label ?filterset? ?filtermode?
p.bonds(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references 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.
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 ehandle ?atom/atomlist?...
Pi(eref,?aref/arefsequence/alabel?,...)
Pi(aref,...)
Pi.Create(eref,?aref/arefsequence/alabel?,...)
Pi.Create(aref,...)
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.
pi defined ehandle label property
p.defined(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 ehandle ?label?...
pi delete ehandle all
p.delete()
Pi.Delete(eref,?pref/plabel/prefsequence?,...)
Pi.Delete(pref,...)
Pi.Delete(eref,“all”)
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.
pi dget ehandle label propertylist ?filterset? ?parameterdict?
p.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
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 ehandle label ?filterlist?
p.exists(?filters=?)
Pi.Exists(eref,label,?filters=?)
Check whether this π system exists. Optionally, a filter list can be supplied to check for the presence of specific features. The command returns boolean 0 if the π system does not exist, or fails the filter, and 1 in case of successful testing.
pi exists $ehandle 99
pi expr ehandle label expression
p.expr(expression)
Compute a standard SQL -style property expression for the π system. This is explained in detail in the chapter on property expressions.
pi fill ehandle label ?property value?...
p.fill({property:value,...})
p.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.
pi filter ehandle label filterlist
p.filter(filters)
Check whether a π system passes a filter list. The return value is boolean 1 for success and 0 for failure.
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 ehandle label propertylist ?filterset? ?parameterdict?
p.get(property=,?filters=?,?parameters=?)
p[property]
p.property
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
pi groups ehandle label ?filterset? ?filtermode?
p.groups(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references 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.
pi groups $ehandle 1
pi index ehandle label
p.index()
Get the index of the π system. The index is the position in the π system list of the ensemble. The first position is index 0.
pi index $ehandle 99
pi jget ehandle label propertylist ?filterset? ?parameterdict?
p.jget(property=,?filters=?,?parameters=?)
This is a variant of
pi get
which returns the result data as a
JSON
formatted string instead of
Tcl
or
Python
interpreter objects.
pi jnew ehandle label propertylist ?filterset? ?parameterdict?
p.jnew(property=,?filters=?,?parameters=?)
This is a variant of
pi new
which returns the result data as a
JSON
formatted string instead of
Tcl
or
Python
interpreter objects.
pi jshow ehandle label propertylist ?filterset? ?parameterdict?
p.jshow(property=,?filters=?,?parameters=?)
This is a variant of
pi show
which returns the result data as a
JSON
formatted string instead of
Tcl
or
Python
interpreter objects.
pi local ehandle label propertylist ?filterset? ?parameterdict?
p.local(property=,?filters=?,?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 ehandle label ss_ehandle ?ss_label? ?matchflags? ?ignoreflags? ?atommatchvar? ?bondmatchvar? ?molmatchvar?
p.match(substructure=,?substructurepisystem=?,?matchflags=?,?ignoreflags=?, ?atommatchvariable=?,?bondmatchvariable=?,?molmatchvariable=?)
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 match 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, or None for Python . In case only a bond or molecule match variable is needed, an empty string can be used to skip the unused match variable argument positions.
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 ehandle label ?filterset? ?filtermode?
p.mol(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the molecules the π system is contained in. This is explained in more detail in the section about object cross-references.
pi new ehandle label propertylist ?filterset? ?parameterdict?
p.new(property=,?filters=?,?parameters=?)
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 ehandle label propertylist ?filterset? ?parameterdict?
p.nget(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
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 ehandle label
Pi.Ref(eref,identifier)
Standard cross-referencing command to obtain the label or reference of the π system as stored in property P_LABEL . This is explained in more detail in the section about object cross-references.
pi pi $ehandle #0
returns the label of the first π system of the ensemble π system list.
pi rings ehandle label ?filterset? ?filtermode?
p.rings(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references 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.
pi rings $ehandle 1
pi rings $ehandle 1 [list heterocycle aroring]
The first example returns the labels or references 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 ehandle label ?filterset? ?filtermode?
p.ringsystems(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references 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 ehandle label ?property value?...
p.set(?property,value?,...)
p.set({property:value,...})
p.property = value
p[property] = value
Standard data manipulation command. It is explained in more detail in the section about setting property data.
pi show ehandle label propertylist ?filterset? ?parameterdict?
p.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 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 ehandle label ?filterset? ?filtermode?
p.sigmas(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the σ systems the π system overlaps with. This is explained in more detail in the section about object cross-references.
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 ehandle label propertylist ?filterset? ?parameterdict?
p.sqldget(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
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
or
Python
script processing.
pi sqlget ehandle label propertylist ?filterset? ?parameterdict?
p.sqlget(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
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
or
Python
script processing.
pi sqlnew ehandle label propertylist ?filterset? ?parameterdict?
p.sqlnew(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
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
or
Python
script processing.
pi sqlshow ehandle label propertylist ?filterset? ?parameterdict?
p.sqlshow(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
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
or
Python
script processing.
pi subcommands
dir(Pi)
Lists all subcommands of the
pi
command. Note that this command does not require an ensemble handle, or a label.
pi surfaces ehandle label ?filterset? ?filtermode?
p.surfaces(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of surface patches the π system is associated with. This is explained in more detail in the section about object cross-references.
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.