The bond command is the generic command used to manipulate bond. The syntax of this command follows the standard schema of command/subcommand/majorhandle/minorlabel .
bond get $ehandle 1 B_ORDER
bond atoms $ehandle 2
This is the list of officially supported subcommands:
bond align3d ehandle label point1 point2 ?property?
b.align3d(point1=,point2=,?coordinateproperty=?)
Align the 3D atomic coordinates (by default in property A_XYZ ) of the molecule the first specified atom of the bond is a member of in such a fashion that the first bond atom is positioned on the first point argument, and the vector to the second bond atom points into the same direction as the vector from the first to the second point argument.The bond lengths are not changed in this process.
The syntax of the point arguments is the generic vector syntax as documented in the
vec
command. If the bond is selected with an identifier different than an atom pair, the first bond atom is the atom moved to the first point argument. If the atom pair specification syntax is used, the first atom in the specification list is the anchor, which may or may not be the first bond atom.
The command fails if property A_XYZ (or is explicitly specified alternative) is not present on the ensemble and cannot be computed.
bond align3d $eh {2 1} 0 x
Atom 2 is moved to the origin, and the bond from atom 2 to atom 1 points in x-direction, i.e. it has a 3D coordinate triple like {0.0,0.0,1.5}, with the bond length as z component. The other atomic coordinates in the molecule are adjusted accordingly.
The command does not check for coordinate overlap with atoms in other molecules in the ensemble.
In case of special bonds, the second atom may not be in the same molecule as the first. This is legal - its coordinates are only needed to compute the axis and degree of rotation - though the second atom is then not moved by the command.
The command returns the label (for Tcl ) or reference (for Python ) of the bond.
bond append ehandle label ?property value?...
b.append({?property:value,?...})
b.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.
bond append $ehandle 1 B_LABELCOLOR “00”
bond atoms ehandle label ?filterset? ?filtermode?
b.atoms(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the atoms which form the bond. This is explained in more detail in the section about object cross-references.
bond atoms $ehandle 1
bond atoms $ehandle 1 {!carbon !hydrogen} count
The first example returns all labels of the atoms in bond 1. The second example will compute the number of atoms in the bond which are neither carbon nor hydrogen.
bond bond ehandle label
Bond.Ref(eref,identifier)
Standard cross-referencing command to obtain the label (for Tcl ) or reference (for Python ) of the bond as stored in property B_LABEL from a bond label, or another bond identifier, such as an atom label pair. This is explained in more detail in the section about object cross-references.
bond bond $ehandle [list 1 2]
returns the label of the bond between atoms 1 and 2, or an empty string if the bond does not exist.
bond change ehandle label deltabondorder/type ?deltacharge?
b.change(deltabondorder=,?deltacharge=?)
Bond.Change(eref=,atoms=,deltabondorder=,?deltacharge=?)
This command changes the order of a bond. It may also be used to create bonds, or to delete bonds.
As in all bond commands, the bond may either be identified by its label or equivalent descriptor, or a set of atom identifiers. In case a new bond is made, a list or tuple of atom labels or other atom identifiers is provided as parameter instead of a single bond identifier. The distinction between atom and bond references is performed via the list length of the label parameter. Anything with more than one list element is interpreted as an atom-based specification. The order of atoms in an atom-based specification is arbitrary.
The parameter deltabondorder is usually a signed integer which defines the bond order change. If it is 0, the command does nothing, if the deltacharge parameter is also zero or omitted. If it is less than zero, the bond order is reduced. For VB bonds, the free electron count on the atoms (property A_FREE_ELECTRONS ) is adjusted. If the bond is not a valence bond, or the change in bond order is larger than the existing bond order, the bond is deleted. If the change in bond order is positive, and the bond type a normal VB bond, the bond order is increased, provided that the atoms have sufficient free electrons for bonding (again property A_FREE_ELECTRONS ). A positive change in bond order for a non-VB bond has no effect.
If a bond type is specified in string form instead of a numerical bond order, the type of the bond is changed in B_TYPE . If it originally was a VB bond, the bond electrons are added to the atom free electron count in A_FREE_ELECTRONS . If the bond type is changed to a VB bond from another type, an attempt to create a single bond is made and the electron count adjusted. If the count would become negative, the operation fails. The Python interface uses the deltabondorder named argument also for this bond type change operation, which is slightly misleading.
If the optional chargedelta parameter is used, electrons which imply formal charge (property A_FORMAL_CHARGE ) are transferred between the atoms before the bond operation. The charge difference is applied to the first atom in the specification, and implicitly the second atom is affected inversely. If the bond was specified by a bond label instead of an atom list, the internal order of the atoms in the bond is used.
bond change [ens create CC] {1 2} -1
bond change [ens create CC] {2 1} -1 1
set ehandle [ens create C=O]; bond change $ehandle {1 2} -1; ens hadd $ehandle
bond change [ens create {[H+].[OH-]}] {1 2} 1 -1
The first example line performs a radical dissociation between the carbon atom (atoms 1 and 2 - when decoding a SMILES string, the atom labels correspond to the sequence in the SMILES string). The bond order change is -1, which cuts the bond because it is only a single bond. Since no charge modification was specified, both atoms end up with a radical electron.
The second line shows the same process as a heterolytic dissociation. The second carbon atom is the recipient of a positive charge, because it was listed first, and the charge delta is +1. The first carbon atom receives the counter-charge and bears a formal charge of -1.
The third example performs a bond order reduction on the C=O double bond, and then saturates the molecule with hydrogen. The result is a reduction of formaldehyde to methanol.
The final example is a recombination reaction of a proton and a hydroxide anion. Because the proton cannot provide any electrons for the new bond, the first step is a formal transfer of one electron (charge -1) to this atom. Implicitly, it is removed from the other atom of the newly formed bond, which is the negatively charged oxygen atom of the hydroxyl anion. The result is a neutral water molecule.
The command returns the new or old bond label for
Tcl
, or a bond reference for
Python
. If the bond was deleted, the return value is zero for
Tcl
, or
None
for
Python
.
bond create ehandle label ?type/order? ?order?
Bond(eref=,atoms=atomsequence/bond,?type=type/order?,?order=?)
Bond.Create(eref=,atoms=atomsequence/bond,?type=type/order?,?order=?)
b.create(?type/order?)
This command creates a new bond, or changes the bond order or bond type of an existing bond. In case a new bond is made, a list of atom labels or other atom identifiers is provided as parameter instead of a single bond identifier. The distinction between atom and bond references is performed via the list length of the label parameter. Anything with more than one list element is interpreted as an atom-based specification. The order of atoms in an atom-based specification is arbitrary. In case a new bond is created, the atoms are entered into the bond in that order. Atom orders in existing bonds are not changed.
The default bond type is a valence bond (
B_TYPE
property value is
vb
) of bond order 1. If this type of bond is created, the bond type identifier may be omitted and a bond order directly specified as an integer. Valence bonds are electron-counted. In order to succeed, the participating atoms must provide sufficient electrons (property
A_FREE_ELECTRONS
) for the bond. Both atoms must provide the same number of electrons. Charge recombination in bond formation is not supported by this command, but can be achieved with the
bond change
command. The free electron counts of the bond atoms are automatically updated. The toolkit does not try to generate more free electrons by deleting hydrogen atoms bonded to the bond atoms or similar operations. If this kind of intelligence is required, it must be explicitly scripted, or the
bond hcreate
command used.
Setting the bond order of an existing bond to 0 deletes the bond.
Besides normal valence bonds, this command can be used to create or manipulate any other bond type which is known to the toolkit. The names of bond classes understood by this command are parsed from the enumeration value of property B_TYPE and may be changed at runtime.
Non-VB bonds do not involve electron counting. It is possible to change the type of a bond with this command, and in case a VB bond is changed to a non-VB bond, the electrons which were used in the VB bond are assigned to the
A_FREE_ELECTRONS
properties of the atoms. In the reverse case the command only succeeds if sufficient free electrons are present. The bond order (stored in property
B_ORDER
) of non-VB bonds is zero and cannot be changed with this command. If the bond type is changed, the bond label may also change. Changing the bond order of an existing bond without a type change is guaranteed to preserve the bond label.
The command can be used to directly create VB bonds with attributes. In addition to a numeric bond order, the following bond types are understood which create (or change to) a VB bond and simultaneously set bond attributes:
It is also possible to spell out the bond order (single, double, etc.) instead of using a numerical value.
The attributes
B_FLAGS
,
B_query(
flags
)
and
B_query(
order
)
of bonds which are created or edited with a standard attribute-less bond order are reset.
The atom list which serves as a bond identifier or atom set for a new bond may contain more than two atoms. There are bond types like 3-center bonds and R-group alternative connection points, or pseudo bond like bond angles and torsion angles which span three four, or even more atoms.
It is not possible with this command to create bonds which involve the exact same set of atoms as an existing bond but which are of different type. It is also not possible to create bonds which include the same atom more than once.
Changing or creating a bond triggers a bondchange invalidation event. All minor object classes depending on an unchanged bond set (such as rings and molecules) as well as all property data on the ensemble which is directly or indirectly sensitive to changes in the bond set is invalidated if it is not explicitly locked.
The return value of this command is the label of the newly created or updated bond for
Tcl
, or a bond reference for
Python
. If the bond was deleted, the return value is zero for
Tcl
, or
None
for
Python
.
bond create [list 1 2] 2
bond create [list #3 #5]
bond create {3 4} complex
The first line creates a standard valence bond with bond order 2 between the atoms with labels 1 and 2, or changes the bond order to a double bond. In case of insufficient bonding electrons, an error is raised. The second example create a single bond between atoms with index (not label) 3 and 5. The final example creates a bond of type complex between atoms 3 and 4, using an abbreviated Tcl list notation. This bond does not perform valence electron counting.
The simple
Python
bond constructor syntax has one special limitation. While it is possible to delete an existing bond via
Bond.Create()
with bond order zero (which then returns
None
), this does not work due to syntactic reasons with the simple
Bond()
constructor, which must return a valid bond reference, or throw an error. In any case, using the
create
subcommand for bond deletion is counterintuitive under normal circumstances.
bond cut ehandle label ?substituentatom1? ?substituentatom2?
b.cut(?substituent=?,?substituent2=?)
Cut the specified bond and optionally add real or pseudo atoms to the cut site. If no substituent atoms are specified, the bond is simply cut and its electrons added to the bond atoms are free electrons. This is equivalent to a
bond delete
command. If substituents are specified, these are immediately linked, via a single bond, to the cut site. If the cut bond had a multiple bond order, unused electrons are added to the free electron count. If the cut bond was not a VB bond, no electrons are freed, and, depending on the type of the substituents, adding a substituent can fail.
Substituents are specified as element symbols, or pseudo element identifiers. If only a single substituent is specified, both sites receive the same substituent, otherwise the first substituent applies to the first bond atom, and the second substituent to the second bond atom. This command only supports bonds with two atoms.
The command returns the atom labels of the substituents. If no substituents are added to an atom, the return value for that atom is an empty string.
bond cut [ens create CC] 1 *
This cuts the C-C bond and adds an open site pseudo atom marker to both carbon atoms. The return value is the list
{9 10}
for the atom labels (references for Python) of the new pseudo atoms.
bond defined ehandle label property
b.defined(property)
This command checks whether a property is defined for the bond. 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.
bond defined $ehandle 1 B_ORDER
checks whether bond 1 is of a type for which bond orders are defined. The return value is a boolean status.
bond delete ehandle label ?label?...
bond delete ehandle all
b.delete()
Bond.Delete(eref,”all”)
Bond.Delete(bref,...)
Bond.Delete(eref,?blabel/bref/brefsequence?,...)
Delete one or more bonds. The atoms which participate in the bonds are not deleted, but in case the bond is a standard valence bond, their free electron count (property A_FREE_ELECTRONS ) is updated. Molecule and ring information, and other minor object classes under the control of the ensemble major object which depend on an unchanged bond set are deleted. Any property data which depends on an unchanged bond set is also invalidated, or, if the property is set up to do so, re-computed.
If the bond which should be deleted does not exist, the request is silently ignored, as long as the bond specification is syntactically correct.
The return value of this command is the total of all bonds successfully deleted.
This command does not try to save stereochemistry by transferring wedge data etc. to an adjacent bond prior to deletion. The
xdelete
command variant offers this feature.
bond delete $ehandle [list 1 2]
bond delfrag ehandle label ?reverse?
b.delfrag(?reverse=?)
This command deletes the bond and (if the reverse flag is not set) all atoms of the minor substituent (as defined by property B_FRAGMENT_DIRECTION ) linked by the bond. If the reverse flag is set, the major substituent is deleted instead. The cut site remains unsubstituted, i.e. no automatic addition of hydrogen is performed.
The command fails of the bond is a ring bond, or not a valence or complex bond.
The return value is the number of deleted atoms.
bond delfrag [ens create CCCl] {2 3}]
The command cuts the bond between atoms 2 and 3 (the C-Cl bond), and then deletes the minor fragment (the Cl atom in this case, because it is the one with a smaller heavy atom count). The deleted fragment is canonic, other properties besides the fragment heavy atom count are used to break ties (see property
B_FRAGMENT_DIRECTION
).
The command can also be fully spelled out as
bond deletefragment
.
bond dget ehandle label propertylist ?filterset? ?parameterdict?
b.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
bond get
command. The difference between
bond get
and
bond 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,
bond get
and
bond dget
are equivalent.
bond exists ehandle label ?filterlist?
b.exists(?filters=?)
Bond.Exists(eref,label,?filters=?)
Check whether this bond exists. Optionally, a filter list can be supplied to check for the presence of specific features, or checking of the bond type. The command returns 0 if the bond does not exist, or fails the filter, and 1 in case of successful testing.
bond exists $ehandle 99
bond exists $ehandle [list 1 2]
The second example checks whether a bond between atoms 1 and 2 exists. Instead of using a single label, all bond labels may be substituted by a list of the labels of their atoms.
bond expr ehandle label expression
b.expr(expression)
Compute a standard SQL -style property expression for the bond. This is explained in detail in the chapter on property expressions.
bond fill ehandle label ?property value?...
b.fill({property:value,...})
b.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.
bond fill $ehandle 1 A_COLOR red
sets the color of the first atom bond 1 participates in to red.
bond filter ehandle label filterlist
b.filter(filters)
Check whether a bond passes a filter list. The return value is boolean 1 for success and 0 for failure.
bond filter $ehandle 1 [list carbon doublebond]
checks whether the bond is a double bond with one or more carbon atoms.
bond flip ehandle label
b.flip()
This utility command manipulates data of property B_FLAGS and possibly B_LABEL_STEREO (and other bond stereo descriptors) plus A_XY and dependent data. If these property data are not already present, the command does nothing.
The mode of operation depends on the bond order.
For single bonds. the command inverts three bit groups in B_FLAGS .
For double bonds, the command inverts all present bond stereo descriptors ( B_LABEL_STEREO , B_CIP_STEREO , B_CISTRANS_STEREO , B_MAP_STEREO , B_HASH_STEREO ) if they are set to a value indicating presence of stereochemistry. Stereo-dependent properties such as B_STEREOINFO and B_STEREOGENIC are invalidated if not locked. In addition, if 2D coordinates are valid in A_XY and the bond is not a ring bond, the smaller half of the structure is rotated around the bond axis in pseudo-3D fashion. This involves updating A_XY and the bond display flags in B_FLAGS , and invalidation of property data dependent on these. If the stereochemistry of a ring bond is changed, the 2D coordinates are deleted. Currently, 3D atomic coordinates are not modified.
The command is usually employed in preparation of a pseudo-3D horizontal or vertical flip of a structure drawing. The bond flags are set in such a way that after mirroring the 2D coordinates, the wedge orientation and ring interior positioning of the bonds are correct in the sense that they still describe the same stereo isomer and ring double bonds are plotted with a shortened bond inside the ring.
The command returns 1 if any bits were changed, 0 otherwise.
bond flip $handle 1
bond get ehandle label propertylist ?filterset? ?parameterdict?
b.get(property=,?filters=?,?parameters=?)
b[property]
b.property
Standard data manipulation command for reading object data. It is explained in more detail in the section about retrieving property data.
bond get $ehandle 1 {B_ISAROMATIC B_ORDER}
yields the aromaticity status flag and the (Kekulé) bond order of bond 1 as a list. If the information is not yet available, an attempt is made to compute it. If the computation fails, an error results.
bond get $ehandle 1 A_ELEMENT ringatom
gives the elements of all atoms in the bonds which are in a ring.
For the use of the optional property parameter list argument, refer to the documentation of the
ens get
command.
Variants of the
bond get
command
are
bond new, bond dget, bond nget, bond show, bond sqldget, bond sqlget, bond sqlnew
and
bond sqlshow
.
bond get $ehandle 1 R_SIZE
bond get $ehandle 1 B_FLAGS(dashed)
bond groups ehandle label ?filterset? ?filtermode?
b.groups(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the groups the bond is related to. This is explained in more detail in the section about object cross-references. A bond is considered to be related to a group if all the atoms in the bond are contained in the group.
bond groups $ehandle 1
bond hadd ehandle label ?filterset? ?flags? ?chargedelta?
b.hadd(?filters=?,?flags=?,?chargedelta=?)
Add a standard set of hydrogens to the atoms of the bonds. If the filterset parameter is specified, the atoms need to pass the filter set in order to be processed.
This command only adds missing implicit hydrogen. It does not reduce the current bond order, or split the bond.
Additional operation flags may be activated by setting the flags parameter to a list of flag names, or a numerical value representing the bit-ored values of the selected flags. By default, the flag set is empty, corresponding to the use of an empty string or none as parameter value. These flags are currently supported:
If a charge delta parameter is specified, the atomic charge and free electrons of the atoms are adapted accordingly before the hydrogens are added. The manipulation of the charge usually changes the number of added hydrogen atoms. It is not possible to change the charge in such a way that the number of free electrons would become negative. This parameter is included for the sake of compatibility with the
atom hadd
command. It is rarely useful for bonds.
Adding hydrogens with this command, except if the
protonate
flag is set, is less destructive to the property data set of the ensemble than adding them with individual
atom create/bond create
commands, because many properties are designed to be indifferent to explicit hydrogen status changes, but are invalidated if the structure is changed in other ways.
The command returns the number of hydrogens which were added in total to both atoms.
bond hcreate ehandle label ?type/order? ?order?
Bond.Hcreate(eref=,atoms=atomsequence/bond,?type=type/order?,?order=?)
b.hcreate(?type/order?)
This is a variant of the
bond create
command. The difference to the normal bond creation command is that this version attempts to delete hydrogen atoms on the bonded atoms if this prevents illegal free electron counts or valences.
All parameters and return values are the same as for
bond create
.
bond hstrip ehandle label ?flags? ?chargedelta?
b.hstrip(?flags=?,?chargedelta=?)
This command removes hydrogens from the atoms of the selected by. By default, all hydrogen atoms are removed.
The flags parameter can be used to make the operation more selective. It may be a list of the following flags:
If the flags parameter is an empty string, or none , it is ignored. The default flag value is wedgetransfer - but the default value is overridden if any flags are set!
If a charge delta parameter is specified, the charge and free electrons of the atoms are adapted accordingly before the hydrogens are added. The manipulation of the charge changes the number of added hydrogen atoms. It is not possible to change the charge in such a way that the number of free electrons would become negative. This option is mostly provided for compatibility with the
atom hstrip
command. It is rarely useful for bonds.
Hydrogen stripping is not as disruptive to the ensemble data content as normal atom deletion, except in case the deprotonate flag is set. The system assumes that this operation is done as part of some file output or visualization preparation. However, if any new data is computed after stripping, the computation functions see the stripped structure, and proceed to work on that reduced structure without knowledge that there are implicit hydrogens.
The return value of the command is the total number of hydrogens removed from all bond atoms.
bond hydrogenate ehandle label ?filterset? ?changeset?
b.hydrogenate(?filters=?,?changeset=?)
Reduce the bond to a single bond except if excluded by the filter set.
If a change set is supplied, its interpretation is the same as in
bond hadd.
The command returns the number of added hydrogens.
bond hydrogenate $eh 1 {!arobond !ccbond}
This reduces the bond to a single bond, provided the bond is not aromatic or a C-C bond.
bond index ehandle label
b.index()
Get the index of the bond. The index is the position in the bond list of the ensemble. The first position is index 0.
bond index $ehandle 99
bond jget ehandle label propertylist ?filterset? ?parameterdict?
b.jget(property=,?filters=?,?parameters=?)
This is a variant of
bond get
which returns the result data as a
JSON
formatted string instead of
Tcl
or
Python
interpreter objects.
bond jnew ehandle label propertylist ?filterset? ?parameterdict?
b.jnew(property=,?filters=?,?parameters=?)
This is a variant of
bond new
which returns the result data as a
JSON
formatted string instead of
Tcl
or
Python
interpreter objects.
bond jshow ehandle label propertylist ?filterset? ?parameterdict?
b.jshow(property=,?filters=?,?parameters=?)
This is a variant of
bond show
which returns the result data as a
JSON
formatted string instead of
Tcl
or
Python
interpreter objects.
bond local ehandle label propertylist ?filterset? ?parameterdict?
b.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.
bond local $ehandle 1 B_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.
bond match ehandle label ss_ehandle ?ss_label? ?matchflags? ?ignoreflags? ?atommatchvar? ?bondmatchvar? ?molmatchvar?
b.match(substructure=,?substructurebond=?,?matchflags=?,?ignoreflags=?, ?atommatchvariable=?,?bondmatchvariable=?,?molmatchvariable=?)
Check whether the selected bond matches a substructure. Only the first substructure bond, or the bond selected by the substructure bond label parameter, is tested. The substructure may be part of any structure ensemble, and even be in the same ensemble as the primary command bond. Both the bond atoms and the bond proper 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 the flag set, an explicit none value must be used. The bit options of the match flag are explained in the documentation of the
match ss
command.
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 (references for Python ). If no match can be found, the variable is set to an empty list. 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
set ss [ens create {[F,Cl,Br,I][C,c]} smarts]
set b_is_cxbond [bond match $ehandle $label $ss {} {} {} amap]
if {$b_is_cxbond} {
set b_xatom [lindex [lindex $amap 0] 1]
set b_catom [lindex [lindex $amap 1] 1]
}
bond mols ehandle label ?filterset? ?filtermode?
b.mols(?filters=?,?mode=?)
Standard cross-referencing command to obtain the label(s) (references in case of Python ) of the molecule(s) the bond is a member of. This is explained in more detail in the section about object cross-references.
bond mols $ehandle 1
bond mols $ehandle 1 heterocycle
The first example simply returns the label(s) of the molecule the bond is a part of. Note that it is possible for bonds to span more than one molecule - this is the reason why the command name is mols , not mol . If a bond spans more than one molecule, a list of the molecule labels is reported.
The second example returns the molecule label(s) if the bond is part of a molecule which contains one or more heterocycles. If the molecule(s) do not contain a heterocycle, an empty list is returned.
bond neighbors ehandle label ?filterset? ?filtermode? ?anchoratomlabel?
b.neighbors(?filters=?,?mode=?,?anchoratom=?)
This command retrieves neighbor atoms of the bond. The atoms which participate in the bond are not included.
By default, a list with the labels (references in case of Python ) of the atoms passing the optional filter set is the result. The retrieval mode may optionally be changed by supplying a filter mode specification list as in the standard cross referencing commands, such as count or exclude . Both parameters may be set to an empty list or entirely omitted if the default function is needed.
This command supports a special filtermode parameter in addition to the standard set ( exists , count , exclude , include ). The bonds parameter, followed by a bit set combination from the allowed values ring , sidechain or bridge can be used for topological filtering of the traversable bonds. By default, no topological bond filtering is applied.
If the optional anchor atom label (or other atom specification) is provided, only atoms which are bonded via a VB or complex bond (
B_TYPE
vb
or
complex
) to this atom are listed. If the anchor atom is one of the bond atoms, the effects is similar to using the
atom neighbors
command, except that the other bond atom(s) are excluded. If the anchor atom is not part of the bond, other neighborhood relationships can be explored.-
The command may also be invoked with the aliases
bond neighbours
and
bond ligands
.
bond neighbors [ens create C=C] 1
bond neighbors [ens create c1ncccc1c1ccccc1] 6 carbon {bonds bridge count}
The first example returns the labels of the hydrogen atoms. The second example returns 1, because the bond has one neighbor atom which is bonded via a bridge bond.
bond new ehandle label propertylist ?filterset? ?parameterdict?
b.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.
For examples, see the
bond get
command. The difference between
bond get
and
bond new
is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.
bond nget ehandle label propertylist ?filterset? ?parameterdict?
b.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
bond get
command. The difference between
bond get
and
bond nget
is that the latter always returns numeric data, even if symbolic names for the values are available.
bond partner ehandle bondlabel atomlabel
b.partner(aref)
Return the label (reference in case of Python ) of the other atom in the indicated bond. In case the bond contains more than two atoms, the first atom which is not the specified atom is returned. Using an atom label which is not participating in the bond results in an error.
set a2 [bond partner $ehandle $b $a1]
bond partners ehandle bondlabel atomlabel
b.partners(aref)
Return the label (reference in case of Python ) of the other atom in the indicated bond. In case the bond contains more than two atoms, a list of the atoms which are not the specified atom is returned. Using an atom label which is not participating in the bond results in an error.
bond pis ehandle label ?filterset? ?filtermode?
b.pis(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the π systems the bond is related to. This is explained in more detail in the section about object cross-references. A bond is considered to be related to a π system if all atoms of the bond are contained in the π system.
bond pis $ehandle 1
Get the labels (references in case of Python ) of the π systems the bond is related to. π 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.
bond permute ehandle label ?targetbondorder?
b.permute(?targetbondorder=?)
Change the bond order by rotating the bond orders of Kekulé-style alternating single/double bond aromatic rings the bond is a member of. This is a useful function if aromatic systems need to be manipulated in reaction transforms and similar circumstances. If no target bond order is specified, an attempt is made to flip the bond between single and double. If a target bond order is set, the function does nothing if the current bond has already the desired bond order. The operation does not change atomic charges and does not succeed if any valence violation is encountered. Sydnones and other exotic aromatic systems can thus fail. In case the bond is a member of more than one eligible ring, the ring which is modified should be considered arbitrary.
The function returns one if the operation succeeds (which includes doing nothing is the target bond order is already present) and zero otherwise. An error is raised only if there are problems with the arguments.
bond purge ehandle label propertylist/stereo/isotope/query
b.purge(propertylist/stereo/isotope/query)
Reset existing property data on a bond. In case the argument is a list of property names, the value on that bond only is reset to the default value of the property. In case the property is not present on the ensemble, the command is ignored. The reset via a property list does
not
trigger a property dependency update. If that is desired, an
ens taint
command must be explicitly scripted.In case a reset property is an atom property instead of a bond property, the reset is executed for all bonds of the atom. Other property object class mismatches are currently not supported.
In addition to standard properties, several special pseudo property names are recognized.
The stereo code resets all bond-centered stereo information on the bond, and will trigger a stereo change event on the ensemble which may invalidate additional data.
The isotope code resets property A_ISOTOPE on the bond atoms, marks the isotope data as tainted and runs a data dependency check.
The query code resets property B_QUERY , marks the query data as tainted and runs a data dependency check.
The command returns the label (for Tcl ) or reference (for Python ) of the bond.
Bond.Ref(eref,identifier)
Python
only method to get a bond reference. See
bond bond
command.
bond rings ehandle label ?filterset? ?filtermode?
b.rings(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the rings the bond is contained in. This is explained in more detail in the section about object cross-references.
bond rings $ehandle 1
bond rings $ehandle 1 [list heterocycle aroring]
The first example returns the labels of all rings the bond is contained in. If the bond is not in any ring, an empty list is returned. Only labels of rings in the SSSR or ESSSR ring set are returned, even if the currently computed ring set is larger. The second example filters the rings - only heteroaromatic rings are reported.
bond ringsystem ehandle label ?filterset? ?filtermode?
b.ringsystem(?filters=?,?mode=?)
Standard cross-referencing command to obtain the label (reference in case of Python ) of the ring system the bonds is contained in. This is explained in more detail in the section about object cross-references.
bond ringsystem $ehandle 1
bond ringsystem $ehandle 1 [list heterocycle aroring]
The first example returns the labels of the ring system the bond is contained in. If the bond is not in any ring system, an empty list is returned. The second example filters the ring systems - a ring system label is obtained only if that ring system contains one or more hetero aromats.
bond rotate ehandle label angle ?property?
b.rotate(angle=,?coordinateproperty=?)
This command rotates one half of a molecule in 3D in property A_XYZ or another specified property around the axis defined by the bond. The rotation angle is specified in degrees.
The section of the molecule which is rotated is not arbitrary and independent of the order of the atoms in the bond or bond specification. If there is a difference between the centrality of the atoms of the bond, the part which is less central is rotated. Molecules other than the one containing the rotation bond are not affected. The static section of the molecule also retains all atomic coordinates. If any rotation is performed, (which excludes cases where the rotated bond is terminal - this is a no-op), both the 3dop and 3dglobalop property invalidation events are generated.
The command fails if no 3D coordinates are present or can be computed, or if the bond is a ring bond.
bond rotate $ehandle [list 5 4] 15
rotates one half of a molecule around the bond between atoms 4 and 5 by 15 degrees.
The command returns the label (for Tcl ) or reference (for Python ) of the bond.
bond set ehandle label ?property value?...
b.set(?property,value?,...)
b.set({property:value,...})
b.property = value
b[property] = value
Standard data manipulation command. It is explained in more detail in the section about setting property data.
bond set $ehandle 1 B_COLOR “blue”
The direct change of critical bond type data, such as the bond order
B_ORDER
, or bond type
B_TYPE
should be avoided. Instead, the bond manipulation commands
bond create
and
bond change
should be used. The dedicated creation, deletion and modification commands automatically take care of bookkeeping tasks such as electron counting for valence bonds. Also, direct setting of the bond data renders most structure information invalid, since most properties depend directly or indirectly on the bond type and order. Careful manual locking and updating of property data is required if direct bond manipulation is attempted.
bond show ehandle label propertylist ?filterset? ?parameterdict?
b.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
bond get
command. The difference between
bond get
and
bond 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,
bond get
and
bond show
are equivalent.
bond sigmas ehandle label ?filterset? ?filtermode?
b.sigmas(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the σ systems the bond is participating in. This is explained in more detail in the section about object cross-references. A bond is considered to be related to a σ system if all atoms of the bond are contained in the σ system.
bond 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.
bond sqldget ehandle label propertylist ?filterset? ?parameterdict?
b.sqlget(?filters=?,?mode=?)
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
bond get
command. The differences between
bond get
and
bond sqldget
are that the latter does not attempt computation of property data, but initializes the property value to the default and return 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.
bond sqlget ehandle label propertylist ?filterset? ?parameterdict?
b.sqlget(?filters=?,?mode=?)
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
bond get
command. The difference between
bond get
and
bond sqlget
is that the
SQL
command variant formats the data as
SQL
values rather than for
Tcl
or
Python
script processing.
bond sqlnew ehandle label propertylist ?filterset? ?parameterdict?
b.sqlnew(?filters=?,?mode=?)
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
bond get
command. The differences between
bond get
and
bond 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.
bond sqlshow ehandle label propertylist ?filterset? ?parameterdict?
b.sqlshow(?filters=?,?mode=?)
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
bond get
command. The differences between
bond get
and
bond 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.
bond stereoligands ehandle label
b.stereoligands()
Return a list of the bond ligand atoms which define the stereochemistry of the bond. The length of the list is always four elements. If the bond is not stereogenic, four empty strings for
Tcl
and four
None
values for
Python
are returned. If the bond is the center bond of an even allene (including cases where rings substitute for an allene double bond), the allene endpoint ligands are returned, each side independently sorted by atom labels in ascending order. If the bond is a normal stereobond, the direct bond ligands are returned, again in independently sorted atom label order for each side. If an electron pair is part of the stereochemistry, it is included as an empty string or
None
after the partner ligand at each bond side.
bond subcommands
dir(Bond)
Lists all subcommands of the
bond
command. Note that this command does not require an ensemble handle, or a bond label.
bond surfaces ehandle label ?filterset? ?filtermode?
b.surfaces(?filters=?,?mode=?)
Standard cross-referencing command to obtain the labels or references of the surface patches a bond is related to. This is explained in more detail in the section about object cross-references. A bond is considered to be related to a surface element if it is linked to any of the atoms in the bond.
bond surfaces $ehandle 1
bond transform ehandle label SMIRKSlist ?direction? ?reactionmode? ?selectionmode? ?flags? ?overlapmode? ?{?exclusionmode? excludesslist}? ?maxstructures? ?timeout? ?maxtransforms? ?niterations?
b.transform(transforms=,?direction=?,?reactionmode=?,?selectionmode=?,?flags=?,?overlapmode=?,?maxstructures=?,?timeout=?,?maxtransforms=?,?iterations=?)
This command is complex, but nearly identical to the
ens transform
command. Please refer to that command for a full description of the command arguments.
The difference to
ens transform
is that the argument bond must be matched in the transform pattern. If the transform matches only elsewhere, no operation is performed. It is not required that the bond is actually modified during the course of the transform - it suffices if it is part of the source pattern match.
The return value is, just as with the
ens transform
command, a list of result ensembles.
bond uncharge ehandle label
b.uncharge()
This command attempts to combine opposing charges on the atoms of the bond by increasing the bond order. If the bond order was increased, the result is 1, otherwise 0. The result for non-VB bonds is always 0.
bond uncharge [ens create {C[N+]([O-])=O}] {2 3}
This example converts the single bond between the nitrogen cation (atom 2) and the oxygen anion (atom 3) to a double bond and thus neutralizes the charges on the atoms.
The command returns the label (for Tcl ) or reference (for Python ) of the bond.
bond xdelete ehandle label ?label?...
bond xdelete ehandle all
b.xdelete()
Bond.Xdelete(eref,?label?,...)
Bond.Xdelete(bref,...)
Bond.Xdelete(eref,“all”)
Delete one or more bonds, while trying to maintain stereochemistry. The atoms which participate in the bonds are not deleted, but in case the bond is a standard valence bond, their free electron count (property A_FREE_ELECTRONS ) is updated. Molecule and ring information, and other minor object classes under the control of the ensemble major object which depend on an unchanged bond set are deleted. Any property data which depends on an unchanged bond set is also invalidated, or, if the property is set up to do so, re-computed. Wedge bonds and other stereochemistry information tied to a deleted bond is transferred to an adjacent bond prior to deletion, if possible.
If the bond which should be deleted does not exist, the request is silently ignored, as long as the bond specification is syntactically correct.
The return value of this command is the total of all bonds successfully deleted.
bond xdelete $ehandle [list 1 2]