deploy: 38943a7

_sources/docs/3DStructureGen/Overview.rst.txt

@@ -0,0 +1,10 @@
+3D Structure Generation
+=======================
+
+Open Babel provides support for generating a reasonable 3D structure just given connectivity information. It also has the ability to generate multiple conformers for each molecule. These topics are discussed below.
+
+.. toctree::
+
+   SingleConformer.rst
+   multipleconformers.rst
+

_sources/docs/3DStructureGen/SingleConformer.rst.txt

@@ -0,0 +1,104 @@
+Generate a single conformer
+===========================
+
+There are several steps involved in generating a low-energy conformer from a 0D or 2D structure.
+
+OBBuilder
+---------
+
+The :obapi:`OBBuilder` class is the part of Open Babel that can take a
+2D or 0D structure and generate a 3D structure. The 3D structure is
+made very quickly using a combination of rules (e.g. sp\ :sup:`3`\  atoms should have four bonds arranged in a tetrahedron) and common fragments (e.g. cyclohexane is shaped like a chair).
+
+The 3D structures that come straight out of OBBuilder may be useful for some purposes but most people will want to "clean them up". This is because they may have clashes or have high energy structures due to some strain. The conformer search or geometry optimization methods described below are typically used after calling OBBuilder.
+
+Full discussion of the methods for coordinate generation is available in 'Fast, efficient fragment-based coordinate generation for Open Babel' `*J. Cheminf.* (2019) **11**, Art. 49.<https://doi.org/10.1186/s13321-019-0372-5>`. Please cite this paper if you use the coordinate generation features in Open Babel.
+
+The functionality of OBBuilder is not directly available through **obabel** but it is used as the necessary first step of the Gen3D operation discussed below.
+
+Conformer searching
+-------------------
+
+Given a 3D structure, the goal of conformer searching is to find a low energy conformation. This may be useful as a "clean-up" procedure after an initial 3D structure generation. Note that conformer searching does not alter stereochemistry.
+
+The Open Babel library provides access to several algorithms for conformer searching. All of these algorithms adopt the torsion-driving approach; that is, conformations are generated by setting torsion angles to one of a number of allowed values. The allowed values are listed in the data file :file:`torlib.txt`; for example, C-C bonds in alkanes have three allowed values: -60, 60 and 180.
+
+1. :obapi:`Systematic Rotor Search <SystematicRotorSearch>`: Systematically
+   iterate through all possible
+   conformers according to Open Babel's torsion library.
+   This approach is thorough and will
+   find the global minimum. However as
+   the number of conformations increases by multiples for each additional
+   rotational bond, this can take quite a while for molecules with even just
+   7 rotatable bonds. This approach scales to the power of N, where N is the
+   number of rotatable bonds.
+
+2. :obapi:`Fast Rotor Search <FastRotorSearch>`: This iterates through the
+   same conformer space as the
+   SystematicRotorSearch but it greedily optimises the torsion angle at each
+   rotatable bond in turn, starting from the most central. Thus it scales
+   linearly with the number of rotatable bonds.
+
+3. :obapi:`Random Rotor Search <RandomRotorSearch>`: Conformations are
+   generated by randomly choosing from the allowed torsion angles.
+
+4. :obapi:`Weighted Rotor Search <WeightedRotorSearch>`: This method uses an
+   iterative procedure to find a
+   global minimum. As with the Random Rotor Search, it randomly choses from
+   the allowed torsion angles but the choice is reweighted based on the energy
+   of the generated conformer. Over time, the generated conformer for each
+   step should become increasingly better.
+
+For each of these methods, the lowest energy conformation found is selected. In some cases, the entire set of conformations generated is also available. Many
+of these methods include an option to optimize the geometry of conformations
+during the search. This greatly slows down the procedure but may produce more
+accurate results.
+
+The choice of which algorithm to use depends on the speed/accuracy tradeoff with
+which you are happy, and also on the number of rotatable bonds in the molecule.
+Are you looking for a reasonable structure for 3D display? Or are you looking
+for a structure close to the global minimum?
+
+To use from **obabel**, see the help for the conformer operation (``obabel -L conformer``). This operation is used both for conformer searching and for the genetic algorithm conformer generation described below.
+
+Here is an example of use from Python:
+
+::
+
+    >>> ff = ob.OBForceField.FindForceField("mmff94")
+    >>> ff.Setup(obmol)
+    True
+    >>> print(ff.Energy())
+    15.179054202
+    >>> ff.SystematicRotorSearch(100)
+    >>> print(ff.Energy())
+    10.8861155747
+
+Gen3D
+-----
+
+To illustrate how some of the above methods might be used in practice, consider the **gen3d** operation. This operation (invoked using ``--gen3d`` at the commandline) generates 3D structures for 0D or 2D structures using the following series of steps, all of which have been described above:
+
+1. Use the OBBuilder to create a 3D structure using rules and fragment templates
+
+2. Do 250 steps of a steepest descent geometry optimization with the MMFF94
+   forcefield
+
+3. Do 200 iterations of a Weighted Rotor conformational search (optimizing each
+   conformer with 25 steps of a steepest descent)
+
+4. Do 250 steps of a conjugate gradient geometry optimization
+
+Taken together, all of these steps ensure that the generated structure is likely to be the global minimum energy conformer. However, for many applications where 100s if not 1000s of molecules need to be processed, gen3d is rather slow:
+
+ 1. ``--fastest``  only generate coordinates, no force field or conformer search
+
+ 2. ``--fast``  perform quick forcefield optimization
+
+ 3. ``--medium`` **(default)** forcefield optimization + fast conformer search
+
+ 4. ``--better`` more optimization + fast conformer search
+
+ 5. ``--best`` more optimization + significant conformer search
+
+Details on some of the trade-offs involved are outlined in 'Fast, efficient fragment-based coordinate generation for Open Babel' `*J. Cheminf.* (2019) **11**, Art. 49.<https://doi.org/10.1186/s13321-019-0372-5>`. If you use the 3D coordinate generation, please cite this paper.

