reaction get $xhandle X_IDENT

reaction add

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

reaction add xhandle ?ehandle?...

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

x.add(?ReactionSMILES/SMIRKS/BASE64Blob?,?decodermode?)

x.add(eref,...)

x.add((eref,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?...

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

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

reaction append $xhandle X_NAME “_new”

reaction assign

reaction assign xhandle srcproperty dstproperty

x.assign(srcproperty=,dstproperty=)

Assign property data to another property on the same reaction. Both properties must be associated with the reaction object class. This process is more efficient than going through a pair of reaction get/reaction set commands, because in most cases no string or Tcl/Python script object representations of the property data need to be created.

Both source and destination properties may be addressed with field specifications. A data conversion path must exist between the data types of the involved properties. If any data conversion fails, the command fails. For example, it is possible to assign a string property to a numeric property - but only if all property values can be successfully converted to that numeric type. The reverse example case always succeeds, out-of-memory errors and similar global events excluded.

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.

The command returns the original object handle for Tcl , or object reference for Python .

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?

x.cast(objectclass=,?properties=?)

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 or reference of the new object, or the input object handle or reference in case of mode reaction .

reaction clear

reaction clear xhandle ?role? ?deleteensembles?

x.clear(?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

x.copy(xref_dst)

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 or reference of destination reaction. It is allowed to copy a reaction onto itself.

reaction create

reaction create	?RxnSMILES/SMIRKS/RInChI/BASE64Blob/KEGGID/patran/RxnMinimol/HexRxnMinimol? 	?decodermode?

reaction create ?ehandle?...

reaction create ?{ehandle role}?...

Reaction(?RxnSMILES/SMIRKS/RInchI/BASE64Blob/KEGGID/patran/RxnMinimol/HexRxnMinimol?,?decodermode?)

Reaction(eref,...)

Reaction((eref,role),...)

Reaction.Create(RxnSMILES/SMIRKS/RInchI/BASE64Blob/KEGGID/patran/RxnMinimol/HexRxnMinimol,?decodermode?)

Reaction.Create(eref,...)

Reaction.Create((eref,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 or reference.

Example:

set xhandle [reaction create]

The first command variant is intended for creating a reaction with data is the use of a single-argument line notation. The supported line notations include Reaction SMILES or SMIRKS , RInChI strings, hex-encoded versions thereof, a KEGG reaction identifier in the form RPxxxxx, a Cactvs base64-encoded serialized reaction object string (see reaction pack ), a raw reaction Minimol byte blob (computed as property X_MINIMOL ), a hex-encoded form thereof, 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: rinchi: 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 (alias smirks ) , strictsmarts (alias strictsmirks ) , hadd, nohadd, transform or pattern (alias patran ) can be requested. In smarts or strictsmarts mode, full SMARTS or SMIRKS encodings are recognized, which are useful for reaction substructure searches or SMIRKS transforms. The difference between smarts and strictsmarts is that the latter enforces aliphaticity checks (see ens create ). No implicit hydrogen is added in that mode. For special purposes, there is also a strictatomsmirks / strictatomsmarts mode, which enforces strict rules only for atom matching, but not bond matching. The nohadd mode does not supports SMARTS constructs, but neither are implicit hydrogens are instantiated.The hadd mode adds a standard hydrogen set. In order to force a full hydrogen addition to the raw decoded reaction even if it would not be done otherwise, use the mode forcehadd . 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 or an RInChI string, 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.

If the argument of the command is a single ensemble handle or reference, and this ensemble possesses valid A_CGR_CHANGE and B_CGR_CHANGE properties indicating that it is a condensed graph representation of a reaction (property X_CGR ), the CGR representation is expanded and the new reaction consists of two newly created reagent and product ensembles. The original input structure remains unchanged, and does not become a reaction member ensemble.

Ensembles which are decoded from the arguments have normal object handles or references 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]} smirks]

set xhandle [reaction create KEGG:RP09586]

set xhandle [reaction create [list C1CCCCC1 reagent] [list c1ccccc1 product]]

The 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 (or None in Python ) as argument 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 sequence of two components instead. In that notation, the first list element is the normal ensemble handle or reference 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?

x.dataset(?filters=?)

Return the dataset handle or reference 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 or None for Python is returned.

Example:

reaction dataset $xhandle

reaction defined

reaction defined xhandle property

x.defined(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?...

x.delete()

Reaction.Delete(“all”)

Reaction.Delete(?xrefsequence/xref/xhandle?,...)

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. If a reaction is part of a linked reaction network, the reaction is removed from the network, but the network continues to exist as long as there are other linked reactions in it.

The command returns the number of deleted reactions.

Example:

reaction delete $xhandle

reaction delete $xhandlelist1 $xhandlelist2

reaction dget

reaction dget xhandle propertylist ?filterset? ?parameterdict?

x.dget(property=,?filters=?,?parameters=?)

Reaction.Dget(data,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 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.

The Python class method is a one-shot command. The transient ensemble created from the initialization items is automatically deleted when the command finishes. The data for the creation of the temporary ensemble is equivalent to the first argument of the standard constructor. Additional constructor parameters cannot be used.

reaction dup

reaction dup xhandle ?dataset? ?position?

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

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

The duplicate ensemble is placed into the same dataset as the source, if it is a member of a dataset. Specifying an explicitly empty dataset argument (including None for Python ) places the duplicate outside any dataset, regardless of the dataset membership of the source ensemble.

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.

The reaction hdup command is a variant of this command. It automatically adds a hydrogen set to the duplicate.

If the reaction is part of a linked reaction network, the network is not duplicated. The new reaction is not linked to any other reactions. You can use the xdup command variant for this purpose.

Example:

set xdup [reaction dup $xhandle]

reaction ens

reaction ens xhandle ?filterlist?

x.ens(?filters=?)

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?

x.exists(?filters=?)

Reaction.Exists(xref=,?filters=?)

Check whether a reaction handle is valid. The command returns boolean 0 or 1. Optionally, the reaction may be filtered by a standard filter list, and if it does not pass the filter, it is reported as not valid. 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?

x.expand(?allowambiguous=?,?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

x.expr(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

x.filter(filters)

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 ?objclass?

x.forget(?objectclass=?)

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

The command returns the original ensemble handle or reference.

reaction get

reaction get xhandle propertylist ?filterset? ?parameterdict?

reaction get xhandle attribute

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

x.get(attribute)

x[property/attribute]

x.property/attribute

Reaction.Get(data,property=,?filters=?,?parameters=?)

Reaction.Get(data,attribute)

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

Instead of using a property name or a reaction attribute, it is also possible to use any valid value of property E_REACTION_ROLE to directly access specific ensembles of the reaction. The allowed values are dynamically read from the property definition and thus customizable.

Example:

set ehp [reaction get $xh product]

set ehp [reaction ens $xh product]

These commands yield the same results, but the first directly tests the values of E_REACTION_ROLE of the reaction ensembles, while the second one uses the predefined product filter.

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

In addition to property data and reaction role selectors, a reaction object possesses a few attributes, which can be retrieved with the get command (but not by 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 object can be deleted with a standard reaction delete command. This attribute is read-only. Objects 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 object 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 object 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 object 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 object 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 pointer references. This attribute is read-only.
• javaobject
  If the toolkit was compiled with JNI support, this attribute reports the memory address of the JNI wrapper class instance, if it exists.
• loopitem
  A read-only attribute returning the handle of the currently active iterator item.
• modcount
  Object data modification count. This attribute is read-only.
• mutexcount
  The number of recursive mutex locks held for this object. Only supported on Linux.
• 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.
• record
  The current iterator record (starting with 1) of the reaction. It is possible to set the value and thus skip or revisit reaction ensembles in the iterator.
• 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.
• scoped
  A boolean object visibility control flag. If set, and global control flag ::cactvs(object_scope) is also set, the object is visible only in the Tcl interpreter which set the scope flag and thus claimed it. Object list commands executed in other interpreters omit this object, and attempts to decode its handle in other interpreters will fail. The most common use of this feature is the hiding of persistent chemistry objects in scripted property computation functions.
• selected
  Flag indicating whether the object 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 object, 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?

x.getparam(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 ( None for Python ). 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 dictionary 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?

x.hadd(?filters=?,?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?

x.hdup(?target=?,?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 hierarchy

reaction hierarchy xhandle ?filterlist? ?root?

x.hierarchy(?filters=?,?root=?)

Return the hierarchy handle or reference of the hierarchy the reaction is part of. If the reaction is not member of a hierarchy, or does not pass all of the optional filters, an empty string or None for Python is returned. By default, the hierarchy object which directly contains the reaction is returned. If the root flag is set, the root hierarchy object is reported instead, which is the same only if the hierarchy has only a single level.

Example:

reaction hierarchy $xhandle

reaction hstrip

reaction hstrip xhandle ?flags? ?changeset?

x.hstrip(?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 hydrogenate

reaction hydrogenate xhandle ?filterset? ?changeset?

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

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

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

The command returns the number of added hydrogens.

reaction index

reaction index xhandle

x.index()

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 jget

reaction jget xhandle propertylist ?filterset? ?parameterdict?

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

Reaction.Jget(data,property=,?filters=?,?parameters=?)

This is a variant of reaction get which returns the result data as a JSON formatted string instead of Tcl or Python interpreter objects. The command is usable only for property data, not attribute retrieval.

reaction jnew

reaction jnew xhandle propertylist ?filterset? ?parameterdict?

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

Reaction.Jnew(data,property=,?filters=?,?parameters=?)

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

reaction jshow

reaction jshow xhandle propertylist ?filterset? ?parameterdict?

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

Reaction.Jshow(data,property=,?filters=?,?parameters=?)

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

reaction ldup

reaction ldup ?xhandlelist?...

Reaction.Ldup(?exref/xrefsequence?,...)

Duplicate all reactions in the argument list(s) in default mode.

The return value is a single list (even if multiple source lists are used) of the duplicated reaction handles or references. If an argument list element is an empty string (or None for Python ), it indicates a missing object, and the output list also receives an empty string element (for Tcl ) or None (for Python ) at its position, without raising an error.

reaction lhdup

reaction lhdup ?xhandlelist?...

Reaction.Lhdup(?xref/xrefsequence?,...)

Duplicate all reaction in the argument list(s) in default mode, and add hydrogens.

The return value is a single list (even if multiple source lists are used) of the duplicated reaction handles or references. If an argument list element is an empty string (or None for Python ), it indicates a missing object, and the output list also receives an empty string element (for Tcl ) or None (for Python ) at its position, without raising an error.

reaction link

reaction link xhandle ?xhandle?...

x.link(?xhandle/xref?,...)

Link the reaction to any number of additional reactions, creating a reaction network in the process. Duplicate links, or links to reactions which already exist are ignored. A reaction cannot link to itself.

The command returns the number of newly created reaction links.

reaction links

reaction links xhandle ?filterlist? ?recursive?

x.links(?filters=?,?recursive=?)

Return the set of reactions this reaction is linked to as a list of reaction handles or reaction references. The set may optionally be filtered by standard reaction-level filter conditions. If the recursive boolean flag is set linked reactions beyond the first neighbor sphere are also included, with duplicates of reactions in closer spheres removed.

reaction list

reaction list ?filterlist?

Reaction.List(?filters=?)

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?

x.lock(property=,?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.

The return value is the original reaction handle or reference.

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 loop

reaction loop xhandle objvar ?maxrec? ?offset? body

x.loop(function=,?maxloop=?,?offset=?,?variable=?)

for e in x:

Loop over the ensembles in a reaction. This command is similar to molfile loop . On each iteration, the variable is set to the handle of the current member object, and then the body code is executed. The loop object is an original ensemble, not a duplicate.

Ensembles should not be removed from the reaction during the loop.

If a maximum record count is set, the loop terminates after the specified number of iterations. If the maximum record argument is set to an empty string, a negative value, or all , the loop covers all reaction elements. This is also the default. The return value is the number of calls to the body code block.

For Tcl scripts, within the loop, the standard Tcl break and continue commands work as expected. If the body script generates an error, the loop is exited.

If no offset is specified, the loop starts at the first element. Within the loop body, the reaction attribute record is continuously updated to indicate the current loop position. Its value starts with one, like file records in the molfile loop command.

The Python version of the loop method does intentionally have a different argument sequence for convenience. The function argument may either be a multi-line string (similar to the Tcl construct), or a function reference. Functions are called with the reference of the current loop ensemble as single argument, and have their own context frame, so that the specification of a reference variable is not generally useful in that call style, though is is allowed. For string function blocks the code is executed in the local call frame, and the variable with the current object reference is visible locally. Script code blocks must be written with an initial indentation level of zero. Within the Python functions, the normal break and continue loop control commands cannot be used to to scope limitations. Instead, the custom exceptions BreakLoop and ContinueLoop can be raised. These are automatically caught and processed in the loop body handler code.

In Python , there is also an object iterator so that simple loops over reaction ensemble can be written with a for statement. The reaction object iterator is of the self style (i.e. there is one per reaction, these are not independent objects), so nesting them is not possible on the same reaction.

Python object loop constructs and their peculiarities are discussed in more detail in the general chapter on Python scripting.

Example:

reaction loop $xh eh {

	puts „[ens get $eh E_REACTION_ROLE] at position[reaction get $xh record]“

}

reaction max

reaction max xhandle propertylist ?filterset?

x.max(property=,?filters=?)

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 merge

reaction merge xhandle ?xhandle?...

x.merge(?xhandle?,...)

Merge individual reactions into a multi-step reaction with intermediates. The current product ensemble of the target reaction object (first reaction handle in Tcl ) gets reassigned as intermediate in E_REACTION_ROLE . Next, for every merged reaction, its intermediates and then the product are duplicated and appended to the target reaction. The merged source reactions remain unchanged. No check is performed that the original target reaction product ensemble and the reagent ensemble of a merged reaction are compatible.

If the merge reactions are specified, the command does nothing. It is not possible to merge a reaction with itself.

The command result is the target ensemble handle or reference.

Example:

set xh1 [reaction create CCO>>C=C]
set xh2 [reaction create C=C.ClCl>>ClCCCl]
reaction merge $xh1 $xh2

The result is a reaction with ethanol as reagent, ethene as intermediate, and dichloroethane as product. The explicit chlorine reagent of the second reaction is not represented in the result.

reaction metadata

reaction metadata xhandle property ?field ?value??

x.metadata(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.

Valid field names are bounds , comment , info , flags , parameters and unit .

Examples:

array set gifparams [reaction metadata $xhandle X_GIF parameters]

reaction metadata $xhandle X_CONDITIONS comment “Check with legal dept whether dehydration in molten Pu metal requires special 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?

x.min(propery=,?filters=?)

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?

x.move(?target=?,?position=?)

Make the reaction a member of a dataset, or remove it from a dataset. If the dataset handle or reference parameter is omitted, or is an empty string, or None for Python , the object is removed from its current dataset. The dataset handle or reference may be the name of a remote dataset for moving objects over a network connection.

If a target dataset handle or reference is specified, the object is added to the dataset, if allowed by the acceptance bits of the dataset, and removed from any dataset it was member of before the execution of the command. By default the object is added to the end of the dataset object list, but the final optional parameter allows the specification of a dataset 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 object is appended as per the default. It is legal to use this command for moving objects within the same dataset.

Another special position value is random or rnd . This value moves to the object 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 of the object prior to the move operation. It is either a dataset handle/reference, or an empty string ( Tcl ) or None ( Python ) 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 interacts with the insert control mechanism of size-constrained datasets. More information is provided in the description of the sizecontrol dataset parameter.

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.

Example:

reaction move $xhandle blockbuster@server2:9998 end

This command moves the reaction to the dataset which was set up as listener on port 9998 and pass phrase blockbuster on host server2 . The local reaction is deleted, and its copy is inserted at the end of the remote dataset.

reaction mutex

reaction mutex xhandle mode

x.mutex(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.

The command returns the current lock count.

reaction need

reaction need xhandle propertylist ?mode? ?parameterdict?

x.need(property=,?mode=?,?parameters=?)

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 original reaction handle or reference.

Example:

reaction need $xhandle E_WEIGHT recalc

reaction new

reaction new xhandle propertylist ?filterset? ?parameterdict?

x.new(property=,?mode=?,?parameters=?)

Reaction.New(data,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 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? ?parameterdict?

x.nget(property=,?mode=?,?parameters=?)

Reaction.Nget(data,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 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 nnew

reaction nnew xhandle propertylist ?filterset? ?parameterdict?

x.nnew(property=,?filters=?,?parameters=?)

Reaction.Nnew(data,property=,?filters=?,?parameters=?)

Standard data manipulation command for reading object data and attributes. 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 nnew is that the latter always returns numeric data, even if symbolic names for the values are available, and that property data re-computation is enforced.

reaction nitrostyle

reaction nitrostyle xhandle style

x.nitrostyle(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 original reaction handle or reference.

reaction pack

reaction pack xhandle ?maxsize? ?requestprops? ?suppressedprops? ?compressionlib?

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

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 tables the reaction or its ensembles are associated with 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 optional property parameter lists 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 or reaction create commands.

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

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 .

The return value of this command is the packed string.

In Python , reactions support the standard pickle / unpickle protocol.

Example:

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

reaction properties

reaction properties xhandle ?pattern? ?intersectionmode?

x.properties(?pattern=?,?intersectionmode=?)

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 or x.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?

x.purge(properties=,?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.

If another object class name, such as ens or atom , is used instead of a property name, all properties of that class set on the reaction ensembles are deleted, if they are not locked, or filtered out by the optional empty-only flag.

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:

• atomquery
  Delete all atom query information from the reaction ensembles ( A_QUERY and other query properties).
• atomstereochemistry
  Delete all atomic atom stereo descriptors from the reaction ensembles, but keep those for bonds.
• bondquery
  Delete all bond query information from the reaction ensembles ( B_QUERY and other query properties).
• bondstereochemistry
  Delete all bond stereo descriptors from the reaction ensembles, but keep those for atoms.
• isotopes
  Delete isotope information in A_ISOTOPE and other isotope properties which may be defined in future software versions.
• query
  Delete all query information from the reaction ensembles ( A_QUERY , B_QUERY and other query properties).
• 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 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.

The return value is the original reaction handle or reference.

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 ref

Reaction.Ref(identifier)

Python only method to get a reaction reference from a handle or another identifier. For reactions, other recognized identifiers are reaction references, or integers encoding the numeric part of the handle string.

reaction remove

reaction remove xhandle ?enslist?...

x.remove(?erefsequence/eref?,...)

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

x.rename(srcproperty=,dstproperty=)

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

reaction reorder

reaction reorder xhandle

x.reorder()

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

The command returns the original ensemble handle. or reference.

reaction reverse

reaction reverse xhandle

x.reverse()

Reverse the direction of the reaction. Only the roles of ensembles with reagent and product roles are changed.

The command returns the original reaction handle.

reaction scan

reaction scan xhandle expression/queryhandle ?mode? ?parameters?

x.scan(query=,?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, ens 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 for these types of test.

reaction set

reaction set xhandle ?property value?...

x.set(property,value,...)

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

x.property = value

x[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?...

reaction setparam xhandle property dictionary

x.setparam(property,?key,value?...)

x.setparam(property,dict)

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.

The return value is the updated property computation parameter dictionary.

Example:

reaction setparam $xhandle X_GIF comment “Top Secret”

reaction show

reaction show xhandle propertylist ?filterset? ?parameterdict?

x.show(property=,?filters=?,?parameters=?)

Reaction.Show(data,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 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.

The Python class method is a one-shot command. The transient ensemble created from the initialization items is automatically deleted when the command finishes. The data for the creation of the temporary ensemble is equivalent to the first argument of the standard constructor. Additional constructor parameters cannot be used.

reaction sort

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

x.sort(?property=?,?relabel=?,?duplicate=?,?target=?,?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 original reaction handle or reference.

reaction split

reaction split xhandle ?minsize? ?splitproperty?

x.split(?minsize=?,?splitproperty=?)

Split the molecules of the ensembles in the reaction into individual ensembles. The return value is a list of all ensemble handles or references 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 in their old reaction role.

The optional minsize parameter is a minimum for the number of heavy atoms (property M_HEAVY_ATOM_COUNT ) in any of the molecules. If this is not an empty string, molecules which have less atoms than the minimum are not duplicated. 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 split 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? ?parameterdict?

x.sqldget(property=,?mode=?,?parameters=?)

Reaction.Sqldget(data,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 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 or Python script processing.

reaction sqlget

reaction sqlget xhandle propertylist ?filterset? ?parameterdict?

x.sqldget(property=,?mode=?,?parameters=?)

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

reaction sqlnew

reaction sqlnew xhandle propertylist ?filterset? ?parameterdict?

x.sqlnew(property=,?mode=?,?parameters=?)

Reaction.Sqlnew(data,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 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 or Python script processing.

reaction sqlshow

reaction sqlshow xhandle propertylist ?filterset? ?parameterdict?

x.sqlshow(property=,?mode=?,?parameters=?)

Reaction.Sqlshow(data,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 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 or Python script processing.

reaction subcommands

reaction subcommands

dir(Reaction)

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

reaction swapin

reaction swapin xhandle

x.swapin()

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 original reaction handle or reference.

reaction swapout

reaction swapout xhandle

x.swapout()

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 original reaction handle or reference.

Example:

rection swapout $xhandle

reaction tables

reaction tables xhandle ?filterlist?

x.tables(?filters=?)

Return a list of the handles or references 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?

x.taint(property=,?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.

The command returns the original reaction handle or reference.

reaction transfer

reaction transfer xhandle propertylist ?targethandle? ?targetpropertylist?

x.transfer(properties=,?target=?,?targetproperties=?)

Copy property data from one reaction to another reaction or other major object, without going through an intermediate scripting language object representation, or dissociate property data from the reaction. If a property in the argument property list is not already valid on the source reaction, an attempt is made to compute it.

If a target object is specified, and a property is not a reaction property, the operation is implicitly performed on pairs of reaction ensembles with the same reaction role (property E_REACTION_ROLE ) as if a ens transfer command were issued. In this command mode, the return value is the handle of the target reaction. The source and target reactions cannot be the same object.

If a target property list is given, the data from the source is stored as content of a different property on the target. For this, the data types of the properties must be compatible, and the object class of the target property that of the target object. No attempt is made to convert data of mismatched types. In case of multiple properties, the source property list and the target property list are stepped through in parallel. If there is no target property list, or it is shorter than the source list, unmatched entries are stored as original property values, and this implies that the object class of the source and target objects are the same.

If no target object is specified, or it is spelled as an empty string or Python None , the visible effect of the command is the same as a simple reaction get , i.e. the result is the property data value or value list. The property data is then deleted from the source object. In case the data type of the deleted property was a major object (i.e. an ensemble, reaction, table, dataset or network), it is only unlinked from the source object, but not destroyed. This means that the object handles returned by the command can henceforth the used as independent objects. They can be deleted by a normal object deletion command, and are no longer managed by the source object.

Examples:

reaction transfer $xh X_IDENT $xh2

reaction transfer $xh A_MAPPING $xh2

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?

x.trim(?properties=?)

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 unlink

reaction unlink xhandle ?xhandle/all?

x.unlink(“all”)

x.unlink(?xhandle/xref?,...)

Remove links of the reaction to other reactions. The special string argument all removes all links of the reaction. If an argument is a reaction the first reaction is not linked to, it is ignored.

The command returns the number of severed reaction links.

reaction unlock

reaction unlock xhandle propertylist/reaction/all

x.unlock(property=)

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 or references
  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.

The return value is the original reaction handle or reference.

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 ?compressionlib?

Reaction.Unpack(data=,?compressionlib=?)

Unpack a base64-encoded serialized object string which was created by a reaction pack command. The return value of this function is the handle or reference 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.

The default compression library is zlib . For more options, see reaction pack .

Example:

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

set xhandle [reaction unpack $packdata]

reaction valid

reaction valid xhandle propertylist

x.valid(property/propertysequence)

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. For Python , where single-item lists are syntactically not the same as a single value, the return value is a single boolean if the argument was a string or a property reference, and only a single property was decoded.

Example:

reaction valid $xhandle X_IDENT

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

reaction has is an alias to this command.

reaction verify

reaction verify xhandle property

x.verify(property)

Verify the values of the specified property on the reaction. The property data must be valid, and a reaction property. If the data can be found, it is checked against all constraints defined for the property, and, if such a function has been defined, is tested with the value verification function of the property.

If all tests are passed, the return value is boolean 1, 0 if the data could be found but fails the tests, and an error condition otherwise.

reaction weed

reaction weed xhandle keywords

x.weed(keywordsequence)

x.weed(?keyword?,...)

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 original reaction handle or reference.

reaction xdelete

reaction xdelete ?xhandle?...

reaction xdelete all

x.xdelete()

Reaction.Xdelete(“all”)

Reaction.XDelete(?xrefsequence/xref/xhandle?,...)

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. If a reaction is part of a linked reaction network, all reactions in the network are also deleted. This is the difference to the normal delete command or method.

The command returns the number of deleted reactions.

reaction xdup

reaction xdup xhandle ?dataset? ?position?

x.xdup(?target=?,?position=?)

Duplicate the specified reaction and its ensembles, together with any additional reactions it may be linked to (see reaction link/unlink ). The latter behavior is the difference to the standard reaction dup command. The return value is the new reaction handle or reference. If additional reactions were duplicated as part of a linked networks, these can be queried via reaction links . The duplicated reaction ensembles are also assigned unique handles.

The duplicate ensemble is placed into the same dataset as the source, if it is a member of a dataset. Specifying an explicitly empty dataset argument (including None for Python ) places the duplicate outside any dataset, regardless of the dataset membership of the source ensemble.

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.