Commit b5c348c0 authored by Malthe Kjær Bisbo's avatar Malthe Kjær Bisbo
Browse files

Added further documentation, fixed problem with restart option, added gauss_kernel hessian

parent f1210e0d
<!DOCTYPE html>
<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>GOFEE &mdash; GOFEE documentation</title>
<script type="text/javascript" src="../_static/js/modernizr.min.js"></script>
<script type="text/javascript" id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
<script type="text/javascript" src="../_static/jquery.js"></script>
<script type="text/javascript" src="../_static/underscore.js"></script>
<script type="text/javascript" src="../_static/doctools.js"></script>
<script type="text/javascript" src="../_static/language_data.js"></script>
<script type="text/javascript" src="../_static/js/theme.js"></script>
<link rel="stylesheet" href="../_static/css/theme.css" type="text/css" />
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
<link rel="prev" title="Modifying surrogate model" href="../tutorial/modifying_surrogate_model/modifying_surrogate_model.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home"> GOFEE
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
<ul class="current">
<li class="toctree-l1"><a class="reference internal" href="../installation/installation.html">Installation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../getting_started/getting_started.html">Getting started</a></li>
<li class="toctree-l1"><a class="reference internal" href="../tutorial/tutorial.html">Tutorial</a></li>
<li class="toctree-l1 current"><a class="current reference internal" href="#">GOFEE</a><ul>
<li class="toctree-l2"><a class="reference internal" href="#surrogate">Surrogate</a></li>
<li class="toctree-l2"><a class="reference internal" href="#kernel">Kernel</a></li>
<li class="toctree-l2"><a class="reference internal" href="#startgenerator">StartGenerator</a></li>
<li class="toctree-l2"><a class="reference internal" href="#candidategenerator">CandidateGenerator</a></li>
<li class="toctree-l2"><a class="reference internal" href="#rattlemutation">RattleMutation</a></li>
<li class="toctree-l2"><a class="reference internal" href="#permutationmutation">PermutationMutation</a></li>
</ul>
</li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
<nav class="wy-nav-top" aria-label="top navigation">
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">GOFEE</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="breadcrumbs navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html">Docs</a> &raquo;</li>
<li>GOFEE</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/GOFEE/GOFEE.rst.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<div class="section" id="gofee">
<h1>GOFEE<a class="headerlink" href="#gofee" title="Permalink to this headline"></a></h1>
<dl class="class">
<dt id="gofee.GOFEE">
<em class="property">class </em><code class="sig-prename descclassname">gofee.</code><code class="sig-name descname">GOFEE</code><span class="sig-paren">(</span><em class="sig-param">structures=None</em>, <em class="sig-param">calc=None</em>, <em class="sig-param">gpr=None</em>, <em class="sig-param">startgenerator=None</em>, <em class="sig-param">candidate_generator=None</em>, <em class="sig-param">trajectory='structures.traj'</em>, <em class="sig-param">kappa=2</em>, <em class="sig-param">max_steps=200</em>, <em class="sig-param">Ninit=10</em>, <em class="sig-param">max_relax_dist=4</em>, <em class="sig-param">Ncandidates=30</em>, <em class="sig-param">population_size=10</em>, <em class="sig-param">dualpoint=True</em>, <em class="sig-param">min_certainty=0.7</em>, <em class="sig-param">restart='restart.pickl'</em><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE" title="Permalink to this definition"></a></dt>
<dd><p>GOFEE global structure search method.</p>
<p>Parameters:</p>
<dl class="simple">
<dt>structures: Atoms-object, list of Atoms-objects or None</dt><dd><p>In initial structures from which to start the sesarch.
If None, the startgenerator must be supplied.
If less than Ninit structures is supplied, the remaining
ones are generated using the startgenerator or by rattling
the supplied structures, depending on wether the
startgenerator is supplied.</p>
</dd>
<dt>calc: ASE calculator</dt><dd><p>Specifies the energy-expression
with respect to which the atomic coordinates are
globally optimized.</p>
</dd>
<dt>gpr: GPR object</dt><dd><p>The Gaussian Process Regression model used as the
surrogate model for the Potential energy surface.</p>
</dd>
<dt>startgenerator: Startgenerator object</dt><dd><p>Used to generate initial random
structures. Must be supplied if structures if structues=None.
(This is the recommended way to initialize the search.)</p>
</dd>
<dt>candidate_generator: OperationSelector object</dt><dd><p>Object used to generate new candidates.</p>
</dd>
<dt>trajectory: str</dt><dd><p>Name of trajectory to which all structures,
evaluated during the search, is saved.</p>
</dd>
<dt>kappa: float</dt><dd><p>How much to weigh predicted uncertainty in the acquisition
function.</p>
</dd>
<dt>max_steps: int</dt><dd><p>Number of search steps.</p>
</dd>
<dt>Ninit: int</dt><dd><p>Number of initial structures. If len(structures) &lt;
Ninit, the remaining structures are generated using the
startgenerator (if supplied) or by rattling the supplied
‘structures’.</p>
</dd>
<dt>max_relax_dist: float</dt><dd><p>Max distance (in Angstrom) that an atom is allowed to
move during surrogate relaxation.</p>
</dd>
<dt>Ncandidates: int</dt><dd><p>Number of new cancidate structures generated and
surrogate-relaxed in each search iteration.</p>
</dd>
<dt>population_size: int</dt><dd><p>Maximum number of structures in the population.</p>
</dd>
<dt>dualpoint: boolean</dt><dd><p>Whether to use dualpoint evaluation or not.</p>
</dd>
<dt>min_certainty: float</dt><dd><p>Max predicted uncertainty allowed for structures to be
considdered for evaluation. (in units of the maximum possible
uncertainty.)</p>
</dd>
<dt>restart: str</dt><dd><p>Filename for restart file.</p>
</dd>
</dl>
<dl class="method">
<dt id="gofee.GOFEE.certainty_filter">
<code class="sig-name descname">certainty_filter</code><span class="sig-paren">(</span><em class="sig-param">structures</em><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.certainty_filter" title="Permalink to this definition"></a></dt>
<dd><p>Method to filter away the most uncertain surrogate-relaxed
candidates, which might otherewise get picked for first-principles
evaluation, based on the very high uncertainty alone.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.dump">
<code class="sig-name descname">dump</code><span class="sig-paren">(</span><em class="sig-param">data</em><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.dump" title="Permalink to this definition"></a></dt>
<dd><p>Method to save restart-file used if the search is
restarted from some point in the search.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.evaluate">
<code class="sig-name descname">evaluate</code><span class="sig-paren">(</span><em class="sig-param">a</em><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.evaluate" title="Permalink to this definition"></a></dt>
<dd><p>Method to evaluate the energy and forces of the selacted
candidate.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.evaluate_initial_structures">
<code class="sig-name descname">evaluate_initial_structures</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.evaluate_initial_structures" title="Permalink to this definition"></a></dt>
<dd><p>Evaluate energies and forces of all initial structures
(self.structures) that have not yet been evaluated.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.generate_candidate">
<code class="sig-name descname">generate_candidate</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.generate_candidate" title="Permalink to this definition"></a></dt>
<dd><p>Method to generate new candidate.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.get_dualpoint">
<code class="sig-name descname">get_dualpoint</code><span class="sig-paren">(</span><em class="sig-param">a</em>, <em class="sig-param">lmax=0.1</em>, <em class="sig-param">Fmax_flat=5</em><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.get_dualpoint" title="Permalink to this definition"></a></dt>
<dd><p>Returns dual-point structure, i.e. the original structure
perturbed slightly along the forces.</p>
<p>lmax: The atom with the largest force will be displaced by
this distance</p>
<p>Fmax_flat: maximum atomic displacement. is increased linearely
with force until Fmax = Fmax_flat, after which it remains
constant as lmax.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.get_initial_structures">
<code class="sig-name descname">get_initial_structures</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.get_initial_structures" title="Permalink to this definition"></a></dt>
<dd><p>Method to prepare the initial structures for the search.</p>
<p>The method makes sure that there are atleast self.Ninit
initial structures.
These structures are first of all the potentially supplied
structures. If more structures are required, these are
generated using self.startgenerator (if supplied), otherwise
they are generated by heavily rattling the supplied structures.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.get_surrogate_relaxed_candidates">
<code class="sig-name descname">get_surrogate_relaxed_candidates</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.get_surrogate_relaxed_candidates" title="Permalink to this definition"></a></dt>
<dd><p>Method supplying a number of surrogate-relaxed new
candidates. The method combines the generation of new
candidates with subsequent surrogate relaxation.
The tasks are parrlelized over all avaliable cores.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.read">
<code class="sig-name descname">read</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.read" title="Permalink to this definition"></a></dt>
<dd><p>Method to restart a search from the restart-file and the
trajectory-file containing all structures evaluated so far.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.run">
<code class="sig-name descname">run</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.run" title="Permalink to this definition"></a></dt>
<dd><p>Method to run the search.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.select_with_acquisition">
<code class="sig-name descname">select_with_acquisition</code><span class="sig-paren">(</span><em class="sig-param">structures</em>, <em class="sig-param">kappa</em><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.select_with_acquisition" title="Permalink to this definition"></a></dt>
<dd><p>Method to select single most “promizing” candidate
for first-principles evaluation according to the acquisition
function min(E-kappa*std(E)).</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.surrogate_relaxation">
<code class="sig-name descname">surrogate_relaxation</code><span class="sig-paren">(</span><em class="sig-param">a</em>, <em class="sig-param">Fmax=0.1</em>, <em class="sig-param">steps=200</em>, <em class="sig-param">kappa=None</em><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.surrogate_relaxation" title="Permalink to this definition"></a></dt>
<dd><p>Method to carry out relaxations of new candidates in the
surrogate potential.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.train_surrogate">
<code class="sig-name descname">train_surrogate</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.train_surrogate" title="Permalink to this definition"></a></dt>
<dd><p>Method to train the surrogate model.
The method only performs hyperparameter optimization every
ten training instance, as carrying out the hyperparameter
optimization is significantly more expensive than the basic
training.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.update_population">
<code class="sig-name descname">update_population</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.update_population" title="Permalink to this definition"></a></dt>
<dd><p>Method to update the population with the new pirst-principles
evaluated structures.</p>
</dd></dl>
<dl class="method">
<dt id="gofee.GOFEE.write">
<code class="sig-name descname">write</code><span class="sig-paren">(</span><em class="sig-param">a</em><span class="sig-paren">)</span><a class="headerlink" href="#gofee.GOFEE.write" title="Permalink to this definition"></a></dt>
<dd><p>Method for writing new evaluated structures to file.</p>
</dd></dl>
</dd></dl>
<div class="section" id="surrogate">
<h2>Surrogate<a class="headerlink" href="#surrogate" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="kernel">
<h2>Kernel<a class="headerlink" href="#kernel" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="startgenerator">
<h2>StartGenerator<a class="headerlink" href="#startgenerator" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="candidategenerator">
<h2>CandidateGenerator<a class="headerlink" href="#candidategenerator" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="rattlemutation">
<h2>RattleMutation<a class="headerlink" href="#rattlemutation" title="Permalink to this headline"></a></h2>
</div>
<div class="section" id="permutationmutation">
<h2>PermutationMutation<a class="headerlink" href="#permutationmutation" title="Permalink to this headline"></a></h2>
</div>
</div>
</div>
</div>
<footer>
<div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
<a href="../tutorial/modifying_surrogate_model/modifying_surrogate_model.html" class="btn btn-neutral float-left" title="Modifying surrogate model" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left"></span> Previous</a>
</div>
<hr/>
<div role="contentinfo">
<p>
&copy; Copyright 2020, Malthe Kjær Bisbo, Bjørk Hammer
</p>
</div>
Built with <a href="http://sphinx-doc.org/">Sphinx</a> using a <a href="https://github.com/rtfd/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
</footer>
</div>
</div>
</section>
</div>
<script type="text/javascript">
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
\ No newline at end of file
=====
GOFEE
=====
.. autoclass:: gofee.GOFEE
:members:
Surrogate
=========
.. .. autoclass:: surrogate.gpr.GPR
:members:
Kernel
======
StartGenerator
==============
CandidateGenerator
==================
RattleMutation
==============
PermutationMutation
===================
\ No newline at end of file
===============
Getting started
===============
GOFEE is implemented in python, so a basic understanding of python
is neccisary to use the program.
In addition it relies heavily on the python library ASE
(Atomic Simulation Environment). In particular, some ASE methods
are used to set up the atomistic system of interest, prior to a
GOFEE search. It is therefore a prerequisite to also have basic
experience with especially the :class:`Atoms` object of ASE as well as
trajectory files.
Before continuing complete the :ref:`installation guide <installation>`,
if you have not done it already.
Otherwise you can start getting familiar with GOFEE by going through
some of the examples in the :ref:`tutorial <tutorial>`.
.. GOFEE documentation master file, created by
sphinx-quickstart on Wed Jan 22 20:36:44 2020.
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
Welcome to the documentation for GOFEE!
=================================
=======================================
The global optimization with first-principles energy expression (GOFEE) is
a global optimization method used to optimize the geometry of atomistic
systems.
......@@ -12,5 +8,8 @@ systems.
.. toctree::
:maxdepth: 2
installation/installation
getting_started/getting_started
tutorial/tutorial
GOFEE/GOFEE
.. _installation:
============
Installation
============
=====
GOFEE
=====
The following is an introduction to the structure determination method
:class:`GOFEE`, which relies on Gaussian Process Regression model to
more efficiently explore the configurational search space.
When initializing the search, the two most important pieces of
information, is what system to optimize and what energy expression
(in the form of an ase.calculator) to optimize with respect to.
The calculator is supplied using the ``calc`` keyword.
One way of supplying what system to optimize (although not the typically
recomended one) is to use the ``structures`` keyword to supply
:class:`GOFEE` with a number of pre-prepared ASE :class:`Atoms` objects.
Initializing the search with just a structure and a calculator, and running
the search for 200 iterations using ``max_steps``, can then look like this::
# Creates: structures.traj
import numpy as np
from ase import Atoms
from gpaw import GPAW, FermiDirac, PoissonSolver, Mixer, PW
from gpaw import extra_parameters
extra_parameters['blacs'] = True
from gpaw.utilities import h2gpts
from gofee import GOFEE
# Define calculator
calc=GPAW(poissonsolver = PoissonSolver(relax = 'GS',eps = 1.0e-7),
mode = 'lcao',
basis = 'dzp',
xc='PBE',
gpts = h2gpts(0.2, slab.get_cell(), idiv = 8),
occupations=FermiDirac(0.1),
maxiter=99,
mixer=Mixer(nmaxold=5, beta=0.05, weight=75),
nbands=-50,
kpts=(1,1,1))
# Load structure to initialise search
positions = np.random.uniform(8.5,11.5,36).reshape(-1,3)
a = Atoms('C6H6',
positions=positions,
cell=(20,20,20))
# Initialize and run search
search = GOFEE(structures=a,
calc=calc,
trajectory='structures.traj',
max_steps=200)
search.run()
The search must be run in parallel using MPI. To run the code in
parallel on grendel, use a .job script like the following::
#!/bin/bash
#SBATCH --job-name=C6H6_0
#SBATCH --partition=q12,q16,q16l,q20
#SBATCH --mem=30G
#SBATCH --nodes=1
#SBATCH --time=6:00:00
##SBATCH --exclusive
#SBATCH --ntasks-per-node=10
#SBATCH --cpus-per-task=1
#SBATCH --no-requeue
#SBATCH --array=0-2%3
echo "========= Job started at `date` =========="
# Go to the directory where this job was submitted
cd $SLURM_SUBMIT_DIR
source /home/mkb/.gpaw_py3
source /home/mkb/.GOFEE
# Setup directories to run the search in
base_path=$SLURM_SUBMIT_DIR/runs0/run$SLURM_ARRAY_TASK_ID
mkdir $base_path
# Copy files
cp run_search.py $base_path
cp slab.traj $base_path
# Go to execution directory and run code
cd $base_path
mpiexec --mca mpi_warn_on_fork 0 gpaw-python run_search.py > search.log
echo "========= Job finished at `date` =========="
Other possible keywords are: ``gpr``, ``startgenerator``,
``candidate_generator``, ``trajectory``, ``kappa``, ``Ninit``, ``dmax_cov``,
``Ncandidates``, ``population_size``, ``dualpoint``, ``min_certainty``,
``restart``, which will all be discussed below.
Specifying the system - structures or startgenerator
====================================================
There two ways of supplying the information of what system to optimize.
1) As illustrated above, the search can be initialized with one or more
:class:`Atoms` objects, and the search will optimize all non-fixed
atoms in the system.
2) (The recomended approach) By defining a :class:`StartGenerator`,
that randomly initializes the atoms, to be optimized, within a
user-specified box. Using this box, the atoms are placed within
the cell of a supplied :class:`Atoms` objects, which potentially
contains a number of fixed 'template' atoms. As an example, a
:class:`StartGenerator` for a search for benzene can be mase as::
import numpy as np
from candidate_operations.candidate_generation import StartGenerator
# make slab
slab = Atoms('',
cell=[20,20,20],
pbc=[0, 0, 0])
# Stoichiometry of atoms to be placed
stoichiometry = 6*[1]+6*[6]
# Box in which to place atoms