lhasa append

lhasa append lhandle ?property value?...

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

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

lhasa assign

lhasa assign lhandle srcprop dstprop

l.assign(srcproperty=,dstproperty=)

Assign property data to another property on the same Lhasa object. Both properties must be associated with the Lhasa object class. This process is more efficient than going through a pair of lhasa get/lhasa 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 lhasa 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.

Examples

lhasa assign $lh L_IDENT L_NAME

lhasa classify

lhasa classify lhandle ehandle ?fgclass?

Sub-classify functional groups in the structure according to the Lhasa definition. This is used for checking compatibility of standard reaction conditions with functional groups outside the reaction path.

This command is currently not fully implemented.

lhasa collection

lhasa collection

Lhasa.Collection()

Look into the Lhasa transform directory and identify pre-compiled transform files stored therein. The command returns a tuple of the found transform IDs, which are valid identifiers for the lhasa read command.

lhasa create

lhasa create ?ruledata? ?subroutinedata?..

lhasa create -fromfile/-fromfiles rulefilename ?libfilename?...

Lhasa(?ruledata?,?subroutinedata?,...)

Lhasa.Create(?ruledata?,?subroutinedata?,...)

Lhasa.CreateFromFile(rulefilename,?libfilename?,...)

Create a new Lhasa object and return its object handle. Usually, the content of a transform source file and any required subroutine file contents are specified at creation time. These are directly parsed into an internal byte code representation.

The first command variant expects the rule source code as Latin1 or UTF8 (with BOM ) string blob data, while the second version expects a set of file names, with the file containing Latin1 or UTF8 (with BOM ) source code. The first version is useful in contexts where, for example, the rule source is extracted from a database or other non-file source. The second variant automatically sets the sourcefiles attribute, which is not possible for the first version because the file name is not directly known.

The rule data can either be the source code for a single transform (with one set of 1D and optionally 2D and New1D PATRAN patterns), or a concatenation of one or more classification rules (for example, for the determination of subclasses of functional groups). It is not possible to load more than one transform into a Lhasa object, but any number of these objects, with the same or different rule sources, may be instantiated at any time.

If subroutine source code is used, every subroutine source block must be passed as its own argument. It is neither possible to concatenate transform sources and subroutine sources, nor to used merged subroutine source files. Empty subroutine data blobs or filename arguments, or, for filename input, file names which are actually directories are silently skipped. When reading a rule, an attempt is made to automatically load missing library files by trying to locate a file named, in lowercase, like the subroutine name with a .csr suffix along the directory path specified in : :cactvs(lhasapath) or its Python dictionary equivalent. This only succeeds if the subroutine name to source file mapping follows this scheme - this is the case for most of the original Lhasa library files, but not all of them.

Certain object metadata components, such as the transform name and ID, or the substructure match patterns, are automatically extracted from the rule source during parsing and set as object attributes.

The lhasa react sub command requires the presence of one or more 2D or New1D retro-reaction patterns in the rule source, and these should, on the left - retro-reaction reagent - side, correspond to the 1D patterns as closely as possible, but without excluding any structure motifs which are matched by the somewhat more expressive 1D patterns. Many original Lhasa rules to not provide 2D patterns. If that is the case, they must be manually added before a rule becomes fully usable.

The 2D patterns which can be parsed by the toolkit are an extension of the original Lhasa implementation. There is no requirement that the path is encoded on the reaction arrow line with the offpath components drawn above or below this line. Also, aromatic systems are automatically detected if a full ring with proper VB bond orders is drawn. Diagonal double bonds can be encoded as // or \\ character pairs where one of the characters is one position to the left or right of the normal bond continuation. The 2D patterns become subject to a reaction mapping analysis. For performance reasons, it is advisable to use tagged substituent groups like R1, R2 etc instead of anonymous carbon atoms for large patterns.

Example:

set lh [lhasa create [read_file huisgen.src]]

set lh [lhasa create -fromfile huisgen.src]

lhasa dataset

lhasa dataset lhandle ?filterlist?

l.dataset(?filters=?)

Return the dataset handle or reference of the dataset the Lhasa object is a member of. It the object is not member of a dataset, or does not pass all of the optional filters, an empty string or None for Python is returned.

Putting Lhasa objects into datasets is primarily intended for use with the multi-threading dataset threadexec command.

Example:

lhasa dataset $lhandle

lhasa defined

lhasa defined lhandle property

l.defined(property)

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

lhasa delete

lhasa delete ?lhandle?...

lhasa delete all

l.delete()

Lhasa.Delete(?lhandle/lref?,...)

Lhasa.Delete(“all”)

Delete specific or all Lhasa objects from the toolkit instance. The return value is the number of deleted Lhasa objects.

lhasa dget

lhasa dget lhandle propertylist ?filterset? ?parameterdict?

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

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

lhasa exists

lhasa exists lhandle ?filterlist?

l.exists(?filters=?)

Lhasa.Exists(lref=,?filters=?)

Check whether a table handle or reference is valid. The command returns boolean 0 or 1. Optionally, the table may be filtered by a standard filter list, and if it does not pass the filter, it is reported as not valid.