_sources/docs/3DStructureGen/multipleconformers.rst.txt

@@ -0,0 +1,121 @@
+Generate multiple conformers
+============================
+
+In contrast to conformer searching, the goal of conformer generation is not simply to find a low energy conformation but to generate several different conformations. Such conformations may be required by another piece of software such as some protein-ligand docking and pharmacophore programs. They may also be useful if considering writing some sort of shape comparison method.
+
+Open Babel has two distinct conformer generating codes:
+
+1. Confab: A systematic conformer generator that generates all diverse
+   low-energy conformers.
+
+2. Genetic algorithm: This is a stochastic conformer generator that generates
+   diverse conformers either on an energy or RMSD basis
+
+Genetic algorithm
+-----------------
+
+A genetic algorithm is a general computational method to find a globally optimum solution to some multiparameter problem. It involves a population of conformers which after a series of generations, iteratively arrive at an optimal solution in terms of either RMSD diversity or energy.
+
+Information about using this method is available at the command-line using: ``obabel -L conformer``. Although labelled as "Conformer Searching", if you choose the genetic algorithm method (which is the default) then you can save the conformers in the final generation using ``--writeconformers``. For example, the following line creates 30 conformers optimized for RMSD diversity::
+
+  obabel startingConformer.mol -O ga_conformers.sdf --conformer --nconf 30
+         --score rmsd --writeconformers
+
+In this case ``--score rmsd`` was not strictly necessary as RMSD diversity was the default in any case.
+
+.. _Confab:
+
+Confab
+------
+
+Confab systematically generates all diverse low-energy conformers for molecules. To run Confab use the ``--confab`` operation, and to assess the results by calculating RMSDs to reference structures, use the **confabreport** output format.
+
+.. rubric:: confab operator
+
+*  ``obabel <inputfile> -O <outputfile> --confab [confab options]`` for typical usage
+*  ``obabel -L confab`` for help text
+
+The *inputfile* should contain one or more 3D structures (note that 2D structures will generate erroneous results). Generated conformers are written to the *outputfile*. All of the conformers for a particular molecule will have the same title as the original molecule.
+
+--rcutoff <rmsd>
+    RMSD cutoff (default 0.5 Angstrom)
+--ecutoff <energy>
+    Energy cutoff (default 50.0 kcal/mol)
+--conf <#confs>
+    Max number of conformers to test (default is 1 million)
+--original
+    Include the input conformation as the first conformer
+--verbose
+    Verbose - display information on torsions found
+
+.. rubric:: confabreport format
+
+*  ``obabel <inputfile> [-O <outputfile>] -o confabreport -xf <reference_file> [-xr <rmsd>]`` for typical usage
+*  ``obabel -L confabreport`` for help text
+
+Once a file containing conformers has been generated by Confab, the result can be compared to the original input structures or a set of reference structures using this output format. Conformers are matched with reference structures using the molecule title. For every conformer, there should be a reference structure (but not necessarily *vice versa*).
+
+-f <filename>
+     File containing reference structures
+-r <rmsd>
+     RMSD cutoff (default 0.5 Angstrom)
+
+     The number of structures with conformers within this RMSD cutoff
+     of the reference will be reported.
+
+.. rubric:: Example
+
+The example file, `bostrom.sdf`_, contains 36 molecules which have from 1 to 11 rotatable bonds (see *Bostrom, Greenwood, Gottfries, J Mol Graph Model, 2003, 21, 449*).
+
+We can generate and test up to 100K conformers using Confab as follows::
+
+  > obabel bostrom.sdf -O confs.sdf --confab --conf 100000
+
+  **Starting Confab 1.1.0
+  **To support, cite Journal of Cheminformatics, 2011, 3, 8.
+  ..Input format = sdf
+  ..Output format = sdf
+  ..RMSD cutoff = 0.5
+  ..Energy cutoff = 50
+  ..Conformer cutoff = 1000000
+  ..Write input conformation? False
+  ..Verbose? False
+
+  **Molecule 1
+  ..title = 1a28_STR_1_A_1__C__
+  ..number of rotatable bonds = 1
+  ..tot conformations = 12
+  ..tot confs tested = 12
+  ..below energy threshold = 10
+  ..generated 3 conformers
+
+  ... etc, etc
+
+  0 molecules converted
+
+To check how many of the generated conformers are within 1.0 A RMSD of the original structures, we can use the confabreport format as follows::
+
+  > obabel confs.sdf -oconfabreport -xf bostrom.sdf -xr 1.0
+
+  **Generating Confab Report
+  ..Reference file = bostrom.sdf
+  ..Conformer file = confs.sdf
+
+  ..Molecule 1
+  ..title = 1a28_STR_1_A_1__C__
+  ..number of confs = 3
+  ..minimum rmsd = 0.0644801
+  ..confs less than cutoffs: 0.2 0.5 1 1.5 2 3 4 100
+  ..1 1 3 3 3 3 3 3
+  ..cutoff (1) passed =  Yes
+
+  ... etc, etc
+
+  **Summary
+  ..number of molecules = 36
+  ..less than cutoff(1) = 35
+  52271 molecules converted
+
+.. _bostrom.sdf: ../_static/bostrom.sdf
+
+

