LSD 3.5.2

Last modified: April, 26th 2022.

Table of contents

From spectra to data

The goal of LSD is to help the user to propose one or more molecular structures from data that is mainly extracted from 2D NMR spectra. Recording HMQC (or HSQC), HMBC and COSY spectra is the pre-requisite for LSD use. LSD has no knowledge of chemical shifts. There is no way to introduce this kind of data, for any nucleus type. LSD uses the chemical shift and coupling information provided by the user that are necessary to establish carbon hydridization state or to impose a particular neighborhood to a given atom.

NMR data coding for LSD may initially seem awkward to beginners. The following paragraphs are intended to help them. A useful documentation source may be found in the examples in the Data folder. A data file for LSD is a text file that contains commands, each being followed by one or more parameters. The most useful commands will be first introduced, but a thorough command set description is given in the Data file structure paragraph. A text-type user interface may seem old-fashioned, but it is sometimes easier to modify a text than to navigate though menus and sub-menus whose function is not always totally explicit.

The first step in the elucidation of an unknown molecular structure is to find its elemental formula and to determine the status of all non-hydrogen atoms. The status consists of an index, a chemical symbol, a hybridization state (sp, sp2 or sp3), a number of attached hydrogen atoms and a charge. Defining the status of all atoms is a strong constraint for the user. The status of heteroatoms is not always easy to define, mainly when more than one of their type is present. Even for carbon atoms, the chemical shift value is not sufficient to non-ambiguously deduce the hydridization state. More than a single data set must then be written and tested. More flexibility to status definition will be given in the near future, but for the moment the user has to cope with the present capabilities of LSD.

Atom indexing may be arbitrary. A recommended procedure is the indexing of carbons from 1 in decreasing order of their 13C chemical shift value. Heteroatoms, such as nitrogen or oxygen, receive the following numbers as indexes. Carbon indexes are then reported in the 1D projections around the 2D HMQC and HMBC spectra. It is possible to have another atom type (X) provided that its valence is defined by the user.

The command that defines an atom status is MULT. Uppercase letters need to be uppercase. MULT is followed by the atom index, the chemical symbol, 1, 2 or 3 for the hydridization state (sp, sp2 or sp3), the multiplicity (number of bound hydrogen atoms) and the charge (facultative). The command MULT 1 C 2 0 says that atom 1 is a quaternary (0) sp2 (2) carbon (C). The data file contains as many MULT lines as non-hydrogen atoms in the molecule.

The following step is the indexing of hydrogen atoms. Again, the indexes may be given arbitrarily, but it is handy to give the same index to the proton and to the carbon atom that is attached to it. The HMQC (or HSQC) spectrum matches carbon and proton indexation schemes. Two inequivalent hydrogen atoms within a methylene group get the same index. The hydrogen indexes are then copied in the projections around the 2D COSY and HMBC spectra. A correlation in a 2D spectrum is characterized by the type of spectrum, the index of the atom in dimension 1 (carbon index in HMQC and HMBC spectra), and the index of the atom in dimension 2 (always a hydrogen atom index). The command HMQC 4 4 indicates that carbon 4 and hydrogen 4 are bound together. The HMQC and HSQC commands are equivalent. Commands HMBC and COSY are coded in the same way.

Any easily deduced bond must be given to LSD through a BOND command. It takes the indexes of the bound atoms as parameters. If carbon 1 is that of a keto group and if there is an sp2 oxygen 22, the command BOND 1 22 establishes the bond between atoms 1 and 22.

Unless specified, the order of the commands within a data file has no importance. The text that follows the EXIT command is ignored. Apart from purely NMR derived commands, other commands are needed for execution control. One should prefer to group them at the beginning of the data file. MULT, HMQC, COSY, HMBC, and BOND commands constitute the basic part of LSD data files.

A less trivial part in the writing of LSD data files is the definition of atom properties and of the associated lists. An atom property (PROP command) indicates for an atom or for all atoms in a list the number of neighbors that must be members of another atom list. The number 0 means "all". For example, the chemical shift of the carbon atoms indexed 8, 9 and 10 is about 15 ppm. The hydrogen atoms indexed 8, 9 and 10 are those of methyl groups appearing at about 1 ppm as singlets. Carbons 8, 9 and 10 are most probably bound only to quaternary carbons. You need to build two lists in order to code this constraint with LSD. The first list contains the atoms 8, 9 and 10 while the second one contains all the quaternary carbons. An atom list is described by its index and its content. The content is either explicitely defined (giving the index of all atoms within the list) or using atom status. It is also possible to combine lists according to the operations defined in the set theory. Back to the example, LIST L1 8 9 10 defines list 1 and puts atoms 8, 9 and 10 in it. QUAT L2 defines list 2 and puts all quaternary carbons in it. Once L1 and L2 are defined, the constraint on atoms 8, 9 and 10 is coded by the PROP L1 0 L2 command. It could have also been possible to write PROP L1 1 L2, because a methyl group carbon always has a single neighbor. List and property definition commands are treated in the order they are written in the data file. Changing their order can change their meaning.

