.. role:: raw-html-m2r(raw)
:format: html
Evolutionary search
===================
Overview
--------
The key features and performance of the evolutionary search (EVOS) are
described in Section 6 of Ref. [1_]. The evolutionary algorithm (EA)
enables an efficient identification of ground state configurations at
a given chemical composition. The EA is particularly advantageous in
dealing with large structures when no experimental structural input is
available [2_] [3_].
The searches can be performed for 3D crystals, 2D films, and 0D
clusters. Population of structures can be generated either randomly or
using available structural information. Essential evolutionary
operations are 'crossover', when a new configuration is created based
on two parent structures in the previous generation, and 'mutation',
when a parent structure is randomly distorted.
For 0D nanoparticles, we have introduced a multitribe EA that allows
an efficient simultaneous optimization of clusters in a specified size
range [4_]. A separate bash script is needed to submit the
co-evolutionary search and exchange seeds among tribes at the end of
each cycle of isolated evolution.
The EA engine in MAISE expects local relaxations of structures to be
performed by an external code (flag `CODE <#code>`_) using a
queueing system (flag `QUET <#quet>`_). The current version is linked
with VASP for DFT calculations and with MAISE for neural network
calculations. The majority of the algorithm's numerous parameters
related to the generation, evolution, and selection of structures have
been tuned for typical crystalline unit cells with up to about 50
atoms and clusters with a few hundred atoms.
In order to run an EA optimization, the user should
+ configure the ``setup`` file (`Internal settings`_)
+ place submission files in the ``INI`` directory (`External settings`_)
+ run ``maise`` in the automated or manual mode (`Job execution`_)
.. _1: https://arxiv.org/abs/2005.12131
.. _2: https://journals.aps.org/prb/abstract/10.1103/PhysRevB.95.014114
.. _3: https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.109.075501
.. _4: https://pubs.rsc.org/en/content/articlelanding/2019/cp/c9cp00837c#!divAbstract
Internal settings
-----------------
All internal settings are specified in the ``setup`` file.
`Table 1 <#table1>`_ lists the group of general FLAGs that define the system type, population size, queue type, analysis, etc.
.. _table1:
.. table:: Table 1: General evolutionary search FLAGs.
+-----------------+-----------------------------------------------------------+
| FLAG | Short description |
| | |
+=================+===========================================================+
| `JOBT <#jobt>`_ | EVOS: auto run (10); soft exit (11); hard exit (12) |
| | analysis (13); manual run (14) |
+-----------------+-----------------------------------------------------------+
| `NMAX <#nmax>`_ | maximum number of atoms |
+-----------------+-----------------------------------------------------------+
| `MMAX <#mmax>`_ | maximum number of neighbors within cutoff radius |
+-----------------+-----------------------------------------------------------+
| `NSPC <#nspc>`_ | number of species types |
+-----------------+-----------------------------------------------------------+
| `TSPC <#tspc>`_ | species types |
+-----------------+-----------------------------------------------------------+
| `ASPC <#aspc>`_ | atom number of each species |
+-----------------+-----------------------------------------------------------+
| `CODE <#code>`_ | MAISE-INT (0); VASP-EXT (1); MAISE-EXT (2) |
+-----------------+-----------------------------------------------------------+
| `QUET <#quet>`_ | queue type: torque (0); slurm (1) |
+-----------------+-----------------------------------------------------------+
| `NDIM <#ndim>`_ | structure type: crystal (3); film (2); cluster (0) |
+-----------------+-----------------------------------------------------------+
| `LBOX <#lbox>`_ | box size for clusters or films |
+-----------------+-----------------------------------------------------------+
| `NPOP <#npop>`_ | population size |
+-----------------+-----------------------------------------------------------+
| `SITR <#sitr>`_ | starting iteration |
+-----------------+-----------------------------------------------------------+
| `NITR <#nitr>`_ | number of iterations |
+-----------------+-----------------------------------------------------------+
| `TINI <#tini>`_ | starting options if SITR=0 |
+-----------------+-----------------------------------------------------------+
| `TIME <#time>`_ | max time per relaxation |
+-----------------+-----------------------------------------------------------+
| `PGPA <#pgpa>`_ | pressure in GPa |
+-----------------+-----------------------------------------------------------+
| `KMSH <#kmsh>`_ | reciprocal spacing for VASP KPOINTS generation |
+-----------------+-----------------------------------------------------------+
| `DENE <#dene>`_ | energy window for selecting distinct structures |
+-----------------+-----------------------------------------------------------+
| `SCUT <#scut>`_ | RDF difference for selecting distinct structures |
+-----------------+-----------------------------------------------------------+
| `SEED <#seed>`_ | random number generator seed (0 for system time) |
+-----------------+-----------------------------------------------------------+
The second group of FLAGs in `Table 2 <#table2>`_ define operations to
generate or evolve structures. Structure type in the table below
defines the unit cell dimensionality, i.e., 3D for crystals, 2D for
films, and 0D for clusters. Zero-parent structures are generated from
scratch. One-parent structures are created by modifying a randomly
picked structure from a previous generation. Two-parent structures are
created by crossover of two randomly picked structures from the
previous generation. For crystals and films, creation of initial unit
cells is controlled only by `TINI <#tini>`_ while creation of offspring
can be done with either `MUTE <#mute>`_ or `MATE <#mate>`_.
The parameters are fractions from 0 to 1 defining what part of the
population will be created with a particular operation. The total must
add up to 1. Let's say the population consists of 20 clusters (`NPOP
<#npop>`_), `TETR <#tetr>`_ =0.1, `PLNT <#plnt>`_ =0.1, `MATE
<#mate>`_ =0.7, and `MUTE <#mute>`_ =0.1. Then the initial population
will have 10 TETRIS-type and 10 seeded structures [20*0.1/(0.1+0.1)
each]. All other populations will have 2 TETRIS-type, 2 seeded, 14
crossed-over, and 2 mutated clusters.
.. _table2:
.. table:: Table 2: FLAGs defining structure generation and evolution.
+-----------------+---------------------------------+---------+----------------+
| FLAG | Operation type | Parent | Structure |
| | | number | type |
+=================+=================================+=========+================+
| `MATE <#mate>`_ | crossover with planar cut | 2 | 0D 2D 3D |
+-----------------+---------------------------------+---------+----------------+
| `MUTE <#mute>`_ | mutation via distortion | 1 | 0D 2D 3D |
+-----------------+---------------------------------+---------+----------------+
| `TETR <#tetr>`_ | generation with TETRIS | 0 | 0D 3D |
+-----------------+---------------------------------+---------+----------------+
| `PLNT <#plnt>`_ | generation with seeds | 0 | 0D |
+-----------------+---------------------------------+---------+----------------+
| `PACK <#pack>`_ | generation of packed shapes | 0 | 0D |
+-----------------+---------------------------------+---------+----------------+
| `RAND <#rand>`_ | generation of random shapes | 0 | 0D 3D |
+-----------------+---------------------------------+---------+----------------+
| `SWAP <#swap>`_ | crossover with sphere cut | 2 | 0D |
+-----------------+---------------------------------+---------+----------------+
| `RUBE <#rube>`_ | Rubik's cube mutation | 1 | 0D |
+-----------------+---------------------------------+---------+----------------+
| `REFL <#refl>`_ | symmetrization via reflection | 1 | 0D |
+-----------------+---------------------------------+---------+----------------+
| `INVS <#invs>`_ | symmetrization via inversion | 1 | 0D |
+-----------------+---------------------------------+---------+----------------+
| `CHOP <#chop>`_ | mutation via facet chop | 1 | 0D |
+-----------------+---------------------------------+---------+----------------+
The remaining FLAGs in `Table 3 <#table3>`_ specify the mutation and crossover operations.
.. _table3:
.. table:: Table 3: FLAGs defining mutation and crossover operations.
+-----------------+-----------------------------------------+----------------+
| FLAG | Short description | Structure |
| | | type |
+=================+=========================================+================+
| `ELPS <#elps>`_ | cluster ellipticity | 0D |
+-----------------+-----------------------------------------+----------------+
| `MCRS <#mcrs>`_ | mutation rate in crossover | 0D 2D 3D |
+-----------------+-----------------------------------------+----------------+
| `SCRS <#scrs>`_ | swapping rate in crossover | 0D 2D 3D |
+-----------------+-----------------------------------------+----------------+
| `LCRS <#lcrs>`_ | lattice vector distortion in crossover | 2D 3D |
+-----------------+-----------------------------------------+----------------+
| `ACRS <#acrs>`_ | atomic position distortion in crossover | 0D 2D 3D |
+-----------------+-----------------------------------------+----------------+
| `SDST <#sdst>`_ | swapping rate in mutation | 0D 2D 3D |
+-----------------+-----------------------------------------+----------------+
| `LDST <#ldst>`_ | lattice vector distortion in mutation | 2D 3D |
+-----------------+-----------------------------------------+----------------+
| `ADST <#adst>`_ | atomic position distortion in mutation | 0D 2D 3D |
+-----------------+-----------------------------------------+----------------+
| `MAGN <#magn>`_ | max number of tries for crossover | 0D 2D 3D |
+-----------------+-----------------------------------------+----------------+
:raw-html-m2r:`` **JOBT** controls the job
type and can be changed during the run to stop the evolutionary search run in the automated mode.
+ **10** The evolutionary search will auto run from iteration `SITR <#sitr>`_ until iteration `NITR <#nitr>`_.
+ **11** The auto run will exit at the end of the current iteration.
+ **12** The auto run will be stopped, submitted jobs cancelled, and the current iteration deleted.
+ **13** `Search analysis`_ will examine all created minima stored in the EVOS directory and will select structures within `DENE <#dene>`_ different by at least `SCUT <#scut>`_.
+ **14** The evolutionary run will run manually one generation at a time.
:raw-html-m2r:`` **NMAX** should be the sum of atoms of all species.
:raw-html-m2r:`` **MMAX** is the maximum number of nearest neighbors within the 6.0 A cutoff.
:raw-html-m2r:`` **NSPC** is the number of species, e.g., 2 for a binary compound.
:raw-html-m2r:`` **TSPC** specifies the atomic number of each species, e.g., '5 26' for B and Fe. In case a neural network model is used, the atomic numbers must be ordered from smallest to largest.
:raw-html-m2r:`` **ASPC** specifies the number of atoms of each species each unit cell in the population will have, e.g., '8 2' for Fe\ :sub:`2`\B\ :sub:`8`\.
:raw-html-m2r:`` **CODE** specifies what external code will be used for performing local optimizations of structures.
+ **1** VASP: calculation at the DFT level
+ **2** MAISE: calculation at the neural network level
:raw-html-m2r:`` **QUET** sets the type of the queueing system
for submission of local optimization jobs with the external code specified by `CODE <#code>`_.
:raw-html-m2r:`` **NDIM** is the dimensionality of
the system. 3D crystals are fully periodic. 2D films are periodic in
(x,y) and constrained to the (x,y) plane, with the c lattice vector
specified by `LBOX <#lbox>`_. 0D clusters are non-periodic, with all 3
lattice vectors set to `LBOX <#lbox>`_.
:raw-html-m2r:`` **LBOX** is the fixed lattice
vector length in A for simulating 2D films or 0D clusters. The a and
b lattice vectors in films can be arbitrary. In DFT calculations, the
**LBOX** value should be just large enough, e.g., 18-20 A for
clusters with 50-100 atoms, to ensure at least 8-10 A between atoms
in different unit cells along non-periodic directions. In NN
calculations, **LBOX** should ensure at least R\ :sub:`c`\ separation
between atoms in different unit cells; it can be arbitrarily large
because, in contrast to the case of DFT, it does not affect the
calculation speed. R\ :sub:`c`\ is the interatomic interaction cut-off
parameter specified for a NN potential at the end of the ``model``
file.
:raw-html-m2r:`` **NPOP** specifies the number of
structure members in the population. It is good practice to set the
value to at least the total number of atoms in the unit cell, e.g.,
16-32 for 16-atom structures. The code will generate **NPOP**
offspring members and submit them to the queue separately in each
generation.
:raw-html-m2r:`` **SITR** specifies the starting
iteration. For a new evolutionary run, set it to 0. For continuing a
finished run, set it to the previous `NITR <#nitr>`_ value; in this
case, MAISE will read in the population from the ``EVOS/GXXX``
directory, where XXX is (NITR-1).
:raw-html-m2r:`` **NITR** is the total number of
generations which can be changed during the evolutionary run. As the
global search convergence is highly dependent on the species types and
the system size, there is no single value that can ensure the location
of the ground state. Searches for 3D crystals with up to 10 atoms
typically converge within 100-500 local optimizations defined as
NPOP × NITR. Larger 3D systems with 16-28 atoms per unit cell
can take 1000-5000 local optimizations.
:raw-html-m2r:`` **TINI** specifies how structures
will be generated in a new search (if `SITR <#sitr>`_ is not 0 the
code will ignore the **TINI** option and simply use the last
generation).
+ **0** Structures will be generated randomly.
+ **1** The code will use ``INI/POSCAR000`` and randomize the atomic positions and lattice vectors. This option dramatically accelerates finding (meta)stable configurations related to the specified structure.
+ **2** The code will use the lattice vectors from ``INI/POSCAR000`` and generate atomic positions randomly. This option is helpful, e.g., when the lattice constants are known from experiment.
+ **3** (Beta version) The code will use the lattice vectors from ``INI/POSCAR000`` and space group from ``INI/SYMINI000`` to generate unit cells with the specified symmetry. The operation will choose random Wyckoff positions and generate random values for non-fixed Wyckoff parameters. The space group must be specified in the following format:
.. literalinclude:: ./file/SYMINI000
:language: none
:raw-html-m2r:`` **TIME** specifies the maximum
time in seconds allowed for a local structure relaxation with an
external code. The time starts after a job starts running. Once the
run time exceeds the specified value, e.g., in case the relaxation is
stuck or the node is down, the code will delete the job. A message of
the failed relaxation will be written to ``log.out``. In case too many
relaxations fail in the zeroth generation, the search will be
terminated. A typical VASP relaxation job in evolutionary runs for
medium-size structures with 8-12 atoms is under 9600 seconds on 16
cores. A typical MAISE job for up to 100-atom structures is under 600
seconds on 16 cores.
:raw-html-m2r:`` **PGPA** sets a target hydrostatic
pressure. The value will be used to update ``INI/INCAR0`` for VASP jobs
and ``INI/NNET/setup`` for MAISE jobs.
:raw-html-m2r:`` **KMSH** defines the reciprocal
spacing in 1/A to generate ``KPOINTS`` for VASP calculations. If the
relaxation involves several cycles with different levels of accuracy
it is better to use a separate script to generate a k-mesh with the
desired cycle-dependent density. A custom Python script is available
upon request.
:raw-html-m2r:`` **DENE** is an enthalpy window in
eV/atom for selecting relevant structures during a `Search analysis`_
job. 3D systems typically have a few different local minima
within 0.010-0.020 eV/atom above the most stable structure.
:raw-html-m2r:`` **SCUT** is the RDF difference for
finding distinct structures during a `Search analysis`_ job. The
selection proceeds from the most stable structure up the
enthalpy-ranked list. If **SCUT** is set, e.g., to 0.95, a structure
that has a scalar product with an already selected structure above
this **SCUT** value will be considered too similar and not included.
:raw-html-m2r:`` **SEED** specifies the starting
seed of the random number generator. It should be set to zero to
generate the seed from the system time and define a unique run.
.. figure:: ./figs/operations.png
:width: 450px
:align: center
Illustration of select generation and evolution operations for clusters.
:raw-html-m2r:`` **MUTE** defines what fraction of
the population that will be generated with a mutation operation. For
arandomly picked parent structure, it will displace the atomic
positions by a distance specified by `ADST <#adst>`_, distort the lattice
constants by a fraction specified by `LDST <#ldst>`_, and perform swaps of
atomic positions defined by `SDST <#sdst>`_.
:raw-html-m2r:`` **MATE** defines what fraction of
the population that will be generated with the crossover operation
using two random parents from a previous generation. Two parent
structures are sliced approximately in half with a planar cut.
:raw-html-m2r:`` **TETR** defines what fraction of
the population of 0D clusters or 3D crystals that will be generated
randomly at the beginning or during the run using the TETRIS operation
introduced in our recent study [4_]. For clusters, it involves
shooting atoms one by one toward the origin from different random
directions and keeping each atomic position closest to the origin.
For crystals, it involves a similar approach but atoms are dropped
down along the c axis.
:raw-html-m2r:`` **PLNT** defines what fraction of
the population of 0D clusters that will be 'planted' at the beginning
of an evolutionary run by randomly picking one of the seed structures
provided by the user as ``INI/POSCARXXX`` where XXX ranges from 0 up
to `NPOP <#npop>`_. As described in [4_], a few atoms on these
clusters' surface will be adjusted to explore close surface
configurations. In case of multitribe co-evolution, the seed clusters
can have different number of atoms, as the code will either remove
atoms randomly from the surface or add atoms randomly to the surface
to achieve the target number. This option currently works only for a
single species.
:raw-html-m2r:`` **PACK** defines what fraction of
the population of 0D clusters that will be generated at the beginning
of an evolutionary run by creating ordered structures with FCC, BCC,
or HCP lattice with random facets. The type of the 3 lattices is
chosen randomly.
:raw-html-m2r:`` **RAND** defines what fraction of
the population of 0D clusters or 3D crystals that will be generated
randomly at the beginning or during the run using the RAND (formerly
BLOB) operation operation [4_]. For clusters, atoms are placed
randomly within a sphere with an estimated cluster radius and then
readjusted with a repulsive potential to ensure physical
distances. The sphere can be made into an ellipsoid with an `ELPS
<#elps>`_ parameter to promote construction of non-spherical shapes.
:raw-html-m2r:`` **SWAP** defines what fraction of
the population of 0D clusters that will be generated with the
crossover operation using two random parents from a previous
generation. Two parent structures are sliced with a spherical cut,
i.e., the offspring inherits the core from one parent and the shell
from the other. The operation was introduced for testing purposes and
turned out to be less efficient than the standard crossover operation
`MATE <#mate>`_ with the planar cut [4_].
:raw-html-m2r:`` **RUBE** defines what fraction of
the population of 0D clusters that will be generated with a Rubik's
cube operation. The transformation involves a rotation of
approximately half of a parent structure along a randomly chosen axis
by a random angle. The operation proved to be comparable in efficiency
to the standard crossover `MATE <#mate>`_ [4_].
:raw-html-m2r:`` **REFL** defines what fraction of
the population of 0D clusters that will be generated with a reflection
operation. A parent structure is sliced with a planar cut
approximately in half and only one half is kept. The missing half is
regenerated by applying mirror symmetry across the plane used for the
cut. Any pairs of atoms of the same species that happen to be too
close to each other are merged into one.
:raw-html-m2r:`` **INVS** defines what fraction of
the population of 0D clusters that will be generated with an inversion
operation with the same idea as the reflection operation `REFL
<#refl>`_.
:raw-html-m2r:`` **CHOP** defines what fraction of
the population of 0D clusters that will be generated with a chop
operation that helps create facets. Up to square root of the total
number of atoms are selected with a single planar cut and relocated to
random positions on the opposite side.
:raw-html-m2r:`` **ELPS** is a dimensionless
parameter defining the ellipticity of the cluster shapes generated
with `TETR <#tetr>`_ and `RAND <#rand>`_ operations. It is introduced
to promote the introduction of non-spherical motifs in the
population. A value of 0.3 will tell the code to pick the ellipticity
parameter randomly between 0.7 and 1.3. The principal axis will be
randomly oriented along x, y, or z.
:raw-html-m2r:`` **MCRS** defines the mutation rate
in crossover operations. Note that this additional mutation is applied
*after* the structure is created with the crossover.
:raw-html-m2r:`` **SCRS** defines the swapping rate
in crossover operations if the structure is selected to have an
additional mutation. It means that for systems with more than one
species type, the code will perform MCRS × NMAX swaps of atomic
positions.
:raw-html-m2r:`` **LCRS** defines the lattice
vector distortions in crossover operations if the structure is
selected to have an additional mutation. A typical 0.1 dimensionless
value means that the lattice vector components will be distributed
primarily between 0.9 and 1.1 of the original values according to the
normal distribution. It must be set to zero for clusters.
:raw-html-m2r:`` **ACRS** defines the atomic
position displacements in crossover operations if the structure is
selected to have an additional mutation. A typical 0.1 A value means
that atoms will be displaced by a random distance primarily
within the 0.1-A sphere from the original position.
:raw-html-m2r:`` **SDST** defines the swapping rate
in mutation operations. It means that for systems with more than one
species type, the code will perfom MCRS × NMAX swaps of atomic
positions.
:raw-html-m2r:`` **LDST** defines the lattice
vector distortions in mutation operations. A typical 0.2 dimensionless
value means that the lattice vector components will be distributed
primarily between 0.8 and 1.2 of the original values according to the
normal distribution. It must be set to zero for clusters.
:raw-html-m2r:`` **ADST** defines the atomic
position displacements in mutation operations. A typical 0.2 A value
means that atoms will be displaced by a random distance primarily
within the 0.2-A sphere from the original position.
:raw-html-m2r:`` **MAGN** is the maximum number of
tries per generation allowed to create the set of new structures in
the crossover operations. For populations with very different motifs,
e.g., with large mismatches in crystal unit cells or cluster shapes,
it may be difficult to find two compatible parent structures that will
produce an offspring with physically meaningful distances. The code
will exit if the number of attempts exceeds the default 1000000
value. Setting **MAGN** to 10000000 is recommended for larger
structures.
External settings
-----------------
Please place the following input and submission files into the ``INI`` directory.
VASP calculations
~~~~~~~~~~~~~~~~~
* ``sub0`` is a submission file that defines the queue type, the number of cores/nodes, the number of relaxation steps, etc.
.. literalinclude:: ./file/vasp-sub0
:language: none
* ``POTCAR`` defines the pseudopotential in VASP calculations. Make sure that the species order is consistent with `TSPC <#tspc>`_ !
* ``INCAR0`` sets up VASP calculations.
* ``KPOINTS`` is optional. There are three ways to specify k-mesh:
+ define ``KPOINTS`` file for each relaxation cycle in ``INI`` and copy it to the work direcory; to be used in searches with fixed unit cells
+ define `KMSH <#kmsh>`_ in ``setup`` that will generate a single ``KPOINTS`` with targeted spacing in the reciprocal space
+ use a custom python script to generate ``KPOINTS`` for each cycle; available upon request
* ``POSCAR000`` is optional for seeding the search, see `TINI <#tini>`_ and `PLNT <#plnt>`_.
It is advisable to run a few cycles of local optimizations and finish the calculation with the most accurate 'static' run. Note that MAISE will only read the final enthalpy from ``OUTCAR.0``.
MAISE calculations
~~~~~~~~~~~~~~~~~~
* ``sub0`` is a submission file that defines the queue type, the number of cores/nodes, the number of relaxation steps, etc.
.. literalinclude:: ./file/maise-sub0
:language: none
* ``NNET/setup`` sets up MAISE local relaxation jobs. Make sure to check
+ `NPAR <#npar>`_ parallelization parameter
+ `MITR <#mitr>`_ iteration number
+ `PGPA <#pgpa>`_ external pressure
* ``NNET/model`` defines the interatomic potential for the MAISE local relaxation job.
* ``NNET/maise-nnet`` is the standard MAISE executable that will perform the local relaxation.
* ``POSCAR000`` is optional for seeding the search, see `TINI <#tini>`_ and `PLNT <#plnt>`_.
Job execution
-------------
An evolutionary search can be run either in automated (`JOBT <#jobt>`_
= 10) or manual (`JOBT <#jobt>`_ = 14) mode as described below.
Search auto run
~~~~~~~~~~~~~~~
The automated evolutionary optimization (`JOBT <#jobt>`_ = 10) is launched by
running MAISE in the background as
.. code-block:: console
$ nohup maise &
The search (re)starts from a given generation and proceeds for a
specified number of iterations (FLAG `NITR <#nitr>`_). In each cycle,
the code generates a new population, submits a job for each structure
to a specified queue, checks if the jobs finished successfully,
processes the results, and outputs enthalpy and volume for each
structure.
During the local optimizations performed externally, the evolutionary
search job uses virtually no CPU resources and only checks the status
of local optimizations every 5 seconds. Since running programs in the
background is discouraged on most supercomputers, an evolutionary
search can be run alternatively in the manual mode.
Search manual run
~~~~~~~~~~~~~~~~~
The manual evolutionary optimization (`JOBT <#jobt>`_ = 14) is done by
running MAISE once per generation (the `SITR <#sitr>`_ and `NITR
<#nitr>`_ FLAGs are ignored in this case):
.. code-block:: console
$ maise
Each execution of the code will analyze the previous generation, write
down the information to ``eXXXX.dat`` files as described in the
following section, generate new structures in the ``EVOS/GXXX/``
directory, and create submission scripts ``gYYY`` in the working
directory for running each structure.
For example, in a search with 10 members per population and two
completed generations ``EVOS/G001/`` and ``EVOS/G001/``, the code will
create 10 subdirectories ``EVOS/G002/M010/`` through ``EVOS/G002/M019/``
with one new offspring structure in each. The corresponding scripts
``g010`` through ``g019`` can be submitted to compute nodes. If the
jobs are run elsewhere, one should replace the ``M010/``-``M019/``
directories in ``EVOS/G002/`` with the completed runs. The subsequent
execution of MAISE will process the results and generate the next set
in ``EVOS/G003/``.
Search check
~~~~~~~~~~~~
The search engine launched in the automated mode can complete the global
optimization without any supervision. However, it is good practice to
monitor the progress by checking the following output files. Note that
MAISE reads the final enthalpy in external VASP or MAISE runs from
``OUTCAR.0`` in each ``EVOS/GXXX/MYYY`` directory.
* ``log.out`` stores all MAISE messages about structure generation, structure selection, etc.
* ``EVOS/GXXX/MYYY`` stores results for YYYth member in the XXXth generation (see note below).
* ``ebest.dat`` stores the enthalpy in eV/atom for the best member in each generation.
* ``erank.dat`` stores the enthalpy in eV/atom for each member in each generation.
* ``eplot.dat`` stores enthalpy vs volume in eV/atom vs :math:`A^{3}`/atom for all minima.
* ``elink.dat`` stores heredity for each offspring.
Note that each ``EVOS/GXXX`` contains double the population size
`NPOP <#npop>`_: directories numbered from `NPOP <#npop>`_ to (2 *
`NPOP <#npop>`_ - 1) have optimization runs with offspring, while
directories numbered from 0 to (`NPOP <#npop>`_ - 1) have the new
population chosen from the pool of old parents and new offspring.
By running the following bash script ``plot`` during or after the evolutionary run, one can visualize the information in these files.
.. code-block:: console
$ plot
.. literalinclude:: ./file/plot
:language: none
The energy profile and structure heredity are shown in ``evolution.png``.
.. figure:: ./figs/evolution.png
:width: 450px
:align: center
The distribution of enthalpy vs volume is shown in ``collection.png``.
.. figure:: ./figs/collection.png
:width: 450px
:align: center
Search analysis
~~~~~~~~~~~~~~~
After a search is completed, one can perform a separate analysis job
to select most relevant distinct local minima. Please set `JOBT
<#jobt>`_ to **13**, adjust `DENE <#dene>`_ and `SCUT <#scut>`_, and
run MAISE:
.. code-block:: console
$ maise
The analysis output with `DENE <#dene>`_ = 0.040 eV/atom and `SCUT
<#scut>`_ = 0.99 for an evolutionary search for Mg\ :sub:`8`\Ca\ :sub:`4`\ modeled with a
neural network potential is shown below.
.. literalinclude:: ./file/evos-ana.dat
:language: none
In this case, MAISE scanned all 6400 structures stored in ``EVOS``,
found 304 of them to be within the specified 40 meV/atom window,
determined that only 3 of them were unique based on the specified 0.99
scalar product cutoff, and found space groups along with Pearson
symbols for the structures in the selected group. The corresponding
original ``POSCAR`` files were placed in the ``POOL`` and
``POOL/SET0`` directories.
Note that at least half of the saved 6400 structures appear twice
because ``EVOS`` keeps both parent and offspring structures in each
generation. In addition, some minima may be found independently
multiple times during the search. For this reason, the 304 found
minima within 40 meV/atom are likely true duplicates rather than
closely related structures. The existence of only 3 unique structures
in such a large enthalpy window is unusual. Typically, one finds
dozens of crystal structures within 10 meV/atom and hundreds of
cluster structures within 5 meV/atom.
Additional analysis can be performed by running several consecutive
`JOBT <#jobt>`_ = 13 runs as described below. It is intended primarily
for checking and comparing the results of NN-based searches with DFT.
The **first pass** will collect all finished runs in ``EVOS``, save
select structures in ``POOL/SET0``, and write the analysis results in
``ana0.dat``. Make sure that the pool size is not too large by
checking ``ana0.dat``, adjusting the `DENE <#dene>`_ and `SCUT
<#scut>`_ selection criteria, and re-running the analysis as
needed. In case the code finds that``POOL/INI0`` directory is present,
it will submit further relaxation and symmetrization jobs for each
structure in ``POOL/SET0` using NN settings in ``POOL/INI0`` and
outputting the results in ``POOL/RUN0``. Make sure all the jobs are
finished before proceeding with the next analysis step.
The **second pass** will automatically detect all finished runs in
``POOL/RUN0``, save select structures in ``POOL/SET1``, and write
analysis results in ``ana1.dat``. Now, if ``POOL/INI1`` is present,
the run will additionally submit relaxation jobs for each structure in
``POOL/SET1` using DFT settings in ``POOL/INI1`` and outputting
the results in ``POOL/RUN1``. Again, it is a good idea to check the
pool size and adjust the `DENE <#dene>`_ and `SCUT <#scut>`_ settings
before placing ``INI1`` into ``POOL``. Make sure all the jobs are
finished before proceeding with the next analysis step.
The **final pass** will automatically detect all finished runs in
``POOL/RUN1``, save select structures in ``POOL/SET2``, and write
analysis results in ``ana2.dat``.
The post-search finer relaxation of a small pool of structures allows
one to use shorter relaxation during the searches. Note that ``EVOS``
is analyzed when neither ``POOL/RUN0`` nor ``POOL/RUN1`` is present,
while ``POOL/RUN0`` is analyzed when ``POOL/RUN1`` is not present.
Search example
--------------
An example available on `Github
`_
sets up an evolutionary search for Mg\ :sub:`8`\Ca\ :sub:`4`\ using
our neural network interatomic potential.