Package: quippy-ase
QUIP - QUantum mechanics and Interatomic PotentialsTheQUIPpackage is a collection of software tools to carry out
molecular dynamics simulations. It implements a variety of interatomic
potentials and tight binding quantum mechanics, and is also able to
call external packages, and serve as plugins to other software such asLAMMPS,CP2Kand also the python frameworkASE.
Various hybrid combinations are also supported in the style of QM/MM,
with a particular focus on materials systems such as metals and
semiconductors.For more details, see theonline documentation. There is separatedocumentation for SOAP and GAP.Long term support of the package is ensured by:Noam Bernstein (@bernstei, Naval Research Laboratory)Gabor Csanyi (@gabor1, University of Cambridge)James Kermode (@jameskermode, University of Warwick)Portions of this code were written by: Albert Bartok-Partay, Livia
Bartok-Partay, Federico Bianchini, Anke Butenuth, Marco Caccin,
Silvia Cereda, Gabor Csanyi, Alessio Comisso, Tom Daff, ST John,
Chiara Gattinoni, Gianpietro Moras, James Kermode, Letif Mones,
Alan Nichol, David Packwood, Lars Pastewka, Giovanni Peralta, Ivan
Solt, Oliver Strickson, Wojciech Szlachta, Csilla Varnai, Steven
Winfield, Tamas K Stenczel, Adam Fekete.Copyright 2006-2021.Most of the publicly available version is released under the GNU
General Public license, version 2, with some portions in the public
domain. The GAP code, included as a submodule, is distributed under
a non-commericalacademic source licenseCiting QUIP, quippy and GAPPlease cite the following publication if you use QUIP:@ARTICLE{Csanyi2007-py,title="Expressive Programming for Computational Physics in Fortran 95+",author="Cs{\'a}nyi, G{\'a}bor and Winfield, Steven and Kermode, J R and DeVita, A and Comisso, Alessio and Bernstein, Noam and Payne,Michael C",journal="IoP Comput. Phys. Newsletter",pages="Spring 2007",year=2007}If you use thequippyPython interface, please cite:@ARTICLE{Kermode2020-wu,title="f90wrap: an automated tool for constructing deep Pythoninterfaces to modern Fortran codes",author="Kermode, James R",journal="J. Phys. Condens. Matter",month=mar,year=2020,keywords="Fortran; Interfacing; Interoperability; Python; Wrapping codes;f2py",language="en",issn="0953-8984, 1361-648X",pmid="32209737",doi="10.1088/1361-648X/ab82d2"}If you use the GAP code please cite@ARTICLE{Bartok2010-pw,title="Gaussian approximation potentials: the accuracy of quantummechanics, without the electrons",author="Bart{\'o}k, Albert P and Payne, Mike C and Kondor, Risi andCs{\'a}nyi, G{\'a}bor",journal="Phys. Rev. Lett.",volume=104,number=13,pages="136403",month=apr,year=2010,issn="0031-9007, 1079-7114",pmid="20481899",doi="10.1103/PhysRevLett.104.136403"}FeaturesThe following interatomic potentials are presently coded or linked in QUIP:BKS (van Beest, Kremer and van Santen) (silica)EAM (fcc metals)Fanourgakis-Xantheas (water)Finnis-Sinclair (bcc metals)Flikkema-BromleyGAP (Gaussian Approximation Potentials) with (growing...)online documentationGuggenheim-McGlashanBrenner (carbon)OpenKIM (general interface)Lennard-JonesMBD (many-body dispersion correction)MorsePartridge-Schwenke (water monomer)Stillinger-Weber (carbon, silicon, germanium)SiMEAM (silicon)Sutton-ChenTangney-Scandolo (silica, titania etc)Tersoff (silicon, carbon)Tkatchenko-Sheffler pairwise dispersion correctionThe following tight-binding functional forms and parametrisations are
implemented:BowlerDFTBGSPNRL-TBThe following external packages can be called:CASTEPVASPCP2KASAPMolproASE (required if usingquippyPython interface; latest version
recommended)Code philosophy and goalsQUIP was born because of the need to efficiently tie together a wide
variety of different models, both empirical and quantum mechanical. It
will not be competitive in terms of performance with codes such as LAMMPS
and Gromacs. The Atomic Simulation Environment also does this, and is
much more widely used, but QUIP has a number of unique features:Access to Fortran types and routines from Python via thequippypackageSupport for Gaussian Approximation Potentials (GAP) -online docsDoes not assume minimum image convention, so interatomic potentials can
have cutoffs that are larger than the periodic unit cell sizeBinary Installation of QUIP and quippyBinary
for QUIP and the associated quippy Python bindings
that provide interopability with the Atomic Simulation Environment (ASE) are
available from thePython package index(PyPI) under the package namequippy-ase.
This means you can install the latest release with:pipinstallquippy-aseInstalling viapipalso makes thequipandgap_fitcommand line
programs available (providing thedirectory that pip installs scripts
tois on yourPATH).Currently, wheels are available forx86_64architectures
with Python 3.6+ on macOS and glibc-based Linux distributions
(e.g. Ubuntu, CentOS) and for macOS arm64. The wheels are updated periodically
using GitHub Actions CI. Please openissueshere if you have problems installing withpip.Precompiled ContainersIf you have access toDockerorSingularity, you can try one of theprecompiled imagesto get up and running quickly.Compilation InstructionsTo compile QUIP the minimum requirements are:A working Fortran compiler. QUIP is tested withgfortran4.4 and
later, andifort11.1.Linear algebra libraries BLAS and LAPACK. QUIP is tested with
reference versionslibblas-devandliblapack-devon Ubuntu
12.04, andmkl11.1 withifort.MPI: To use the MPI parallelisatin ofgap_fit, you need a
ScaLAPACK library, e.g.libscalapack-openmpion Ubuntu, or
as part of the MKL.Clone the QUIP repository from GitHub. The--recursiveoption
brings in submodules automatically (If you don't do this, then
you will need to rungit submodule update --init --recursivefrom the top-level QUIP directory after cloning) ::gitclone--recursivehttps://github.com/libAtoms/QUIP.gitOne submodule is the GAP code, which can be found insrc/GAP.
Note that GAP is distributed under a diferentlicense.GAP is a machine learning method that uses Gaussian process
regression, and needs large data files to run. You can find
potentials that have been published as well as training data in
ourdata repository, see also theonline docs.Decide your architecture by looking in thearch/directory, and
define an environmental variableQUIP_ARCH, e.g.::exportQUIP_ARCH=linux_x86_64_gfortranfor standard gfortran on Linux. Here is where you can adjust which
compiler is being used, if you do not like the defaults. You may need to
create your ownarch/Makefile.${QUIP_ARCH}file based on an existing file for
more exotic systems.MPI: Some arch files already include adjustments for MPI use. Those
usually havempiin their name, e.g.linux_x86_64_gfortran_openmpi+openmp.Customise QUIP, set the maths libraries and provide linking options::makeconfigMakefile.config will create a build directory,build/${QUIP_ARCH},
and all the building happen there. First it will ask you some
questions about where you keep libraries and other stuff, if you
don't use something it is asking for, just leave it blank. The
answers will be stored inMakefile.incin thebuild/${QUIP_ARCH}directory, and you can edit them later (e.g. to change compiler, optimisation
or debug options).If you later make significant changes to the configuration such as
enabling or disabling tight-binding support you should force a
full rebuild by doing amake deepclean; make.MPI: To use the MPI parallelisation ofgap_fit, you have to add
your system library to the linking options, e.g.-lscalapackor-lscalapack-openmpi, enable GAP support, enable QR decomposition,
and enable ScaLAPACK.Compile all programs, modules and libraries::makeFrom the top-levelQUIPdirectory. All programs are built inbuild/${QUIP_ARCH}/. You can also find compiled object files
and libraries (libquip.a) in that directory. Programs can be
called directly from that directory.Other useful make targets include:make install: copies all compiled programs it can find toQUIP_INSTALLDIR, if it's defined and is a directory (full path
required), and copies bundled structures toQUIP_STRUCTS_DIRif it is defined.make libquip:   Compile QUIP as a library and link to it.
This will make all the various libraries and combine them into one:build/${QUIP_ARCH}/libquip.a, which is what you need to link with
(as well as LAPACK).A good starting point is to use thequipprogram, which can
calculate the properties of an atomic configuration using a
variety of models. For example::quipatoms_filename=test.xyzinit_args='IP LJ'\param_filename=share/Parameters/ip.parms.LJ.xmlEassuming that you have a file calledtest.xyzwith the following
data in it representing Cu atoms in a cubic fcc lattice::4
Lattice="3.61 0 0 0 3.61 0 0 0 3.61" Properties=species:S:1:pos:R:3
Cu     0.000 0.000 0.000
Cu     0.000 1.805 1.805
Cu     1.805 0.000 1.805
Cu     1.805 1.805 0.000The Lennard-Jones parameters in the above example are defined in theip.parms.LJ.xmlfile undershare/Parameters(ensure the path
to this file is correct). The format of the atomic configuration is
given inExtended XYZformat, in which the first line is the number of atoms, the second line
is a series of key=value pairs, which must at least contain the Lattice
key giving the periodic bounding box and the Properties key that
describes the remaining lines. The value of Properties is a sequence of
triplets separated by a colon (:), that give the name, type and number
of columns, with the type given by I for integers, R for reals, S for
strings.Most string arguments can be replaced by--helpand QUIP programs
will  then print  a  list  of allowable  keywords  with brief  help
messages as to their usage,  so e.g.init_args=--helpwill give a
list of potential model  types (and some combinations). The parsing
is recursive,  soinit_args="IP --help"will then proceed  to list
the types of interatomic potentials (IP) that are available.To compile the Python wrappers (quippy), the minimum requirements
are as follows.f90wrapwill be installed automatically by the build
process, but you might need to check that the directory wherepipinstalls executuable scripts to is on your path (e.g. by settingPATH=~/.local/bin:$PATH).Python 3NumPy(numpy>=1.5.0)Atomic Simulation Environment(ase>=3.17.0)f90wrap(optional)SciPy(optional)matscipy.Note: If you are using a Python virtual environment (virtualenv) and would like
to installquippyinto it, ensure the environment is activated
(source <env_dir>/bin/activate, where<env_dir>is the root of
your virtual environment)beforebuildingquippy(otherwise library
versions may cause unexpected conflicts).To compile the Python wrappers (quippy), run::makequippyQuippy can be used by adding thelibdirectory inquippy/build/${QUIP_ARCH}to your$PYTHONPATH, however it can be
more convenient to install into a specific Python distribution::makeinstall-quippywill either install into the current virtualenv or attempt to install
systemwide (usually fails withoutsudo). To install only for the
current user (into~/.local), execute the commandQUIPPY_INSTALL_OPTS=--user make install-quippy,
or useQUIPPY_INSTALL_OPTS=--prefix=<directory>to install into a
specific directory.QUIPPY_INSTALL_OPTScan also be set in the filebuild/${QUIP_ARCH}/Makefile.inc.More details on the quippy installation process and troubleshooting for
common build problems are available in theonline documentation.To run the unit and regression tests, which depend onquippy::bash     make testTo get back to a state near to a fresh clone, usebash     make distcleanSome functionality is only available if you check out other
modules within theQUIP/src/directories, e.g. theThirdParty(DFTB parameters, TTM3f water model).In order to run QUIP potentials via LAMMPS,make libquipto get QUIP
into library form, and then follow the instructions in theLAMMPS documentation. You need at least 11 Aug 2017 version or later.Developer notes:Fixing/updating the version of GAP:cdsrc/GAPgitcheckout<commit>ORgitcheckoutmainUpdating the version in theQUIPrepository:cd ../..
git add src/GAP
git commit -m "updating the version of GAP"Mac OSWe do not recommend Apple-shipped compilers and python, and we do not test
compatibility with them. Either use MacPorts or Homebrew to obtain GNU compilers,
and also use the python from there or Anaconda. As of this edit, gcc-8.1 produces as
internal compiler error, but gcc-4.6 through to gcc-7 is fine.Triggering the wheel buildWheels are built on push and pull requests topublicusingcibuildwheelwiththis workflow.To make a release candidate create a tag with a suffix such as-rc1for the first attempt,
push to trigger the build:gitcommit-m'release v0.x.z-rc1'gittagv0.x.y-rc1
gitpush--tagsIf all goes well, the.whlfiles will show up as assets within a new GitHub
release. The installation process can now be tested locally.Release wheels to PyPIOnce everything works correctly, make a full release (i.e. create a tag named
justv0.x.ywithout the-rc1suffix). This will trigger the upload of wheels
and source distribution to PyPI.