Fchl doc (qmlcode#41)

* Updated FCHL documentation

.travis.yml

@@ -1,17 +1,12 @@
 language: python
+
 sudo: required
 dist: trusty
+
 group: edge
+
 deploy:
-#   matrix:
-#   - provider: pypi
-#     user: andersx
-#     on:
-#       branch: master
-#       condition: ${TRAVIS_PYTHON_VERSION} = "2.7"
-#     password:
-#       secure: OhTw5j/R9a2kZ/jkz6ZXcQcLoqq/Z5sslQ5j+OxnssyZUfgeeqNyWj8T74aVoRtrWVz20i756opLd8cgGcKOYesXAjNFJHmymABnQQnYrpBBk8NSyfaJ8CnNHiGhJCAFRp9x+Jbb+9BpDswg2UBQPj5b4krOZVcT53JIM5qEGDo3bpOCgy5VlMtSCKOjyUxYwgcHTGDnpDNSa2QwIcMcT1R0cyEMZ/AOKAwbkh99s6x/bwi2PYutfdxIwnuWMSAPzvbKJfb82xQzkGf4+JS/elr583zT0QyXP3BRvWyHfLh/K+fUGSc805Ay/GIE2ZHKUHiuHo/DunmbjlxHrBuJWXpuyMHJwiRLngo80OY/5dMnVLiz84MfxdrSzNsZoV9/fPM1W6OSsuX75axUjYyZsf23hmVHKUJNmMa8wGp/KYo6i/ZoVwKDmKB1Ap0Qr7Qigwn/N7DYg2oSi9ypdtgkFnBGhovXtbCNqSUM5hTBxc+jl1xlxZMvPjxagbyut9F+5JjI/PO+zva0uL9jjKgsMeOarQfsETfxfC8x4oZ0+Pe/5lLeBlVkqepCvtBpBEyZnHYvD7G4LFLbNpxTAL84BjwA5C1C4gTQVbEs8tw02rN7Ro91+0Qh1cSY4L3qFuCZdvWfBTxWT2NvpuxSlM+ywO8S8c9tInGdtGEPyu9RvfI=
-- provider: pages
+  provider: pages
   local_dir: ${TRAVIS_BUILD_DIR}/docs/build/html
   skip_cleanup: true
   repo: qmlcode/qmlcode.github.io
@@ -20,40 +15,47 @@ deploy:
   on:
     branch: master
     condition: ${TRAVIS_PYTHON_VERSION} = "2.7"
+
 python:
-- '2.7'
-- '3.5'
-- '3.6'
+  - "2.7"
+  - "3.5"
+  - "3.6"
+
 before_install:
-- sudo apt-get update -qq
+  - sudo apt-get update -qq
+
 install:
-- sudo apt-get install -qq gcc gfortran libblas-dev liblapack-dev
-- sudo apt-get install -qq gcc-4.8 gfortran-4.8
-- |
-  if [ ${TRAVIS_PYTHON_VERSION:0:1} = 3 ]; then
-      sudo apt-get install python3-numpy
-      pip3 install scipy
-      python3 setup.py build
-      python3 setup.py install
-      pip3 install sphinx
-      pip3 install sphinx-rtd-theme
-      cd ${TRAVIS_BUILD_DIR}/docs
-      make html
-  elif [ ${TRAVIS_PYTHON_VERSION} = "2.7" ]; then
-      sudo apt-get install python-numpy
-      pip2 install scipy
-      python2 setup.py build
-      python2 setup.py install
-      pip2 install sphinx
-      pip2 install sphinx-rtd-theme
-      cd ${TRAVIS_BUILD_DIR}/docs
-      make html
-  else
-      echo "ERROR: Unknown Python version."
-  fi
+ - sudo apt-get install -qq gcc gfortran libblas-dev liblapack-dev
+ - sudo apt-get install -qq gcc-4.8 gfortran-4.8
+ - |
+   if [ ${TRAVIS_PYTHON_VERSION:0:1} = 3 ]; then
+       sudo apt-get install python3-numpy
+       pip3 install scipy
+       python3 setup.py build
+       python3 setup.py install
+       pip3 install sphinx
+       pip3 install sphinx-rtd-theme
+       cd ${TRAVIS_BUILD_DIR}/docs
+       make html
+   elif [ ${TRAVIS_PYTHON_VERSION} = "2.7" ]; then
+       sudo apt-get install python-numpy
+       pip2 install scipy
+       python2 setup.py build
+       python2 setup.py install
+       pip2 install sphinx
+       pip2 install sphinx-rtd-theme
+       cd ${TRAVIS_BUILD_DIR}/docs
+       make html
+   else
+       echo "ERROR: Unknown Python version."
+   fi
+
+
 before_script:
-- cd ${TRAVIS_BUILD_DIR}/tests/
+ - cd ${TRAVIS_BUILD_DIR}/tests/
+
 script:
-- nosetests -v
+ - nosetests -v
+
 notifications:
   email: false

docs/source/examples.rst

@@ -1,4 +1,4 @@
-xamples
+Examples
 --------
 
 Generating representations using the ``Compound`` class
@@ -132,12 +132,14 @@ The easiest way to calculate the kernel matrix using an explicit, local represen
 
     (3, 7101, 7101)
 
+Note that ``mol.representation`` is just a 1D numpy array.
+
 
 Generating the SLATM representation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The Spectrum of London and Axillrod-Teller-Muto potential (SLATM) representation requires additional input to reduce the size of the representation.
-This input (the types of many-body terms) is generate via the ``get_slatm_mbtypes()`` function. The function takes a list of the nuclearges for each molecule in the dataset as input. E.g.:
+This input (the types of many-body terms) is generate via the ``get_slatm_mbtypes()`` function. The function takes a list of the nuclear charges for each molecule in the dataset as input. E.g.:
 
 
 .. code:: python
@@ -171,64 +173,142 @@ The ``local`` keyword in this example specifies that a local representation is p
     # Generate one representation
     rep = generate_slatm(coordinates, nuclear_charges, mbtypes)
 
-Generating the ARAD representation and kernels
+Here ``coordinates`` is an Nx3 numpy array, and ``nuclear_charges`` is simply a list of charges.
+
+Generating the FCHL representation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-The ARAD representation does not have an explicit representation in the form of a vector, and the L2-distance must be calculated analytically in a separate kernel function.
-The syntax is analogous to the explicit representations (e.g. Coulomb matrix, BoB, SLATM, etc), but is handled by kernels from the separate ``qml.arad`` module.
+The FCHL representation does not have an explicit representation in the form of a vector, and the kernel elements must be calculated analytically in a separate kernel function.
+The syntax is analogous to the explicit representations (e.g. Coulomb matrix, BoB, SLATM, etc), but is handled by kernels from the separate ``qml.fchl`` module.
 
-.. code:: python
+The code below show three ways to create the input representations for the FHCL kernel functions.
 
-    from qml.arad import get_local_kernels_arad
+First using the ``Compound`` class:
 
-    # Assume the QM7 dataset is loaded into a list of Compound()
-    for compound in qm7:
+.. code:: python
 
-        # Generate the desired representation for each compound
-        compound.generate_arad_representation(size=23)
+    # Assume the dataset is loaded into a list of Compound()
+    for compound in mols:
+
+        # Generate the desired representation for each compound, cut off in angstrom
+        compound.generate_fchl_representation(size=23, cut_off=10.0)
     
-    # Make Numpy array of the representation
-    X = np.array([c.representation for c in qm7])
+    # Make Numpy array of the representation, which can be parsed to the kernel
+    X = np.array([c.representation for c in mols])
     
-    # List of kernel-widths
-    sigmas = [50.0, 100.0, 200.0]
+
+The dimensions of the array should be ``(number_molecules, size, 5, size)``, where ``size`` is the
+size keyword used when generating the representations. 
+
+In addition to using the ``Compound`` class to generate the representations, FCHL representations can also be generated via the ``qml.fchl.generate_fchl_representation()`` function, using similar notation to the functions in the ``qml.representations.*`` functions.
+
+
+.. code:: python
+
+    from qml.fchl import generate_representation 
+
+    # Dummy coordinates for a water molecule
+    coordinates = np.array([[1.464, 0.707, 1.056],
+                            [0.878, 1.218, 0.498],
+                            [2.319, 1.126, 0.952]])
+
+    # Oxygen, Hydrogen, Hydrogen
+    nuclear_charges = np.array([8, 1, 1])
+
+    rep = generate_representation(coordinates, nuclear_charges)
+
+To create the representation for a crystal, the notation is as follows:
+
+
+.. code:: python
+
+    from qml.fchl import generate_representation 
+
+    # Dummy fractional coordinates
+    fractional_coordinates = np.array(
+            [[ 0.        ,  0.        ,  0.        ],
+             [ 0.75000042,  0.50000027,  0.25000015],
+             [ 0.15115386,  0.81961403,  0.33154037],
+             [ 0.51192691,  0.18038651,  0.3315404 ],
+             [ 0.08154025,  0.31961376,  0.40115401],
+             [ 0.66846017,  0.81961403,  0.48807366],
+             [ 0.08154025,  0.68038678,  0.76192703],
+             [ 0.66846021,  0.18038651,  0.84884672],
+             [ 0.23807355,  0.31961376,  0.91846033],
+             [ 0.59884657,  0.68038678,  0.91846033],
+             [ 0.50000031,  0.        ,  0.50000031],
+             [ 0.25000015,  0.50000027,  0.75000042]]
+        )
+
+    # Dummy nuclear charges
+    nuclear_charges = np.array(
+            [58, 58, 8, 8, 8, 8, 8, 8, 8, 8, 23, 23]
+        )
+
+    # Dummy unit cell
+    unit_cell = np.array(
+            [[ 3.699168,  3.699168, -3.255938],
+             [ 3.699168, -3.699168,  3.255938],
+             [-3.699168, -3.699168, -3.255938]]
+        )
+
+    # Generate the representation
+    rep = generate_representation(fractional_coordinates, nuclear_charges, 
+            cell=unit_cell, neighbors=100, cut_distance=7.0)
+
+
+The neighbors keyword is the max number of atoms with the cutoff-distance
+
+Generating the FCHL kernel 
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following example demonstrates how to calculate the local FCHL kernel elements between FCHL representations. ``X1`` and ``X2`` are numpy arrays with the shape ``(number_compounds,max_size, 5,neighbors)``, as generated in one of the previous examples. You MUST use the same cut-off distance to generate the representation and calculate the kernel.
+
+
+.. code:: python
+
+    from qml.fchl import get_local_kernels
+
+    # You can get kernels for multiple kernel-widths
+    sigmas = [2.5, 5.0, 10.0]
 
     # Calculate the kernel-matrices for each sigma
-    K = get_local_kernels_arad(X, X, sigmas)
+    K = get_local_kernels(X1, X2, sigmas, cut_distance=10.0)
 
     print(K.shape)
 
-.. code:: 
 
-    (3, 7101, 7101)
+As output you will get a kernel for each kernel-width.
 
-The dimensions of the input should be ``(number_molecules, size, 5, size)``, where ``size`` is the
-size keyword used when generating the representations. 
+.. code:: 
+
+    (3, 100, 200)
 
-In addition to using the ``Compound`` class to generate the representations, ARAD representations can also be generated via the ``qml.arad.generate_arad_representation()`` function, using similar notation to the functions in the ``qml.representations.*`` functions.
 
-In case the two datasets used to calculate the kernel matrix are identical 
-- resulting in a symmetric kernel matrix - it is possible use a faster kernel,
-since only half of the kernel elements must be calculated explicitly:
+In case ``X1`` and ``X2`` are identical, K will be symmetrical. This is handled by a separate function with exploits this symmetry (thus being twice as fast).
 
 .. code:: python
+    
+    from qml.fchl import get_local_symmetric_kernels
 
-    from qml.arad import get_local_symmetric_kernels_arad
+    # You can get kernels for multiple kernel-widths
+    sigmas = [2.5, 5.0, 10.0]
 
     # Calculate the kernel-matrices for each sigma
-    K = get_local_symmetric_kernels_arad(X, sigmas)
+    K = get_local_kernels(X1, sigmas, cut_distance=10.0)
 
     print(K.shape)
 
+
 .. code:: 
 
-    (3, 7101, 7101)
+    (3, 100, 100)
 
-In addition to the local kernel, the ARAD module also provides kernels for atomic properties (e.g. chemical shifts, partial charges, etc). These have the name "atomic", rather than "local".
+In addition to the local kernel, the FCHL module also provides kernels for atomic properties (e.g. chemical shifts, partial charges, etc). These have the name "atomic", rather than "local".
 
 .. code:: python
 
-    from qml.arad import get_atomic_kernels_arad
-    from qml.arad import get_atomic_symmetric_kernels_arad
+    from qml.fchl import get_atomic_kernels
+    from qml.fchl import get_atomic_symmetric_kernels
 
 The only difference between the local and atomic kernels is the shape of the input.
 Since the atomic kernel outputs kernels with atomic resolution, the atomic input has the shape ``(number_atoms, 5, size)``.

docs/source/qml.rst

@@ -45,12 +45,12 @@ qml\.Compound class
     :undoc-members:
     :show-inheritance:
 
-qml\.arad module
-----------------
-
-.. automodule:: qml.arad
-    :members:
-    :show-inheritance:
+.. qml\.arad module
+.. ----------------
+.. 
+.. .. automodule:: qml.arad
+..     :members:
+..     :show-inheritance:
 
 qml\.fchl module
 ----------------

qml/compound.py

@@ -33,7 +33,7 @@
 from .representations import generate_eigenvalue_coulomb_matrix
 from .representations import generate_slatm
 
-from .arad import generate_arad_representation
+from .fchl import generate_representation as generate_fchl_representation
 
 class Compound(object):
     """ The ``Compound`` class is used to store data from  
@@ -245,16 +245,15 @@ def generate_bob(self, size=23, asize = {"O":3, "C":7, "N":3, "H":16, "S":1}):
         self.representation = generate_bob(self.nuclear_charges, self.coordinates, 
                 self.atomtypes, asize = asize)
 
-    def generate_arad_representation(self, size = 23):
-        """Generates the representation for the ARAD-kernel. Note that this representation is incompatible with generic ``qml.kernel.*`` kernels.
+    def generate_fchl_representation(self, max_size = 23, cell=None, neighbors=24,cut_distance=5.0):
+        """Generates the representation for the FCHL-kernel. Note that this representation is incompatible with generic ``qml.kernel.*`` kernels.
     :param size: Max number of atoms in representation.
     :type size: integer
     """
-        self.representation = generate_arad_representation(self.coordinates,
-                self.nuclear_charges, size=size)
+        self.representation = generate_fchl_representation(self.coordinates,
+                self.nuclear_charges, max_size=max_size, cell=cell, neighbors=neighbors,cut_distance=cut_distance)
 
-        assert (self.representation).shape[0] == size, "ERROR: Check ARAD descriptor size!"
-        assert (self.representation).shape[2] == size, "ERROR: Check ARAD descriptor size!"
+        assert (self.representation).shape[0] == max_size, "ERROR: Check FCHL descriptor size!"
 
     def generate_slatm(self, mbtypes,
         local=False, sigmas=[0.05,0.05], dgrids=[0.03,0.03], rcut=4.8, pbc='000',