atom get $ehandle 1 A_SYMBOL

atom get $ehandle ^1 A_SYMBOL

atom get $ehandle #0 A_SYMBOL

atom get $ehandle {A_LABEL = 1} A_SYMBOL

atom hadd $ehandle 2

atom anchormatch

atom anchormatch ehandle label ss_ehandle ?ss_label? ?matchflags? ?ignoreflags? 	?atommatchvar? ?bondmatchvar? ?molmatchvar?

a.anchormatch(substructure=,?substructureatom=?,?matchflags=?,?ignoreflags=?,	?atommatchvariable=?,?bondmatchvariable=?,?molmatchvariable=?)

This command is a variant of the atom match command. The difference is that the full substructure is matched, and not just its first or selected atom. A substructure match anchor between the command atom and the first or selected substructure atom is enforced (see -anchor option of the match ss command).

Example:

set eh [ens create CCO]

echo [atom match $eh 3 O(C)(C)]

echo [atom anchormatch $eh 3 O(C)C]

The first command matches, because only the first substructure atom is checked. The second fails, even though the first substructure atom is a match - but then its environment does not fit.

atom angle

atom angle ehandle label label2 label3 ?property?

a.angle(atom2=,atom3=,?coordinateproperty=?)

Compute the angle between 3D atomic coordinates stored in a property between the three atom arguments, which are considered linked in the specified sequence. The source property for atomic coordinates is by default A_XYZ , but another property can be set, which also needs to be an atomic float vector.

The return value is the angle in degrees between the vectors implicitly constructed from the 3D atomic coordinate of the second atom pointing to that of the first, and from the second atom to the third. No bonds need to exist between the atoms. All atoms used in a statement must be different, and possess 3D coordinates initially, or after an automatically started computation of the source property.

atom append

atom append ehandle label ?property value?...

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

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

Example:

atom append $ehandle 1 A_SUPERATOMSTRING “_linker”

atom atom

atom atom ehandle identifier

Atom.Ref(eref,identifier)

Standard cross-referencing command to obtain the label (or reference object, for Python ) of the atom as stored in property A_LABEL . This is explained in more detail in the section about object cross-references.

Example:

atom atom $ehandle #0

returns the label of the first atom of the ensemble atom list.

atom bondangles

atom bondangles ehandle label ?filterset? ?filtermode?

a.bondangles(?filterset?,?mode?)

Standard cross-referencing command to obtain the labels or references of the bond angle objects the atom is participating in. This is explained in more detail in the section about object cross-references.

atom bonds

atom bonds ehandle label ?filterset? ?filtermode?

a.bonds(?filterset?,?mode?)

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

Examples:

atom bonds $ehandle 1

atom bonds $ehandle 1 {1 doublebond triplebond} count

The first example returns all labels of the bonds atom 1 is participating in. The second example returns the number of double or triple bonds the atom is a part of.

atom change

atom change ehandle label element ?linkatom? ?removeh?

a.change(replacement=,?linkatom=?,?removeh=?)

This command is very similar to the command atom replace . The important difference is that the element parameter is always interpreted as an element symbol encoding, and not primarily as an ensemble handle, ensemble handle/molecule label pair or SMILES string.

The rest of the command is explained in the paragraph on atom replace .

Example:

atom change $eh 1 C

atom change $eh 2 Z

The first example changes the atom with label 1 to a neutral carbon atom. Bonds of the old atom 1 are inherited if possible. If this is not possible due to valence violations, an error is raised. The second example changes an atom to a query specification for an electro-negative element.

atom charge

atom charge ehandle label chargedelta

a.charge(chargedelta=)

Try to change the formal charge A_FORMAL_CHARGE of the atom by the specified amount. The free electron count A_FREE_ELECTRONS is also adjusted, and other charge- or free-electron-dependent properties on the ensemble are recursively invalidated. Impossible final charge values are rejected. If the desired charge state can only be reached by deprotonation, this is automatically attempted, and a bond change property invalidation event is processed.

The command returns the atom label (for Tcl ) or reference (for Python ).

atom create

atom create ehandle ?symbol? ?bondtype atomlabel?...

Atom(eref,?symbol?,?bondtype,aref?...)

Atom.Create(eref,?symbol?,?bondtype,aref?...)

Create a new atom in the ensemble. By default, the atom is added without any bonds or charge and the standard set of free electrons. The symbol parameter is usually an element symbol, which is decoded in a case-sensitive fashion. If it is omitted, an unspecified atom is created. The isotopic element symbols D and T are recognized and decoded to the corresponding hydrogen isotopes, setting the A_ISOTOPE property.

This command may also be used to add various pseudo and query atoms. Allowable symbols for this purpose are

• 3DPOINT or DU or BQ for points in 3D space
• POLY for polymers
• EPAIR , EP or LP for lone pairs
• * or OV for an open valence pseudo atom
• ~ for a superatom with a yet undefined identifier string
• HA for a generic hydrogen acceptor
• HD for a generic hydrogen donor
• A for a query atom which is not hydrogen
• Q for a query atom which is a hetero atom (not C or H)
• M for a query atom which is a metal
• ? for a query atom which can be any atom
• X for a query element list with the halogens
• Y for a query element list with the electro-negative elements N,O,Cl,Br
• Z for a query element list with the electro-negative elements N,O,F,S,Cl,Br,I
• L for a query element list with a yet undefined set of elements
• @ for a delocalization anchor
• R for a query atom of type insulator .