A common temptation for beginners is spectra over-interpretation, meaning that non-significant information is introduced. Inconsistent or wrong data leads LSD to fail, producing a message that indicates which is the deepest analysis level reached (the so much hated "max stack level: " message). Introducing nJ COSY or HMBC correlations with n greater than 3 also leads LSD to fail, unless otherwise specified (see below). In order to avoid this unpleasant situation, the weakest COSY and HMBC correlations should be first written as comments, by putting a semicolon at the beginning of the corresponding commands. If the number of found solutions is too big, it's time to remove semicolons to impose more property or correlation constraints to the problem.

New with version 3.1.0: Elimination of invalid HMBC correlations
Two reasons may be invoked if the analysis of a HMBC correlation does not lead to a solution. Either the present state of the molecule is not compatible with the analyzed correlation (case 1), or the correlation itself is invalid (case 2). The latter case arises either by accident (spectral artefact or typing error, for example) or because the correlation arises from a coupling through more than three bonds. In case 1, the resolution mecanism will be able to correct the structure state to produce a solution if the entire data set is correct. In case 2, no correction can lead to a solution. The invalid correlation can now be eliminated to check whether it is responsable for the resolution failure.

The ELIM command provides the maximum number of correlations it is possible to eliminate, so that at least one solution is produced. The ELIM command also provides the maximum allowed number of bonds between the atoms in all eliminated correlations. The latter constraint may be deactivated for the detection of accidentally invalid correlations.

This brief overview of LSD commands will allow users to be more familiar with the writing of data files. However, reading of Data file structure is a mandatory step in the learning of the LSD command language.

Command interpreter

In order to process the content of an LSD input file by typing system commands, Linux and Mac users need to open a "Terminal" application, which is named "Command prompt" in Windows MSDOS.

The syntax of system commands may differ between Linux/Mac and MSDOS.

Both command interpreters indicate that the user may start to type a command by displaying a character string named "prompt".

In the following sections, UNIXprompt$ is the Linux/Mac prompt (Unix-type systems) and DOSprompt$ is the Windows prompt. The commands that follow the simple prompt$ are valid for the two types of command interpreter.

In both cases, use the cd command to set the LSD executable in the current directory.

The Linux/Mac users need to have the current directory (named .) in the list of directories in which the Terminal searches the executable files. This can temporarily be achieved by typing

UNIXprompt$ export PATH=.:$PATH

From data to structures

A data file named "pinene" is provided in the Data folder.
Running LSD on it is simple achieved using:

UNIXprompt$ cp Data/pinene .
DOSprompt$ copy Data\pinene.lsd .

UNIXprompt$ lsd pinene
DOSprompt$ lsd pinene.lsd

LSD writes that 1 solution is found.
A file named pinene.sol is created, containing atom connectivity information.
Any data file named abc or abc.xyz produces a solution file named abc.sol or abc.xyz.sol.
A 2D coordinate file pinene.coo can then be generated:

prompt$ outlsd 6 < pinene.sol > pinene.coo

The outlsd program creates 2D coordinates from connectivities.
The result is viewed using a Postscript® previewer.
Postscript drawings are first produced with:

prompt$ genpos < pinene.coo > pinene.ps

and displayed on screen using:

prompt$ xpsview pinene.ps

if xpsview is the currently available Postscript display program (might be open, gv or gsview64).
A double click on the pinene.ps file icon shows the result as well.

Very quick start

The command:

prompt$ solve pinene

does the whole job in one shot: structure resolution, creation and display of the structure drawings.
It is generally not a good idea to proceed this way with a new data set.
However, this can be done once the data set runs from the command line without any error (see From data to structures).

Drawing improvement

The coordinates generated by outlsd sometime produce drawings that are difficult to read.
A simple program named m_edit was written in order to interactively improve the quality of the structure drawings.
You need to have Tcl/Tk and the wish command installed in order to run M_EDIT (version 8.0 or later).
The command

prompt$ m_edit

launches m_edit.
The File menu allows to read and save files, and to exit from the program. The View menu is used to navigate forward and backward through a set of structures within a file. The supported file formats are .coo (the LSD-specific format) and .sdf.

Using m_edit is very intuitive: atoms are moved using the left mouse button.
There is no multiple atom selection mechanism available yet, sorry.

Molecules are selected by default, as shown by their title, written in black. The Select menu allow to unselect(title in red)/reselect(title in black) molecules. The status of the current molecule can be changed by clicking on the title. Selected molecules can be kept (and the unselected one removed) using the Keep item of the Select menu.

Molecule drawings can be horizontally and vertically flipped using the Arrange menu.
A buffer (Buffer menu) was added, so that a modified molecule set (item Save To) can be retrieved (item Load From).

Data file structure

A data file is made of commands and comments.
The number of commands is limited to 300.
A comment is everything between a ";" and the end of the line.

