Skip to content
This repository was archived by the owner on Dec 8, 2024. It is now read-only.

Commit 3d7487d

Browse files
andersxandersx
authored
Fchl doc (#41)
* Updated FCHL documentation
1 parent e356f0c commit 3d7487d

File tree

8 files changed

+362
-189
lines changed

8 files changed

+362
-189
lines changed

‎.travis.yml

+41-39
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,12 @@
11
language: python
2+
23
sudo: required
34
dist: trusty
5+
46
group: edge
7+
58
deploy:
6-
# matrix:
7-
# - provider: pypi
8-
# user: andersx
9-
# on:
10-
# branch: master
11-
# condition: ${TRAVIS_PYTHON_VERSION} = "2.7"
12-
# password:
13-
# 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=
14-
- provider: pages
9+
provider: pages
1510
local_dir: ${TRAVIS_BUILD_DIR}/docs/build/html
1611
skip_cleanup: true
1712
repo: qmlcode/qmlcode.github.io
@@ -20,40 +15,47 @@ deploy:
2015
on:
2116
branch: master
2217
condition: ${TRAVIS_PYTHON_VERSION} = "2.7"
18+
2319
python:
24-
- '2.7'
25-
- '3.5'
26-
- '3.6'
20+
- "2.7"
21+
- "3.5"
22+
- "3.6"
23+
2724
before_install:
28-
- sudo apt-get update -qq
25+
- sudo apt-get update -qq
26+
2927
install:
30-
- sudo apt-get install -qq gcc gfortran libblas-dev liblapack-dev
31-
- sudo apt-get install -qq gcc-4.8 gfortran-4.8
32-
- |
33-
if [ ${TRAVIS_PYTHON_VERSION:0:1} = 3 ]; then
34-
sudo apt-get install python3-numpy
35-
pip3 install scipy
36-
python3 setup.py build
37-
python3 setup.py install
38-
pip3 install sphinx
39-
pip3 install sphinx-rtd-theme
40-
cd ${TRAVIS_BUILD_DIR}/docs
41-
make html
42-
elif [ ${TRAVIS_PYTHON_VERSION} = "2.7" ]; then
43-
sudo apt-get install python-numpy
44-
pip2 install scipy
45-
python2 setup.py build
46-
python2 setup.py install
47-
pip2 install sphinx
48-
pip2 install sphinx-rtd-theme
49-
cd ${TRAVIS_BUILD_DIR}/docs
50-
make html
51-
else
52-
echo "ERROR: Unknown Python version."
53-
fi
28+
- sudo apt-get install -qq gcc gfortran libblas-dev liblapack-dev
29+
- sudo apt-get install -qq gcc-4.8 gfortran-4.8
30+
- |
31+
if [ ${TRAVIS_PYTHON_VERSION:0:1} = 3 ]; then
32+
sudo apt-get install python3-numpy
33+
pip3 install scipy
34+
python3 setup.py build
35+
python3 setup.py install
36+
pip3 install sphinx
37+
pip3 install sphinx-rtd-theme
38+
cd ${TRAVIS_BUILD_DIR}/docs
39+
make html
40+
elif [ ${TRAVIS_PYTHON_VERSION} = "2.7" ]; then
41+
sudo apt-get install python-numpy
42+
pip2 install scipy
43+
python2 setup.py build
44+
python2 setup.py install
45+
pip2 install sphinx
46+
pip2 install sphinx-rtd-theme
47+
cd ${TRAVIS_BUILD_DIR}/docs
48+
make html
49+
else
50+
echo "ERROR: Unknown Python version."
51+
fi
52+
53+
5454
before_script:
55-
- cd ${TRAVIS_BUILD_DIR}/tests/
55+
- cd ${TRAVIS_BUILD_DIR}/tests/
56+
5657
script:
57-
- nosetests -v
58+
- nosetests -v
59+
5860
notifications:
5961
email: false

‎docs/source/examples.rst

+110-30
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
xamples
1+
Examples
22
--------
33

44
Generating representations using the ``Compound`` class
@@ -132,12 +132,14 @@ The easiest way to calculate the kernel matrix using an explicit, local represen
132132
133133
(3, 7101, 7101)
134134
135+
Note that ``mol.representation`` is just a 1D numpy array.
136+
135137

136138
Generating the SLATM representation
137139
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
138140

139141
The Spectrum of London and Axillrod-Teller-Muto potential (SLATM) representation requires additional input to reduce the size of the representation.
140-
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.:
142+
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.:
141143

142144

143145
.. code:: python
@@ -171,64 +173,142 @@ The ``local`` keyword in this example specifies that a local representation is p
171173
# Generate one representation
172174
rep = generate_slatm(coordinates, nuclear_charges, mbtypes)
173175
174-
Generating the ARAD representation and kernels
176+
Here ``coordinates`` is an Nx3 numpy array, and ``nuclear_charges`` is simply a list of charges.
177+
178+
Generating the FCHL representation
175179
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
176-
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.
177-
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.
180+
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.
181+
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.
178182

179-
.. code:: python
183+
The code below show three ways to create the input representations for the FHCL kernel functions.
180184

181-
from qml.arad import get_local_kernels_arad
185+
First using the ``Compound`` class:
182186

183-
# Assume the QM7 dataset is loaded into a list of Compound()
184-
for compound in qm7:
187+
.. code:: python
185188
186-
# Generate the desired representation for each compound
187-
compound.generate_arad_representation(size=23)
189+
# Assume the dataset is loaded into a list of Compound()
190+
for compound in mols:
191+
192+
# Generate the desired representation for each compound, cut off in angstrom
193+
compound.generate_fchl_representation(size=23, cut_off=10.0)
188194
189-
# Make Numpy array of the representation
190-
X = np.array([c.representation for c in qm7])
195+
# Make Numpy array of the representation, which can be parsed to the kernel
196+
X = np.array([c.representation for c in mols])
191197
192-
# List of kernel-widths
193-
sigmas = [50.0, 100.0, 200.0]
198+
199+
The dimensions of the array should be ``(number_molecules, size, 5, size)``, where ``size`` is the
200+
size keyword used when generating the representations.
201+
202+
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.
203+
204+
205+
.. code:: python
206+
207+
from qml.fchl import generate_representation
208+
209+
# Dummy coordinates for a water molecule
210+
coordinates = np.array([[1.464, 0.707, 1.056],
211+
[0.878, 1.218, 0.498],
212+
[2.319, 1.126, 0.952]])
213+
214+
# Oxygen, Hydrogen, Hydrogen
215+
nuclear_charges = np.array([8, 1, 1])
216+
217+
rep = generate_representation(coordinates, nuclear_charges)
218+
219+
To create the representation for a crystal, the notation is as follows:
220+
221+
222+
.. code:: python
223+
224+
from qml.fchl import generate_representation
225+
226+
# Dummy fractional coordinates
227+
fractional_coordinates = np.array(
228+
[[ 0. , 0. , 0. ],
229+
[ 0.75000042, 0.50000027, 0.25000015],
230+
[ 0.15115386, 0.81961403, 0.33154037],
231+
[ 0.51192691, 0.18038651, 0.3315404 ],
232+
[ 0.08154025, 0.31961376, 0.40115401],
233+
[ 0.66846017, 0.81961403, 0.48807366],
234+
[ 0.08154025, 0.68038678, 0.76192703],
235+
[ 0.66846021, 0.18038651, 0.84884672],
236+
[ 0.23807355, 0.31961376, 0.91846033],
237+
[ 0.59884657, 0.68038678, 0.91846033],
238+
[ 0.50000031, 0. , 0.50000031],
239+
[ 0.25000015, 0.50000027, 0.75000042]]
240+
)
241+
242+
# Dummy nuclear charges
243+
nuclear_charges = np.array(
244+
[58, 58, 8, 8, 8, 8, 8, 8, 8, 8, 23, 23]
245+
)
246+
247+
# Dummy unit cell
248+
unit_cell = np.array(
249+
[[ 3.699168, 3.699168, -3.255938],
250+
[ 3.699168, -3.699168, 3.255938],
251+
[-3.699168, -3.699168, -3.255938]]
252+
)
253+
254+
# Generate the representation
255+
rep = generate_representation(fractional_coordinates, nuclear_charges,
256+
cell=unit_cell, neighbors=100, cut_distance=7.0)
257+
258+
259+
The neighbors keyword is the max number of atoms with the cutoff-distance
260+
261+
Generating the FCHL kernel
262+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
263+
264+
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.
265+
266+
267+
.. code:: python
268+
269+
from qml.fchl import get_local_kernels
270+
271+
# You can get kernels for multiple kernel-widths
272+
sigmas = [2.5, 5.0, 10.0]
194273
195274
# Calculate the kernel-matrices for each sigma
196-
K = get_local_kernels_arad(X, X, sigmas)
275+
K = get_local_kernels(X1, X2, sigmas, cut_distance=10.0)
197276
198277
print(K.shape)
199278
200-
.. code::
201279
202-
(3, 7101, 7101)
280+
As output you will get a kernel for each kernel-width.
203281

204-
The dimensions of the input should be ``(number_molecules, size, 5, size)``, where ``size`` is the
205-
size keyword used when generating the representations.
282+
.. code::
283+
284+
(3, 100, 200)
206285
207-
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.
208286
209-
In case the two datasets used to calculate the kernel matrix are identical
210-
- resulting in a symmetric kernel matrix - it is possible use a faster kernel,
211-
since only half of the kernel elements must be calculated explicitly:
287+
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).
212288

