mol get $ehandle 1 M_WEIGHT

mol delete $ehandle 2

mol dup $ehandle primary

set pmol_label [mol mol $ehandle primary]

mol append

mol append ehandle label ?property value?...

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

m.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:

mol append $ehandle 1 M_NAME “_linker”

mol align3d

mol align3d ehandle label box/center/masscenter/pmi ?usehydrogens? ?property?

m.align3d(?mode=?,?usehydrogens=?,?coordinateproperty=?)

Perform a 3D alignment by modifying standard atom coordinates property A_XYZ , or an alternative explicitly specified atomic coordinate property.

The possible alignment modes are

• box
  move center of enclosing 3D coordinate box to origin
• center
  move average atom coordinates to origin
• masscenter
  move mass-weighted atom coordinates to origin
• pmi
  align ensemble to principle moments of inertia (largest on x axis), and move the mass-weighted center to the origin.

By default all atoms of the molecule are used to compute the alignment rotation and movement vectors, including hydrogens. If these should be omitted from computing the movement vectors (but not the subsequent atom movement), the optional usehydrogens parameter can be set to false .

The command returns the label or reference of the molecule.

mol atoms

mol atoms ehandle label ?filterset? ?filtermode?

m.atoms(?filters=?,?mode=?)

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

Example:

mol atoms $ehandle !hydrogen

returns the labels of the non-hydrogen atoms in the molecule.

mol bondangles

mol bondangles ehandle label ?filterset? ?filtermode?

m.bondangles(?filters=?,?mode=?)

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

mol bonds

mol bonds ehandle label ?filterset? ?filtermode?

m.bonds(?filters=?,?mode=?)

Standard cross-referencing command to obtain the labels or references of the bonds the molecule contains. This is explained in more detail in the section about object cross-references. Bonds which cross into other molecules are not listed. Such bonds may exist if they are not of a bond type which is used to group atoms into molecules.

Examples:

mol bonds $ehandle 1

mol bonds $ehandle 1 {1 doublebond triplebond} count

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

mol compare

mol compare ehandle label ehandle2 label2

m.compare(mref)

Compare two molecules, yielding a stable sort order. The compared attributes are, in this order, the number of atoms, the number of bonds, the molecular weight, the number of ESSSR rings and finally the stereo- and isotope aware 64-bit hashcode ( M_ISOTOPE_STEREO_HASHY ). The command returns 1 if the first molecule is larger, -1 if the second is larger, and 0 if they are identical according to the comparison scheme.

The compared property values, with the exception of the final hashcode tiebreaker, are compatible with the RDKit model.

mol defined

mol defined ehandle label property

m.defined(property)

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

mol defined $ehandle 1 M_NAME

checks whether molecule 1 is of a type for which M_NAME is defined.

mol delete

mol delete ehandle ?label?...

mol delete ehandle all

m.delete()

Mol.Delete(eref,”all”)

Mol.Delete(mref,...)

Mol.Delete(eref,?mlabel/mref/mrefsequence?,...)

Delete molecules from the ensemble. All minor objects on the same ensemble which contain atoms from the deleted molecules, such as rings, groups and ring systems, are also deleted. However, these minor object sets are not completely destroyed and property data on the remaining objects remains valid, if those properties are not invalidated by merge events.

Deleting a molecule triggers a merge invalidation event, but not atomchange/bondchange events. Property data which is susceptible to this invalidation mode is recursively deleted from the ensemble.

The special label all deletes all molecules in the ensemble. Usually this is equivalent to ens clear , but in theory there may exist atom-class objects which are not part of a molecule, and these are then retained.

The command returns the number of deleted molecules.

Example:

mol delete $ehandle 1

mol dget

mol dget ehandle label propertylist ?filterset? ?parameterdict?

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

mol dup

mol dup ehandle label ?datasethandle? ?position?

m.dup(?target=?,?position=?)

Duplicate a single molecule into a new ensemble. The function returns the new ensemble handle or reference.

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 (or None for Python ) is passed, the duplicate is not made a dataset member, even if the input ensemble is in a dataset.

The new ensemble preserves ring information and associated property data and other minor object data from the original ensemble for all minor objects which exclusively refer to atoms which are part of the duplicated molecule. Minor objects outside the duplicated molecule, or spanning multiple molecules are not duplicated.