A command is made of a command mnemonic, generally followed by 1 to 5 parameters.
All parts of a command are separated by spaces. Commands are case-sensitive.
From version 3.2.0 included, the EXIT command may be omitted. If there, everything beyond it is ignored.

All command mnemonics are made of 4 alphanumeric characters.
Some of them end with space characters (^), such as CH^^.

Mnemonics are followed by parameters, separated by blanks.
The parameter types are described using the following symbols:

The parameters of a command are successively referenced by P1, P2, P3, P4 and P5.
The EXIT command is the only one without any parameter.

Basic commands

List definition

The commands that are described here help to define the lists of atoms that are required by the PROP command.
They are interpreted in the order in which they are written.
They are hereafter sorted according to their number of arguments:

Execution control

Substructural information

Solutions found by LSD after correlation analysis and uncomplete atom pairing can be selected according to a substructure constraint.
The substructure constraint is provided by substructure definitions and by the way they are combined.
A substructure is either native (defined in the problem input file, as it was before version 3.2.0), or externally defined.
The Data/pinene file contains an example of substructural constraint coding.

A substructure is a set of sub-atoms (SSTR commands) that are connected by sub-bonds (LINK commands) and eventually pre-assigned (ASGN commands).

An external substructure is referred to by a fragment number and the path to the file that contains its definition. The latter is coded exactly in the same way as it is for a native substructure.

Results of substructure searches are combined together to determine the validity of the current structure:

The DEFF, SKEL, PATH, and FEXP commands implement in LSD the functionnality of solution filtering.
In the absence of FEXP and SKEL commands, the native substructure is taken into account, if it exists.
If a FEXP or SKEL command is present, the native substructure is accessed to via F0 as if a DEFF F0 "..." existed. If no native substructure is defined, F0 is the empty substructure, the one that always matches a structure.
If the parameter of SUBS is 0, no substructure search at all is performed. If it is -1, the result of the evaluation of the logical expression that is provided by the FEXP command is inverted.

The SKEL command associates a fragment number (see DEFF) with a SKELeton name, a name like PINANE that refers to a substructure that fits with pinene and with many other natural compounds.
LSD searches in a user provided sketelon database for a file that describes that skeleton. The fragment number is then associated with the file path that leads to the corresponding LSD substructure file.
The default location of the skeleton database is the Filters directory that comes with the other LSD files. A PATH command replaces the default location of the skeleton database by a new one. Subsequent PATH commands define alternative locations in which skeletons can also be found.
Each time a SKEL command is processed all the defined skeleton database directories are explored and all their embedded sub-directories as well. Each time a file named toc (Table of Contents) is found during this exploration, its contents is scanned. If the searched skeleton name is found at line n of a toc file, then a file named filen must exist in the same directory and should be the substructure description file that corresponds to the desired skeleton.
The PATH command has no influence on the behavior of the DEFF command. A toc file must only contain a single skeleton name per line, a name must not contain a separation character such as a blank or a tab.
A converter named mol2ab is available to help users translate MDL .mol files into LSD substructure description files.

LSD comes with a non-exhaustive collection of natural product skeletons. They are provided as MDL .mol files in the MOL directory so that users could create LSD substructure files at their own convenience using mol2ab. The result of the conversion of all files in the MOL directory is stored in Filters/TERPENES directory.

Creating substructure files with mol2ab

The mol2ab program converts structures in .mol format into substructures for LSD.
Users can convert the .mol files that are supplied with LSD or their personal files, produced by any chemical structure drawing program.
The following rules apply to the conversion process:

Usage:
prompt$ mol2ab Directory pilot-file

The pilot-file must contain lines with two fields:

The Directory must exist and should be empty. It will be filled with the initial .mol files (renamed file1.mol ... filen.mol) and their equivalent LSD files (file1 ... filen) if n is the number of lines in the pilot file.
A toc file is also created so that LSD can retrieve substructure files from skeleton names.

Example: The making of Filters/MONOTERP.
The following commands are written for UNIX-like systems.
The current directory of the command interpreter is initially the one of LSD.
For Windows, the /s must by replaced by \s.

 prompt$  cd MOL
 prompt$  cd Monoterp_mol
 prompt$  mkdir MONOTERP
 prompt$  ../../mol2ab MONOTERP ../monoterp_mol.txt

Result processing with outlsd

In order to use outlsd, LSD must not be run with DISP 0.
The outlsd program reads from and writes to standard devices.
It takes an integer n comprised between 1 and 10 as argument.

prompt$ outlsd 7 < pinene.sol > pinene.sdf

Depending on n, the result contains

Options 2, 3 and 4 are not available anymore, starting from version 3.4.1.

Result viewing with genpos

The option 6 of outlsd produces an output that starts with the magic word DRAW, in a format suitable for its treatment by the genpos program. genpos reads and writes from standard devices and generates PostScript instructions.

prompt$ genpos < pinene.coo > pinene.ps

The resulting file can be opened by Postscript previewers or be sent to Postscript printers.

Copyright(C)2000 CNRS-UMR 7312-Jean-Marc Nuzillard