213289
.. code:: python
290+
291+
from qml.fchl import get_local_symmetric_kernels
214292
215-
from qml.arad import get_local_symmetric_kernels_arad
293+
# You can get kernels for multiple kernel-widths
294+
sigmas = [2.5, 5.0, 10.0]
216295
217296
# Calculate the kernel-matrices for each sigma
218-
K = get_local_symmetric_kernels_arad(X, sigmas)
297+
K = get_local_kernels(X1, sigmas, cut_distance=10.0)
219298
220299
print(K.shape)
221300
301+
222302
.. code::
223303
224-
(3, 7101, 7101)
304+
(3, 100, 100)
225305
226-
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".
306+
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".
227307

228308
.. code:: python
229309
230-
from qml.arad import get_atomic_kernels_arad
231-
from qml.arad import get_atomic_symmetric_kernels_arad
310+
from qml.fchl import get_atomic_kernels
311+
from qml.fchl import get_atomic_symmetric_kernels
232312
233313
The only difference between the local and atomic kernels is the shape of the input.
234314
Since the atomic kernel outputs kernels with atomic resolution, the atomic input has the shape ``(number_atoms, 5, size)``.

‎docs/source/qml.rst

+6-6
Original file line numberDiff line numberDiff line change
@@ -45,12 +45,12 @@ qml\.Compound class
4545
:undoc-members:
4646
:show-inheritance:
4747

