documentation update

README.md

@@ -4,11 +4,16 @@
 
 # Metallicious 
 
-Metallicious (a playful combination of "metal" and "delicious") is an automated tool for creating force fields for metal-containing systems with a covalent model of the metal. By utilizing a library of templates, Metallicious identifies the template that matches the metal site in the structure. It copies the bonded parameters from the template and performs charge redistribution to account for charge transfer. In cases where no suitable template is found, Metallicious automatically performs parameterization.
+Metallicious (a playful combination of "metal" and "delicious") is an automated tool for creating force fields for 
+metal-containing systems with a covalent model of the metal. By utilizing a library of templates, metallicious identifies 
+the template that matches the metal site in the structure. It copies the bonded parameters from the template and performs 
+charge redistribution to account for charge transfer. In cases where no suitable template is found, metallicious 
+automatically performs parameterization.
 
 <img src="images/summary.png" height="150"/>
 
-Metallicious works with minimal user input, relying heavily on educated guesses, which may not always yield the expected results. Therefore, it is recommended to use the tool with caution.
+Metallicious works with minimal user input, relying heavily on educated guesses, which may not always yield the expected 
+results. Therefore, it is recommended to use the tool with caution.
 
 
 
@@ -18,31 +23,28 @@ conda install rdkit autode psiresp mdanalysis networkx qcelemental==0.25.1 amber
 pip install metallicious
 ```
 ## Quick start
-Parametrization of structure with coordinates saved as `supramolecular_cage.xyz` with (nonbonded) topology `supramolecular_cage.top` (of the whole structure): 
-```
-from metallicious import supramolecular_structure
-cage = supramolecular_structure('supramolecular_cage.xyz',
-                                metal_charges={'metal name 1': charge of metal 1(integer), 'metal name 2':charge of metal 2(integer),...},
-                                topol='supramolecular_cage.top', vdw_type='uff')
-cage.parametrize(out_coord='out.pdb', out_topol='out.top')
-```
+Parametrization of structure with coordinates saved as `supramolecular_cage.xyz` (*.xyz, *.pdb, *gro, etc. formats 
+supported by MDAnalysis) with (nonbonded) force-field parameters `supramolecular_cage.top` (*top, *prmtop, etc. supported by ParmEd), 
+which consists of two metals Pd2+ and Ru2+ and organic linkers, the input file might look like this:
 
-For example, for the structure ru_pd.xyz with force-field parameters saved as ru_pd.top, which consists of two metals Pd2+ and Ru2+, the input file looks like this:
 ```
 from metallicious import supramolecular_structure
-cage = supramolecular_structure('ru_pd.xyz', metal_charges={'Ru': 2, 'Pd':2 }, topol='ru_pd.top', vdw_type='uff')
+cage = supramolecular_structure('supramolecular_cage.xyz',
+                                metal_charges={'Ru': 2, 'Pd':2 },
+                                topol='supramolecular_cage.top',
+                                vdw_type='uff')
 cage.parametrize(out_coord='out.pdb', out_topol='out.top')
 ```
-The `supramolecular_structure` function takes a coordination file (*.xyz, *.pdb, *.gro, etc. supported by MDAnalysis), topology file (*top, *prmtop, supported by ParmEd), dictionary of metal ions along with their charge (and in case template parametrization is needed multiplicity) and type of Van der Waals metal parameters as input.
+The `supramolecular_structure` function takes a coordination file, topology file , dictionary of metal ions along with 
+their charge (and in case template parametrization is needed multiplicity) and type of Lennard-Jones library as an input.
 
-See [examples/](https://github.com/tkpiskorz/metallicious/tree/main/metallicious/examples) for
-more examples and [metallicious.readthedocs.io](https://metallicious.readthedocs.io/en/latest/) for
-additional documentation.
+See [examples/](https://github.com/tkpiskorz/metallicious/tree/main/metallicious/examples) for more examples and 
+[metallicious.readthedocs.io](https://metallicious.readthedocs.io/en/latest/) for additional documentation.
 
 ## Command line
 It is also possible to use the metallicious just form command line. For example:
 ```
-metallicious -f cage.xyz -vdw_type merz-tip3p -metal_and_charges Pd 2 -prepare_topol
+metallicious -f supramolecular_cage.xyz -vdw_type merz-tip3p -metal_and_charges Pd 2 Ru 2 -prepare_topol
 ```
 For details, see:
 ```

docs/source/examples.rst