Instead of an element symbol, the periodic system number of an element may also be used, optionally prefixed with a hash character (#) in SMILES style. Additionally, the standard Beilstein query atoms, such as ‘ [Alk] ’, as well as CCDC element groups, such as ‘ [3A] ’, are supported.

If the superatom symbol ~ is followed by more characters, these are copied to the superatom identifier string ( A_SUPERATOMSTRING property). If a known fragment is specified this way, it may be expanded later.

The command returns the automatically assigned label of the new atom, or the atom reference for Python . Note that this command does not require a label parameter, since it creates new atoms.

This command updates the ensemble information and recursively purges information which is susceptible to atom changes. For atom properties which survive this step, a default value is added, if the property is not part of the set of properties managed actively by this command, such as the free electron count and the atom label.

After the atom symbol, an additional sequence of (non-nested) bond type and atom label parameters may be specified. The recognized bond types are the same as in bond create . Bonds of the requested type are created and link the new atom to existing atoms in one step. This bond creation process is limited by the valence restrictions of the involved atoms. Successful bond creation triggers a bond change property data invalidation event.

The atom create command can also be accessed, for historical reasons, as atom add . This alias is deprecated.

The return value is the label of the new atom.

Examples:

atom create $ehandle C

atom add $ehandle ?

atom expand $ehandle [atom add $ehandle ~FMOC]

atom create $ehandle N = $a1 single $a2

The first example adds a carbon atom to the ensemble. The second line adds an any query pseudo atom, which, in the context of a substructure search, matches any atom. The third example adds a superatom named FMOC in the inner command. Since this is a fragment name the library understands by default, it may be expanded to the full FMOC fragment with the outer command. Finally, a nitrogen atom is added and immediately bonded via a double bond to the atom identified by the label in variable a1 , and via a single bond to the atom in a2 .

atom defined

atom defined ehandle label property

a.defined(property)

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

Example:

atom defined $ehandle 1 A_XYZ

checks whether atom 1 is of a type for which A_XYZ is defined.

The command returns a boolean status value.

atom delete

atom delete ehandle ?label?...

atom delete ehandle all

a.delete()

Atom.Delete(eref,?alabel/aref/arefsequence?,...)

Atom.Delete(aref,...)

Atom.Delete(eref,“all”)

Delete zero or more atoms. All bonds which the atoms participate in are also deleted. The electron counts of surviving atoms participating in deleted bonds are automatically updated. Molecule and ring information, and other minor object classes under the control of the ensemble major object which depend on an unchanged atom set are deleted. Any property data which depends on an unchanged atom set is also invalidated, or, if the property is set up to do so, re-computed.

Note that this command does not delete hydrogen atoms the deleted atoms were bonded to. These remain in the ensemble as isolated, now unbonded atoms. The atom xdelete subcommand also deletes these hydrogen atoms.

The special atom label all requests deletion of all atoms. Usually, this is equivalent to ens clear .

The return value of the command is the number of deleted atoms.

Example:

atom delete $ehandle 1

This command is one of few atom subcommands which do not require an atom label. If no label is given, the command does nothing. This is useful for list expansions where the list might be empty:

eval atom delete $ehandle $delatomlist

atom delete $ehandle {*}$delatomlist

atom dget

atom dget ehandle label propertylist ?filterset? ?parameterdict?

a.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 atom get command. The difference between atom get and atom 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, atom get and atom dget are equivalent.

atom deprotonate

atom deprotonate ehandle label ?count?

a.deprotonate(?count=?)

Attempt to remove one ore more protons from the atom, with adjustment of formal atom charge and processing of appropriate structure change property data invalidation events.

The command returns the atom label (for Tcl ) or atom reference (for Python ).

atom distance

atom distance ehandle label ?label2? ?property?

a.distance(?atom2=?,?coordinateproperty=?)

Compute the 3D distance between two atoms based on the values of a coordinate property. The source property for atomic coordinates is by default A_XYZ , but another property can be specified, which also needs to be an atom float vector.

The command returns the value as a floating point number in the unit of the source property (Angstrom in case the default A_XYZ is used). An equivalent explicit vector arithmetic script is

vec len [vec subtract [ens get $eh $label A_XYZ] [ens get $eh $label2 A_XYZ]]

If a second atom identifier is not specified, or given as an empty string, the result is a nested list of the distances to all bonded neighbor atoms, regardless of the bond types. Each sublist consists of the partner atom label and the bond length from the current atom to that neighbor.

In order to obtain the topological distance between atoms, use the atom topodistance command, or compute property A_TOPO_DISTANCE .

atom dup

atom dup ehandle ?label_list? ?datasethandle? ?position?

a.dup(?dataset=?,?position=?)

Atom.Dup(eref,aref_tuple,?dataset=?,?position=?)

Duplicate zero or more atoms, plus all the bonds existing between them, into a new ensemble. This command is very similar to ens fragment , and the same caveats about preserved and destroyed data in the duplicate apply.

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.

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

The command returns the handle of the new ensemble object for Tcl , or an ensemble reference for Python .

Example:

set ehfrag [atom dup $eh {*}$alist]

atom ens

a.ens()

Python -only method to get the ensemble reference from an atom reference.

atom exists

atom exists ehandle label ?filterlist?

a.exists(?filters=?)

Atom.Exists(eref,label,?filters=?)

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

Example:

atom exists $ehandle 99

atom expand

atom expand ehandle label ?allowambiguous? ?noimplicith?

a.expand(?allowambiguous=?,?noimplicith=?)

This command attempts to expand a superatom. A superatom is either an atom for which the atom type property A_TYPE is set to super (the preferred method), or a standard atom ( A_TYPE normal) with certain property data.

For a successful expansion, the first class of explicit superatoms must have a valid A_SUPERATOMSTRING property value which can be located in the table of known superatom identifiers. The second class of normal atoms needs a valid A_TEXTLABEL property data with a known superatom identifier in its label text field. The use of normal atoms as superatom surrogates is deprecated.

If the allowambiguous flag parameter is set, superatoms of uncertain status are expanded. Some superatom names are ambiguous, for example Al , which may both refer to the element and alanine . The superatom table protects against unchecked expansion of such atoms by containing an ambiguity flag which is set in such cases.

By default, the fragments from the superatom table are imported with a full set of hydrogens. If the optional noimplicith flag is set, only hydrogens which are explicitly spelled out in the superatom definition are included. For example, superatoms COO and COOH are expanded to the same form with an acidic hydrogen by default, but if the flag is set, only the second form has it.

The command returns 1 if the atom was a superatom and expansion was successful, 0 otherwise. It may also raise an error if a superatom was found, but expansion failed, for example because of an illegal bonding situation which does not allow the creation of the required normal bonds to the expanded fragments.

The expanded superatom and all other atoms in the original ensemble retain their labels.

Only a single level of superatoms is expanded - if the expanded fragment contains another superatom, it remains in its original form.

Examples:

atom expand $ehandle [atom create $ehandle ~BOC]

This command immediately expands the freshly created BOC fragment. A command sequence like

atom set $ehandle [ens create C 0] A_TEXTLABEL(label) COOMe

atom expand $ehandle 1

also works, but is deprecated.

atom expr

atom expr ehandle label expression

a.expr(expression)

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

atom fill

atom fill ehandle label ?property value?...

a.fill({property:value,...})

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

Example:

atom fill $ehandle 1 B_COLOR red

sets the color of the first bond atom 1 participates in to red.

The command returns the first fill value.

atom filter

atom filter ehandle label filterlist

a.filter(filters)

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

Example:

atom filter $ehandle 1 [list carbon doublebond]

checks whether the atom is a carbon atom with a double bond.

atom get

atom get ehandle label propertylist ?filterset? ?parameterdict?

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

a[property]

a.property

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

Examples:

atom get $ehandle 1 {A_SYMBOL A_ELEMENT}

yields the atomic symbol and the element number of atom 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.

atom get $ehandle 1 B_ORDER ringbond

will give the bond orders of all bonds of the atom 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 atom get command are atom new, atom dget, atom nget, atom show, atom sqldget , atom sqlget, atom sqlnew and atom sqlshow.

Further examples:

atom get $ehandle 1 A_SYMBOL

atom get $ehandle 1 A_FLAGS(boxed)

In the Python case, the first variant accepts property lists/tuples containing string property names and/or property references, or a string property list in addition to a single property. Property references can be used instead of strings only in the first variant, both as single arguments or as part of lists/tuples. Direct indexed access to property fields also requires the first version, as does the use of filters or specific computation parameters.

atom groups

atom groups ehandle label ?filterset? ?filtermode?

a.groups(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the groups the atom is a member of. This is explained in more detail in the section about object cross-references.

Example:

atom groups $ehandle 1

atom hadd

atom hadd ehandle label ?filterset? ?flags? ?chargedelta?

a.hadd(?filters=?,?flags=?,?chargedelta=?)

Add a standard set of hydrogens to the atom. If the filterset parameter is specified, the atom needs to pass the filter set in order to be processed.

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:

• no2dcoords
  Do not assign 2D coordinates to the added hydrogens, even if the rest of the atoms in the ensemble have valid 2D coordinates. In any case, 2D coordinates are never added when the ensemble does no already possess valid 2D coordinates.
• no3dcoords
  Do not assign 3D coordinates to the added hydrogens, even if the rest of the atoms in the ensemble have valid 3D coordinates. In any case, 3D coordinates are never added when the ensemble does no already possess valid 3D coordinates.
• noanions
  Do not add hydrogen to atoms with a negative formal charge.
• noatoms
  Do not add hydrogen to atoms without any bonds.
• nocations
  Do not add hydrogen to atoms with a positive formal charge.
• noelements
  Do not add hydrogen if the ensemble consists purely of isolated metal atoms, which probably represent the material in elementary form, or as an alloy.
• noexcessvalences
  Similar to nohighvalences , but hydrogen is not added to any atom which is not in its lowest standard bonded valence state.
• nofixatomtext
  Do not adjust property A_TEXTLABEL (if present) by removing references to implicit H from it on atoms where hydrogen is added. For example, by default “NHCOOEt” becomes “NCOOEt” after adding an instantiated hydrogen to the nitrogen atom. This reduces confusion on the hydrogen status when rendering all atoms.
• nohighvalences
  Do not add hydrogen to atoms which already exceed their lowest standard valence minus any formal charge. This option only applies to elements which have a defined lowest standard valence (this is configurable via the element table).
• nomemory
  Do not remember the added hydrogen atoms as automatically added. Normally, a flag is retained as part of the atom information which distinguishes atoms which were added by automatic processing, such as hydrogen addition, from those which were originally input.
• nometals
  Do not attempt to add hydrogen to atoms which are metals (as defined in the system element table).
• nospecial
  Do not perform hydrogen addition to atoms which participate in non-standard bonds (all bonds with B_TYPE not normal ).
• keepflags
  For expert use only. Do not discard min/max values and property scope flags for atom properties when hydrogen is added.
• protonate
  Add a single proton to the atom. The charge of the atom is increased, only a single hydrogen is added regardless of the standard number of missing hydrogens, and this command will issue the standard property invalidation event for atom and bond changes.
• resetmemory
  Reset the origin flag described above for all atoms in the ensemble. All current atoms appear to be part of the original atom set.

If a charge delta parameter is specified, the atomic charge and free electrons of the atom 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.

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.

Example:

set ehandle [ens create FC(F)(F)(F)]

atom delete $ehandle 1

atom hadd $ehandle 2

transforms tetrafluoromethane to trifluoromethane .

atom hdelete

atom hdelete ehandle ?label?...

atom hdelete ehandle all

a.hdelete()

Atom.Hdelete(eref,?alabel/aref/arefsequence?,...)

Atom.Hdelete(aref,...)

Atom.Hdelete(eref,“all”)

Delete zero or more atoms. All bonds which the atoms participate in are also deleted. The electron counts of surviving atoms participating in deleted bonds are automatically updated. Molecule and ring information, and other minor object classes under the control of the ensemble major object which depend on an unchanged atom set are deleted. Any property data which depends on an unchanged atom set is also invalidated, or, if the property is set up to do so, re-computed.

Additionally, and different from the simple atom delete command, all cut VB valences on the neighbor atoms which will not be deleted with the same statement are saturated with added hydrogen atoms. Only the cut valences are treated, this is not necessarily equivalent to a atom hadd command on the neighbors.

Otherwise, the command performs the same actions as the simple atom delete command.

The all command variants are identical to that of the simple atom delete command since no neighbor atoms for hydrogenation remain.

The command returns the number of deleted atoms.

atom hdup

atom hdup ehandle ?label_list? ?datasethandle? ?position?

a.hdup(?dataset=?,?position=?)

Atom.Hdup(eref,aref_tuple,?dataset=?,?position=?)

Duplicate zero or more atoms, plus all the bonds existing between them, into a new ensemble, and plug all open valences by adding standard hydrogens. This command is similar to ens hfragment , and the same caveats about preserved and destroyed data in the duplicate apply.

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.

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

The command returns the handle of the new ensemble object for Tcl , or an ensemble reference for Python .

atom hstrip

atom hstrip ehandle label ?flags? ?chargedelta?

a.hstrip(?flags=?,?chargedelta=?)

This command removes hydrogens from the selected atom. 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:

• deprotonate
  If this flag is set, a single proton is removed from the atom. This command variant does issue a standard atom and bond change property invalidation event, and it always ends processing after removing the first proton. Proton removal decreases the charge of the atom by one.
• keepalphawedge
  Keep hydrogen atoms which are bonded to an atom which is at the tip of a wedgebond. This flag excludes the case where the bond to the hydrogen atom is the wedge bond - use the keepwedge flag to cover this case.
• keepisotopes
  Keep hydrogen atoms which are isotope labels (including enriched/depleted 1H).
• keeporiginal
  Hydrogen atoms which were not automatically added via a hydrogen addition command are retained. Note that these commands can be run in a mode which does not leave information about automatic addition - hydrogens added this way do not survive.
• keepprotons
  Keep any molecules which consist only of hydrogen atoms (such as protons, hydride anions, and molecular hydrogen).
• keepspecial
  If this flag is set, hydrogens which are usually displayed, such as on aldehydes, wedge bonds, carbon triple bonds or hetero atoms are retained.
• keepwedge
  Keep hydrogens which are at the end of a wedge bond, indicating stereochemistry.
• normalize
  Normalize the wedge pattern for standard cases, removing excess wedges from hydrogens if the result structure is still stereochemically defined. Hydrogens which lose their wedge in this process are no longer protected by the keepwedge flag.
• wedgetransfer
  If a hydrogen atom is removed which is at the end of a wedge, the wedge information is saved by transferring the wedge (changing its up/down status if necessary) to an adjacent, surviving bond. This flag has no effects if the keepspecial or keepwedge flags are set. This flag is set by default.

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 atomic charge and free electrons of the atom are adapted accordingly before the hydrogens are added. The manipulation of the charge will usually change 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.

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 the structure may contain implicit hydrogens.

The return value of the command is the number of hydrogens removed.

Example:

atom hstrip $ehandle 1 [list keeporiginal wedgetransfer]

atom hydrogenate

atom hydrogenate ehandle label ?filterset? ?changeset?

a.hydrogenate(?filters=?,?changeset=?)

Reduce all bonds the atom participates in to single bonds except those excluded by the filter set.

If a change set is supplied, its interpretation is the same as in atom hadd.

The command returns the number of added hydrogens.

Example:

atom hydrogenate $eh 1 {!arobond !ccbond}

This reduces all non-aromatic hetero bonds atom 1 participates in to single bonds.

atom index

atom index ehandle label

a.index()

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

Example:

atom index $ehandle 99

atom invert

atom invert ehandle label

a.invert()

Invert the stereochemistry at the atom, provided it is an sp3-type atomic stereo center, which includes those which use an electron pair as pseudo ligand and allenes with an odd number of atoms. This command updates any atomic stereo descriptors and bond wedges to the ligands if set, but only compute A_LABEL_STEREO . No check it made whether the atom can physically be a stereo center, but if the A_LABEL_STEREO descriptor is zero, or describes non-sp3 types of stereochemistry such as square planar, the command does nothing and returns 0, but will not raise an error. For odd allenes, bond wedges at the terminal atoms are updated, not those at the center atom.

If stereochemistry was inverted, this command issues a stereo change property invalidation event and additionally invalidates the A_STEREOGENIC and B_STEREOGENIC properties, because the stereo potential of centers which possess two ligand groups which only differ in stereochemistry may have changed.

If the command finds a defined stereo center and succeeds in inverting it, it returns 1, 0 otherwise.

atom isotopecheck

atom isotopecheck ehandle label ?extended?

a.isotopecheck(extended=)

Test whether the isotope label of the atom, if it exists, is physically reasonable. The command returns boolean true if the label is OK, or is not set. If no isotope is set in A_ISOTOPE , the command always reports no problems.

By default, a smaller isotope table is used which contains only isotopes which are sufficiently long-lived to perform chemistry on. These include naturally occurring isotopes as well as isotopes used for experimental labeling, such as 1T or 14C. If the extended boolean flag is set, a larger table containing all known isotopes of the elements is used.

The isocheck command is an alias.

atom jget

atom jget ehandle label propertylist ?filterset? ?parameterdict?

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

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

atom jnew

atom jnew ehandle label propertylist ?filterset? ?parameterdict?

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

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

atom jshow

atom jshow ehandle label propertylist ?filterset? ?parameterdict?

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

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

atom local

atom local ehandle label propertylist ?filterset? ?parameterdict?

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

Example:

atom 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 in a global re-computation.

atom match

atom match ehandle label ss_ehandle ?ss_label? ?matchflags? ?ignoreflags? 	?atommatchvar? ?bondmatchvar? ?molmatchvar?

a.match(substructure=,?substructureatom=?,?matchflags=?,?ignoreflags=?,	?atommatchvariable=?,?bondmatchvariable=?,?molmatchvariable=?)

Check whether the selected atom matches a substructure. Only the first substructure atom, or the atom 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 atom.

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.

Example:

set ss [ens create {[F,Cl,Br,I]} smarts]

set a_is_halogen [atom match $ehandle $label $ss 1]

atom mol

atom mol ehandle label ?filterset? ?filtermode?

a.mol(?filters=?,?mode=?)

Standard cross-referencing command to obtain the label (for Tcl ) or reference (for Python ) of the molecule the atom is a member of. This is explained in more detail in the section about object cross-references.

Examples:

atom mol $ehandle 1

atom mol $ehandle 1 heterocycle

The first example returns the label of the molecule. Note that it is possible for pseudo atoms to be outside of any molecule. In this case, an empty string is returned. The second example returns the molecule label if the atom is part of a molecule which contains one or more heterocycles. If the molecule does not contain a heterocycle, an empty string is returned. Note the use of mol in singular - an atom can only be a member of one molecule, or of none.

atom neighbors

atom neighbors ehandle label ?filterset? ?filtermode? ?sphere? ?allowduplicates?

a.neighbors(?filters=?,?mode=?,?sphere=?,?allowduplicates=?)

This command (which can also be invoked as subcommand neighbours , or ligands ) is a cross-referencing command with some extra options and, in some filter modes, slightly different behavior than the standard object cross-reference subcommands.

In the simplest case, it returns the labels (for Tcl ) or references (for Python ) of the immediate neighbor atoms. A neighbor atom is an atom which is bonded via a standard (covalent, BTYPE_VB ) or complex ( BTYPE_COMPLEX ) bond to the originating atom. In case the filter list contains bond filters, the bond leading to the originating atom must pass the check, not just any bond of the neighbor atom.

Example:

atom neighbors $ehandle 1 doublebond

returns all neighbor atom labels which are bonded via a double bond. Neighbor atoms which participate in a double bond with other atoms, but not the originating atom, are not returned.

This command supports special filtermode parameters in addition to the standard set ( exists , count , exclude , include ). The notraverse parameter, followed by a list of atom labels in any of the standard atom specification styles is a list of atoms which are not traversed during sphere expansion. 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.

Example:

atom neighbors [ens create CC(C)C] 2 {} {notraverse {3 4}} 2

only returns the hydrogen atoms 5, 6, 7 on atom 1, since carbon atoms 3 and 4 are blocked. If the atoms in the traversal block list are part of the requested sphere, they are listed.

By default atoms in the immediate neighborhood are examined, but this change be changed by the sphere parameter. The immediate neighbors are in sphere 1 (the default for this parameter), the next group of atom is in sphere 2, and so on. If the sphere is not 1, the special filtering of bonds is no longer active and the normal object substitution mechanism for cross referencing is used. When going beyond the first sphere, it is also possible that an atom may be reached by multiple paths of the selected length. By default, these atoms are returned only once, but with the last optional parameter this behavior may be changed. A positive sphere value only selects atoms in that sphere. A negative sphere parameter value returns a list of all neighbors up to and including the sphere identified by the absolute sphere value.

Example:

atom neighbors $ehandle 1 {carbon aroatom} count 2

counts the number of aromatic carbon atoms in a distance of two bonds.

atom new

atom new ehandle label propertylist ?filterset? ?parameterdict?

a.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 atom get command. The difference between atom get and atom new is that the latter forces the re-computation of the property data, regardless whether it is present and valid, or not.

atom nget

atom nget ehandle label propertylist ?filterset? ?parameterdict?

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

atom paths

atom paths ehandle label targetlabel ?minlength? ?maxlength? ?filterset? 	?atomproperty? ?maxpathcount? ?flags?

a.paths(target,?minlength=?,?maxlength=?,?filters=?,?atomproperty=?,	?maxpathcount=?,?flags=?)

This command finds all paths between a pair of atoms, walking along bonds of the types which define molecules. By default, these are bond types normal , complex and 3center , but this can be changed by modifying the control variable ::cactvs(molecule_bond_set) .

The return value of the command is a nested list, even it only a single path is found. Every sublist contains all the labels (for Tcl ) or references (for Python ) of the atoms in a single path, including those of the start and end atoms. Every bond is used only once in any path, and no path crossings through an atom are allowed. Every atom, with the possible exception of path end points, appear only once in any single path. Paths from an atom via some bonds back to itself are allowed. The atom must be a ring member for such paths to exist.

If the destination atom is specified as an empty string, all possible paths emerging from the source atom and not violating any other specified constraints are returned. This includes shorter sub-paths which are contained in a longer paths - these are reported as separate result items.

By default, all paths of length greater than zero are returned. The lengths of acceptable paths may be specified by the optional parameters. If only the minimum length is set, this value is also used for the maximum length, resulting in only paths of a specific length to be reported. The maximum path count parameter can be used to limit the number of paths found. However, the order of the found paths does depend on the arrangement of the atoms in the bonds, so it is generally not canonic. Omitting this parameter or setting it to a negative value disabled the maximum path count check.

A non-empty filter set can be used to restrict the atoms that are eligible to be part of the path. Normally, these are atom filters, such as !hydrogen , but other types may be used in special circumstances. Bond filters are however applied to the union of all bonds of an atom, not just the specific bond traversed in a path. For example, a doublebond filter lets an atom pass if it participates in any double bond, and does not necessarily mean the bond the atom was reached over in the path. Filters are not applied to the start atom of the path.

The default report value for an atom is its label, i.e. property A_LABEL . However, any other present or computable atom property may be specified instead with the optional atom property parameter. The parameter may also refer to a property field in case the property is indexible.

The final optional flag parameter is a list of additional keywords which further modify the path atom selection and result reporting. Currently, the following keywords are recognized:

• noringchaincrossing
  The path may not jump from a chain atom to a ring atom, or vice versa
• concatenate
  The report format for each individual path is not a Tcl list, but a string where the report atom property values are directly concatenated
• printbondorder
  Every report value after that of the first path atom is prefixed with a character indicating the bond order from the set “-=#&” for bond orders one to four, with a colon for aromatic bonds, and a question mark for non-VB bonds. Additionally, a @ is added if the bond closes a ring to the first path atom.

Example:

atom paths [ens create C1CCC1] 1 1

reports the paths {1 2 3 4 1} and {1 4 3 2 1}, which correspond to walking the ring clockwise and counter clockwise, respectively.

atom paths [ens create CC=C] 1 3 3 3 {} A_ELEMENT -1 {printbondorder concatenate}

returns {6-6=6}.

atom pis

atom pis ehandle label ?filterset? ?filtermode?

a.pis(?filters=?,?mode=?)

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

Examples:

atom pis $ehandle 1

Get the labels of the π systems the atom is participating in. π 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.

atom protonate

atom protonate ehandle label ?count?

a.protonate(?count=?)

Attempt to add one ore more protons to the atom, with adjustment of formal atom charge and processing of appropriate structure change property data invalidation events.

The command returns the label (for Tcl ) or reference (for Python ) of the atom.

atom purge

atom purge ehandle label propertylist/stereo/isotope/query

a.purge(propertylist/stereo/isotope/query)

Reset existing property data on an atom. In case the argument is a list of property names, the value on that atom 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 a bond property instead of an atom property, the reset is executed for all bond atoms. 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 atom-centered stereo information on the atom, including wedges in property B_FLAGS that point to the atom, and will trigger a stereo change event on the ensemble which may invalidate additional data.

The isotope code resets property A_ISOTOPE on the atom, marks the isotope data as tainted and runs a data dependency check.

The query code resets property A_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 atom.

atom ref

Atom.Ref(eref,identifier)

Python only method to get an atom reference. See atom atom command.

atom replace

atom replace ehandle label fragment/element ?fragmentlabel? ?removeh?

a.replace(replacement=,?linkatom=?,?removeh=?)

Replace an atom by a fragment. The fragment may be an atom, a molecule, or even a multi-molecule ensemble. The fragment parameter is either an ensemble handle, a SMILES string, or a list of an ensemble handle and a molecule label, identifying one molecule within that ensemble. For Python, it may also be a molecule reference. Ensembles or molecules identified by handles will not be destroyed, because the command works on a duplicate.

If the fragment parameter cannot be decoded as any of those fragment definition styles, an attempt is made to interpret is as an element or pseudo-element symbol. Deuterium and tritium isotopes may be specified as D and T, and standard query atom and superatom specifications are also understood with a syntax identical to the atom create command. For standard element modifications, such as by a molecule editor, the atom change variant of this command is preferred, because that command does not attempt to decode the fragment parameter in the other styles first and thus avoids problems with element symbols that are at the same time valid SMILES strings.

The first atom in the atom list of the selected fragment structure (which does not necessarily correspond to the lowest label in that structure) is the default link atom on the fragment. The link atom is the fragment atom which replaces the original atom in the input ensemble. A different link atom can be selected by providing a valid label (not an index) of a fragment atom as optional parameter.

All valence bonds ( B_TYPE normal), ionic ( B_TYPE ionic ) and complex bonds ( B_TYPE complex ) to the original atom are preserved with their bond order, as are standard bond attributes (property B_FLAGS ). It is possible to replace atoms with more than one neighbor, or with multiple or aromatic bonds. In the atom change variant of this command, it is an error if the fragment link atom cannot provide sufficient electrons to satisfy the VB bonds of the replaced atom. In atom replace mode, existing bonds that cannot be recreated are silently ignored. If the removeh flag is set, the program will attempt to find required valence electrons by removing hydrogen atoms from the link atom. If no more hydrogens can be found, electron pairs are used as a last resort, but without trying to adjust formal charges. The 2D coordinates of the link atom (property A_XY ), if present, are set to the old coordinates of the replaced atom. Other properties are lost or adapted according to the merge functions of the underlying property definitions.

The return value of this command is the label (for Tcl ) or reference (for Python ) of the fragment link atom, which is the same as the label of the replaced atom. All atom and bond labels in the base fragment are guaranteed to be preserved, with the exception of the labels of the bonds around the replaced atom. The labels of the added fragment are generally changed, but are copied to properties A_LABEL% , B_LABEL% etc. before the merge.

Examples:

set ehandle [ens create CCBr]

set newlabel [atom replace $ehandle 3 [ens create Cl 0]]

set newlabel [atom change $ehandle 3 Cl]

atom replace $ehandle $newlabel {FC(F)F} 2 1

The second line replaces atom 3 (bromine) with a chlorine atom. The chlorine ensemble was generated without hydrogens, to Cl has a bonding electron. Also, the default link atom of the fragment is the only atom, so there cannot be any question about the fragment link location. The new label of the Cl atom is stored - but this is not really required, since it is always 3, the label of the replaced atom. Line three is the same exchange expressed in the more efficient syntax of the atom change command variant.

The fourth example code line replaces the chlorine atom with a CF3 group. That group is set up by an in-line SMILES string. The fragment link atom is set to 2 (the carbon atom - labels from SMILES decoding follow the atom order). Since this fragment was generated with an extra hydrogen atom on carbon, the final parameter makes sure that this atom is removed before the replacement operation, yielding an electron on the CF3 carbon atom for bonding to the main structure. If the hydrogen removal flag is not set, the operation will fail with this fragment. Without automatic hydrogen removal, the fragment needs to be written as F[C](F)F for successful replacement, with explicitly suppressed hydrogen addition at the carbon atom.

atom rings

atom rings ehandle label ?filterset? ?filtermode?

a.rings(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the rings the atom is a member of. This is explained in more detail in the section about object cross-references.

Examples:

atom rings $ehandle 1

atom rings $ehandle 1 [list heterocycle aroring]

The first example returns the labels of all rings the atom is a member of. If the atom 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.

atom ringsystems

atom ringsystems ehandle label ?filterset? ?filtermode?

a.ringsystems(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the ring systems the atom is a member of. This is explained in more detail in the section about object cross-references.

Examples:

atom ringsystems $ehandle 1

atom ringsystems $ehandle 1 [list heterocycle aroring]

The first example returns the labels of the ring system the atom is a member of. If the atom is not in any ring, 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.

atom set

atom set ehandle label ?property value?...

a.set(?property,value?,...)

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

a.property = value

a[property] = value

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

Example:

atom set $ehandle 1 A_COLOR “blue”

The direct change of critical atom type data, such as the element A_ELEMENT , element symbol A_SYMBOL , or atom type A_TYPE should be avoided. It is safer to create a new atom, delete the old atom, and establish new bonds if an atom needs to be changed in its type, or to use the atom replace command. The dedicated creation, deletion and replacement commands will automatically take care of bookkeeping tasks such as electron counting for valence bonds. Also, direct setting of the element data will render most structure information invalid, since most properties depend directly or indirectly on the element composition. Careful manual locking and updating of property data is required if direct element manipulation is attempted.

The command returns the first data value.

atom show

atom show ehandle label propertylist ?filterset? ?parameterdict?

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

atom sigmas

atom sigmas ehandle label ?filterset? ?filtermode?

a.sigmas(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the σ systems the atom is a member of. This is explained in more detail in the section about object cross-references.

Examples:

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

atom sqldget

atom sqldget ehandle label propertylist ?filterset? ?parameterdict?

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

atom sqlget

atom sqlget ehandle label propertylist ?filterset? ?parameterdict?

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

atom sqlnew

atom sqlnew ehandle label propertylist ?filterset? ?parameterdict?

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

atom sqlshow

atom sqlshow ehandle label propertylist ?filterset? ?parameterdict?

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

atom stereoligands

atom stereoligands ehandle label

a.stereoligands()

Get the set of ligands which define the stereochemistry of an atom. If the atom is not stereogenic, the result is a list of four empty strings for Tcl or None values for Python . If the atom is the center atom of an odd allene, the list contains the substituents at either end of the allene, independently sorted by atom label in ascending order for each side. If the atom is a normal tetrahedral or square planar center, the direct ligands in sorted ascending label order are returned. If one of the ligands is an electron pair, it is returned as an an empty or None list element in last position. If the atom is a pyramidal or octahedral stereo center, the normal 4-element list is expanded to include the extra atoms.

atom subcommands

atom subcommands

dir(Atom)

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

atom surfaces

atom surfaces ehandle label ?filterset? ?filtermode?

a.surfaces(?filters=?,?mode=?)

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

Example:

atom surfaces $ehandle $label

Note that individual surface patches are not required to be associated with any atom.

atom topodistance

atom topodistance ehandle label targetlabel ?bondclasses?

a.topodistance(target=,?bondclasses=?)

Compute the minimum topological distance to the second atom. By default, only VB bonds are traversed, but the optional argument allows the specification of a custom bit set of traversed bond classes.

If there is no path between the atoms, the result is -1. The distance of an atom to itself is zero.

In case many topological distances within a structure are needed, it is faster to compute property A_TOPO_DISTANCE once.

atom torsion

atom torsion ehandle label label2 label3 label4 ?property?

a.torsion(atom2=,atom3=,atom4=,?coordinateproperty=?)

Compute the torsion angle in degrees between the four atoms, which are considered to be linked in the specified sequence, i.e. the first three atoms defined the first plane, and the last three atoms the second plane. The torsion angle is the vector angle of the normals of the two implicitly defined planes and is always in the +/-180 degrees range.

The source property for atomic coordinates is by default A_XYZ , but another property can be set, which also needs to be an atomic float vector. All atoms used in a statement must be different, and possess 3D coordinates initially, or after an automatically initiated attempt to compute 3D atomic coordinate property. No bonds need to exist between the atoms.

atom uncharge

atom uncharge ehandle label

a.uncharge()

Perform a chemistry-smart transformation of the atom to remove or at least minimize its formal charge. Depending on the atom charge, type and element, this involves addition or removal of hydrogen atoms, or, if these are not available or the element has no clear hydrogen count/formal charge rules, direct editing of the formal charge and modification of the free electron count.

The command returns the number of change operations on the atom. These are either hydrogen additions and deletions, or direct formal charge changes.

atom valencecheck

atom valencecheck ehandle label ?nitrogenmode?

a.valencecheck(?nitrogenmode=?)

Perform a valence check on the atom, comparing the current bonding situation at the atom to the list of element-specific valence states in the system element table. This command is intentionally quite picky, discouraging for example the use of pentavalent nitrogen by default. For the calculation of valence, only bonds of type normal are taken into account. Complex bonds and pseudo bond types thus do not interfere in the calculation. Some more exotic metals with many different valence states, or few well-defined covalent compounds, such as vanadium or rhodium, always pass.

The handling of nitrogen in pentavalent or ionic form can be controlled by setting the optional nitrogenmode argument, or modifying the global : :cactvs(nitrogen_valence_check) variable.Possible values are xionic , ionic (the default), asis , pentavalent and xpentavalent . These are the same values as with the ens nitrostyle command - please refer to that command for more information. In asis mode, both ionic and pentavalent forms pass.

The return value of this command is 0 for failure, 1 for pass.

Note that this command assumes that all hydrogen atoms are in place. Processing structures with Implicit hydrogen atoms is not supported.

Example:

atom valencecheck [ens create {CN(=O)=O}] 2

atom valencecheck [ens create {C[N+](=O)[O-]}] 2

These sample commands check the valence state of atom 2, the nitrogen atom in two different encodings of nitromethane. The first encoding returns 0, the second 1.

atom valcheck is a short alias.

atom vicinity

atom vicinity ehandle label maxdistance ?mindistance? ?filterset? ?property?

a.vicinity(maxdistance=,?mindistance=?,?filters=?,?coordinateproperty=?)

Get a list of the labels of atoms located in a 3D distance range from a query atom. The distance is computed from the atomic coordinates in property A_XYZ , or another float-vector atomic property explicitly specified. Query distances are specified in Angstrom, or whatever the default unit of a custom property is. If no minimum distance is given, it is assumed to be zero. Nevertheless, the query atom itself is never part of the returned set.

The reported atoms do not need to be bonded to the query atom directly or indirectly. If no atoms are found in the distance range, or none pass the optional filter set, an empty list results. If there are no atomic 3D coordinates, and these cannot be computed, an error is raised.

atom xdelete

atom xdelete ehandle ?label?...

atom xdelete ehandle all

a.xdelete()

Atom.Xdelete(eref,?alabel/aref/arefsequence?,...)

Atom.Xdelete(aref,...)

Atom.Xdelete(eref,“all”)

This command is a variation of the atom delete command. The only difference is that it also deletes all hydrogen atoms the deleted atoms were bonded to.

The special atom label all requests deletion of all atoms. Usually, this is equivalent to ens clear .

The return value of the command is the number of deleted atoms.

Example:

atom xdelete $ehandle 1

This command is one of few atom subcommands which do not require an atom label. If no label is given, the command does nothing. This is useful for list expansions where the list might be empty:

atom xdelete $ehandle {*}$delatomlist

atom xhdelete

atom xhdelete ehandle ?label?...

atom xhdelete ehandle all

a.xhdelete()

Atom.Xhdelete(eref,?alabel/aref/arefsequence?,...)

Atom.Xhdelete(aref,...)

Atom.Xhdelete(eref,“all”)

This command is a variation of the atom delete command. The difference is that it also deletes all hydrogen atoms the deleted atoms were bonded to, and the cut bond valences to atoms which are not hydrogen, and not deleted by the same statement, are saturated with added hydrogen atoms.

The special atom label all requests deletion of all atoms. Usually, this is equivalent to ens clear .

The return value of the command is the number of deleted atoms.