lhasa filter

lhasa filter lhandle filterlist

l.filter(filters)

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

lhasa get

lhasa get lhandle propertylist ?filterset? ?parameterdict?

lhasa get lhandle attribute

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

l.get(attribute)

l.property/attribute

l[property/attribute]

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

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

In addition to retrieving property data, this command is also used to retrieve a large set of attribute values from the Lhasa object. All attributes which can be set (see lhasa set command) can also be queried. In addition, there are a number of attributes which cannot be set by script commands but are automatically updated when a rule is compiled, or a lhasa react or lhasa score command is executed. These are:

• 1dpatterns
  A list of the ensemble handles or references of the 1D patterns defined as part of the transform.
• 2dpatterns
  A list of the reaction handles or references of the 2D patterns defined as part of the transform.
• baserating
  The base rating of the transform. If individual rating factors are defined in the rule ( TYPICAL*YIELD , etc.), the base rating is computed from a weighted average of these factors, as per the official Lhasa formula. This supersedes any value defined by a RATING statement. If only a RATING statement is part of the rule, its value is returned. If neither rating factors not a plain rating are specified, the default base rating of 50 is substituted.
• codetable
  The command returns the handle or reference of a newly generated table object which contains a human-readable representation of the compiled source. When writing this table as a tab-separated file (or directly as an Excel file), this is a useful tool to debug compilation issues. The table is not associated with the Lhasa object. It must be managed and discarded independently.
• conditional*flexibility (or conditionalflexibility)
  The enumerated value of the base rating factor as defined in the rule, or undefined .
• coverage
  The count of opcodes which were evaluated at least once as result of lhasa score commands during the lifetime of the Lhasa object. This number is less than or equal to the total number of opcodes ( opcodecount attribute) and the same as the number of set bits in the coveragevector attribute.
• coveragevector
  A bit vector with the length equal to the number of byte-compiled opcodes indicating if an opcode has been evaluated at least once during the lifetime of the Lhasa object as the result of running lhasa score commands. This information is used to help constructing test data sets exercising all relevant aspects of a transform.
• cost
  The enumerated value of the base rating factor as defined in the rule, or undefined .
• debugtable
  The table handle or reference of the integrated table object which stores scoring execution trace data if the debugtable flag is set in the execflags attribute. The table only exists if a trace was executed, and it is re-used for further traced scoring executions. The table is an integral part of the Lhasa object and is fully managed by it. If no table has been set up, and empty string for Tcl or None for Python is returned. The table is used in the CHMTRN Web tool for debugging and explaining transform execution.
• delta
  The reaction-specific delta value added to the Hammet electrophilic substitution reactivity function value when using such Hammet equation. The value is specified via a DELTA statement in the source.
• description
  Free-form text extracted from the transform rule source header.
• forwardtests
  Get the information from the FORWARD*REACTION*VERIFICATION block, if one is present in the transform. This is a list, where each list contains in nested fashion a list of the numbers of reagent molecules from the scan verification block starting with number one, and a second list of all expected forward reaction products as ensembles generated from the forward reaction of the indicated reagents.
• generalrefs
  A list of the general (not conditional) literature references defined in the transform.
• handle
  The object handle.
• heteroselectivity
  The enumerated value of the base rating factor as defined in the rule, or undefined .
• history
  A nested list/tuple of the authors and dates of transform source code changes, as encoded by written*by and changed*by statements. The simpler author attribute contains the name of the first author only.
• homoselectivity
  The enumerated value of the base rating factor as defined in the rule, or undefined .
• intermol_reagentquery1
  Return Cactvs query for molfile scan and variants which checks for the presence of a suitable reagent pattern of the first reagent. The exact match mode depends on the setting of the countedreagentquery and exclusivereagentquery flags in the execflags parameter.
• intermol_reagentquery2
  Return Cactvs query for molfile scan and variants which checks for the presence of a suitable reagent pattern of the second reagent.The exact match mode depends on the setting of the countedreagentquery and exclusivereagentquery flags in the execflags parameter. If no second reagent is defined, the returned query never matches.
• intermol_reagentquery3
  Return Cactvs query for molfile scan and variants which checks for the presence of a suitable reagent pattern of the third reagent. The exact match mode depends on the setting of the countedreagentquery and exclusivereagentquery flags in the execflags parameter. If no third reagent is defined, the returned query never matches.
• intermol_reagentquery4
  Return Cactvs query for molfile scan and variants which checks for the presence of a suitable reagent pattern of the fourth reagent. The exact match mode depends on the setting of the countedreagentquery and exclusivereagentquery flags in the execflags parameter. If no fourth reagent is defined, the returned query never matches.
• intramol_reagentquery
  Return a Cactvs query for molfile scan and variants which checks for the presence of a suitable reagent pattern within a single record. Any ensemble which simultaneously contains a pattern for any variant of the first, second ... up to the number of reagents in a reaction is a match.
• keywords
  A free-form list of keywords associated with the transform.
