Merge pull request #43 from martimunicoy/devel

Release 0.3.0

docs/charge.rst

@@ -18,3 +18,4 @@ Primary objects
 
     Am1bccCalculator
     GasteigerCalculator
+    OPLSChargeCalculator

docs/examples.rst

@@ -0,0 +1,2 @@
+.. _examples ::
+.. mdinclude:: ../examples/README.md

docs/index.rst

@@ -14,6 +14,8 @@ User guide
 
   installation
   releasehistory
+  usage
+  examples
 
 
 API documentation

docs/installation.rst

@@ -81,3 +81,41 @@ installed and have to be installed manually such as:
 - AmberTools
 
 For this reason, the installation through `conda` is recommended.
+
+
+External dependencies
+=====================
+
+Some of the functionalities of `offpele` require external dependencies.
+They are normally included with the standard `conda` installation, as
+explained above. However, the Schrodinger toolkit must be installed
+manually. It is only required when combining `Open Force Field` parameters
+with `OPLS2005` (as it uses the Schrodinger's `ffld_server`). Nevertheless,
+in case that Schrodinger dependencies are missing, `offpele` can still be
+employed to generate pure `Open Force Field` parameters.
+
+The easiest way to get a valid Schrodinger installation is downloading
+`Free Maestro <https://www.schrodinger.com/freemaestro>`_. It can be
+installed in both platforms that are supported by `offpele`: Linux and
+MacOS. Once installed, `offpele` will need an environment variable to be
+set in order to known the Schrodinger's installation path. So, please,
+check that the following environment variable is set before running
+`offpele` if you plant to work with `OPLS2005` parameters:
+
+.. code-block:: bash
+
+   $ export SCHRODINGER=/path/to/Schrodinger/installation/
+
+For example, in MacOS, a typical installation path is
+`/opt/schrodinger/suites2020-2/`. Therefore:
+
+.. code-block:: bash
+
+   $ export SCHRODINGER=/opt/schrodinger/suites2020-2/
+
+This variable must be set every time `offpele` is employed to work with
+`OPLS2005` parameters in a new console session. To avoid future concerns about
+this issue, you can set the environment variable automatically every time you
+initiate a bash session in your console. You can do so by modifying your
+`.bashrc`, `.bash_profile` or `.zshrc` (in case of a `zsh` shell) by adding the
+line above.

docs/releasehistory.rst

@@ -18,19 +18,23 @@ New features
 - `PR #28 <https://github.com/martimunicoy/offpele/pull/28>`_: Adds a new method to define a `Molecule` object through a SMILES tag. This molecule can be written as a PDB file later for PELE.
 - `PR #31 <https://github.com/martimunicoy/offpele/pull/31>`_: Adds the possibility to combine nonbonding and solvent parameters from OPLS2005 with bonding parameters from OFF.
 - `PR #36 <https://github.com/martimunicoy/offpele/pull/36>`_: Minor changes to improve the quality of the code.
-- `PR #37 <https://github.com/martimunicoy/offpele/issues/37>`_: Adds a new partial charge calculator that uses OPLS2005 to assign partial charges. Includes new flags in the CLI from main.py to combine bonding and nonbonding parameters and partial charges from OPLS2005.
+- `PR #38 <https://github.com/martimunicoy/offpele/pull/38>`_: Adds a new partial charge calculator that uses OPLS2005 to assign partial charges. Includes new flags in the CLI from main.py to combine bonding and nonbonding parameters and partial charges from OPLS2005.
+- `PR #42 <https://github.com/martimunicoy/offpele/pull/42>`_: Improves the documentation, adding a section specific for CLI-usage and API examples.
+- `PR #46 <https://github.com/martimunicoy/offpele/pull/46>`_: Adds a tag to Molecule class. Besides, the handling of Molecule names is improved. Both attributes can be set when initiating the molecule.
 
 Bugfixes
 """"""""
 - `PR #22 <https://github.com/martimunicoy/offpele/pull/22>`_: Fixes many bugs. For example, the default output name of the solvent parameters template is changed to `ligandParams.txt`, which is the name that PELE expects.
 - `PR #32 <https://github.com/martimunicoy/offpele/pull/32>`_: Minor fixes in ToolkitWrapper classes.
 - `PR #34 <https://github.com/martimunicoy/offpele/pull/34:>`_: Improves the translation of dihedrals coming from the Open Force Fielf Toolkit and corrects the lack of exclusions in PELE 1-4 list that result from Impact's dihedral definitions.
+- `PR #46 <https://github.com/martimunicoy/offpele/pull/46>`_: Prevents molecule to be untagged when loading it from a SMILES tag.
 
 Tests added
 """""""""""
 - `PR #31 <https://github.com/martimunicoy/offpele/pull/31>`_: Adds tests to validate some functions of the new SchrodingerToolkitWrapper.
 - `PR #34 <https://github.com/martimunicoy/offpele/pull/34>`_: Adds tests to further validate the assignment of parameters from the Open Force Field Toolkit.
-- `PR #37 <https://github.com/martimunicoy/offpele/issues/37>`_: Adds tests to validate the new OPLS charge calculator.
+- `PR #38 <https://github.com/martimunicoy/offpele/pull/38>`_: Adds tests to validate the new OPLS charge calculator.
+- `PR #46 <https://github.com/martimunicoy/offpele/pull/46>`_: Adds tests to validate the name and tag assignment to Molecule class.
 
 
 0.2.1

docs/usage.rst

@@ -0,0 +1,232 @@
+.. _installation ::
+
+Generate PELE parameter files
+*****************************
+
+The main purpose of `offpele` is to build the parameter files for PELE. Basically, PELE requires two files for each non-standard residue found in the system:
+
+- `IMPACT template <https://eapm-bsc.github.io/PELE-repo/fileFormats.html#impact-template-file-format>`_: a file containing the atom types and parameters of the ligand. Its job is to link each atom with the corresponding parameters using PDB atom names. Thus, PDB atom names in the input PDB file must match with the expected PDB atom names in the Impact file. This file intrinsically contains the information about the topology and connectivity of each residue.
+
+- `Rotamer library <https://eapm-bsc.github.io/PELE-repo/fileFormats.html#ligand-rotamer-library-file>`_: a file containing the branches that can rotate with respect to a central atomic core. Each branch consists in a set of consecutive rotatable bonds.
+
+Besides, a third file with the `Solvent parameters` might be required when employing the OBC implicit solvent.
+
+.. image:: figures/PELE_templates_scheme.png
+  :width: 400
+  :alt: Scheme with all the files that PELE requires to run a simulation
+
+The `Open Force Field Toolkit <https://github.com/openforcefield/openforcefield>`_ is employed to assign the parameters to each atom according to its chemical environment. Besides, the PDB atom names are stored using `RDKit <https://www.rdkit.org>`_. With this dual molecular representation, `offpele` can run the parameterization workflow of Open Force Field while tracking the PDB atom names with RDKit.
+
+.. image:: figures/dual_representation.png
+  :width: 400
+  :alt: Scheme with the dual molecular representation employed in offpele
+
+
+Basic usage
+===========
+The more straightforward way to install `offpele` along with the required dependencies is through the command-line interface built in `main.py <https://github.com/martimunicoy/offpele/blob/master/offpele/main.py>`_ module. Therefore, the parameter files for a particular ligand can be obtained with:
+
+.. code-block:: bash
+
+   $ python -m offpele.main my_ligand.pdb
+
+.. code-block::
+
+     ------------------------------------------------------------
+     Open Force Field parameterizer for PELE v0.3.0
+     ------------------------------------------------------------
+      - General:
+        - Input PDB: my_ligand.pdb
+        - Output path: None
+        - Write solvent parameters: False
+        - DataLocal-like output: False
+      - Parameterization:
+        - Force field: openff_unconstrained-1.2.0.offxml
+        - Charges method: am1bcc
+        - Use OPLS nonbonding parameters: False
+        - Use OPLS bonds and angles: False
+      - Rotamer library:
+        - Resolution: 30
+        - Exclude terminal rotamers: True
+     ------------------------------------------------------------
+      - Loading molecule from RDKit
+      - Generating rotamer library
+      - Loading forcefield
+      - Computing partial charges with am1bcc
+      - All files were generated successfully
+     ------------------------------------------------------------
+
+Command-line arguments
+======================
+Almost all the important settings can be tuned up through command-line
+arguments. To obtain the full list of flags you can type:
+
+.. code-block:: bash
+
+   $ python -m offpele.main --help
+
+.. code-block::
+
+     usage: main.py [-h] [-f NAME] [-r INT] [-o PATH] [--with_solvent]
+                    [--as_DataLocal] [-c NAME] [--include_terminal_rotamers]
+                    [--use_OPLS_nonbonding_params] [--use_OPLS_bonds_and_angles]
+                    PDB FILE
+
+     positional arguments:
+       PDB FILE              Path PDB file to parameterize
+
+     optional arguments:
+       -h, --help            show this help message and exit
+       -f NAME, --forcefield NAME
+                             OpenForceField\'s forcefield name. Default is
+                             openff_unconstrained-1.2.0.offxml
+       -r INT, --resolution INT
+                             Rotamer library resolution in degrees. Default is 30
+       -o PATH, --output PATH
+                             Output path. Default is the current working directory
+       --with_solvent        Generate solvent parameters for OBC
+       --as_DataLocal        Output will be saved following PELE's DataLocal
+                             hierarchy
+       -c NAME, --charges_method NAME
+                             The name of the method to use to compute charges
+       --include_terminal_rotamers
+                             Not exclude terminal rotamers when building the
+                             rotamer library
+       --use_OPLS_nonbonding_params
+                             Use OPLS to set the nonbonding parameters
+       --use_OPLS_bonds_and_angles
+                             Use OPLS to set the parameters for bonds and angles
+
+Find below the complete list of command-line arguments in full detail.
+
+PDB file
+--------
+It is a mandatory positional argument that points to the PDB file which
+contains ligand to parameterize.
+
+- Flag: PDB FILE
+- Type: string
+- Example: the code below will run `offpele` to parameterize the ligand at `path/to/my_ligand.pdb`
+
+  .. code-block:: bash
+
+        $ python -m offpele.main path/to/my_ligand.pdb
+
+Force field
+-----------
+It defines the Open Force Field force field to employ to parameterize the ligand.
+
+- Flag: -f NAME, --forcefield NAME
+- Type: string
+- Default: 'openff_unconstrained-1.2.0.offxml'
+- Example: the code below will run offpele using the forcefield named as 'openff_unconstrained-1.0.0.offxml'
+
+  .. code-block:: bash
+
+        $ python -m offpele.main path/to/my_ligand.pdb -f openff_unconstrained-1.0.0.offxml
+
+Rotamer library resolution
+--------------------------
+It defines the resolution, in degrees, to use in the rotamer library.
+
+- Flag: -r INT, --resolution INT
+- Type: int
+- Default: 30
+- Example: the code below will run offpele using a resolution of 60 for the rotamer library
+
+  .. code-block:: bash
+
+        $ python -m offpele.main path/to/my_ligand.pdb -r 60
+
+Output path
+-----------
+It defines the output path where the resulting files will be saved.
+
+- Flag: -o PATH, --output PATH
+- Type: string
+- Default: '.', the current working directory
+- Example: the code below will save the results into my_custom_folder/
+
+  .. code-block:: bash
+
+        $ python -m offpele.main path/to/my_ligand.pdb -o my_custom_folder
+
+Include solvent parameters
+--------------------------
+It also generates the OBC solvent parameters and saves them into the output location.
+
+- Flag: --with_solvent
+- Default: False, not include
+- Example: the code below will generate and save the OBC solvent parameters
+
+  .. code-block:: bash
+
+        $ python -m offpele.main path/to/my_ligand.pdb --with_solvent
+
+Save output as DataLocal
+------------------------
+It saves the output files following the DataLocal hierarchy expected by PELE.
+
+- Flag: --as_DataLocal
+- Default: False, not save output files as DataLocal
+- Example: the code below will generate and save output files following the DataLocal hierarcy of PELE
+
+  .. code-block:: bash
+
+        $ python -m offpele.main path/to/my_ligand.pdb --as_DataLocal
+
+Charges method
+--------------
+It sets the method to compute the partial charges.
+
+- Flag: -c NAME, --charges_method NAME
+- Type: string
+- Choices: one of ['gasteiger', 'am1bcc', 'OPLS']
+- Default: 'am1bcc'
+- Example: the code below will calculate partial charges using 'gasteiger' method
+
+  .. code-block:: bash
+
+        $ python -m offpele.main path/to/my_ligand.pdb -c gasteiger
+
+Include terminal rotamers
+-------------------------
+It always includes terminal rotamers, even if they belong to a terminal methyl group whose rotation is trivial in PELE.
+
+- Flag: --include_terminal_rotamers
+- Default: False, exclude terminal rotamers
+- Example: the code below will generate a rotamer library including all terminal rotamers
+
+  .. code-block:: bash
+
+        $ python -m offpele.main path/to/my_ligand.pdb --include_terminal_rotamers
+
+Parameterize non-bonding terms with OPLS2005
+--------------------------------------------
+  .. warning::
+      This option requires a valid Schrodinger installation with the ffld_server. An environment variable called `SCHRODINGER` must be set, pointing to the Schrodinger's installation path.
+
+It uses `OPLS2005` to parameterize the non-bonding terms of the ligand. It also assigns the atom types according to this force field.
+
+- Flag: --use_OPLS_nonbonding_param
+- Default: False, exclude terminal rotamers
+- Example: the code below will parameterize the non-bonding terms with OPLS2005
+
+  .. code-block:: bash
+
+        $ python -m offpele.main path/to/my_ligand.pdb --use_OPLS_nonbonding_param
+
+Parameterize bonding and angular terms with OPLS2005
+----------------------------------------------------
+  .. warning::
+      This option requires a valid Schrodinger installation with the ffld_server. An environment variable called `SCHRODINGER` must be set, pointing to the Schrodinger's installation path.
+
+It uses `OPLS2005` to parameterize the bonds and angle terms of the ligand.
+
+- Flag: --use_OPLS_bonds_and_angles
+- Default: False, exclude terminal rotamers
+- Example: the code below will parameterize the non-bonding, bonding and angular terms with OPLS2005
+
+  .. code-block:: bash
+
+        $ python -m offpele.main path/to/my_ligand.pdb --use_OPLS_nonbonding_param --use_OPLS_bonds_and_angles

examples/OFF_parameterization/ANI.pdb

@@ -0,0 +1,26 @@
+HETATM    1  C1  UNL     1       2.707   0.165  -0.078  1.00  0.00           C  
+HETATM    2  O1  UNL     1       1.710  -0.820  -0.275  1.00  0.00           O  
+HETATM    3  C2  UNL     1       0.352  -0.469  -0.131  1.00  0.00           C  
+HETATM    4  C3  UNL     1      -0.647  -1.401  -0.315  1.00  0.00           C  
+HETATM    5  C4  UNL     1      -1.973  -1.045  -0.172  1.00  0.00           C  
+HETATM    6  C5  UNL     1      -2.345   0.254   0.161  1.00  0.00           C  
+HETATM    7  C6  UNL     1      -1.347   1.190   0.345  1.00  0.00           C  
+HETATM    8  C7  UNL     1      -0.016   0.821   0.198  1.00  0.00           C  
+HETATM    9  H1  UNL     1       3.654  -0.234  -0.494  1.00  0.00           H  
+HETATM   10  H2  UNL     1       2.497   1.105  -0.608  1.00  0.00           H  
+HETATM   11  H3  UNL     1       2.823   0.325   1.034  1.00  0.00           H  
+HETATM   12  H4  UNL     1      -0.383  -2.426  -0.576  1.00  0.00           H  
+HETATM   13  H5  UNL     1      -2.775  -1.768  -0.313  1.00  0.00           H  
+HETATM   14  H6  UNL     1      -3.399   0.508   0.268  1.00  0.00           H  
+HETATM   15  H7  UNL     1      -1.614   2.218   0.607  1.00  0.00           H  
+HETATM   16  H8  UNL     1       0.757   1.578   0.349  1.00  0.00           H  
+CONECT    1    2    9   10   11
+CONECT    2    3
+CONECT    3    4    4    8
+CONECT    4    5   12
+CONECT    5    6    6   13
+CONECT    6    7   14
+CONECT    7    8    8   15
+CONECT    8   16
+END
+

examples/OFF_parameterization/BNZ.pdb

@@ -0,0 +1,53 @@
+HEADER    HYDROLASE                               16-AUG-14   4W52
+REMARK   4 4W52 COMPLIES WITH FORMAT V. 3.30,
+REMARK 888
+REMARK 888 WRITTEN BY MAESTRO (A PRODUCT OF SCHRODINGER, LLC)
+TITLE     T4 LYSOZYME L99A WITH BENZENE BOUND
+EXPDTA    X-RAY DIFFRACTION
+REMARK   2 RESOLUTION.    1.50 ANGSTROMS
+REMARK   3  R VALUE : 0.165000
+REMARK   3  FREE R VALUE : 0.182000
+REMARK 200  TEMPERATURE           (KELVIN) : 100.00
+REMARK 200  PH                             : 7.50
+REMARK 350 BIOMOLECULE: 1
+REMARK 350 APPLY THE FOLLOWING TO CHAINS: A
+REMARK 350   BIOMT1  1   1.000000 0.000000 0.000000   0.000000
+REMARK 350   BIOMT2  1   0.000000 1.000000 0.000000   0.000000
+REMARK 350   BIOMT3  1   0.000000 0.000000 1.000000   0.000000
+CRYST1   60.350   60.350   96.610  90.00  90.00 120.00 P 32 2 1      6
+HET    BNZ  L   1      12
+HETNAM     BNZ BENZENE
+FORMUL   1  BNZ    C6 H6
+MODEL        1
+HETATM    1  C1  BNZ L   1     -32.969   6.196   2.877  0.70 15.06           C  
+HETATM    2  C2  BNZ L   1     -32.945   7.046   3.973  0.70 12.84           C  
+HETATM    3  C3  BNZ L   1     -33.719   6.798   5.113  0.70 12.24           C  
+HETATM    4  C4  BNZ L   1     -34.540   5.680   5.143  0.70 13.09           C  
+HETATM    5  C5  BNZ L   1     -34.545   4.825   4.044  0.70 12.54           C  
+HETATM    6  C6  BNZ L   1     -33.787   5.069   2.915  0.70 14.23           C  
+HETATM    7  H1  BNZ L   1     -32.360   6.413   2.012  1.00  0.00           H  
+HETATM    8  H2  BNZ L   1     -32.318   7.925   3.961  1.00  0.00           H  
+HETATM    9  H3  BNZ L   1     -33.672   7.473   5.955  1.00  0.00           H  
+HETATM   10  H4  BNZ L   1     -35.158   5.487   6.007  1.00  0.00           H  
+HETATM   11  H5  BNZ L   1     -35.156   3.935   4.055  1.00  0.00           H  
+HETATM   12  H6  BNZ L   1     -33.823   4.399   2.069  1.00  0.00           H  
+CONECT    1    2    6    7
+CONECT    1    2
+CONECT    2    1    3    8
+CONECT    2    1
+CONECT    3    2    4    9
+CONECT    3    4
+CONECT    4    3    5   10
+CONECT    4    3
+CONECT    5    4    6   11
+CONECT    5    6
+CONECT    6    1    5   12
+CONECT    6    5
+CONECT    7    1
+CONECT    8    2
+CONECT    9    3
+CONECT   10    4
+CONECT   11    5
+CONECT   12    6
+ENDMDL
+END