reaction get $xhandle X_IDENT

reaction add

reaction add xhandle ?ReactionSMILES/SMIRKS/BASE64Blob? ?decodermode?

reaction add xhandle ?ehandle?...

reaction add xhandle ?{ehandle role}?...

Add ensembles to a reaction. The syntax of the various variants to specify ensembles and their reaction roles are the same as in the reaction create command.

Example:

reaction add [reaction create] $reagent_ehandle $product_ehandle

reaction append

reaction append xhandle property value ?property value?

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

Example:

reaction append $xhandle X_NAME “_new”

reaction assign

reaction assign xhandle srcprop dstprop

Copy data from one property to another. Both properties must be associated with the same object class. The source property (but currently not the destination property) may be specified as an indexed property subfield. There must be a conversion path between the data types of the two properties or property subfields involved for the operation to succeed. For example, assigning a string property to a numeric property succeeds only if the string data items contain suitable numbers.

The original property data remains valid. The command variant reaction rename directly exchanges the property name without any data duplication or conversion, if that is possible. In any case, the original property data is no longer present after the execution of this command variant.

If the properties are not associated with reactions (prefix X_ ), the operation is performed on all reaction ensembles.

Examples:

reaction assign $xh A_XY A_XY%

This code snippet creates a backup atomic 2D layout coordinates on all reaction ensembles.

reaction rename $xh X_IDENT X_NAME

Reassign the data in property X_IDENT to property X_NAME . If possible, this is done without memory reallocation and decoding/encoding procedures.

reaction cast

reaction cast xhandle dataset/ens/reaction/table ?propertylist?

Transform the reaction into a different object. Depending on the target object class, the result is as follows:

• dataset
  A new dataset which contains which contains the reaction as first object.
• ens
  The reagent ensemble of the reaction, or the first other ensemble in the reaction is there is no reagent, or a newly created empty ensemble as last resort. The rest of the reaction and reaction ensembles are destroyed.
• reaction
  Only supplied for the sake of completeness. This mode does nothing.
• table
  A new table with one row and automatically generated columns for all properties of the input reaction of the reaction (X_*) object class. The row is filled with the input reaction data, and the reaction is moved to the internal dataset of the table.

If the optional property list is specified, an attempt is made to compute the listed properties before the cast operation, so that they may become a part of the new object. No error is raised if a computation fails.

The command returns the handle of the new object, or the input object handle in case of mode reaction .

reaction clear

reaction clear xhandle ?role? ?deleteensembles?

Remove and optionally delete ensembles of a reaction. By default, all reaction ensembles are moved out of the reaction, but they are not deleted. If a reaction role is given (possible roles are taken from the enumeration of property E_REACTION_ROLE , the default set is unknown, reagent, product, solvent, catalyst, intermediate, impurity, byproduct, agent and waste ), only those ensembles with the specified role are removed. If the deleteensemble flag is set, targeted ensembles are not simply removed from reaction membership, but destroyed.

The command returns the count of removed or deleted ensembles.

Examples:

reaction clear $xhandle

reaction clear $xhandle solvent 1

The first example removes all ensembles from the reaction, but keeps them in memory, and they can still be accessed via their handles. The second example removes all solvent ensembles from the reaction and destroys them.

reaction copy

reaction copy src_xhandle dst_xhandle

Create a copy of the input reaction in the framework of an existing reaction. The old data of the destination reaction is destroyed, but its handle is reused for the copy. The destination handle can be an empty string. In that case, the reaction is duplicated and a new handle assigned.

This command is useful when references to a reaction handle are potentially stored in unknown locations, and the reaction needs to be updated.

The return value of the command is the handle of destination reaction. It is allowed to copy a reaction onto itself.

reaction create

reaction create ?ReactionSMILES/SMIRKS/BASE64Blob/KEGGID/patran? ?decodermode?

reaction create ?ehandle?...

reaction create ?{ehandle role}?...

This command creates a new reaction. Without any parameters, an empty reaction without any ensembles in it is made. The return value is the new reaction handle.

Example:

set xhandle [reaction create]

The first variant for creating a reaction with data is the use of a single-argument line notation. The supported line notations include Reaction SMILES or SMIRKS , hex-encoded versions thereof, a KEGG reaction identifier in the form RPxxxxx, a Cactvs base64-encoded serialized reaction object string (see reaction pack ), or a base64-encoded compressed file content, such as an MDL RXN file record. For the last variant, the compression algorithm may be raw zlib, gzip or zip and is automatically detected. Additionally, any of those forms may be passed as a data URI. If a data URI is detected, its payload is extracted and used as argument in a second pass. The data for the decoding of KEGG IDs is downloaded from the KEGG site via an http connection and requires that the interpreter is allowed port 80 Internet access.

Similar to the ens create command, it is also possible to prefix the structure encoding, if it is a line notation or an encoding without line breaks, with smiles: smirks: or kegg: in order to explicitly name the encoding of these formats.

The only multi-line encoding recognized by this command are Lhasa Patran reaction patterns. They are automatically decoded in a form which makes them suitable for use in lhasa reaction processor objects. Reactions stored in uncompressed files must be read by means of a molfile read command.