• killline
  The transform source code line of the statement which terminated the last rule execution, or the special string values scoretoolow and wrongfragmentcount if the execution was stopped outside the compiled transform code due to these conditions. The value is 0 if the run was not terminated. It is automatically reset before processing any pattern match in a lhasa score command.
• max2dfragments
  The maximum number of fragments on the product side of 2D or New1D patterns defined in the transform source.
• mechblock
  A list of the opcode indices of the first and last CHMTRN statements defining the mechanism block.
• min2dfragments
  The minimum number of fragments on the product side of 2D or New1D patterns defined in the transform source.
• new1dpatterns
  A list of the reaction handles of all New1D patterns defined as part of the transform.
• newbaserating
  The computed transform base rating as defined by the rating factors (see baserating ). If the rule does not define rating factors, an empty string is reported.
• opcodecount
  The number of compiled opcodes.
• opcodes
  A sequential list of all opcodes byte-compiled from the transform text. Each list element is a dictionary with all attributes applicable to the specific opcode.
• optionalrefs
  A list of all optional (conditional) literature references defined in the transform source.
• orientational*selectivity (or orientationalselectivity )
  The enumerated value of the base rating factor as defined in the rule, or undefined .
• productpatterns
  A list of all ensemble handles for the product patterns defined by 2D or New1D patterns in the transform. Note that in the original rule text these are written on the left side of the reaction scheme because transforms work in retro-synthetic direction!
• reactiondataset
  The handle of the dataset object embedded in the Lhasa object which contains reaction products after running a lhasa react command.
• reactionproducts
  A list of all product ensembles generated by the last lhasa react command.
• reactions
  A list of the reaction handles of all 2D and New1D patterns defined as part of the transform.
• reagentcount
  The maximum number of reagents defined in in any 2D or New1D pattern of the transform. This defines also the last supported reagent query ( intermol_reagentquery[1234] ) for a given transform.
• reagentpatterns
  A list of all ensemble handles for the reagent patterns defined by 2D or New1D patterns in the transform. Note that in the original rule text these are written on the right side of the reaction scheme because transforms work in retro-synthetic direction!
• reliability
  The enumerated value of the base rating factor as defined in the rule, or undefined .
• reputation
  The enumerated value of the base rating factor as defined in the rule, or undefined .
• rho
  The reaction-specific multiplier value applied to the Hammet electrophilic substitution reactivity function when using such Hammet equation. The value is specified via a RHO statement in the source.
• ruleflags
  An enumerated list of all the descriptive rule flags set in the transform source code, or none . The recognized set is subgoals*allowed , subgoals*not*allowed , fga*allowed , fga*not*allowed , unmasking , symmetrical , reconnective , simplifying , disconnective and student . None of these currently has an effect on the execution of the rule code.
• safety
  The enumerated value of the base rating factor as defined in the rule, or undefined .
• scantests
  Get the data from a REAGENT*SCAN*VERIFICATION blob, if it is present in the transform. The result is a list of ensembles. In property E_REAGENT_SCAN_VERIFICATION these ensebmels contain information about their expected reagent roles (intramolecular reagent, intermolecular reagent 1, etc.).
• scoredataset
  The handle of the dataset embedded in the Lhasa object which contains scored reactions after running the lhasa score command.
• scoreduplicatecount
  The number of score pattern matches in the last lhasa score command which executed without rejection by KILL or DISCONTINUE statements in the transform evaluation code, but which were then removed from the scored result set because they were a structural duplicate of an earlier result.
• scorekillcount
  The number of score pattern matches which were killed during the execution of the transform evaluation code by the last lhasa score command. The count includes implicit kills by scores decreasing below the kill threshold and similar events.
• scorematchcount
  The number of topologically distinct score pattern matches found by the last lhasa score command.
• scoredreactions
  A list of the scored reactions generated as result of the last lhasa score command.
• scoretests
  Get the contents of the RETRO*SCORING*VERIFICATION block as a list, if such a block is defined in the transform. Each list element consists of a list of the expected outcome ( killed or scored ) and the test ensemble handle or reference. If the expected result is a kill, the next list element contains the opcode index (zero-based) of the statement which caused the kill. If the expected result is a successful score, the next element is the final score, followed by another nested list, where each element consists of the zero-based opcode index which produced a score modification ( ADD or SUBTRACT ), followed by the score delta.
• standardreagentsdataset
  Get the handle or reference of the dataset object which holds the simple standard reagents collection for Lhasa operations. This is a collection of about 85 bulk chemicals which are used in some Lhasa transforms, but are not usually contained in starting material catalogs. This includes reagents such as water, chlorine gas, ozone, or methanol. The dataset is instantiated and filled with the default set when the first Lhasa engine object is created. It is shared between all Lhasa objects. It can be manipulated by adding, removing or editing the contained structures. If a Lhasa forward reaction reagent set fails to explicitly include any of those small molecules when they are required for the reaction, they are automatically added. See also the lhasa react command.
• superatomattachment
  A boolean value indicating whether the current transform may create leaving groups with superatom components, such as generic alkyl groups. This is extracted from the specifics of the bytecodes of the compiled transform. Not all transform executions with the potential to generate such compounds will do so under all circumstances due to the possibility of encoding multiple reaction paths in the transform.