Example:

mol dup $ehandle 1 [dataset create]

Duplicate the molecule with label one and move the new single-molecule ensemble into a newly created dataset.

mol ens

m.ens()

Python -only method to get the ensemble reference from a molecule reference.

mol exists

mol exists ehandle label ?filterlist?

m.exists(?filters=?)

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

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

Example:

mol exists $ehandle 99

mol expand

mol expand ehandle label ?allowambiguous? ?noimplicith?

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

This command expands all superatoms in the molecule. The mechanisms for the expansion of superatoms are described in detail for the atom expand command. This command is functionally equivalent, working on all atoms in the molecule instead a single atom.

Example:

mol expand $ehandle 1

The command returns the total number of successfully expanded atoms.

mol expr

mol expr ehandle label expression

m.expr(expression)

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

mol fill

mol fill ehandle label ?property value?...

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

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

The command returns the first fill value.

Example:

mol fill $ehandle 1 B_COLOR red

sets the color of the first bond molecule 1 contains to red.

mol filter

mol filter ehandle label filterlist

m.filter(filters)

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

Example:

mol filter $ehandle 1 [list carbon doublebond]

checks whether the molecule contains one or more carbon atoms and one or more double bonds. The double bond does not need to be with a carbon atom.

mol get

mol get ehandle label propertylist ?filterset? ?parameterdict?

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

m[property]

m.property

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

Examples:

mol get $ehandle 1 {M_WEIGHT A_ELEMENT}

yields a list with two elements, consisting of the molecular weight as the first element and the element numbers of all atoms in the molecule as a nested list as the second result list element. If the information is not yet available, an attempt is made to compute it. If the computation fails, an error results.

mol get $ehandle 1 B_ORDER ringbond

gives the bond orders of all bonds of the molecule 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 mol get command are mol new , mol dget, mol show, mol sqldget, mol sqlget, mol sqlnew and mol sqlshow .

Further examples:

mol get $ehandle 1 E_NAME

mol get $ehandle 1 A_FLAGS(boxed)

mol groups

mol groups ehandle label ?filterset? ?filtermode?

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

Standard cross-referencing command to obtain the labels or references of the groups the molecule contains. This is explained in more detail in the section about object cross-references. Groups which contain atoms from more than one molecule are included.

Example:

mol groups $ehandle 1

mol hadd

mol hadd ehandle label ?filterset? ?flags?

m.hadd(?filters=?,?flags=?)

Add a standard set of hydrogens to the molecule. If the filterset parameter is specified, only those atoms which pass the filter set are 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:

• keepflags
  For expert use only. Do not discard min/max values and property scope flags for atom properties when hydrogen is added.
• 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 ).
• protonate
  Add a single proton to the molecule, to the first suitable atom. The charge of the selected 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. In the molecule command variant, this option is rarely useful. It is supported for compatibility with the atom hadd command.
• 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.

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 {[C].[C]}]

mol hadd $ehandle 1

adds four hydrogens to the first carbon atom, transforming it into methane, but leave the second carbon atom untouched.

mol hdup

mol hdup ehandle label ?datasethandle? ?position?

m.hdup(?target=?,?position=?)

This command provides the same functionality as mol dup , except that it also adds a standard set of hydrogens to the new ensemble.

mol hstrip

mol hstrip ehandle label ?flags?

m.hstrip(?flags=?)

This command removes hydrogens from the selected molecule. By default, all hydrogen atoms in the molecule 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 first suitable atom. This command variant triggers 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. In the molecule command variant, this flag is rarely useful - it is supported for compatibility with the atom hstrip command.
• 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 these commands commands can be run in a mode which does not leave information about automatic addition - hydrogens added this way are not protected.
• 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!

Hydrogen stripping is not as disruptive to the ensemble data content as normal atom deletion, except when 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:

mol hstrip $ehandle 1 [list keeporiginal wedgetransfer]

mol hydrogenate

mol hydrogenate ehandle label ?filterset? ?changeset?

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

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

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

The command returns the number of added hydrogens.

Example:

mol hydrogenate $eh 1 {!arobond !ccbond}

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

mol image

mol image ehandle label ?width? ?height? ?options?