Without setting a specific decoder mode in the following optional argument, the data string is decoded in the format-specific default mode (i.e. as standard SMILES strings for the SMILES family) and molecules with a complete hydrogen set are generated if the encoding supports such a distinction.

For Reaction SMILES variants, the explicit decoder modes smarts, hadd, nohadd, pattern or patran and transform can be requested. In smarts mode, full SMARTS or SMIRKS encodings are recognized, which are useful for reaction substructure searches or SMIRKS transforms. No implicit hydrogen is added in that mode. The nohadd mode does not supports SMARTS constructs, but no implicit hydrogens are instantiated either.The hadd mode adds a standard hydrogen set. The transform mode is similar to the smarts mode, but additionally hydrogen atoms encoded explicitly are not instantiated but rather translated into a hydrogen count query specification. This is useful for some classes of SMIRKS transforms. SMILES atom mapping specifications are allowed in all modes. The explicit pattern or patran modes should be used when decoding patran patterns - but then this is already the default for this type of data.

In case the argument is a Reaction SMILES variant and an agent in Daylight nomenclature is specified (the middle section between the >> characters), it is assigned the reaction role agent , which is rather unspecific. It may subsequently be changed by setting the E_REACTION_ROLE property of the agent ensemble.

Ensembles which are decoded from the arguments have normal handles and may be addressed via these just like ensembles which are not part of a reaction.

Examples:

set xhandle [reaction create C=O>Cc1ccccc1>CO]

ens set [reaction ens $xhandle agent] E_REACTION_ROLE solvent

set xhandle [reaction create {[C:1]=[O:2]>>[C:1][O:2]} smarts]

set xhandle [reaction create KEGG:RP09586]

A second reaction create command variant uses a set of ensemble handles as arguments and makes these ensembles members of the newly created reaction. The reaction role of the ensembles is determined by default by their position in the argument list. The first ensemble is the reagent , followed by product, solvent, catalyst, intermediate, impurity, byproduct, agent and waste in that order. It is possible to skip a role by providing an empty string as parameter placeholder. If necessary, ensembles are removed from an existing reaction and transferred to the new one, since an ensemble cannot be a member of more than one reaction at a time. In case the default order-dependent reaction role assignment is not convenient, any argument may be specified as a list of two components instead. In that notation, the first list element is the normal ensemble handle and the second the applicable role designator encoded as a string from above set.

Examples:

set xhandle [reaction create $reagent_ehandle [ens create CO] {} {[Pt]}]

This example creates a reaction from an existing reagent ensemble and then adds a product ensemble and platinum as catalyst . The solvent parameter position is skipped by entering an empty string.

Finally, it is possible to explicitly specify the role by not just providing an ensemble handle as parameter, but a list consisting of an ensemble handle and its reaction role.

Example:

set xhandle [reaction create [list $product_handle product] \ 

	[list [ens create {[Pt]} catalyst]]

reaction dataset

reaction dataset xhandle ?filterlist?

Return the dataset handle of the dataset the reaction is a member of. It the reaction is not member of a dataset, or does not pass all of the optional filters, an empty string is returned.

Example:

reaction dataset $xhandle

reaction defined

reaction defined xhandle property

This command checks whether a property is defined for the reaction. 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 reaction valid command is used for this purpose.

reaction delete

reaction delete all

reaction delete xhandlelist ?xhandlelist?...

Delete reactions and the ensembles which are part of the deleted reactions. The special parameter all may be used to delete all reactions currently registered in the application. Alternatively, any number of lists of reaction handles may be specified for specific reaction deletions.

The command returns the number of deleted reactions.

Example:

reaction delete $xhandle

reaction delete $xhandlelist1 $xhandlelist2

reaction dget

reaction dget xhandle propertylist ?filterset? ?parameterlist?

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

For examples, see the reaction get command. The difference between reaction get and reaction 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, reaction get and reaction dget are equivalent.

reaction dup

reaction dup xhandle ?dataset? ?position?

Duplicate the specified reaction and its ensembles. The return value is the new reaction handle. The duplicated reaction ensembles are also assigned unique handles.

The duplicate reaction is placed into the same dataset as the source, if that one is in a dataset. Specifying an explicitly empty dataset argument places the duplicate outside any dataset, regardless of the dataset membership of the source reaction.

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 reaction is inserted at the given position, starting with 0. If the requested position is larger than the current size of the dataset, the reaction is appended.

Example:

set xhdup [reaction dup $xhandle]

reaction ens

reaction ens xhandle ?filterlist?

Return a list of the handles of the ensembles which are a part of the reaction. Optionally, these ensembles may be filtered by a simple filter list.

Example:

reaction ens $xhandle metal

Find all ensembles in the reaction which contain one or more metal atoms.

reaction exists

reaction exists xhandle ?filterlist?

Check whether a reaction handle exists. The command returns 0 or 1. Optionally, the reaction may be filtered by a standard filter list. If filters in the filter list operate on ensembles, it is sufficient if a single ensemble of the reaction passes the filter.

Example:

reaction exists $xhandle solvent

Check whether the reaction with the handle in variable $xhandle exists and, if it exists, whether it contains a solvent ensemble.

reaction expand

reaction expand xhandle ?allowambigous? ?noimplicith?

This command expands all superatoms in the ensembles of the reaction. 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 all of the reaction ensembles instead a single atom.

Example:

reaction expand $xhandle

The command returns the total number of successfully expanded atoms in all reaction ensembles.

reaction expr

reaction expr xhandle expression

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

reaction filter

reaction filter xhandle filterlist

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

Example:

reaction filter [reaction create {C=C>[Pt]>CC}] platinum

checks whether the reaction involves a platinum atom in any role.1 If the filter operates on ensembles or minor objects, it is sufficient to have a single ensemble or ensemble minor object pass the filter condition.

reaction forget

reaction forget xhandle ?minor_obj_class?

This command is essentially the same as the ens forget command. It is applied to all ensembles in the reaction.

reaction get

reaction get xhandle propertylist ?filterset? ?parameterlist?

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

Examples:

reaction get $xhandle {X_IDENT X_NAME}

yields the ID and name of the reaction as a list. If the information is not available, an attempt is made to compute it. If the computation fails, an error results.

reaction get $xhandle {E_FORMULA E_WEIGHT}

reports the formula and molecular weight of all reaction ensembles. The result is delivered as a nested list. The first list contains the formulae, the second list contains the weights.

Currently, it is not possible to use filters with this command (and the other retrieval command variants) which are not operating directly on the reaction object, but on objects lower in the hierarchy such as ensembles or atoms.

For the use of the optional property parameter list argument, refer to the documentation of the ens get command.

Variants of the reaction get command are reaction new, reaction dget, reaction nget, reaction show, reaction sqldget, reaction sqlget, reaction sqlnew, and reaction sqlshow .

In addition to property data, a reaction object possesses a few attributes, which can be retrieved with the get command (but not its related sister subcommands like dget, sqlget, etc.). Some of them are also modifiable via reaction set. These attributes are:

• coords
  If the toolkit was compiled with factory support, these are the coordinates of the object icon on its workbench, encoded as integer pair. This attribute can be changed.
• deletable
  Flag indicating whether the reaction can be deleted with a standard reaction delete command. This attribute is read-only. Reactions which are, for example, property data values or a part of a molfile loop command cannot be deleted by standard means.
• failures
  If the property computation failure cache is active, return a list of all properties which have failed computation for this ensemble after the last structural change. This attribute is read-only.
• footer
  If the toolkit was compiled with factory support, this is the footer of the object icon on a workbench. This attribute can be changed.
• gflags
  If the toolkit was compiled with factory support, this is the currently set object icon rendering flag collection.
• header
  If the toolkit was compiled with factory support, this is the header of the object icon on a workbench. This attribute can be changed.
• hidden
  Flag indicating whether the reaction is hidden. This is not the same as the invisible state. This attribute is intended to be used for rendering selections. This attribute can be changed.
• incomplete
  Boolean status flag indicating an aborted input operation during the read of the structure from file, which returned the structure intact but without the complete set of associated data. An aborted input may be either be the result of an explicitly set input control flag, or by encountering property data which could not be decoded. This attribute is read-only.
• invisible
  Flag indicating whether the ensemble is invisible. This is not the same as the hidden state. An invisible object is no longer accessible via its handle. This is usually the case for objects which are scheduled for deletion, but still have lingering referring pointers. This attribute is read-only.
• modcount
  Reaction data modification count. This attribute is read-only.
• pyobject
  If the toolkit was compiled with Python support, this attribute reports the memory address of the Python wrapper class instance, if it exists. This attribute is read-only.
• pyrefcount
  If the toolkit was compiled with Python support, this attribute reports the reference count of the Python wrapper class instance, if it exists. This attribute is read-only.
• refcount
  If the Tcl interpreter is using native Cactvs objects instead of string-based major object handles and integer-based minor object labels to identify toolkit objects, this returns the number of Tcl object references active for this ensemble. This attribute is read-only.
• selected
  Flag indicating whether the reaction is selected. This attribute can be changed.
• tooltip
  If the toolkit was compiled with factory support, this is the tooltip of the object icon on a workbench. This attribute can be changed.
• uuid
  An automatically generated UUID globally identifying the object. This attribute is read-only, different for every reaction, and not dependent on its contents.
• x
  If the toolkit was compiled with factory support, this is the x coordinate of the object icon on its workbench. This attribute can be changed.
• y
  If the toolkit was compiled with factory support, this is the y coordinate of the object icon on its workbench.This attribute can be changed.

reaction getparam

reaction getparam xhandle property ?key? ?default?

Retrieve a named computation parameter from valid property data. If the key is not present in the parameter list, an empty string is returned. If the default argument is supplied, that value is returned in case the key is not found.

If the key parameter is omitted, a complete set of the parameters used for computation of the property value is returned in key/value format.

This command does not attempt to compute property data. If the specified property is not present, an error results.

Example:

reaction getparam $xhandle X_GIF format

returns the actual format of the image, which could be GIF , PNG , or various bitmap formats.

reaction hadd

reaction hadd xhandle ?filterset? ?flags? ?changeset?

Add a standard set of hydrogens to the ensembles of the reaction. 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 reaction 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 reaction 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 reaction 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 first suitable atom. The charge of the atom is increased and only a single hydrogen is added regardless of the standard number of missing hydrogens, and this command does issue the standard property invalidation event for atom and bond changes. In the reaction 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 reaction ensembles. All current atoms appear to be part of the original atom set.

Adding hydrogens with this command is less destructive to the property data set of the reaction ensembles than adding them with individual atom create/bond create commands, except in case the protonate flag is set, because many properties are designed to be indifferent to explicit hydrogen status changes, but are invalidated if the structure is changed in other ways.

If the effects of the hydrogen addition step to the validity of the property data set should not be handled according to this standard procedure, it is possible to explicitly generate additional property invalidation events by specifying an event list as the optional last parameter, for example a list of atom and bond to trigger both the atom change and bond change events.

The command returns the number of hydrogens which were added to all reaction ensembles.

Example:

set xhandle [reaction create {[C]=[C]>>[C]-[C]}]

reaction hadd $xhandle

adds a total of ten hydrogens to the two reaction ensembles, transforming them into hydrogen-complete ethene and ethane.

reaction hdup

reaction hdup xhandle ?dataset? ?position?

This command performs the same operation as the reaction dup command, but additionally adds a standard set of hydrogens to all ensembles of the duplicated reaction.

reaction hstrip

reaction hstrip ehandle ?flags? ?changeset?

This command removes hydrogens from all ensembles in the reactions. By default, all hydrogen atoms on the ensemble 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 reaction 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 hadd command are retained. Note that hydrogen addition commands can be run in a mode which does not leave information about automatic addition - hydrogens added this way will also 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 wedges from hydrogens if the result 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 the changeset parameter is used, all property change events listed in the parameter are triggered.

Hydrogen stripping is not as disruptive to the data content of the reaction ensembles as normal atom deletion, except in case the deprotonate flag is set. The system assumes that this operation is done as part of some file output or visualization preparation. However, if any new data is computed after stripping, the computation functions see the stripped structure, and proceed to work on that reduced structure without knowledge that there are implicit hydrogens.

The command returns the total number of hydrogens stripped from all reaction ensembles.

Example:

reaction hstrip $xhandle [list keeporiginal wedgetransfer]

reaction index

reaction index xhandle

Get the position of the reaction in the object list of its dataset. If the reaction is not member of a dataset, -1 is returned.

reaction list

reaction list ?filterlist?

This command returns a list of the reaction handles currently registered in the application. This list may optionally be filtered by a standard filter list. If the filter operates on the reaction ensembles and not on the reaction object, it is sufficient if a single reaction ensemble passes the filter.

Example:

reaction list solvent

lists the handles of all reactions in the application which contain a solvent ensemble.

reaction lock

reaction lock xhandle propertylist/reaction/all ?compute?

Lock property data of the reaction, meaning that it is no longer subject to the standard data consistency manager control. The data consistency manager deletes specific property data if anything is done to the reaction which would invalidate the information. Blocking the consistency manager can be useful when building reactions from components in a script. Property data remains locked until is it explicitly unlocked.

The property data to lock can be selected by providing a list of the following identifiers:

• Property names
  Valid property instances on the reaction, reaction ensembles, or ensemble minor objects are locked. If the boolean compute flag is set, an attempt is made to compute the property if it is not yet present. Otherwise, a request to lock non-existent data is silently ignored. It is not possible to lock individual property fields.
• all
  All valid reaction properties are locked. Ensemble properties and ensemble minor object properties are not affected. The compute flag is ignored.
• reaction
  This is an object class identifier. All property data which is controlled by the reaction major object and attached to the specified object class is locked. Since reactions do not contain minor objects, this identifier is equivalent to all .

The lock can be released by a reaction unlock command.

Example:

set xhandle [reaction create {C=C>[Pt]>CC}]

reaction lock $xhandle X_GIF 1

reaction clear $xhandle agent

reaction unlock $xhandle X_GIF

In this example, first a reaction depiction in property data X_GIF is generated and locked. After that, the reaction and reaction ensembles can be manipulated without losing the image data. The agent is removed in the next step - but the X_GIF image which shows the catalyst and which normally would have been deleted when the agent is removed is kept. Finally, the image property data is put back under the standard control of the data consistency manager.

reaction max

reaction max xhandle propertylist ?filterset?

Get the maximum values of the properties named in the propertylist parameter. The return value of the command is a list of the maximum property values. While it is possible to work with reaction properties, this is pointless since there is only a single instance of a reaction property per reaction. Usually, ensemble or ensemble minor object properties are retrieved. The objects whose property values are used for the determination of the maximum values may optionally be filtered by a standard filter set.

Example:

reaction max $xhandle E_WEIGHT {1 reagent product}

computes the maximum molecular weight from the reagent and product ensembles, ignoring other reaction ensembles such as solvents or catalysts.

reaction metadata

reaction metadata xhandle property field ?value?

Obtain property metadata information, or set it. The handling of property metadata is explained in more detail in its own introductory section. The related commands reaction setparam and reaction getparam can be used for convenient manipulation of specific keys in the computation parameter field. Metadata can only be read from or set on valid property data.

Examples:

array set gifparams [reaction metadata $xhandle X_GIF parameters]

reaction metadata $xhandle X_CONDITIONS comment “Check with legal dept whether oxidation in molten Pu metal requires regulatory approval”

The first line retrieves the computation parameters of the property X_GIF as keyword/value pairs. These are read into the array variable gifparams , and may subsequently be accessed as $gifparams(format) , $gifparams(height) , etc. The second example shows how to attach a comment to a property value.

reaction min

reaction min xhandle propertylist ?filterset?

Get the minimum values of the properties named in the propertylist parameter. The return value of the command is a list of the minimum property values. While it is possible to work with reaction properties, this is pointless since there is only a single instance of a reaction property per reaction. Usually, ensemble or ensemble minor object properties are retrieved. The objects whose property values are used for the determination of the minimum values may optionally be filtered by a standard filter set.

Example:

reaction min $xhandle E_WEIGHT {1 reagent product}

computes the minimum molecular weight from the reagent and product ensembles, ignoring other reaction ensembles such as solvents or catalysts.

reaction move

reaction move xhandle ?datasethandle|remotehandle? ?position?

Make a reaction a member of a dataset, or remove it from a dataset. If the dataset handle parameter is omitted, or an empty string, the reaction is removed from its current dataset. If it was not a dataset member, this command does nothing. The dataset handle may be the name of a remote dataset for moving reactions over a network connection.

If a dataset handle is specified, the reaction is added to the dataset, and removed from any dataset it was member of before the execution of the command. By default the reaction is added to the end of the dataset object list, but he final optional parameter allows the specification of an object list index. The first position is index zero. If the parameter value end is used, or the index is bigger than the current number of dataset objects minus one, the reaction is appended as by the default. It is legal to use this command for moving reactions within the same dataset.

Another special position value is random . This value moves to the reaction to a random position in the dataset. Using this mode with remote datasets is currently not supported.

The dataset handle cannot be a transient dataset.

The return value of the command is the dataset membership of the reaction prior to the move. It is either a dataset handle, or an empty string if it was not member of a dataset.

Examples:

reaction move $xhandle $dhandle 0

reaction move $xhandle

In the first sample line, the reaction is inserted as the first element in a dataset. The second line reverts this operation and removes the reaction from the dataset.

This command can be used with a remote dataset descriptor. In that case, the reaction is packed into a serialized object representation, transmitted over the network and restored as member of the remote dataset at the specified position. The local reaction is deleted if the transfer succeeds.

reaction mutex

reaction mutex xhandle mode

Manipulate the object mutex. During the execution of a script command, the mutex of the major object(s) associated with the command are automatically locked and unlocked, so that the operation of the command is thread-safe. This applies to builds that support multi-threading, either by allowing multiple parallel script interpreters in separate threads or by supporting helper threads for the acceleration of command execution or background information processing.

This command locks major objects for a period of time that exceeds a single command. A lock on the object can only be released from the same interpreter thread that set the lock. Any other threaded interpreters, or auxiliary threads, block until a mutex release command has been executed when accessing a locked command object. This command supports the following modes::

• lock
  Increase the recursive mutex lock count on the object. The command returns the current lock count after the command, excluding the transient single-command lock.
• reset
  Release all persistent locks on the object, if they exist.
• test
  Return the current persistent lock count on the object. This excludes the transient per-command lock.
• unlock
  Decrease the recursive lock count on the object. The command returns the current lock count after the command, excluding the transient single-command lock. Unlocking an object which has not been persistently locked results in an error.

There is no trylock command variant because the command already needs to be able to acquire a transient object mutex lock for its execution.

reaction need

reaction need xhandle propertylist ?mode?

Standard command for the computation of property data, without immediate retrieval of results. This command is explained in more detail in the section about retrieving property data.

The return value is the reaction handle.

Example:

reaction need $xhandle E_WEIGHT recalc

reaction new

reaction new xhandle propertylist ?filterset? ?parameterlist?

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

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

reaction nget

reaction nget xhandle propertylist ?filterset? ?parameterlist?

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

For examples, see the reaction get command. The difference between reaction get and reaction nget is that the latter always returns numeric data, even if symbolic names for the values are available.

reaction nitrostyle

reaction nitrostyle xhandle style

Change the internal encoding of nitro groups and similar functional groups in the ensembles of the reaction. Possible values for the style parameter are:

• asis No change
• ionic Change to encoding to a positive charge on the center atom, and a negative on one of the oxygens
• xionic As above, but also change the encoding of azides, etc.
• neutral Change the encoding to the neutral form with extended valence. pentavalent is an alias.
• xneutral As above, but also change the encoding of azides, etc.

The command returns the reaction handle.

reaction pack

reaction pack xhandle ?maxsize? ?request_propertylist? ?suppress_propertylist?

Pack the reaction object 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. The reaction ensembles and their property data are part of the dump. Further object relationships, such as datasets the reaction or reaction ensembles might be a member in, or table associations are not saved.

The maximum size of the object string (default -1, meaning unlimited size) 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 other 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 reaction.

Reactions can be restored from a packed object string by the reaction unpack command.

The reaction object and its ensembles remain in existence after using this command.

Example:

set dbstring [reaction pack [reaction create CC=O>>CCO]]

reaction properties

reaction properties xhandle ?pattern? ?intersectmode?

Get a list of valid properties of the reaction proper and the reaction ensembles. By default, reaction properties (prefix X_ ), dataset properties (prefix D_ ), as well as the properties of the ensembles in the reaction (prefix E_ ) and the properties of their minor objects (atoms, bonds, etc.) are listed.

Property subsets may be selected by a non-empty filter pattern. In case of reaction ensemble or minor ensemble object properties which are not present in all reaction ensembles, the default intersect mode is union , meaning that all properties are reported for which at least one instance exists. The alternative mode intersect only lists those ensemble properties which are present in all reaction ensembles.

This command may also be invoked as reaction props .

Example:

reaction properties $xhandle X_*

reaction props $xhandle E_* intersect

The first example returns a list of the currently valid reaction properties. The second example lists all reaction properties which are present in all reaction ensembles.

reaction purge

reaction purge xhandle propertylist/reaction/specialname ?emptyonly?

Delete property data from the reaction. The properties may be reaction properties (prefix X_ ), dataset properties (prefix D_ ) or properties of the reaction ensembles, such as ensemble or atom properties. If a property marked for deletion is not present on an object, it is silently ignored. If the reaction is not a dataset member, a request for the deletion of dataset properties is also ignored. If the object class name reaction is used instead of a specific property name, all reaction property data ( X_ prefix) is deleted from the reaction.

Besides normal property and class names, a few convenient special names for common property deletion tasks on the ensembles of the reaction are defined and can be used as a replacement for the property list. These include:

• atomstereochemistry
  Delete all atomic atom stereo descriptors, but keep those for bonds.
• bondstereochemistry
  Delete all bond stereo descriptors, but keep those for atoms.
• isotopes
  Delete isotope information in A_ISOTOPE and other isotope properties which may be defined in future software versions.
• radicals
  Delete atomic radical information in A_RADICAL and other radical-related properties which may be defined in future software versions.
• stereochemistry
  Delete all stereochemistry descriptors, including 2D wedges, but not 3D coordinates. The implicit property list includes A_LABEL _STEREO, B_LABEL_STEREO, A_CIP_STEREO, B_CIP_STEREO, A_DL_STEREO, B_CISTRANS_STEREO, A_HASH_STEREO, B_HASH_STEREO , A_MAP_STEREO , B_MAP_STEREO , A_STEREOINFO , B_STEREOINFO , A_STEREO_GROUP , M_STEREO_COUNT , E_STEREO_COUNT and B_FLAGS (only selected bits, the property remains valid if present).
• wedges
  Delete wedge bond flags in property B_FLAGS . If B_FLAGS is not present, the command is ignored and no computation attempt is made.

The optional boolean flag emptyonly can be used to to restrict the deletion to those properties where all the values for a property associated with a major object (such as on all atoms in an ensemble for atom properties, or just the single ensemble property value for ensemble properties) are set to the default property value.

Examples:

reaction purge $xhandle X_IDENT

reaction purge $xhandle E_IDENT 1

The first example deletes the property data X_IDENT for the selected reaction if it is present. The second example deletes property E_IDENT from all ensembles in the reaction if the property value on that ensemble is equal to the default value for E_IDENT .

reaction remove

reaction remove xhandle ?enslist?...

Remove the ensembles in the ensemble lists from the reaction. If an ensemble from the list is not part of the reaction, it is ignored. Removed ensembles are not destroyed and remain accessible via their handles.

The command returns the number of removed ensembles.

Examples:

reaction remove $xhandle $ehandle

reaction remove $xhandle [reaction ens $xhandle]

The first example removes the ensemble from the reaction if it is part of the reaction. The second example removes all ensembles from the reaction - this is essentially the same as reaction clear .

reaction rename

reaction rename xhandle srcproperty dstproperty

This is a variant of the reaction assign command. Please refer the command description in that paragraph.

reaction reorder

reaction reorder xhandle 

Sort the ensembles in the reaction into standard sequence ( reagent/product/solvent/catalyst/ intermediate/impurity/byproduct/agent/waste ). In addition, empty reagent and product (but not solvent , etc.) ensembles are automatically created in the reaction in case they are not present.

The command returns the ensemble handle.

reaction scan

reaction scan xhandle expression ?mode? ?parameters?

Perform a query on the reaction object. The syntax of the query expression and the optional selection list is the same as that of the dataset scan command with a transient dataset consisting of the current reaction only. For more details, please refer to the paragraphs on dataset scan and molfile scan .

The return value depends on the mode. The default query mode, different from the default in dataset scan , is exists .

In case the query contains ensemble structure match conditions which are not part of a reaction query, or there are ensemble data retrieval specifications, these are tested on and applied to the reagent ensemble of the reaction. Reactions which do not possess a reagent ensemble (half reactions, etc.) are ignored.

reaction set

reaction set xhandle property value ?property value?...

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

Examples:

reaction set $xhandle X_NAME “New multi-component reaction”

reaction set $xhandle E_IDENT “X-124”

The first line is a simple set operation for a reaction property. The second line shows how to set properties of multiple ensembles in one step. The same property value is assigned to all ensembles.

reaction setparam

reaction setparam xhandle property key value ?key value?...

Set or update a property computation parameter in the metadata parameter list of a valid property. This command is described in the section about retrieving property data. The current settings of the computation parameters in the property definition are not changed.

Example:

reaction setparam $xhandle X_GIF comment “Top Secret”

reaction show

reaction show xhandle propertylist ?filterset? ?parameterlist?

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

For examples, see the reaction get command. The difference between reaction get and reaction 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, reaction get and reaction show are equivalent.

reaction sort

reaction sort xhandle ?sort_property? ?relabel? ?duplicate? ?datasethandle? ?position?

This command applies the ens sort command to all reaction ensembles. Please refer to the descriptors of the ens sort command for an explanation of the parameters.

The command returns the reaction handle.

reaction split

reaction split xhandle ?dropsize? ?splitproperty?

Split the molecules of the ensembles in the reaction into individual ensembles. The return value is a list of all ensemble handles in the reaction after the operation, similar to the output of a reaction ens command. The initial reaction ensembles are modified, and their old handles may be reused as one of the new single-molecule ensemble handles. If an input ensemble contains only a single molecule, and that molecule passes the optional size filter, the command is a no-op for that ensemble. All result ensembles remain members of the reaction.

The optional dropsize parameter is a minimum for the number of atoms in any of the molecules. If this is not an empty string, molecules which have less atoms than the minimum are deleted from all reaction ensembles. If all molecules in a reaction ensemble are smaller than the required size, the ensemble is destroyed.

The optional split property argument can be used to spit an ensemble on values of a molecule property, which needs to be either already set or computable, instead of simply separating fragments on connectivity. All molecules in an input ensemble which have a common value of this property are put into a joint result ensemble, and each distinct property value starts a new result ensemble. Molecules with a common property value do not need to be present in the input ensemble in a consecutive sequence, nor are there any special requirements for the data type or value range of the split property, as long as the data type has a comparison function. If the values of the split property are distinct over all molecules in an input ensemble, the outcome of command is indistinguishable from running it without any split property.

Comparison of property values is performed separately within every reaction ensemble, not across the complete ensemble set in the reaction.

reaction sqldget

reaction sqldget xhandle propertylist ?filterset? ?parameterlist?

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

For examples, see the reaction get command. The differences between reaction get and reaction sqldget are that the latter does not attempt computation of property data, but initializes the property value to the default and returns that default, if the data is not present and valid; and that the SQL command variant formats the data as SQL values rather than for Tcl script processing.

reaction sqlget

reaction sqlget xhandle propertylist ?filterset? ?parameterlist?

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

For examples, see the reaction get command. The difference between r eaction get and reaction sqlget is that the SQL command variant formats the data as SQL values rather than for Tcl script processing.

reaction sqlnew

reaction sqlnew xhandle propertylist ?filterset? ?parameterlist?

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

For examples, see the reaction get command. The differences between reaction get and reaction sqlnew are that the latter forces re-computation of the property data, and that the SQL command variant formats the data as SQL values rather than for Tcl script processing.

reaction sqlshow

reaction sqlshow xhandle propertylist ?filterset? ?parameterlist?

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

For examples, see the reaction get command. The differences between reaction get and reaction sqlshow are that the latter does not attempt computation of property data, but raises an error if the data is not present and valid, and that the SQL command variant formats the data as SQL values rather than for Tcl script processing.

reaction subcommands

reaction subcommands

Lists all subcommands of the reaction command. Note that this command does not require a reaction handle.

reaction swapin

reaction swapin xhandle

Swap a reaction from the disk store fully back to memory, and disable further automatic loading and shelving. If the reaction was not swapped out, the command does nothing.

The command returns the reaction handle.

reaction swapout

reaction swapout xhandle

Release most of the reaction data from memory and store it in a temporary disk store. The reaction handle remains valid. As soon as it is used in a command again after this command has been executed, the swapped reaction data is automatically reloaded from file, and then stored again when the object lock is released. To disable the automatic swapping of a reaction, use the reaction swapin command.

This command is intended to be used in cases where a large number of reactions must be kept in memory. Its use is not generally encouraged - it is only useful in case the programmer knows about access patterns. In other cases, the standard virtual memory mechanism of the operating system might yield better performance results.

The reactions are stored as binary blobs in a key/value store in a process-specific swap directory cactvs%d , ( %d is replaced by the process ID) which is created automatically in the standard temporary directory. When a reaction is deleted, its swap record is also removed, if one was created during the lifetime of the reaction. When a Cactvs application program exits, the swap store as well as the swap directory are automatically deleted, even without explicit deletion of the last set of reactions in memory. In case of program crashes, the swap directory and its contents may however survive. If reaction swapping is used with unstable applications, the temporary directory should be checked from time to time.

The command returns the reaction handle.

Example:

rection swapout $xhandle

reaction tables

reaction tables ehandle ?filterlist?

Return a list of the handles of all table objects the reaction is associated with. Optionally, the table set may be filtered by a simple filter list. If the reaction is not related to any table, or none of these tables passes the filter list, an empty string is returned.

This command is only available if the toolkit was compiled with table support.

Example:

reaction tables $xhandle

reaction taint

reaction taint xhandle propertylist/changeset ?purge?

Trigger a property data tainting event which acts on the reaction data, and the data of all ensembles in the reaction. If the reaction is a member of a dataset, or its ensembles are, the dataset and its objects are not tainted.

The command arguments are the same as for the ens taint command and explained there.

reaction transfer

reaction transfer xhandle target_xhandle propertylist

Move property data from one reaction to another, without going through an intermediate scripting language object representation. If the property is not already valid on the source ensemble, an attempt is made to compute it.

If the property is not a reaction property, but an ensemble property, or a property of ensemble minor objects, the property data is transfered between all ensemble pairs in the two reactions which serve the same reaction role (reagent, product, etc). The order of these ensembles in their reactions is arbitrary. Further processing of the data in each ensemble pair is then performed as in an ens transfer command. Please refer to the documentation of that command for additional information.

The return value of the command is the target reaction handle.

Examples:

reaction transfer $xh $xh2 X_IDENT

reaction transfer $xh $xh2 A_MAPPING

The first example is a simple data copy. The second example transfers atom property A_MAPPING between the reagent and product ensembles of the reaction, and any other reaction ensemble where the property is valid, and a pair of ensembles with the same reaction role can be found. The order of the atoms in an ensemble pair is not required to be identical - property A_LABEL is used to identify corresponding atoms.

reaction trim

reaction trim xhandle ?propertylist?

Reduce the information content of a reaction to a standard minimum set and discard any additional information. This process minimizes the storage requirements of the reaction. The properties of the minimum set are computed if required. The retained property set is designed to support a faithful representation of the connectivity of the reaction ensembles including bond and atom labels and types as well as formal charges, stereochemistry, isotopes and atom mapping information, but not of any 2D or 3D coordinates or auxiliary additional attributes of atoms, bonds or other chemical objects or the reaction object proper.

The optional fourth argument is a list of properties which should be retained in addition to the standard set. If any of these are not present on the reaction (or its ensembles) that is to be trimmed, they are silently ignored and no attempt is made to compute them. Specifying properties of the standard retention set in this list is allowed but has no additional effect.

The return value of the command is a list of the remaining properties of the reaction and the reaction ensembles. The properties of the latter are reported as the union of the properties of the individual reaction ensembles (see reaction props command).

Example:

reaction trim $xhandle {X_SMILES E_NAME X_NAME}

reaction unlock

reaction unlock xhandle propertylist/reaction/all

Unlock property data for the reaction, meaning that they are again under the control of the standard data consistency manager.

The property data to unlock can be selected by providing a list of the following identifiers:

• Property names
  Valid property instances on the reaction, reaction ensembles, or ensemble minor objects are unlocked. Non-existent data is silently ignored. It is not possible to unlock individual property fields.
• all
  All valid reaction properties are unlocked. Ensemble properties and ensemble minor object properties are not affected.
• reaction
  This is an object class identifier. All property data which is controlled by the reaction major object and attached to the specified object class is unlocked. Since reactions do not contain minor objects, this identifier is equivalent to all .

Property data locks are obtained by the reaction lock command.

Example:

set xhandle [reaction create {C=C>[Pt]>CC}]

reaction lock $xhandle X_GIF 1

reaction clear $xhandle agent

reaction unlock $xhandle X_GIF

In this example, first a reaction depiction in property data X_GIF is generated and locked. After that, the reaction and reaction ensembles can be manipulated without losing the image data. The agent is removed in the next step - but the X_GIF image which shows the catalyst and which normally would have been deleted when the agent is removed is kept. Finally, the image property data is put back under the standard control of the data consistency manager.

reaction unpack

reaction unpack packstring

Unpack a base64-encoded serialized object string which was created by a reaction pack command. The return value of this function is the handle of the newly created reaction object, which is an exact duplicate of the packed original reaction.

Reactions may also be unpacked by a reaction create command.

Example:

set packdata [reaction pack [reaction create C=O>>CO]]

set xhandle [reaction unpack $packdata]

reaction valid

reaction valid xhandle propertylist

Returns a list of boolean values indicating whether values for the named properties are currently set for the reaction. No attempt at computation is made.

Example:

reaction valid $xhandle X_IDENT

reports whether the reaction has a standard ID (has a valid X_IDENT property) or not.

reaction weed

reaction weed xhandle keywords

This command performs standard clean-up operations on all ensembles in the reaction. The supported operations are described in more detail in the section on the equivalent ens weed command.

The return value of this command is the reaction handle.