• thermodynamics
  The enumerated value of the base rating factor as defined in the rule, or undefined .
• typical*yield (or typicalyield )
  The enumerated value of the base rating factor as defined in the rule, or undefined .

Variants of the lhasa get command are lhasa new, lhasa dget, lhasa jget, lhasa jnew, lhasa jshow, lhasa nget, lhasa show, lhasa sqldget, lhasa sqlget, lhasa sqlnew, and lhasa sqlshow . These commands only work on property data and cannot be used to access engine attributes.

lhasa getparam

lhasa getparam lhandle property ?key? ?default?

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

lhasa jget

lhasa jget lhandle propertylist ?filterset? ?parameterdict?

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

This is a variant of lhasa 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.

lhasa jnew

lhasa jnew lhandle propertylist ?filterset? ?parameterdict?

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

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

lhasa jshow

lhasa jshow lhandle propertylist ?filterset? ?parameterdict?

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

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

lhasa list

lhasa list ?pattern?

Lhasa.List(?pattern=?)

Return a list of all currently existing Lhasa object handles or references. If a filter pattern is specified, only objects matching it are listed. The pattern syntax is the same as in the standard Tcl command string match .

lhasa metadata

lhasa metadata lhandle property ?field ?value??

l.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 lhasa setparam and lhasa 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 .

lhasa move

lhasa move lhandle ?datasethandle? ?position?

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

Make the Lhasa object 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.

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.

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.

lhasa mutex

lhasa mutex lhandle mode

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

lhasa need

lhasa need lhandle propertylist ?mode? ?parameterdict?

l.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 table handle or reference.

lhasa new

lhasa new lhandle propertylist ?filterset? ?parameterdict?

l.new(property=,?filters=?,?parameters=?)

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

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

lhasa nget

lhasa nget lhandle propertylist ?filterset? ?parameterdict?

l.nget(property=,?filters=?,?parameters=?)

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

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

lhasa nnew

lhasa nnew lhandle propertylist ?filterset? ?parameterdict?