@@ -9,9 +9,9 @@ This is extended desription of the examples provided in metallicious package (se
 Example 1: Quick start
 ------------
 
-Simple parametrization of the cage with 2 metals. As an input we provide coordination file in PBD format and non-bonded
-force-field parameters in *.top format (GROMACS). Moreover, LJ parameters of the Ru and Pd are taken from universal force-field
-(vdw_type=uff), as they are only one available for Ru metal.
+Simple parametrization of the cage with two metals. As input, we provide a coordination file in PBD format and non-bonded
+force-field parameters in *.top format (GROMACS). Moreover, LJ parameters of the Ru and Pd are taken from the universal force-field
+(vdw_type='uff'), as Ru is available only in this library.
 
 .. code-block:: python
 
@@ -21,19 +21,24 @@ force-field parameters in *.top format (GROMACS). Moreover, LJ parameters of the
     cage.parametrize(out_coord='out.pdb', out_topol='out.top')
 
 
-Example 2: automated organic force-field
+Example 2a: Automated initial force-field parameters
 ------------
 
-In case of lack of the topology simple parametrization using AmberTools with GAFF force-field is done of the linker.
-*metallicious* will prepare the non-bonded force-field paramters of the whole structure which is saved to folder "init_topol".
+If the force-field parameters are missing, the linker(s) can be parametrized using AmberTools with a GAFF force field.
+*metallicious* will prepare the non-bonded force-field parameters of the whole structure, which are saved to the folder "init_topol."
 
 .. code-block:: python
 
     from metallicious import supramolecular_structure
     cage = supramolecular_structure('ru_pd.xyz', metal_charges={'Ru': 2, 'Pd':2 }, vdw_type='uff')
     cage.parametrize(out_coord='out.pdb', out_topol='out.top', prepare_initial_topology=True)
 
-The parameters can be saved to AMBER format force-field
+
+Example 2b: Different formats
+------------
+
+The parameters can be saved to different formats supported by MDAnalysis and parmED.
+For example, they can be saved into AMBER format force-field:
 
 .. code-block:: python
 
@@ -42,11 +47,11 @@ The parameters can be saved to AMBER format force-field
     cage.parametrize(out_coord='out.inpcrd', out_topol='out.prmtop', prepare_initial_topology=True)
 
 
-Example 3
+Example 3: Homoleptic cage
 ------------
 
-If the cage is homoleptic and you have available force-field paramters of the linker, you can use them as an input to
-generate initial topology of the whole structure.
+In the case of homoleptic cages (all linkers are the same), *metallicious* can use force-field parameters of single linker,
+which will be used to generate the initial topology of the whole structure:
 
 .. code-block:: python
 
@@ -55,11 +60,17 @@ generate initial topology of the whole structure.
     cage.prepare_initial_topology(homoleptic_ligand_topol='linker.top')
     cage.parametrize(out_coord='out.pdb', out_topol='out.top')
 
-Introduction to examples 4 and 5:
+Missing templates
 ------------
-Cage shown below have rather complex metal binding site.
 
-The template for this metal site is not available in metallicious. Therfore running command:
+Inevitably, one will encounter structures for which the library has no suitable template. For example, there is not template available for the structure shown below:
+
+.. image:: images/lewis.png
+  :width: 400
+  :align: center
+  :alt:
+
+Running python script:
 
 .. code-block:: python
 
@@ -68,17 +79,21 @@ The template for this metal site is not available in metallicious. Therfore runn
                                     vdw_type='merz-opc')
     cage.parametrize(out_coord='out.pdb', out_topol='out.top', prepare_initial_topology=True)
 
-raises an error "Topology file not specified, please provide topology, or use prepare_initial_topology=True".
+will rise an error:
+
+.. code-block:: python
+
+    "Template not found (try to (a) parametrize it (specify multiplicity) or (b) truncate template)"".
 
 Two solutions are available:
-1. parametrize the metal site. This is done by providing multiplicity of the metal:
-2. use truncation scheme (caution needed)
+1. Create a new template, which is automated but time-consuming
+2. use truncation schemes, which are fast but with reduced accuracy (caution is also needed)
 
 Example 4: Parametrization of new template
 ------------
 
-If paramters for the template are not available, you might decide to parametrize them. In *metallicious* this is done by
-specifing the multiplicity of the metal which also enembales QM calculation. For this functionality, the additional
+If template parameters are unavailable, one may want to parametrize them. In *metallicious*, this is done by
+specifying the multiplicity of the metal, which signals *metallicious* to perform QM calculations if necessary. For this functionality, the additional
 dependencies (see installation guide) are needed (`autode <https://github.com/duartegroup/autodE>`_, `ORCA <https://orcaforum.kofo.mpg.de/app.php/portal>`_, and `psiRESP <https://github.com/lilyminium/psiresp>`_).
 
 .. code-block:: python
