Added cites and changed interface to be cite consistent (#17)

* Added citations

* Renamed interface to be consistent with cites

README.rst

@@ -85,15 +85,60 @@ How to use
 How to cite
 ===========
 
-.. code-block:: python
+Please cite the representation that you are using accordingly.
+
+- | **Implementation**
+  Toolkit for Quantum Chemistry Machine Learning,
+  https://github.com/qmlcode/qmllib, <version or git commit>
+
+- | **FCHL19** ``generate_fchl19``
+  FCHL revisited: Faster and more accurate quantum machine learning,
+  Christensen, Bratholm, Faber, Lilienfeld,
+  J. Chem. Phys. 152, 044107 (2020),
+  https://doi.org/10.1063/1.5126701
+
+- | **FCHL18** ``generate_fchl18``
+  Alchemical and structural distribution based representation for universal quantum machine learning,
+  Faber, Christensen, Huang, Lilienfeld,
+  J. Chem. Phys. 148, 241717 (2018),
+  https://doi.org/10.1063/1.5020710
+
+- | **Columb Matrix** ``generate_columnb_matrix_*``
+  Fast and Accurate Modeling of Molecular Atomization Energies with Machine Learning,
+  Rupp, Tkatchenko, Müller, Lilienfeld,
+  Phys. Rev. Lett. 108, 058301 (2012)
+  DOI: https://doi.org/10.1103/PhysRevLett.108.058301
+
+- | **Bag of Bonds (BoB)** ``generate_bob``
+  Assessment and Validation of Machine Learning Methods for Predicting Molecular Atomization Energies,
+  Hansen, Montavon, Biegler, Fazli, Rupp, Scheffler, Lilienfeld, Tkatchenko, Müller,
+  J. Chem. Theory Comput. 2013, 9, 8, 3404–3419
+  https://doi.org/10.1021/ct400195d
+
+- | **SLATM** ``generate_slatm``
+  Understanding molecular representations in machine learning: The role of uniqueness and target similarity,
+  Huang, Lilienfeld,
+  J. Chem. Phys. 145, 161102 (2016)
+  https://doi.org/10.1063/1.4964627
+
+- | **ACSF** ``generate_acsf``
+  Atom-centered symmetry functions for constructing high-dimensional neural network potentials,
+  Behler,
+  J Chem Phys 21;134(7):074106 (2011)
+  https://doi.org/10.1063/1.3553717
+
+- | **AARAD** ``generate_aarad``
+  Alchemical and structural distribution based representation for universal quantum machine learning,
+  Faber, Christensen, Huang, Lilienfeld,
+  J. Chem. Phys. 148, 241717 (2018),
+  https://doi.org/10.1063/1.5020710
 
-    raise NotImplementedError
 
 =========
 What TODO
 =========
 
-* Setup ifort flags
-* Setup based on FCC env variable or --global-option flags
-* Find MKL from env (for example conda)
-* Find what numpy has been linked too (lapack or mkl)
+- Setup ifort flags
+- Setup based on FCC env variable or --global-option flags
+- Find MKL from env (for example conda)
+- Find what numpy has been linked too (lapack or mkl)

src/qmllib/representations/__init__.py

@@ -1 +1,17 @@
-from .representations import *  # noqa:F403
+from qmllib.representations.arad import generate_arad  # noqa:403
+from qmllib.representations.fchl import (  # noqa:F403
+    generate_fchl18,
+    generate_fchl18_displaced,
+    generate_fchl18_displaced_5point,
+    generate_fchl18_electric_field,
+)
+from qmllib.representations.representations import (  # noqa:F403
+    generate_acsf,
+    generate_bob,
+    generate_coulomb_matrix,
+    generate_coulomb_matrix_atomic,
+    generate_coulomb_matrix_eigenvalue,
+    generate_fchl19,
+    generate_slatm,
+    get_slatm_mbtypes,
+)

src/qmllib/representations/arad/arad.py

@@ -23,7 +23,8 @@ def getAngle(sp: ndarray, norms: ndarray) -> ndarray:
     return angles
 
 
-def generate_arad_representation(
+
+def generate_arad(
     nuclear_charges: ndarray, coordinates: ndarray, size: int = 23, cut_distance: float = 5.0
 ) -> ndarray:
     """Generates a representation for the ARAD kernel module.

src/qmllib/representations/fchl/fchl_representations.py

@@ -5,7 +5,7 @@
 from numpy import ndarray
 
 
-def generate_representation(
+def generate_fchl18(
     nuclear_charges: ndarray,
     coordinates: Union[ndarray, List[List[float]]],
     max_size: int = 23,
@@ -84,7 +84,7 @@ def generate_representation(
     return M
 
 
-def generate_displaced_representations(
+def generate_fchl18_displaced(
     nuclear_charges, coordinates, max_size=23, neighbors=23, cut_distance=5.0, cell=None, dx=0.005
 ):
     """Generates displaced representations for the FCHL kernel module.
@@ -121,7 +121,7 @@ def generate_displaced_representations(
                 displaced_coordinates = copy.deepcopy(coordinates)
                 displaced_coordinates[i, xyz] += disp
 
-                rep = generate_representation(
+                rep = generate_fchl18(
                     nuclear_charges,
                     displaced_coordinates,
                     max_size=size,
@@ -135,7 +135,7 @@ def generate_displaced_representations(
     return reps
 
 
-def generate_displaced_representations_5point(
+def generate_fchl18_displaced_5point(
     nuclear_charges, coordinates, max_size=23, neighbors=23, cut_distance=5.0, cell=None, dx=0.005
 ):
     """Generates displaced representations for the FCHL kernel module, using a 5-point stencil.
@@ -172,7 +172,7 @@ def generate_displaced_representations_5point(
                 displaced_coordinates = copy.deepcopy(coordinates)
                 displaced_coordinates[i, xyz] += disp
 
-                rep = generate_representation(
+                rep = generate_fchl18(
                     nuclear_charges,
                     displaced_coordinates,
                     max_size=size,
@@ -186,7 +186,7 @@ def generate_displaced_representations_5point(
     return reps
 
 
-def generate_representation_electric_field(
+def generate_fchl18_electric_field(
     nuclear_charges: ndarray,
     coordinates: ndarray,
     fictitious_charges: Union[ndarray, List[float]] = "gasteiger",

src/qmllib/representations/representations.py

@@ -103,7 +103,7 @@ def generate_coulomb_matrix(
         raise ValueError("Unknown sorting scheme requested")
 
 
-def generate_atomic_coulomb_matrix(
+def generate_coulomb_matrix_atomic(
     nuclear_charges: ndarray,
     coordinates: ndarray,
     size: int = 23,
@@ -240,7 +240,7 @@ def generate_atomic_coulomb_matrix(
         raise ValueError("Unknown sorting scheme requested")
 
 
-def generate_eigenvalue_coulomb_matrix(
+def generate_coulomb_matrix_eigenvalue(
     nuclear_charges: ndarray, coordinates: ndarray, size: int = 23
 ) -> ndarray:
     """ Creates an eigenvalue Coulomb Matrix representation of a molecule.
@@ -332,7 +332,7 @@ def generate_bob(
 def get_slatm_mbtypes(nuclear_charges: List[ndarray], pbc: str = "000") -> List[List[int64]]:
     """
     Get the list of minimal types of many-body terms in a dataset. This resulting list
-    is necessary as input in the ``generate_slatm_representation()`` function.
+    is necessary as input in the ``generate_slatm()`` function.
 
     :param nuclear_charges: A list of the nuclear charges for each compound in the dataset.
     :type nuclear_charges: list of numpy arrays
@@ -729,7 +729,7 @@ def generate_acsf(
             return rep, grad
 
 
-def generate_fchl_acsf(
+def generate_fchl19(
     nuclear_charges: ndarray,
     coordinates: ndarray,
     elements: List[int] = [1, 6, 7, 8, 16],
@@ -748,9 +748,10 @@ def generate_fchl_acsf(
     gradients: bool = False,
 ) -> Union[Tuple[ndarray, ndarray], ndarray]:
     """
-
     FCHL-ACSF
 
+    https://pubs.aip.org/aip/jcp/article/152/4/044107/1064737/FCHL-revisited-Faster-and-more-accurate-quantum
+
     Reasonable hyperparameters:
 
     Sigma ~ 21.0

tests/test_arad.py

@@ -2,7 +2,7 @@
 from conftest import ASSETS, get_energies
 
 from qmllib.representations.arad import (
-    generate_arad_representation,
+    generate_arad,
     get_atomic_kernels_arad,
     get_atomic_symmetric_kernels_arad,
     get_global_kernels_arad,
@@ -30,7 +30,7 @@ def test_arad():
         properties.append(data[filename])
 
     for coord, atoms in molecules:
-        rep = generate_arad_representation(atoms, coord)
+        rep = generate_arad(atoms, coord)
         representations.append(rep)
 
     representations = np.array(representations)
@@ -73,7 +73,7 @@ def test_arad():
     molid = 5
     coordinates, atoms = molecules[molid]
     natoms = len(atoms)
-    X1 = generate_arad_representation(atoms, coordinates, size=natoms)
+    X1 = generate_arad(atoms, coordinates, size=natoms)
     XA = X1[:natoms]
 
     K_atomic_asymm = get_atomic_kernels_arad(XA, XA, sigmas)

tests/test_energy_krr_atomic_cmat.py

@@ -2,7 +2,7 @@
 from conftest import ASSETS, get_energies, shuffle_arrays
 
 from qmllib.kernels import get_local_kernels_gaussian, get_local_kernels_laplacian
-from qmllib.representations import generate_atomic_coulomb_matrix
+from qmllib.representations import generate_coulomb_matrix_atomic
 from qmllib.solvers import cho_solve
 from qmllib.utils.xyz_format import read_xyz
 
@@ -23,7 +23,7 @@ def test_krr_gaussian_local_cmat():
     for filename in filenames:
         coord, atoms = read_xyz((ASSETS / "qm7" / filename).with_suffix(".xyz"))
 
-        representation = generate_atomic_coulomb_matrix(atoms, coord, size=23, sorting="row-norm")
+        representation = generate_coulomb_matrix_atomic(atoms, coord, size=23, sorting="row-norm")
 
         all_representations.append(representation)
         all_properties.append(data[filename])
@@ -106,7 +106,7 @@ def test_krr_laplacian_local_cmat():
     for filename in filenames:
         coord, atoms = read_xyz((ASSETS / "qm7" / filename).with_suffix(".xyz"))
 
-        representation = generate_atomic_coulomb_matrix(atoms, coord, size=23, sorting="row-norm")
+        representation = generate_coulomb_matrix_atomic(atoms, coord, size=23, sorting="row-norm")
 
         all_representations.append(representation)
         all_properties.append(data[filename])

tests/test_fchl_acsf.py

@@ -7,7 +7,7 @@
 import numpy as np
 from conftest import ASSETS
 
-from qmllib.representations import generate_fchl_acsf
+from qmllib.representations import generate_fchl19
 from qmllib.utils.xyz_format import read_xyz
 
 np.set_printoptions(linewidth=666, edgeitems=10)
@@ -20,7 +20,7 @@ def get_acsf_numgrad(coordinates, nuclear_charges, dx=1e-5):
     natoms = len(coordinates)
     true_coords = deepcopy(coordinates)
 
-    true_rep = generate_fchl_acsf(nuclear_charges, coordinates, gradients=False, **REP_PARAMS)
+    true_rep = generate_fchl19(nuclear_charges, coordinates, gradients=False, **REP_PARAMS)
 
     gradient = np.zeros((3, natoms, true_rep.shape[0], true_rep.shape[1]))
 
@@ -30,25 +30,25 @@ def get_acsf_numgrad(coordinates, nuclear_charges, dx=1e-5):
             temp_coords = deepcopy(true_coords)
             temp_coords[n, xyz] = x + 2.0 * dx
 
-            (rep, grad) = generate_fchl_acsf(
+            (rep, grad) = generate_fchl19(
                 nuclear_charges, temp_coords, gradients=True, **REP_PARAMS
             )
             gradient[xyz, n] -= rep
 
             temp_coords[n, xyz] = x + dx
-            (rep, grad) = generate_fchl_acsf(
+            (rep, grad) = generate_fchl19(
                 nuclear_charges, temp_coords, gradients=True, **REP_PARAMS
             )
             gradient[xyz, n] += 8.0 * rep
 
             temp_coords[n, xyz] = x - dx
-            (rep, grad) = generate_fchl_acsf(
+            (rep, grad) = generate_fchl19(
                 nuclear_charges, temp_coords, gradients=True, **REP_PARAMS
             )
             gradient[xyz, n] -= 8.0 * rep
 
             temp_coords[n, xyz] = x - 2.0 * dx
-            (rep, grad) = generate_fchl_acsf(
+            (rep, grad) = generate_fchl19(
                 nuclear_charges, temp_coords, gradients=True, **REP_PARAMS
             )
             gradient[xyz, n] += rep
@@ -66,11 +66,9 @@ def test_fchl_acsf():
 
     coordinates, nuclear_charges = read_xyz(ASSETS / "qm7/0101.xyz")
 
-    (repa, anal_grad) = generate_fchl_acsf(
-        nuclear_charges, coordinates, gradients=True, **REP_PARAMS
-    )
+    (repa, anal_grad) = generate_fchl19(nuclear_charges, coordinates, gradients=True, **REP_PARAMS)
 
-    repb = generate_fchl_acsf(nuclear_charges, coordinates, gradients=False, **REP_PARAMS)
+    repb = generate_fchl19(nuclear_charges, coordinates, gradients=False, **REP_PARAMS)
 
     assert np.allclose(repa, repb), "Error in FCHL-ACSF representation implementation"
 

tests/test_fchl_acsf_energy.py

@@ -2,7 +2,7 @@
 from conftest import ASSETS, get_energies, shuffle_arrays
 
 from qmllib.kernels import get_local_kernel, get_local_symmetric_kernel
-from qmllib.representations import generate_fchl_acsf
+from qmllib.representations import generate_fchl19
 from qmllib.solvers import cho_solve
 from qmllib.utils.xyz_format import read_xyz
 
@@ -27,7 +27,7 @@ def test_energy():
         # Associate a property (heat of formation) with the object
         all_properties.append(data[xyz_file])
 
-        representation = generate_fchl_acsf(atoms, coord, gradients=False, pad=27)
+        representation = generate_fchl19(atoms, coord, gradients=False, pad=27)
 
         all_representations.append(representation)
         all_atoms.append(atoms)

tests/test_fchl_acsf_forces.py

@@ -12,7 +12,7 @@
     get_gp_kernel,
     get_symmetric_gp_kernel,
 )
-from qmllib.representations import generate_fchl_acsf
+from qmllib.representations import generate_fchl19
 from qmllib.solvers import cho_solve, svd_solve
 
 np.set_printoptions(linewidth=999, edgeitems=10, suppress=True)
@@ -59,7 +59,7 @@ def get_reps(df):
 
         energy = float(df["atomization_energy"][i])
 
-        (x1, dx1) = generate_fchl_acsf(nuclear_charges, coordinates, gradients=True, pad=max_atoms)
+        (x1, dx1) = generate_fchl19(nuclear_charges, coordinates, gradients=True, pad=max_atoms)
 
         x.append(x1)
         f.append(force)