48-
qml\.arad module
49-
----------------
50-
51-
.. automodule:: qml.arad
52-
:members:
53-
:show-inheritance:
48+
.. qml\.arad module
49+
.. ----------------
50+
..
51+
.. .. automodule:: qml.arad
52+
.. :members:
53+
.. :show-inheritance:
5454
5555
qml\.fchl module
5656
----------------

‎qml/compound.py

+6-7
Original file line numberDiff line numberDiff line change
@@ -33,7 +33,7 @@
3333
from .representations import generate_eigenvalue_coulomb_matrix
3434
from .representations import generate_slatm
3535

36-
from .arad import generate_arad_representation
36+
from .fchl import generate_representation as generate_fchl_representation
3737

3838
class Compound(object):
3939
""" 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}):
245245
self.representation = generate_bob(self.nuclear_charges, self.coordinates,
246246
self.atomtypes, asize = asize)
247247

248-
def generate_arad_representation(self, size = 23):
249-
"""Generates the representation for the ARAD-kernel. Note that this representation is incompatible with generic ``qml.kernel.*`` kernels.
248+
def generate_fchl_representation(self, max_size = 23, cell=None, neighbors=24,cut_distance=5.0):
249+
"""Generates the representation for the FCHL-kernel. Note that this representation is incompatible with generic ``qml.kernel.*`` kernels.
250250
:param size: Max number of atoms in representation.
251251
:type size: integer
252252
"""
253-
self.representation = generate_arad_representation(self.coordinates,
254-
self.nuclear_charges, size=size)
253+
self.representation = generate_fchl_representation(self.coordinates,
254+
self.nuclear_charges, max_size=max_size, cell=cell, neighbors=neighbors,cut_distance=cut_distance)
255255

256-
assert (self.representation).shape[0] == size, "ERROR: Check ARAD descriptor size!"
257-
assert (self.representation).shape[2] == size, "ERROR: Check ARAD descriptor size!"
256+
assert (self.representation).shape[0] == max_size, "ERROR: Check FCHL descriptor size!"
258257

259258
def generate_slatm(self, mbtypes,
260259
local=False, sigmas=[0.05,0.05], dgrids=[0.03,0.03], rcut=4.8, pbc='000',

0 commit comments

Comments
 (0)