@@ -88,7 +103,8 @@ dependencies (see installation guide) are needed (`autode <https://github.com/du
                                     vdw_type='merz-opc')
     cage.parametrize(out_coord='out.pdb', out_topol='out.top', prepare_initial_topology=True)
 
-Bare in mind that parametrization of template is time-consuming. It will perform DFT optimalisation using ORCA/autodE. By default autodE uses 4 cores but this can be modified:
+Bear in mind that the parametrization of the template is time-consuming due to the computational cost of QM calculations.
+By default, autodE uses 4 CPUs, which can be modified:
 
 .. code-block:: python
 
@@ -99,21 +115,30 @@ Bare in mind that parametrization of template is time-consuming. It will perform
                                     vdw_type='merz-opc')
     cage.parametrize(out_coord='out.pdb', out_topol='out.top', prepare_initial_topology=True)
 
-By default parametrization is done on D3BJ-PBE0/def2-SVP (keywords = ['PBE0', 'D3BJ', 'def2-SVP', 'tightOPT', 'freq']).
-This can be changed by specifying keywords in class supramolecular structure class:
+By default, QM calculations are done using D3BJ-PBE0/def2-SVP (keywords = ['PBE0', 'D3BJ', 'def2-SVP', 'tightOPT', 'freq']),
+which can be changed by specifying "keywords" in the supramolecular_structure class:
 
 .. code-block:: python
 
     from metallicious import supramolecular_structure
     cage = supramolecular_structure('cage.pdb', topol='topol.top', metal_charges={'Pd':2 },
-    vdw_type='merz-opc', keywords= ['B3LYP', '6-31G*', 'tightOPT', 'freq'])
+    vdw_type='merz-opc', keywords= ['D3BJ', 'B3LYP', '6-31G*', 'tightOPT', 'freq'])
     cage.parametrize(out_coord='out.pdb', out_topol='out.top', prepare_initial_topology=True)
 
 
 Example 5
 ------------
 
-Truncation scheme are very simple
+Truncation schemes allow the "recycling" of existing templates from the library by reducing their size, which might match the metal site of interest.
+Three schemes are available, cutting the template at a distance of 3-bond, 2-bond, and 1-bond from the metal centre.
+For example, one of the existing templates in the library can be truncated as follows:
+
+.. image:: images/truncation.png
+  :width: 400
+  :align: center
+  :alt: Here should be shown how template is truncated
+
+result in templates which might match the metal site. They can be used by specifying truncation_scheme in the supramolecular_structure class:
 
 .. code-block:: python
 
@@ -122,3 +147,4 @@ Truncation scheme are very simple
                                      vdw_type='merz-opc', truncation_scheme='dihedral')
     cage.parametrize(out_coord='out.pdb', out_topol='out.top')
 
+However, they come with reduced accuracy and need to be used cautiously.

docs/source/index.rst

@@ -1,13 +1,17 @@
 Welcome to metallicious's documentation!
 ===================================
 
-**metallicious** is an automated tool for creating force fields for metal-containing systems with a covalent model of the metal. By utilizing a library of templates, Metallicious identifies the template that matches the metal site in the structure. It copies the bonded parameters from the template and performs charge redistribution to account for charge transfer. In cases where no suitable template is found, Metallicious automatically performs parameterization.
+*metallicious* is an automated tool for creating force fields for metal-containing systems with a covalent model of the
+metal. By utilizing a library of templates, *metallicious* identifies the template that matches the metal site in the
+structure. It copies the bonded parameters from the template and performs charge redistribution to account for charge transfer.
+In cases where no suitable template is found, *metallicious* automatically performs parameterization.
 
 .. image:: images/summary.png
   :align: center
   :width: 400
   :alt: Figure of summary of metallicious protocol
 
+|
 
 **Limitations**: The code currently supports organometallic structures with metals separated by at least 2 non-metal atoms. Metal clusters are not supported. Additionally, metals of the same type must have the same charge and multiplicity.
 

docs/source/installation.rst

@@ -4,7 +4,7 @@ Installation
 
 
 The easiest way to install *metallicious* is to use `Anaconda <https://anaconda.org/anaconda/python>`_, as *metallicious* depends on external packages.
-Create new conda environment:
+Create a new conda environment:
 
 .. code-block:: bash
 

docs/source/tutorials.rst

@@ -7,7 +7,7 @@ Tutorials
 Tutorial 1: Force-field parameters from SMILES string
 ------------
 
-It is extremely simple to obtain force-field parameters just from SMILES string by combining  functionality of metallicious with `cgbind <https://github.com/duartegroup/cgbind/tree/master>`_:
+It is straightforward to obtain force-field parameters just from SMILES string by combining the functionality of metallicious with `cgbind <https://github.com/duartegroup/cgbind/tree/master>`_:
 
 .. code-block:: python
 
@@ -26,18 +26,17 @@ It is extremely simple to obtain force-field parameters just from SMILES string
 Tutorial 2: Parametrization of template for gallium cages (known issue and solution)
 ------------
 
-Metallicious uses educated guesses along the way. While we observe that for most cases this work, we also found one outlier: parametrization of template for gallium cages.
-To parametrize the template, *metalliciuos* uses charge of the metal (user input) and guessed charge of the attached ligand fragment.
-Charge of organic ligand is guessed by rdkit frp, 3D structure of the atoms. While this works for most of the molecules,
-sometimes there might be ambiguity about the structure. In this example template site can have to sites:
+Metallicious uses educated guesses along the way. While we observe that this works in most cases, we also found one outlier: parametrization of the template for [Ga4L6]12- cages.
+To parametrize the template, *metalliciuos* uses the charge of the metal (user input) and guessed charge of the attached ligand fragment.
+The charge of the organic ligand is guessed by rdkit from the 3D structure of the atoms. While this works for most of the molecules,
+sometimes there might be ambiguity about the structure. In this example, the coordinating ligand can have two chemical structures:
 
 .. image:: images/gallium.png
   :width: 200
   :align: center
   :alt:
 
-As you can see the drown structure can correspond to two possible variation: 1,2benzodiol. and 1,2.
-To correct this one needs to overwrite the guesses charges.
+*metallicious* incorrectly guesses the neutral charge of the ligand. However, this behaviour can be corrected by overwriting guessed charges:
 
 .. code-block:: python
 
@@ -49,26 +48,26 @@ To correct this one needs to overwrite the guesses charges.
     cage.unique_sites[0].ligand_charges = [-2, -2, -2] #this specifies ligands' charges
     cage.parametrize()
 
-While it is worth to aware of this, this template is part of the default library therefore it is already parametrized.
-
+While it is worth noting this, this template is part of the default library, so it is already parametrized.
 
 
 Tutorial 3: Using custom template
 ------------
 
-One might decide that they parametrized template using specific technique and did not save it to the library. One might use this template on purpose for specific applicatin
+One might decide that they parametrized the template using a specific technique and did not save it to the library. One might use this template on purpose for specific application
 
 .. code-block:: python
 
-    cage = supramolecular_structure(f'{name:}/bonded/saturated_template_optimised.xyz',
-                                    metal_charges={metal_name: metal_charges_dic[folder_name]},
-                                    vdw_type = library_name, search_library=False)
-    cage.extract_unique_metal_sites()
-    cage.sites[0].fp_coord_file = f'{name:}/template.pdb'
-    cage.sites[0].fp_topol_file = f'{name:}/template.top'
-    cage.sites[0].load_fingerprint()
-    cage.sites[0].set_cutoff()
-    cage.unique_sites = []
+    cage = supramolecular_structure(f'cage.xyz',
+                                    metal_charges={'Pd': 2},
+                                    vdw_type = 'uff',
+                                    search_library=False)
+    cage.extract_unique_metal_sites() # extracts template structures (needed to detect sites)
+    cage.sites[0].fp_coord_file = f'selected_template.pdb' # loads coordinates of the template
+    cage.sites[0].fp_topol_file = f'selected_template.top' # loads force-field parameters of the template
+    cage.sites[0].load_fingerprint() # loads template into the class
+    cage.sites[0].set_cutoff() # reads the radius of the template
+    cage.unique_sites = [] # overwrites list with templates to parameterize (no template parametrization needed)
     cage.parametrize(out_coord='saturated_template.pdb', out_topol='saturated_template.top')
 
 
@@ -80,3 +79,12 @@ One might however opt for higher level of theory or include implicit solvent eff
 This requires only change of the library_directory, as there are not templates inside, we need to parametrize them using new method:
 
 
+.. code-block:: python
+
+    from metallicious import supramolecular_structure
+    cage = supramolecular_structure('nonbonded.pdb', {'Pd': (2, 1)},
+                                    topol = 'noncovalent_complex.top',
+                                    vdw_type='uff'
+                                    library_path=f'/path/to/new/library/',
+                                    keywords = ['CPCM(Water)', 'PBE0', 'D3BJ', 'def2-SVP', 'tightOPT', 'freq'])
+    cage.parametrize()

docs/source/usage.rst

@@ -45,8 +45,10 @@ If you don't have a topology file, you can generate a simple force-field paramet
     cage.prepare_initial_topology()
     cage.parametrize(out_coord='out.pdb', out_topol='out.top')
 
-However, we do not intend to automate the parametrization of the organic part of the molecule.
-Please refer to specialized tools such as gromacs, atb, ambertools, and charmm-gui.
+Please note that our focus was on covalent metal parametrization; only basic support for the organic molecule parametrization is available.
+For more robust parameterization protocols, please refer to specialized tools such as
+`gromacs <https://www.gromacs.org/>`_, `ATB <https://atb.uq.edu.au/>`_,
+`ambertools <https://ambermd.org/AmberTools.php>`_, and `charmm-gui <https://www.charmm-gui.org/>`_.
 
 Handling missing templates
 ------------