Actualització manual

docs/index.rst

@@ -21,7 +21,7 @@ The basic tasks included in the current version of **cosymlib** are:
 
     * Calculation of Continuous Shape Measures (CShMs)
     * Calculation of Continuous Symmetry Measures (CSMs)
-    * Calculation of Continuous Chirality Measures (CCM)
+    * Calculation of Continuous Chirality Measures (CCMs)
 
 2. **Electronic structure analysis**
 
@@ -40,7 +40,7 @@ The basic tasks included in the current version of **cosymlib** are:
     api
 
 **Cosymlib** is being developed by the **Electronic Structure & Symmetry (ESS)** group
-at the Department de Ciència de Material i Química Física
+at the Department de Ciència de Materials i Química Física
 and the Institut de Química Teòrica i Computacional (IQTCUB). University of Barcelona.
 
 ------

docs/install.rst

@@ -3,67 +3,67 @@
 Installation
 ============
 
-:program:`cosymlib` is available in both GitHub and PyPI repositories (https://pypi.org/project/cosymlib/).
-Installation via PyPI is simpler and it is recommended for most users.
+:program:`cosymlib` is available in both the GitHub and PyPI repositories (https://pypi.org/project/cosymlib/).
+Installation via PyPI is simpler and it is recommended for most users. Follow the instructions below to
+install :program:`cosymlib` in your computer.
 
-from PyPI (recommended)
------------------------
+Installing cosymlib from PyPI (recommended)
+-------------------------------------------
 
-This installation requires :program:`pip`  ( https://pip.pypa.io/en/stable/installing/) to be installed
-in your system. We strongly recommend the use of python environments, for more details refer to
-https://docs.python.org/3/library/venv.html . For most users the basic installation proceed as follows:
+This installation requires :program:`pip` (https://pip.pypa.io/en/stable/installing/) to be installed
+in your system. We strongly recommend the use of python environments, for more details on this, refer to
+https://docs.python.org/3/library/venv.html. For most users the basic installation should proceed as follows:
 
-1. Create a virtual environment at path <venv>::
+1. Create a virtual environment at path <venv> ::
 
     $ python3 -m venv <venv>
 
-2. Activate environment ::
+2. Activate this virtual environment ::
 
     # on MAC / Linux
     $ source <venv>/bin/activate
 
     # on windows (powershell) [see note below]
     C:\> <venv>\Scripts\Activate.ps1
 
-3. Install cosymlib ::
+3. Install :program:`cosymlib` ::
 
     $ pip install numpy
     $ pip install cosymlib
 
-4. Deactivate environmen ::
+4. Deactivate the virtual environment ::
 
     $ deactivate
 
 
-To use :program:`cosymlib` it is necessary to activate the environment every time a new shell is open.
-On Linux/MAC all the scripts contained in :program:`cosymlib` will be accessible in this environment. ::
+To use :program:`cosymlib` you will need to activate the virtual environment every time that you open a new shell.
+On Linux/MAC all the scripts contained in :program:`cosymlib` will be accessible in this environment: ::
 
     $ source <venv>/bin/activate
     $ <script_name> <script_options>
     $ deactivate
 
-
-On windows, to execute the scripts it is necessary to type *python* followed by the full path of the script name ::
+On Windows, to execute the scripts you should type *python* followed by the full path of the script name: ::
 
     C:\> python <venv>\Scripts\<script_name> <script_options>
 
 .. note::
-    On windows it may be necessary to add user execution permissions to activate the environment.
-    To do this open a poweshell as administrator and type ::
+    On Windows it may be necessary to add user execution permissions to activate the environment.
+    To do this, open a poweshell as administrator and type::
 
       Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
 
-    this has to be done only once to gain execution permissions.
+    You should do this only once in order to gain execution permissions.
 
-from source code
-----------------
+Installing cosymlib's source code
+---------------------------------
 
-Alternatively you can download the latest version of :program:`cosymlib` from github using :program:`git` (https://git-scm.com)
-and install it manually through :file:`setup.py` file using :program:`setuptools` (https://setuptools.readthedocs.io/).
+Alternatively, you can download the latest version of :program:`cosymlib` from github using :program:`git` (https://git-scm.com)
+and install it manually through the :file:`setup.py` file using :program:`setuptools` (https://setuptools.readthedocs.io/).
 
 :program:`cosymlib` contains libraries written in Fortran that require a compiler to build them.
-Before installing cosymlib make sure you have a working Fortran compiler installed in your system.
-For UNIX based systems you can install GNU Fortran Compiler from package repositories by opening a terminal and
+Before installing :program:`cosymlib` make sure you have a working Fortran compiler installed in your system.
+For UNIX based systems you can install the GNU Fortran Compiler from package repositories by opening a terminal and
 typing the following commands:
 
 - **Linux**
@@ -88,17 +88,17 @@ typing the following commands:
 
 - **Windows**
 
- 1. Install windows development environment :program:`Visual Studio` (https://developer.microsoft.com/en-us/windows/downloads/)
+ 1. Install the Windows development environment :program:`Visual Studio` (https://developer.microsoft.com/en-us/windows/downloads/)
 
- 2. Install C/Fortran compiler for windows. We have tested and recommend  :program:`mingw` (https://www.mingw-w64.org)
+ 2. Install C/Fortran compiler for Windows. We have tested and recommend  :program:`mingw` (https://www.mingw-w64.org)
 
 
-To install :program:`cosymlib` download the source code using :program:`git` in your computer by typing: ::
+To install :program:`cosymlib`, download the source code using :program:`git` in your computer by typing: ::
 
     git clone https://github.com/GrupEstructuraElectronicaSimetria/cosymlib.git
 
 This creates a copy of the repository in your computer. You can keep it updated by synchronizing it
-with GitHub repository by using the command: ::
+with the GitHub repository by using the command: ::
 
     git pull
 
@@ -108,7 +108,7 @@ following command to install :program:`cosymlib` : ::
     python setup.py install --user
 
 .. note::
-    :file:`requirements.txt` file located at the repository root directory contains a list of all dependency
+    The :file:`requirements.txt` file located at the repository root directory contains a list of all dependency
     python modules needed for :program:`cosymlib` to run. If any of them are missing in your system you will
     need to install them before running :program:`cosymlib`.
 
@@ -117,11 +117,11 @@ installed you can run the :program:`python` interpreter and execute: ::
 
    import cosymlib
 
-if the execution do not show any errors :program:`cosymlib` has been installed successfully.
+If the execution does not show any errors, then :program:`cosymlib` has been installed successfully.
 
 .. note::
-    For users with Apple M1, scipy library might not properly install when following the next instructions,
-    to solve this, install manually: ::
+    For users with Apple M1, the :program:`scipy` library might not properly install when following the
+    instructions above. To solve this, install it manually: ::
 
      brew install openblas
      brew install lapack
@@ -130,7 +130,7 @@ if the execution do not show any errors :program:`cosymlib` has been installed s
      OPENBLAS=$(brew --prefix openblas) CFLAGS="-falign-functions=8 ${CFLAGS}" pip install --no-use-pep517 scipy==1.7.0
 
 .. note::
-    When using an IDE remember to select the python interpreter in the hombrew path, to find it: ::
+    When using an IDE, remember to select the python interpreter in the hombrew path. To find it: ::
 
      which python3
      >> /opt/homebrew/bin/python3

docs/introduction.rst

@@ -57,7 +57,7 @@ p\ :sub:`i`\  are the position vectors of the vertices of Q and P, respectively,
 and q\ :sub:`0`\  the geometric center of the problem structure Q. The minimization in this
 equation refers to the relative position, orientation, and scaling that must be applied
 to P\ :sub:`0`\  to minimize the sum of squares of distances between their respective vertices,
-which is equivalent to maximizing the overlap <Q|P>. If the matching of the two shapes is described,
+which is equivalent to maximizing the overlap <Q|P>. If the mismatch of the two shapes is described,
 as in the equation above by the distance between vertices of the two objects, a further minimization
 with respect to all possible ways to label the N vertices in the reference structure P\ :sub:`0`\  is
 also needed.
@@ -67,7 +67,7 @@ then S\ :sub:`P`\ (Q) = 0. Since S\ :sub:`P`\ (Q)  is always positive, the large
 less similar is Q to the ideal shape P. It can be shown that the maximum value for
 S\ :sub:`P`\ (Q) is 100, corresponding to the unphysical situation for which all vertices
 of Q collapse into a single point. A more detailed description of continuous shape measures and
-some of their applications in chemistry may be found in the following references: [CShM]_.
+some of their applications in chemistry may be found in the following references [CShM]_:
 
 ---------------------------
 
@@ -115,7 +115,7 @@ is, in principle, previously unknown and must be found in the procedure of compu
 Consider, for instance that we would like to measure the rectangular symmetry for a given general
 quadrangle. Besides optimizing to seek for the translation, rotation, and scaling that leads to the
 optimal overlap of our quadrangle Q with a particular rectangle P as in a shape measure, we will need
-to consider also which is the ratio between the side lengths of best matching rectangle and
+to consider also which is the ratio between the side lengths of the best matching rectangle and
 optimize also with respect to this parameter.
 
 .. image:: images/CSM_def.png
@@ -125,10 +125,12 @@ optimize also with respect to this parameter.
 Although this additional optimization process may seem difficult to generalize for any
 given symmetry group, it has been shown that it is possible to do it efficiently
 using either the folding–unfolding algorithm or via the calculation of intermediate symmetry
-operation measures. As in the case of shape measures, the values of CSMs are also limited
+operation measures.
+
+As in the case of shape measures, the values of CSMs are also limited
 between 0 and 100, with S\ :sub:`G`\ (Q) = 0, meaning that Q is a G-symmetric shape. A more detailed
 description of continuous shape measures and some of their applications in chemistry may be found
-in the following references: [CSM]_.
+in the following references [CSM]_:
 
 ---------------------------
 
@@ -182,7 +184,7 @@ structure is enough in order to guess which one could be the nearest S\ :sub:`n`
 a practical solution is just to calculate this particular S\ :sub:`G`\ (Q) value, or in case of
 doubt, a few S\ :sub:`G`\ (Q) values  for different S\ :sub:`n`\  and pick the smallest one.
 A more detailed description of continuous shape measures and some of their applications in
-chemistry may be found in the following references: [CCM]_.
+chemistry may be found in the following references [CCM]_:
 
 ---------------------------
 
@@ -205,7 +207,7 @@ CSMs for quantum chemical objects
 
 The use of the overlap <Q|P> between two general objects Q and P allows the generalization of
 continuous symmetry and shape measures to more complex objects that cannot be simply described
-by a set of vertices such as matrices or functions. In this case the definition of the continuous
+by a set of vertices, such as matrices or functions. In this case the definition of the continuous
 symmetry measure is:
 
 .. image:: images/QCSM_eq.png
@@ -245,7 +247,7 @@ defined by a set of vertices.
 An interesting extension for functions which are not restricted to positive values, for instance,
 molecular orbitals, is the possibility of calculating continuous symmetry measures for each individual
 irreducible representation of a given point group. A more detailed description of the development and
-some applications of CSMs in quantum chemistry may be found in the following references: [QCSMs]_.
+some applications of CSMs in quantum chemistry may be found in the following references [QCSMs]_:
 
 ---------------------------
 

docs/usage.rst

@@ -6,9 +6,9 @@ How to use cosymlib
 **Cosymlib** is a a python library for computing continuous symmetry & shape measures (CSMs & CShMs).
 Besides using the APIs contained in **cosymlib** to build your own custom-made python programs we have
 also written some general scripts to perform standard tasks such as calculating a continuous shape
-measure for a given structure without need of writing a python script. All this general task scripts
-are called using a similar syntax wich inludes the name of the script, the name of the file containing
-the structural data and optional arguments specifying the tasks we want to perform::
+measure for a given structure without the need of writing a python script. All this general task scripts
+are called using a similar syntax which includes the name of the script, the name of the file containing
+the structural data, and optional arguments specifying the tasks we want to perform::
 
    $ script filename -task1 -task2 ... -taskn
 
@@ -24,19 +24,31 @@ for a H\ :sub:`4`\  molecule in an approximately square geometry:
     H   -0.9  -1.2  0.0
     H    1.1  -1.0  0.0
 
-if we would like to compute the square shape measure S(SP-4) for this 4-vertex
-polygon we simply can call the shape script indicating the name of the .xyz file
+If we would like to compute the square shape measure S(SP-4) for this 4-vertex
+polygon we simply can call the shape script indicating the name of our .xyz file
 containing the coordinates and use the ``-m`` flag (m stands for measure) with the
 SP-4 label to indicate that we want to compute a shape measure using a perfect square
 (SP-4 stands for square planar structure with 4 vertices) as the reference shape::
 
    $ shape struct.xyz -m SP-4
 
-and the shape script wil call the APIs in cosymlib to read first your input file, generate a
+and the shape script wil call the APIs in **cosymlib** to read first our input file, generate a
 molecule object, calculate the S(SP-4) continuous shape measure for it, and print
-the result of the calculation on the screen.
-
-If, for instance, we also want the coordinates for the square with the best overlap
+the result of the calculation on the screen::
+
+ ----------------------------------------------------------------------
+  COSYMLIB v0.10.5
+  Electronic Structure & Symmetry Group
+  Institut de Quimica Teorica i Computacional (IQTC)
+  Universitat de Barcelona
+ ----------------------------------------------------------------------
+  Structure         SP-4
+  H4,               0.520,
+ ----------------------------------------------------------------------
+                    End of calculation
+ ----------------------------------------------------------------------
+
+If, for instance, we also want the coordinates for the square with the optimal overlap
 with our problem structure, we just need to include the ``-s`` flag (where s stands
 for structure) in our call::
 
@@ -47,11 +59,12 @@ these explicit flags the previous command becomes::
 
    $ shape struct.xyz --measure SP-4 --structure
 
-The general task scripts include also ``sym`` and ``cchir`` for
-calculating continuous symmetry and chirality measures for polyhedral structures, as well as
-the ``esym`` script for the continuous symmetry analysis of wavefunctions and electron densities.
+The general task scripts include also ``gsym`` and ``cchir`` for
+calculating continuous symmetry and chirality measures for polyhedral structures, ``shape_map`` for plotting
+shape maps, as well as the ``esym`` and ``mosym`` scripts for the continuous symmetry analysis of electron
+densities and the pseudosymmetry analysis of molecular orbitals, respectively.
 
-Besides these four basic scripts we have also developed ``cosym``, a general script that allows to perform
+Besides these six basic scripts, we have also developed ``cosym``, a general script that allows to perform
 any of the basic calculations above. We could, for instance, use directly ``cosym`` to calculate the previous
 shape measure using the following command::
 
@@ -77,19 +90,25 @@ included in the present distribution of **cosymlib**.
 General task scripts
 --------------------
 
-In cosymlib library there several task scripts availables that can be run in a terminal as command lines. The following
-subsections describe the general usage of all of them.
+The **cosymlib** library includes several scripts to perform basic tasks that can be run in a
+terminal as command line instructions, without the need of writing a full python script. The
+following subsections describe the general usage of all of them.
 
 --------
 
 
 shape
 ^^^^^
-The minimal information needed to run ``shape`` is an input file containing a geometric structure
-described by the coordinates of a set of vertices. Since ``shape`` is mainly intended to be used
-in the context of structural chemistry, the main source of structural information will be a ``fname.xyz``
-file containing a molecular geometry in xyz format (`<http://en.wikipedia.org/wiki/XYZ_file_format>`_)
-An example of a ``cocl6.xyz`` file with the structure for an octahedral CoCl\ :sub:`6`\  fragment
+``shape`` can be used for computing continuous shape measures (CShMs) for geometrical structures
+defined by the cartesian coordinates for a set of vertices, for instance, a molecular structure
+defined by the positions of the atomic nuclei.
+
+The minimal information needed to run ``shape`` is an input file containing the coordinates of a set
+of vertices. Since ``shape`` is mainly intended to be used in the context of structural chemistry, the main
+source of structural information will be a ``fname.xyz`` file containing a molecular geometry in xyz
+format (`<http://en.wikipedia.org/wiki/XYZ_file_format>`_).
+
+An example of a ``cocl6.xyz`` file with the structure for a perfect octahedral CoCl\ :sub:`6`\  fragment
 with 2.4Å Co-Cl interatomic distances is:
 ::
 
@@ -109,20 +128,22 @@ indicated in the first line) contain a label (usually the atomic symbol) and the
 x, y, z for each atom (vertex) in the structure.
 
 ``fname.xyz`` files read by shape may contain a single structure as in the previous example or
-multiple structures (all with the same number of atoms), in which case a block:
+multiple structures (all with the same number N of atoms). In this case  you must append a
 ::
 
-    Title
-    label1 x  y  z
+    N
+    Structure_name
+    label_1  x1  y1  z1
      ...
-    label  x  y  z
+    label_N  xN  yN  zN
 
-describing each structure is repeated as many times as necessary, without leaving
-blank lines between the different structures.
+block for each structure, without leaving any blank lines between them. Note that even if the
+number of vertices N must be the same for all structures, it is mandatory to include it explicitly
+for each block.
 
 Shape is also able to read input structures from files in other formats used in structural chemistry.
-A detailed description of the structural files read by shape can be found in *(include link to
-file formats)*.
+A detailed description of the structural files read by shape can be found in the :ref:`information on input
+formats <input_formats>` section.
 
 The basic call to the shape script must provide the the file containing the input structure and the
 reference shape with respect to which the shape measure is calculated.