This command generates a Tk image object displaying the molecule as an icon. The command is only available in toolkit variants which are linked with the portable Tk GUI toolkit library and which are either statically linked with the GD image drawing library, or can load it dynamically. It is currently not support in the Python interface.

The default image size is 64x64 pixels, but this may be overridden by the width and height parameters. If only width is set, it is also used for the height. The command returns a Tk image handle. These images may for example be placed on Tk canvases as canvas objects, or used on buttons and other GUI objects.

Because of the small size of the images, atoms are not displayed as symbols, but small color-coded squares. This is a command for the implementation of graphical structure-handling applications with icons. For serious structure visualization, use the E_GIF , E_EMF_IMAGE or E_EPS_IMAGE properties.

Additional options may be added by an arbitrary sequence of option/value pairs. Color names can be those registered in the X11 color database, or a numeric specification in the #rrggbb format. These options are currently supported:

• -background color
  Background color. The default is black .
• -border npixels
  Thickness of the image border. The default are 5 pixels.
• -bordercolor color
  Border color. The default is blue.
• -cmode none/special/all
  Display mode for carbon atoms. The default is special , meaning that only carbon atoms which usually are drawn with a C symbol are displayed as colored rectangle and not just a bond node. Highlighted atoms are always displayed.
• -highlightatom label
  Select an atom for highlighting. By default, no atom is highlighted.
• -highlightcolor color
  Set the highlighting color. The default is chartreuse .
• -hmode none/special/all
  Display mode for hydrogen atoms. The default is special , meaning that only hydrogen atoms which usually are drawn with an H symbol are displayed as colored rectangle. Other hydrogen atoms and the bonds leading to them are suppressed. Highlighted atoms are always displayed.
• -imagename name
  Explicitly set a name for the image. By default, a name of the form imagen is automatically generated. It is possible to specify the name of an existing image, which will then be overwritten.
• -linecolor color
  Color of bond lines and wedges. The default is white .

Images are cached. If an image for the selected molecule with the same display attributes exists, it is reused.

Example:

set img [mol image $ehandle 1 80 80 -border yellow -linecolor blue]

canvas create .canvaswin image 50 50 -image $img

mol index

mol index ehandle label

m.index()

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

Example:

mol index $ehandle 99

mol isotopecheck

mol isotopecheck ehandle label ?failedatomvariable? ?extended?

m.isotopecheck(variable=,extended=)

Test whether the isotope labels on the atoms of the molecule, if they exist, are physically reasonable. The command returns the number of failed atoms. If a capture variable is specified, the atom labels or references of these atoms are stored therein. If no isotope labels are set in A_ISOTOPE , the command always reports zero 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 3H 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.

mol jget

mol jget ehandle label propertylist ?filterset? ?parameterdict?

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

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

mol jnew

mol jnew ehandle label propertylist ?filterset? ?parameterdict?

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

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

mol jshow

mol jshow ehandle label propertylist ?filterset? ?parameterdict?

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

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

mol local

mol local ehandle label propertylist ?filterset? ?parameterdict?

m.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:

mol local $ehandle 1 A_LABEL_STEREO

Note that very few computation routines currently support the local re-computation of data - in most cases, this command falls back to a global re-computation.

mol match

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

m.match(substructure=,?substructuremol=?,?matchflags=?,?ignoreflags=?,	?atommatchvariable=?,?bondmatchvariable=?,?molmatchvariable=?)

Check whether the selected molecule matches a substructure. Only the first molecule, or the molecule 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 molecule. Both the atoms in the molecule and the bonds between them are checked.

The precise operation of the substructure match routine can be tuned by providing a standard set of match flags and feature ignore flags. The default match flag set has set bits for the bondorder , atomtree and bondtree comparison features, and an empty ignore set. If a flag set is specified as an empty string, the default set is used. In order to reset a flag set, an explicit none value must be used. The 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. 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 {c1ccccc1.c1ncccc1} smarts]

set m_contains_phenylring [mol match $ehandle $label $ss 1]

mol mol

mol mol ehandle label

Mol.Ref(eref,identifier)

Standard cross-referencing command to obtain the label or reference of the molecule as stored in property M_LABEL . This is explained in more detail in the section about object cross-references.

Example:

mol mol $ehandle #0

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

mol mol $ehandle primary

returns the label of the primary molecule in the ensemble.

mol new

mol new ehandle label propertylist ?filterset? ?parameterdict?

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

mol nget

mol nget ehandle label propertylist ?filterset? ?parameterdict?

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

mol pack

mol pack ehandle label ?maxsize? ?requestprops? ?suppressedprops? ?compressionlib?

m.pack(?maxsize=?,?requestprops=?,?suppressedprops=?,?compressionlib=?)

Pack the selected molecule into a base64-encoded compressed serialized object string. This string does not contain any non-printable characters and is a full dump of the internal state of the object, omitting only property data that was declared to be so easily re-computed that a dump is not worthwhile. Outside object relationship information, such as the dataset the ensemble of the molecule might be a member of, or associated tables of the parent ensemble are not included, and neither are any ensemble properties.

The maximum size of the object string (default -1, meaning unlimited) can be configured by the optional maxsize parameter. The size is specified in bytes. If the pack string would be longer than the maximum size, an error results.

The next two optional parameters allow to request a specific property set to be part of the package, even if it normally would not be included, and to explicitly omit properties from the dump. No property computation is performed, and suppressed properties are not purged from the ensemble.

The default compression library is zlib . Other useful variants include lzo and gzip (and there are other internal types), but these may not be available on all builds due to license issues, and you need to specify the compression library when a dataset is unpacked. It is generally recommended to stay with zlib .

Single-molecule ensembles can be restored from a packed object string by the ens unpack and ens create commands.

The Python Mol class also supports the pickle protocol, but not unpickling. Restoring a pickled molecule can be done via the Ens unpickle method - this is like unpacking the pack string, which also returns a new single-mol ensemble.

mol pis

mol pis ehandle label ?filterset? ?filtermode?

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

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

Examples:

mol pis $ehandle 1

π systems are a rather exotic feature and not commonly used. These are essentially descriptions of bonding interactions which use p or d orbitals, such as in standard covalent multiple bonds. A simple double bond is described with one σ system and one π system in this representation.

mol ref

Mol.Ref(eref,identifier)

Python only method to get a group reference. See mol mol command.

mol replicate

mol replicate ehandle label ?count?

m.replicate(?count=?)

Add duplicates of the selected molecule to the command ensemble. The default number of duplicates is one, but any other number may be requested by setting the count parameter. If the count is less than one, the command is silently ignored.

The command returns the labels or references of all newly created molecules as a list. New molecule labels begin at one plus the highest old label. All atoms, bonds and other chemistry objects which are created by the command are appended to the object lists in the ensemble and will thus bear higher labels than any existing label of their class in the ensemble. This command triggers a merge property invalidation event.

The mol dup command duplicates a molecule into a new ensemble, which is quite different from what this command does.

Example:

set eh [ens create C.CC]

mol dup $eh 1 2

echo [ens get $eh E_SMILES]

returns C.CC.C.C, because the first molecule (label one) was duplicated twice.

mol rings

mol rings ehandle label ?filterset? ?filtermode?

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

Standard cross-referencing command to obtain the labels or references of the rings the molecule contains. This is explained in more detail in the section about object cross-references. Rings which are not restricted to the selected molecule are listed. Under certain circumstances, it is possible to have rings which span more than one molecule.

Examples:

mol rings $ehandle 1

mol rings $ehandle 1 [list heterocycle aroring]

The first example returns the labels of all rings the molecule contains. If the molecule does not contain any rings, an empty list is returned. Only labels of rings in the SSSR or ESSSR set are returned, even if the currently computed ring set is larger. The second example filters the rings - only heteroaromatic rings are reported.

mol ringsystems

mol ringsystems ehandle label ?filterset? ?filtermode?

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

Standard cross-referencing command to obtain the labels or references of the ring systems the molecule contains. This is explained in more detail in the section about object cross-references. Ring systems which are not restricted to the selected molecule are included. Under certain circumstances, it is possible to have ring systems which span more than one molecule.

Examples:

mol ringsystems $ehandle 1

mol ringsystems $ehandle 1 [list heterocycle aroring]

The first example returns the labels of all ring systems the molecule contains. If the molecule does not contain any ring systems, an empty list is returned. The second example filters the ring systems - a ring system label is included in the output list only if that ring system contains one or more hetero aromats.