_sources/docs/Aromaticity/Aromaticity.rst.txt

@@ -0,0 +1,73 @@
+.. include:: <isolat1.txt>
+
+.. |kekule| replace:: Kekul\ |eacute|
+
+Handling of aromaticity
+=======================
+
+The purpose of this section is to give an overview of how Open Babel handles aromaticity. Given that atoms can be aromatic, bonds can be aromatic, and that molecules have a flag for aromaticity perceived, it's important to understand how these all work together.
+
+How is aromaticity information stored?
+--------------------------------------
+
+Like many other toolkits, Open Babel stores aromaticity information separate from bond order information. This means that there isn't a special bond order to indicate aromatic bond. Instead, aromaticity is stored as a flag on an atom as well as a flag on a bond. You can access and set this information using the following API functions:
+
+* OBAtom::IsAromatic(), OBAtom::SetAromatic(), OBBond::UnsetAromatic()
+* OBBond::IsAromatic(), OBBond::SetAromatic(), OBBond::UnsetAromatic()
+
+There is a catch though, or rather a key point to note. OBMols have a flag to indicate whether aromaticity has been perceived. This is set via the following API functions:
+
+* OBMol::SetAromaticPerceived(), OBMol::UnsetAromaticPerceived()
+
+The value of this flag determines the behaviour of the OBAtom and OBBond IsAromatic() functions.
+
+* If the flag is set, then IsAromatic() simply returns the corresponding value of the atom or bond flag. 
+* If unset, then IsAromatic() triggers aromaticity perception (from scratch), and then returns the value of the flag.
+
+Perception of aromaticity
+-------------------------
+
+It's convenient to use the term "perception", but what we mean is to apply an aromaticity model. Currently Open Babel only has a single aromaticity model, which is close to the Daylight aromaticity model. An aromaticity model describes how many pi electrons are contributed by each atom; if this sums to 4n+2 within a cycle, then all atoms and bonds in that cycle will be marked as aromatic.
+
+Applying a model involves creating an instance of OBAromaticTyper(), and calling AssignAromaticFlags() passing an OBMol as a parameter. This wipes any existing flags, sets the atom and bond flags according to the model, and marks the aromaticity as perceived.
+
+If you wish (and know what you are doing), you can apply your own aromaticity model by setting various atoms and bonds as aromatic and then marking the molecule as having aromaticity perceived. Naturally, not all models will make sense chemically. Even more problematic is the situation where no |kekule| form exists that corresponds to the aromatic form. And finally, there is the philosophical question of the meaning of an aromatic atom without aromatic bonds, and vice versa.
+
+SMILES reading and writing
+--------------------------
+
+Putting the pieces together, let's look at the interaction between SMILES reading/writing and the handling of aromaticity.
+
+.. rubric:: Writing SMILES
+
+Unless |kekule| SMILES are requested (via the ``k`` output option), the SMILES writer will always write an aromatic SMILES string. IsAromatic() will be called on atoms and bonds to determine whether to use lowercase letters. As described earlier, this will trigger aromaticity perception according to the default model if the molecules is not marked as having its aromaticity perceived.
+
+.. rubric:: Reading SMILES
+
+The situation when reading SMILES is a bit more involved. If the SMILES string contains lowercase characters and aromatic bonds, this information is used to mark atoms and bonds as aromatic. The molecule is then kekulized to assign bond orders to aromatic bonds. Next, unless the ``a`` option is supplied, the molecule is marked as having its aromaticity unperceived.
+
+That last step might seem strange. Why, after going to the trouble of reading the aromaticity and using it to kekulize, do we then effectively ignore it?
+
+The reason is simply this: when writing an aromatic SMILES, we usually want to use our own aromaticity model and not that present in the input SMILES string. Otherwise, SMILES strings for the same molecule from different sources (that may use different aromaticity models) would not yield the same canonical SMILES string.
+
+Of course, if the SMILES string came from Open Babel in the first place, we are doing unnecessary work when we keep reapplying the same aromaticity model. In this case, you can speed things up by using the ``a`` option, so that the aromaticity information present in the input is retained. The following examples show this in action::
+
+  $ obabel -:cc -osmi
+  C=C
+  $ obabel -:cc -osmi -aa
+  cc
+
+Effect of modifying the structure
+---------------------------------
+
+Perhaps surprisingly, modifying the structure has no effect on the existing aromaticity flags; deleting an atom does not mark aromaticity as unperceived, nor indeed does any other change to the structure such as changing the atomic number of an atom or setting its charge; nor does the use of Begin/EndModify() affect the aromaticity flags. The only way to ensure that aromaticity is reperceived after modifying the structure is to explicitly mark it as unperceived.
+
+The rationale for this is that an efficient toolkit should avoid unnecessary work. The toolkit does not know if a particular modification invalidates any aromaticity already perceived, or even if it did know, it cannot know whether the user actually wishes to invalidate it. It's up to the user to tell the toolkit. This places more responsibility in the hands of the user, but also more power.
+
+To illustrate, let's consider what happens when the user reads benzene from the SMILES string ``c1ccccc1``, and then modifies the structure by deleting an aromatic atom.
+
+As this is an aromatic SMILES string, the SMILES reader will mark all atoms and bonds as aromatic. Next, the molecule itself is marked as not having aromaticity perceived (see previous section). After reading, we can trigger aromaticity perception by calling IsAromatic() on an atom; now, in addition to the atoms and bonds being marked as aromatic, the molecule itself will be marked as having aromaticity perceived.
+
+If at this point we delete a carbon and write out a SMILES string, what will the result be? You may expect something like ``[CH]=CC=C[CH]`` (or ``C=CC=CC`` if we also adjust the hydrogen count on the neighbor atoms) but instead it will be ``[cH]ccc[cH]`` (or ``ccccc`` if hydrogens were adjusted).
+
+This follows from the discussion above - structural modifications have no effect on aromaticity flags. If instead the user wishes the SMILES writer to reperceive aromaticity, all that is necessary is to mark the molecule as not having aromaticity perceived, in which case the |kekule| form will instead be obtained.

_sources/docs/Charges/charges.rst.txt

@@ -0,0 +1,33 @@
+Charge models
+=============
+
+Insert text here.
+
+.. INSERT AUTOMATICALLY GENERATED CONTENT BELOW
+
+Cheminformatics charge models
+-----------------------------
+
+.. rubric:: Assign Gasteiger-Marsili sigma partial charges (gasteiger)
+
+
+
+.. rubric:: Assign MMFF94 partial charges (mmff94)
+
+
+
+Special charge models
+---------------------
+
+.. rubric:: Assign Electronegativity Equilization Method (EEM) atomic partial charges (eem)
+
+
+
+.. rubric:: Assign QEq (charge equilibration) partial charges (Rappe and Goddard, 1991) (qeq)
+
+
+
+.. rubric:: Assign QTPIE (charge transfer, polarization and equilibration) partial charges (Chen and Martinez, 2007) (qtpie)
+
+
+