l.nnew(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 lhasa get command. The difference between lhasa get and lhasa 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.

lhasa properties

lhasa properties lhandle ?pattern? ?noempty?

l.properties(?pattern=?,?noempty=?)

Return a list of the valid properties on the Lhasa object. If desired, the property list can be filtered by the optional string match pattern. Since Lhasa objects incorporate no minor objects, only true Lhasa object properties (standard prefix L_ ) are listed.

If the noempty flag is set, only properties where at least one data element is not the property default value are output. By default, the filter pattern is an empty string, and the noempty flag is not set.

The command may also be written as short form lhasa props .

lhasa purge

lhasa purge lhandle propertylist/table ?emptyonly?

l.purge(?properties=?,?emptyonly=?)

Delete property data from the Lhasa object. In contrast to performing property deletions on, for example, ensembles this operation does not branch out to properties which are stored on objects embedded in the Lhasa objects.

This command only deletes proper Lhasa object properties (usually starting with L_). If the object class name lhasa is used instead of a property name, the data of all Lhasa object properties is deleted.

The optional boolean flag emptyonly restricts the deletion to those properties where the value of a property is identical to the default.

lhasa react

lhasa react lhandle ehandle/ensspec ?ehandle/ensspec?...

l.react(ehandle/eref/espec,?ehandle/eref/espec?,...)

Generate a comprehensive set of forward reaction products of starting materials according to all matching 2D or New1D patterns from the current transform. If New1D patterns are present, only these are used for matching. The starting materials need to match the right side of the patterns, and the number of specified starting material ensembles must be the same as the number of fragments in the pattern. Every substructure pattern fragment must match on a different starting material molecule from the merged input ensemble in the default intermolecular reaction mode, or be part of the same molecule ( intramolecular mode, see forwardmode attribute of the Lhasa object). The order of the input structures vs. the left/right sequence of patterns in the transform code is arbitrary. All possible, but symmetry-filtered pattern match variants of all eligible patterns with respect to the input structure set are evaluated.

The starting material structures can either be normal persistent ensemble handles/references or a decodable structure specification (see ens create ). In the latter case, the decoded input structures are transient and are automatically deleted after the command completes.

The result is a list of all possible duplicate-filtered reaction product ensemble handles or references which could be generated by checking all applicable patterns in all possible match orientations and, upon any successful match, performing the atom and bond changes encoded in the pattern, going from the right side of the pattern to the left. Duplicate result structure filtering is performed according to the configured hash code (see hashproperty Lhasa object attribute). The reaction products reside in a dataset object embedded in the Lhasa object (see reactiondataset attribute) and may be further manipulated there, or moved out by additional script commands. The reagent structures, if they are not transient objects, are not consumed.

When this command is run, any existing product ensembles in the reaction dataset are deleted before the execution commences.

If there is no match, this is not an error. The result structure set is simply empty in that case.

The reagent structures used with this command are usually structures found by scanning a starting material catalog with automatically extracted reagent queries (see reagentquery[1234] attribute).

A successfully performed reaction does not guarantee that the reverse reaction scoring arrives at the same starting materials. There can be alternative retro-synthetic pattern matches, additional potential starting materials like Cl/Br/I alternative leaving group substitutions, starting materials with generic superatoms like „ alkyl “ instead of a specific group, markers for required functional group protection, etc. The products generated by this command are only to be used as starting points for retro-synthetic evaluation. The reagent structures returned by lhasa score need to be matched again vs. a starting material catalog (potentially after attaching protective groups where required, etc.), and the matches from that operation are the real starting materials to be stored in a Lhasa -scored synthetically accessible structure catalog, not the input structures used in this command.

lhasa read

lhasa read bytecodefilename/trafoid

Lhasa.Read(bytecodefilename/trafoid)

Create a Lhasa object by reading a compiled byte code file (see lhasa write command). The argument is either a single file name or transform ID. Any library subroutine files which are required and were specified when the transform was compiled from source (see lhasa create ) are part of the single byte code file.

It is possible to specify input pipes (with a leading vertical bar in the name) and stdin as input. If the file is not specified as full path name, and not readable in the current directory, an attempt is made to find it in the standard transform directory. If the filename is missing the standard .clb suffix, it is automatically appended. If the file name is a simple integer transform ID, a short file name is constructed from this identifier and searched. The default transform collection contains links from the transform ID short file name to the corresponding fully named transform file with the highest version number.

The return value is a new Lhasa object handle or reference.

lhasa ref

Lhasa.Ref(identifier)

Python -only method to get a reference of the Lhasa object from its handle.

lhasa rename

lhasa rename lhandle srcproperty dstproperty

l.rename(srcproperty=,dstproperty=)

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

lhasa reset

lhasa reset lhandle

l.reset()

Reset the Lhasa object from an empty state. All result structures and reaction currently associated with the object are deleted, and the transform definition is purged.

The command is not used in normal processing. Both lhasa react and lhasa score automatically clear their respective result sets when the command is started and can thus be invoked any number of time without resetting.

The command returns the original object handle or reference.

lhasa score

lhasa score lhandle ehandle/ensspec

l.score(ehandle/eref/ensspec)

This command performs a full retro-synthetic evaluation of a product structure according to the CHMTRN script commands encoded in the rule source.

Usually the input structure is one from the result set generated by lhasa react from potential starting materials, but this is not required. The examined structure may either be a normal persistent ensemble handle, or a decodable structure specification (see ens create ). In the latter case, the structure is decoded transiently and automatically deleted when the command finishes.

The command exclusively uses the 1D reaction path specifications encoded in the transform code. All possible, symmetry-filtered matches are found and processed. The result is a duplicate-filtered set of forward reactions, which contain newly created potential reagents and a duplicate of the target structure. Sometimes, transform rules may also encode intermediates. These also become part of the reaction with a suitable E_REACTION_ROLE property value, usually intermediate . These result reactions reside in the dataset embedded in the Lhasa object (see scoredataset attribute) and may be further processed there. Existing score result reactions associated with this Lhasa object are deleted whenever the command it run, so they have to be saved or moved out of their dataset before the command is re-used if they are still needed.

Depending on the transform rule coding, the proposed reagents may contain expandable superatoms (alkyl, halogen) and/or other markers (such as functional groups requiring protection). A second-pass match operation against a starting material catalog is required to obtain real starting materials, and there may be multiple catalog matches if the starting material structure contains variable groups, or different pre-attached protecting groups may be suitable.

A scored structure may be matched by multiple 1D patterns, and any of these may be positioned in multiple different match orientations. Furthermore, multiple reaction variants may be generated from within a transform rule (for example, by means of a BRANCH CHMTRN statement). Therefore, frequently more than a single reaction is the result of a scoring operation on a single structure. It is also possible that no result reactions are reported for a given structure/transform combination, either because no pattern matches, or all possible reaction paths were discarded by means of CHMTRN KILL statements, or unmet score thresholds. This is even possible when the tested structure was generated by a lhasa react command with the same transform - that command performs only pattern matching and atom/bond updates, not reaction knowledge evaluation.

The return value of the command is the highest score among all found retro-reaction paths for the tested product structure, or 0 if there were no result reactions. Every retro-reaction result object holds detailed transform result and logging information in property X_LHASA_SCORE , including its individual score. The result reactions additionally have atom mapping information in A_MAPPING and may contain additional information on the role of specific atoms in property A_FLAGS (especially in bits protected, interfering, participating).

lhasa scorematch

lhasa scorematch lhandle ehandle/espec

l.scorematch(ehandle/eref/ensspec)

Test whether a structure intended to be retro-synthetically scored matches the transform patterns for the current transform. No actual scoring is performed. The return value is the total number of distinct matches of the score structure on all retro patterns. If the value is zero, the structure cannot be processed by the current transform. This command helps in distinguishing between unsuitable score structures and those where all reaction paths are killed by the transform code executed after one or more matches.

lhasa set

lhasa set lhandle ?property/attribute value?...

lhasa set lhandle ?dictionary?

l.set(property/attribute,value,...)

l.set({property/attribute:value,...})

l.property/attribute = value

l[property/attribute] = value

Set one or more attributes of the Lhasa object. All attributes which can be set can also be queried via the lhasa get command. Attributes which cannot be modified are listed under lhasa get .

These are the recognized attributes:

• address_city
  The city part of the author contact address.
• address_country
  The country part of the author contact address, following the ISO3166 standard.
• address_state
  The state part of the author contact address. Empty if not applicable.
• address_street
  The street address part of the author contact address. Includes floor, house number, etc.
• address_zip
  The ZIP code or other applicable postal code of the author contact address.
• affiliation
  The institution the author of the transform rule works for.
• affiliationduns
  The DUNS registration ID of the affiliated institution. This is primarily useful for US government projects.
• affiliationurl
  The URL of the affiliated institution.
• author
  The (first) author of the transform rule . This is a free-form string. When a transform is read from source or compiled code, this is set to the value encoded in the first written*by or changed*by statement.
• authorurl
  A URL with information on the author, or an empty string if unset.
• category
  A category string to be used if the rule definition is stored in a repository.
• classuuid
  The base class UUID of this rule definition.
• comment
  A free-form text comment.
• complexityfilter
  A maximum complexity value (as per property E_COMPLEXITY ) which is acceptable for starting material selection. If the attribute is set to a value larger than zero (the default), a query condition is automatically added to the auto-generated starting material queries (read-only attribute intermol_reagentquery1 etc., see lhasa get command). This attribute can be combined with the element filter attribute.
• date
  This attribute stores the date of the rule definition compilation. It is used for information purposes only. If a new rule is compiled, it is initialized to the current date. When a transform is read from source code, it is set to the last date encoded in written*by or changed*by statements.
• debugimagesize
  The height and width of images measured in 72dpi pixels which are entered in the debug table (see debugtable and execflags attributes) for visualizing the progress of scoring operations. The default image size is 200 pixels.
• doi
  A digital object identifier for the rule, if defined.
• elementfilter
  An element filter (formula match) expression (see molfile scan command). If it is specified as a non-empty string, it is added as an additional criterion to the auto-generated starting material queries (read-only attribute intermol_reagentquery1 etc., see lhasa get command). The attribute can be combined with the complexity filter attribute.
• email
  The email address of the creator of the rule, useful in case a definition file is distributed and anybody has questions.
• execflags
  A collection of flags modifying various aspects of the operation of the object. The recognized flags are:
• checkreactionbonds - if set, the breaking or creation of bonds in retro-synthetic (scoring) direction only succeeds if the bonds are marked in property B_REACTION_CENTER as changed, created or broken. This marking of bonds in this property is automatically applied when the forward reaction for retro analysis is created ( lhasa react ). This option prevents possible deviations of bond transformations into out-of-pattern regions of the product molecule. However, if the retro-analyzed product does not contain B_REACTION_CENTER , for example because the scored product was not generated via the standard mechanism, the analysis fails.
• checkreagents - this flag has only an effect if the scored molecule is the product component of a reaction, where the reagents component contains the starting materials. If set, a check is performed if all, of the retro-synthetically generated fragments match molecules in the reagents component. If not, the generated score structure is discarded. This flag is usually combined with the checkreactionbonds flag and further restricts the score result set. For example, an asymmetric ether usually generated (in absence of interfering features) 6 different score solutions with the Williamson ether synthesis transform - attaching a halogen on the fragment on both sides of the ether oxygen, and proposing the use of chlorine, bromine and iodine as reacting halogen. With the checkreactionbonds flag and properly set properties on the scored structure, only the side of the ether which was reacted in the forward reaction is cut since this encoded in bond property B_REACTION_CENTER . However, this still generates three solutions since the scored product on its own has no knowledge which halogen was used when it was generated from starting materials. If however the scored structure is part of a full forward reaction, only the halogen variant used in its generation is reported as unique scored result.
• countedreagentquery - if set, reagent queries check for single-instance presence of the substructure, discarding structures with multiple pattern matches in non-overlapping locations.
• debugtable - Create and fill an embedded table object with a transform execution trace. This is internally used in the CHMTRN Web tool.
• dumperrorstructure - If a structure triggers an error during retro analysis, dump it as a serialized object into a file in the current directory.
• exclusivereagentquery - if set, suitable reagents do not just need to contain the pattern of a reagent specification, but additionally cannot contain the patterns of any other reagent, except for intramolecular reagents.
• forwardreactiontrace - Trace the execution of forward reactions.
• forwardresultsasreactions - Normally, the forward application of a transform ( lhasa react command) returns the result structures as simple structures, not as part of a full reaction with the starting materials. If this flag is set, the result structures are part of a reaction, with B_REACTION_CENTER and A_MAPPING set on both reagent and product ensemble. This is the preferred mode to generate suitable scoring structures for use with the checkreagents flag.
• forwardscorabilitycheck - if set, perform an extra check on whether the scored molecule matches any of the score patterns, without executing any real scoring.
• forwardstereoexpansion - if set, forward reactions which generate stereogenic centers and bonds in the course of the reaction do not return undefined stereochemistry at these, but an enumeration of molecules with defined stereochemistry, allowing the selection of stereo-specified starting materials from retrosynthetic analysis.
• keepkills - if set, keep killed structures and report them in the score result set with a -999 score, but discontinue execution of the transform.
• nosuperatoms - Do not attach leaving groups with superatoms like [ALK] in retro analysis. Instead, attach a specific minimal leaving group (usually a C1 fragment).
• prefernew1dscorepatterns - if set, prefer the use of the NEW1D pattern(s) not just for forward reactions, but also for scoring, provided they exist. By default, the original 1D pattern(s), if they exist, have precedence for this purpose. In most cases, the left-side portion of a NEW1D pattern is identical to the equivalent 1D pattern, except in cases where the reaction encoding of the NEW1D pattern needs to avoid generic bond types.
• reagentequivalencytrace - A trace option for determining the equivalency of reagents generated during retro analysis.
• registerscore - Register score events and circumstances for later detailed analysis.
• reagentmatchtrace - A trace option for reagent matching.
• reversepatternmatchtrace - A trace option for the pattern matching in retrosynthetic analysis.
• symmetricreagentquery - If more than a single non-overlapping match of the patterns of potential starting materials is allowed (see targetmatchcount attribute), multiple matches are only allowed if they are topologically equivalent. In the default case of allowing only single matches, this flag has no effect.

The default execution flag value is exclusivereagentquery|countedreagentquery.

• forwardmode
  Change the way forward reactions ( lhasa react ) are processed. Possible values are intermolecular (the default) and intramolecular . In intermolecular mode, the reagent patterns of a possible reaction must match onto different molecules in the combined reagent set, and the number of molecules in the set must be the same as the number of disconnected patterns in the matched reaction (usually 2, but up to 4, depending on how the 2D or New*1D pattern is encoded). In intramolecular mode, there can be only one reagent molecule, and all reagent patterns must match in non-overlapping fashion the same molecule.
• hashproperty
  The name of the hash code property used to eliminate structure duplicates. The default is E_HASHISY . New 128-bit hash codes are not yet supported.
• id
  The official registration ID of the transform rule. regid is an alias.
• interferingcolor
  The color to use to mark interfering functional groups in transform result graphical reports. The default is „light salmon“.
• infourl
  A URL with information on the transform rule, or an empty string if unset..
• license
  The license class associated with this transform rule. Setting the license to a standard type updates the associated URL with a standard location.
• licenseurl
  A URL with details about the rule license.
• maxqueryfragments
  The maximum number of molecules in a matching reagent record. The default value is 1, i.e. allow only reagents without counterions, etc.
• mininorganicsize
  The minimum heavy atom count of inorganic fragments generated in retro scoring mechanisms to retain the fragment in the result ensemble. The default is 2, i.e. inorganic fragments such as water with one heavy hetero atom are deleted.
• minmolsize
  The minimum heavy atom count a fragment must meet to be not automatically discarded when a result structure ensemble is logged. The default is 2.
• name
  This is the name of the transform rule. Changing it after it has been defined originally is generally considered bad style, but it is possible.
• orcid
  The ORCID code of the author of the transform rule (see www.orcid.org).
• participatingcolor
  The color used for marking reaction-participating (in CHMTRN parlance) functional group in transform result graphical reports. The default is palegreen .
• phone
  A contact phone number of the author.
• protectedcolor
  The color used for marking functional groups which need protection under the conditions of the retro-reaction. The default is plum .
• reactioncycles
  The number of iterative cycles the lhasa react command should perform when it is run. The default is one, and any other value is useful only under special circumstances.
• reagentexclusionmode
  The mechanism used to exclude parts of potential reagents from matching the reagent pattern because they are already matched by patterns of reagents in other roles. Useful values are combinations of burnatoms , burnbonds , burncarbon , burnterminals , burnringsystems , and burnaroringsystems . The default is burnatoms|burnaroringsystems . Please refer to the match or molfile scan commands for additional information.
• reagentmatchmode
  The substructure match mode to use to match starting materials. This is a standard substructure match parameter and possible value are explained in the section on the match command. The default mode is conditionalnocommonfgatoms .
• references
  Cross references of the rule. This is a nested list of class UUID s and reference type tags.
• scorethreshold
  A positive integer value which specifies a threshold for the accumulated score. If, at the time a result structure is to be reported, its score is below the threshold, reporting is skipped, even though the result structure was not explicitly KILL ed. If the attribute is set to a negative value (which is the default), no result structure score filtering is performed.
• scoredmolcount
  An integer value which can be set to indicate the required number of molecular fragments in the result reagent after executing a lhasa score command. If the number is not negative, only results which match the number are accepted - other outcomes are KILL ed. This is useful to exclude (set to 2 or other number of reagent structures) or require (set to 1) intramolecular retro-reactions. If set to a negative value (the default), not result fragment count filtering is performed.
• sourcefiles
  A list of the names of the files which contained the source code for the compiled transform rule. If the rule was compiled from blob data without reading named files (see lhasa create command) all names are set to an empty string. If this attribute is set, the number of list elements must be the same as the number of data blobs or source files used to compile the rule.
• stereosynthesismode
  This attribute can be set to none (the default), eantioselective or diastereoselective . The set value is checked against CHMTRN target keywords ENANTIOSELCTIVE*SYNTHESIS and DIASTEREOSELECTIVE*SYNTHESIS if they are encountered in transform rules while executing the lhasa score command.
• subtractthreshold
  A positive integer value which leads to the re-interpretation of a SUBTRACT CHMTRN statement as a KILL statement if the final negative delta is larger or equal to the specified threshold. The value only applies to the delta of a single SUBTRACT statement, not the accumulated score. If set to a negative value (which is the default), no command re-interpretation is performed regardless of the demerit.
• targetmatchcount
  Set the desired number of non-overlapping reagent pattern matches in potential starting materials. This number is 1 by default.
• traces
  A list of conditions which limit the range of transform execution traces activated via setting the cactvs(trace) control variable to lhasa . By default, all executed byte-code statements are traced, but trace output can be limited to code sections of interest. The argument is a list of trace sections. Every list element is a nested list of one to three integers. The first element of the nested lists is the start line in the source file of the traced section. Code before that line is not traced. The optional second element is the last source line of the trace section. If it is not set, the trace extends to the end of the source file. The optional third element is the source file index, with zero for the base rule file and one or higher for additional library files. The default value for this element is zero, i.e. if a trace section is specified without an explicit source file index, it applies to the base transform file.
• version
  The version of the node. This is a string in a 1.2.3 (or shortened) style.
• versionuuid
  The version UUID associated with this transform rule version.

lhasa setparam

lhasa setparam lhandle property ?keyword value?...

lhasa setparam lhandle property dictionary

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

l.setparam(property,dict)

Set parameter values in the metadata section of existing property data attached to the Lhasa object. This command does not change the parameters for computations in the property definition (see prop setparam command for this function). It only stores its data in the parameter set which was copied into the metadata when the property was computed for the table.

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

lhasa show

lhasa show lhandle propertylist ?filterset? ?parameterdict?

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

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

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

lhasa sqldget

lhasa sqldget lhandle propertylist ?filterset? ?parameterdict?

l.sqldget(property=,?filters=?,?parameters=?)

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

For examples, see the lhasa get command. The differences between lhasa get and lhasa 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.

lhasa sqlget

lhasa sqlget lhandle propertylist ?filterset? ?parameterdict?

l.sqlget(property=,?filters=?,?parameters=?)

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

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

lhasa sqlnew

lhasa sqlnew lhandle propertylist ?filterset? ?parameterdict?

l.sqlnew(property=,?filters=?,?parameters=?)

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

For examples, see the lhasa get command. The differences between lhasa get and lhasa 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.

lhasa sqlshow

lhasa sqlshow lhandle propertylist ?filterset? ?parameterlist?

l.sqlshow(property=,?filters=?,?parameters=?)

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

For examples, see the lhasa get command. The differences between lhasa get and lhasa 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.

lhasa transfer

lhasa transfer lhandle propertylist ?targethandle? ?targetpropertylist?

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

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

If a target object is specified, the return value is the handle or reference of the target object. The source table and the target object 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 lhasa 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 or references 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.

lhasa valid

lhasa valid lhandle propertylist

l.valid(property/propertysequence)

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

lhasa has is an alias to this command.

lhasa verify

lhasa verify lhandle property

l.verify(property)

Verify the values of the specified property on the Lhasa object. The property data must be valid, and a table 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.

lhasa write

lhasa write lhandle ?filename?

l.write(?filename=?)

Write a byte code file encapsulating the currently loaded and compiled transform or classification rule. This file can be used as input for a lhasa read command to restore the Lhasa object at a later time. Only the rule content and the object metadata is stored, not the current execution state and result data of the Lhasa object. The byte code contains the code generated from all included CHMTRN library files, not just the primary transform file, if applicable.

If no file name is specified, it is constructed from the Lhasa object name and the suffix .clb ( Cactvs Lhasa Binary) without a directory path component. It is possible to use output pipes or (on Linux/Unix) Tcl or Python file handles or references as special output file names. If an explicit empty filename is set (including None for Python ), no disk file is written. Instead, the file contents are returned as byte blob.

The primary purpose of the binary format is distribution of rule content without access to the source code. We have permission from the Lhasa rights holders to distribute binary versions of original Lhasa transforms, but not their source code. Transform source code is only available as part of the standard toolkit package for newly added transform rules not authored by Lhasa Inc. or Lhasa Ltd. Additional source may be made available for customers with an extended license or the legal successors of the members of the original industry consortium sponsoring the development of these rules. In addition, a large part of the Lhasa UK source part has been put into the public domain.

The binary format in this CHMTRN interpreter implementation is intentionally not compatible to the original Lhasa byte code, avoiding its limitations due to insufficient number of bits in the 32-bit values of the virtual processor code.

The return value of the command is the filename, which may have been auto-generated, except in case when the output is a blob.