mol rotate

mol rotate ehandle label angle axis ?center? ?property?

m.rotate(angle=,axis=,?center=?,?coordinateproperty=?)

Rotate the molecule in 3D space on property A_XYZ or a custom atom float vector coordinate property.

This command requires 3D atomic coordinates. If these are not yet present, an attempt is made to compute them. The rotation angle is specified in degrees. The first point is the axis vector - it can be specified in any format the Tcl vec command understands. By default the center of rotation is the center of the molecule bounding box, but by providing explicit center coordinates, any center of rotation can be set.

This operation triggers a 3Dop property invalidation event.

The command returns the original molecule label or reference.

Example:

mol rotate $ehandle 1 50 {1 1 0}

rotates the molecule around its center 50 degrees counter-clockwise along the 45-degrees xy-diagonal.

mol set

mol set ehandle label ?property value?...

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

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

m.property = value

m[property] = value

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

The command returns the first data value.

Example:

mol set $ehandle 1 M_NAME “Pharmacon X-25”

mol show

mol show ehandle label propertylist ?filterset? ?parameterdict?

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

mol sigmas

mol sigmas ehandle label ?filterset? ?filtermode?

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

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

Examples:

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

mol sqldget

mol sqldget ehandle label propertylist ?filterset? ?parameterdict?

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

mol sqlget

mol sqlget ehandle label propertylist ?filterset? ?parameterdict?

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

mol sqlnew

mol sqlnew ehandle label propertylist ?filterset? ?parameterdict?

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

mol sqlshow

mol sqlshow ehandle label propertylist ?filterset? ?parameterdict?

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

mol subcommands

mol subcommands

dir(Mol)

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

mol surfaces

mol surfaces ehandle label ?filterset? ?filtermode?

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

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

Example:

mol surfaces $ehandle $label

Note that surface patches are not required to be associated with any atom, and if they are not, they are implicitly not associated with any molecule.

mol torsions

mol torsions ehandle label ?filterset? ?filtermode?

m.torsions(?filters=?,?mode=?)

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

mol translate

mol translate ehandle label pt1 ?pt2? ?property?

m.translate(point1=,?point2=?,?coordinateproperty=?)

Move the atoms of the molecule by modifying their 3D coordinates in property A_XYZ , or a custom atomic float vector coordinate property. This command requires atomic 3D coordinates and will attempt to compute them if they are not yet present. If no 3D atomic coordinates can be generated, the command fails with an error.

The movement vector may either be specified by a single vector, or two points. If two points are used, the subtraction of the second point from the first is used to compute the movement vector. Both point/vector arguments understand the same vector notation syntax as the vec command.

This command triggers a 3Dglop property invalidation event.

The command returns the original molecule label or reference.

Example:

mol translate $ehandle 1 {1 0 0} {2 0 0}

moves the molecule one Ångström in x-direction.

mol valencecheck

mol valencecheck ehandle label ?failedatomvariable? ?nitrogenmode?

m.valencecheck(?variable=?,?nitrogenmode=?)

Perform a valence check on the molecule, comparing the current bonding situation at all atoms 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 (VB bonds) are taken into account. Complex bonds and pseudo bond types thus do not interfere in the calculation. Some more exotic metal atoms 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 , penta and xpenta . 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 the number of atoms which failed the valence check. If the optional parameter failedatomvariable is specified as non-empty string, it is the name of a variable which is set to a list of the atom labels or references which did fail, or is set to an empty list in case no problems were found.

Note that this command assumes that all hydrogen atoms are in place. Checking molecules with implicit hydrogen atoms is not supported.

Example:

mol valencecheck [ens create {CN(=O)=O.C[N+](=O)[O-]}] 1 badatoms

mol valencecheck [ens create {CN(=O)=O.C[N+](=O)[O-]}] 2 badatoms

These sample commands check the valence situation of nitromethane in two encoding formats. The first molecule, using a pentavalent nitrogen encoding, returns 1, indicating one failed atom, and the variable badatoms is set to 2, the label of the pentavalent nitrogen. The second molecule, checked with the line below, passes without problems, with a return value of 0 and an empty badatoms variable.