diff --git a/docs/figures/ipi-structure-v3.pdf b/docs/figures/ipi-structure-v3.pdf new file mode 100644 index 000000000..ea88801f4 Binary files /dev/null and b/docs/figures/ipi-structure-v3.pdf differ diff --git a/docs/figures/ipi-structure-v3.svg b/docs/figures/ipi-structure-v3.svg new file mode 100644 index 000000000..61fee701b --- /dev/null +++ b/docs/figures/ipi-structure-v3.svg @@ -0,0 +1,4415 @@ + + + + + + image/svg+xmlclient11systemforcesinitializeCleientsserver: i-PIq1 h1u1 f1 x1 U, F, XT, P, ... Sockets (unix/inet)systemmotionoutputforcefield (1)server: i-PI + + + + + + + + +q2 h2q,hu2 f2 x2 Compute U, f, X +q3 h3u3 f3 x3 client 1forcefield (2)client 2forcefield (3)client 3motionensemblesFORCEFIELDSserver: i-PISYSTEMINITIALIZEFORCESENSEMBLEMOTIONSMOTIONOUTPUTSSYSTEMINITIALIZEFORCESMOTIONENSEMBLEFORCEFIELD1 SMOTIONBEADS,CELLOUTPUTSFORCEFIELD2 FORCEFIELD3 main loop: for each system: system.motion.step() smotion.step() for each output: output.write()client1nclient2client3... n replicasV,f,Xq,hV,f,XV,f,Xq,hq,hq,hV,f,X diff --git a/docs/src/getting-started.rst b/docs/src/getting-started.rst index 113c7516a..335cfc36b 100644 --- a/docs/src/getting-started.rst +++ b/docs/src/getting-started.rst @@ -27,10 +27,11 @@ required for the sockets.c wrapper to the sockets standard library. Most electronic structure codes will also need to be linked with some mathematical libraries, such as BLAS, FFTW and LAPACK. Installation instructions for these codes should be provided as part of the code -distribution and on the appropriate website, as given in -:ref:`librarywebsites`. Patching for use with i-PI should not +distribution and on the appropriate website. +Patching for use with i-PI should not introduce further dependencies. + Using the setup.py module ^^^^^^^^^^^^^^^^^^^^^^^^^ @@ -46,7 +47,7 @@ The first step is to build the distribution using: .. code-block:: - > python setup.py build + > python setup.py build Note that this requires the distutils package that comes with the python-dev package. @@ -72,28 +73,28 @@ into, using: .. code-block:: - > mkdir ~/bin - > mkdir ~/lib/py_vers - > mkdir ~/lib/py_vers/site-packages + > mkdir ~/bin + > mkdir ~/lib/py_vers + > mkdir ~/lib/py_vers/site-packages Next, you must tell Python where to find this library, by appending to the Linux environment variable PYTHONPATH, using: .. code-block:: - export PYTHONPATH=$PYTHONPATH:~/lib/py_vers/site-packages/ + export PYTHONPATH=$PYTHONPATH:~/lib/py_vers/site-packages/ Finally, the code can be installed using: .. code-block:: - > python setup.py install –prefix=  + > python setup.py install –prefix=  Either way, it will now be possible to run the code automatically, using .. code-block:: - > i-pi input-file.xml + > i-pi input-file.xml i-PI download @@ -107,102 +108,6 @@ without needing to be installed or compiled, but we include a setup.py module in the main directory so it can be installed to the Python tree if so desired. -Installing NumPy -~~~~~~~~~~~~~~~~ - -NumPy is the standard Python mathematics library, and is used for most -of the array manipulation and linear algebra in i-PI. It should be -installed alongside most standard Python environments on HPC facilities. -Otherwise, it is generally relatively straightforward to install it. - -In any case you must first obtain the NumPy code, which can be -downloaded as a tar file from http://www.numpy.org. If the version of -NumPy being installed is given by “np_vers”, this can be extracted -using: - -Before installing this code it first needs to be configured correctly. -Note that this requires the distutils package that comes with the -python-dev package. Assuming that the required software is installed, -the NumPy package is built using: - -.. code-block:: - - > python setup.py build - -The next step is to install NumPy. By default the download is to the -directory /usr/local. If you have root access, and so can write to /usr, -then all that needs to be done to finish the install is: - -.. code-block:: - - > python setup.py install - -If you do not have root access, then the next step depends on which -version of Python is beind used. With versions 2.6 or later there is a -simple command to automatically download into the directory $HOME/local: - -.. code-block:: - - > python setup.py install –user - -With Python 2.4/2.5 the process is a little more involved. First you -must explicitly install the package in the directory of choice, “np_dir” -say, with the following command: - -.. code-block:: - - > python setup.py install --prefix=np_dir - -Next, you must tell Python where to find this library, by appending to -the Linux environment variable PYTHONPATH. If you are using Python -version “py_vers”, then the NumPy libraries will have been installed in -the directory “np_dir/lib/py_vers/site-packages”, or a close analogue of -this. In the above case the following command will allow the Python -interpreter to find the NumPy libraries: - -.. code-block:: - - > export PYTHONPATH=$PYTHONPATH:np_dir/lib/py_vers/site-packages - -Now Python scripts can import the NumPy libraries using: - -.. code-block:: - - import numpy - -PyFFTW -~~~~~~ - -Some of the steps in the dynamics algorithm involve a change of -variables from the bead coordinates to the normal modes of the ring -polymers. Currently, this transformation is, at least by default, -computed using a fast-Fourier transform (FFT) library within the NumPy -distribution. This however is not the only distribution that could be -used, and indeed faster stand-alone versions exist. The gold-standard -FFT library is the FFTW library, which is a set of C libraries that have -been heavily optimized for a wide range of applications. There have been -a number of Python wrappers built around the FFTW library, one of which -is currently interfaced with i-PI. This code can be found at -https://github.com/hgomersall/pyFFTW, and has documentation at -http://hgomersall.github.io/pyFFTW/. - -This code has the following dependencies: - -- Python version 2.7 or greater - -- Numpy version 1.6 or greater - -- FFTW version 3.2 or greater - -This can be installed in the same way as NumPy, except using the code -distribution above, or using various installation packages as per the -instructions on the above documentation. Note that no other options need -to be specified in the input file; i-PI will check to see if this -library is available, and if it is it will be used by default. Otherwise -the slower NumPy version will be used. - -.. _clientinstall: - Installing clients ------------------ @@ -236,9 +141,7 @@ i-PI functions based on a client-server protocol, where the evolution of the nuclear dynamics is performed by the i-PI server, whereas the energy and forces evaluation is delegated to one or more instances of an external program, that acts as a client. This design principle has -several advantages, in particular the possibility of performing PIMD -based on the forces produced by one’s favourite electronic -structure/empirical force field code. However, it also makes running a +several advantages, but it also makes running a simulation slightly more complicated, since the two components must be set up and started independently. @@ -246,7 +149,7 @@ Running the i-PI server ~~~~~~~~~~~~~~~~~~~~~~~ i-PI simulations are run using the i-pi Python script found in the -“i-pi” directory. This script takes an xml-formatted file as input, and +“bin” directory. This script takes an xml-formatted file as input, and automatically starts a simulation as specified by the data held in it. If the input file is called “input_file.xml”, then i-PI is run using: @@ -272,29 +175,31 @@ their own documentation. .. _driver.x: -Built-in, example client +Built-in, fortran client ^^^^^^^^^^^^^^^^^^^^^^^^ -While i-PI is designed with *ab initio* electronic structure -calculations in mind, it also includes a Fortran empirical potential +i-PI includes a Fortran empirical potential client code to do simple calculations and to run the examples. -The source code for this is included in the directory “drivers”, and can +The source code for this is included in the directory “drivers/f90”, and can be compiled into an executable “i-pi-driver” using the UNIX utility make. -This code currently has four empirical potentials hardcoded into it, a -Lennard-Jones potential, the Silvera-Goldman potential -:cite:`silv-gold78jcp`, a 1D harmonic oscillator potential, -and the ideal gas (i.e. no potential interaction). +This code currently has several empirical potentials hardcoded into it, including +a Lennard-Jones potential, the Silvera-Goldman potential +:cite:`silv-gold78jcp`, +a primitive implementation of the qtip4pf potentail for water , +:cite:`habe+09jcp`, +several toy model potentials, +the ideal gas (i.e. no potential interaction), and several more. How the code is run is based on what command line arguments are passed to it. The command line syntax is: .. code-block:: - > i-pi-driver [-u] -h hostname -p port -m [gas|lj|sg|harm] -o - parameters [-v] + > i-pi-driver [-u] -a address [-p port] -m [model-name] -o [parameters] [-S sockets_prefix] [-v] + The flags do the following: @@ -302,8 +207,8 @@ The flags do the following: Optional parameter. If specified, the client will connect to a unix domain socket. If not, it will connect to an internet socket. --h: - Is followed in the command line argument list by the hostname of the +-a: + Is followed in the command line argument list by the hostname (address) of the server. -p: @@ -329,6 +234,10 @@ The flags do the following: Optional parameter. If given, the client will print out more information each time step. +-S: + Optional parameter. If given, overwrite the default socket prefix used in the creation of files for the socket communication. + (default "/tmp/ipi_") + This code should be fairly simple to extend to other pair-wise interaction potentials, and examples of its use can be seen in the “examples” directory, as explained in :ref:`tests`. @@ -539,7 +448,7 @@ approaches to run i-PI on a HPC system: Testing the install ------------------- -test the installation with ‘nose‘ +test the installation with ‘pytest‘ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ There are several test cases included, that can be run automatically @@ -549,6 +458,10 @@ with ‘i-pi-tests‘ from the root directory. > i-pi-tests +Note 1: pytest and pytest-mock python packages are required to run these tests, but they are required to run i-PI. +Note 2: please compile the fortran driver, as explained in :ref:`driver.x`. +Note 3: use the '-h' flag to see all the available tests + test cases and examples ~~~~~~~~~~~~~~~~~~~~~~~ @@ -556,5 +469,26 @@ The `examples/` folder contain a multitude of examples for i-PI, covering most of the existing functionalities, and including also simple tests that can be run with different client codes. -All the input files are contained in the directory “examples”, which is -subdivided into subfolder that cover different classes of simulations, and/or different client codes. + +The example folders is structured such that each sub-folder is focused on a different aspect of using i-PI: + +- **clients**: + Contains examples that are code-specific, highlighting how the driver code should be set up + (client-specific syntax and tags) to run it properly with i-PI + +- **features** : + Examples of different functionalities implemented in i-PI. + All examples can be run locally with the drivers provided with the code. + +- **hpc_scripts** : + Examples of submission scripts on HPC platforms + +- **temp** : + Temporary folder with historic examples that have not yet been adapted + to the current folder structure + +- **init_files**: + repository of input files shared by many examples + +We keep this folder updated as much as we can, and try to run automated tests on these inputs, but in some cases, e.g. when using external clients, we cannot run tests. +Please report a bug if you find something that is not working. diff --git a/docs/src/index.rst b/docs/src/index.rst index e2b6180ee..524b25e6a 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -1,33 +1,24 @@ Welcome to i-PI's documentation! ================================ -i-PI is a interface for advanced molecular simulations written in -Python, designed to be used together with an *ab initio* evaluation of -the interactions between the atoms. The main goal is to decouple the -problem of evolving the ionic positions to sample the appropriate -thermodynamic ensemble and the problem of computing the inter-atomic -forces. i-PI was initially developed for Path Integral Molecular -Dynamics (PIMD) simulations, and contains probably the most -comprehensive array of PIMD techniques. Since v2.0, however, it also -contains several general-purpose methods for molecular simulations, -ranging from phonon calculators to replica exchange molecular dynamics. - -.. figure:: ../figures/ipi-scheme.* - :width: 90.0% - - Schematic representation of the functioning of i-PI. - +i-PI is a force-engine written in Python 3 with the goal of performing standard and advanced molecular simulations. The implementation is based on a client-server paradigm, where i-PI acts as the server and deals with the propagation of the nuclear dynamics, whereas the calculation of the potential energy, forces and the potential energy part of the pressure virial is delegated to one or more -instances of an external code, acting as clients. Since the main focus -is on performing *ab initio* PIMD – where the cost of the force -evaluation is overwhelming relative to the ionic dynamics – clarity has -been privileged over speed. Still, the implementation of i-PI is -efficient enough that, by tuning the socket parameters and avoiding -excessive I/O it can be used to run empirical forcefields with -tens of thousands of atoms with only a small overhead. +instances of an external code, acting as clients. +Thus, i-PI effectively decouples the problem of evolving the +ionic positions and the problem of computing the system-specific properties + +i-PI was initially developed for Path Integral Molecular +Dynamics (PIMD) simulations, and contains probably the most +comprehensive array of PIMD techniques. However, it has evolved over time to become +a general-purpose code with methods ranging from phonon calculators to replica exchange molecular dynamics. + + +The implementation of i-PI is efficient enough that, by tuning the socket parameters and avoiding +excessive I/O, it can be used to run simulations using empirical forcefields or machine learning +interatomic potentials with tens of thousands of atoms with only a small overhead. This documentation is structured as follows: @@ -35,6 +26,7 @@ This documentation is structured as follows: :maxdepth: 2 introduction + onlinereso features getting-started units diff --git a/docs/src/introduction.rst b/docs/src/introduction.rst index 2848b4d9c..a793fa84b 100644 --- a/docs/src/introduction.rst +++ b/docs/src/introduction.rst @@ -1,65 +1,140 @@ -Introduction -============ - -Path Integral Molecular Dynamics --------------------------------- - -Molecular dynamics (MD) is a technique used to study the properties of a -system of interacting particles by applying Newton’s equations of motion -to produce trajectories which can be used to efficiently explore the -phase space. This can be used to calculate many equilibrium and -dynamical properties and to study systems from isolated gas molecules to -condensed phase bulk materials. - -However, while this technique has been very successful, in most MD -implementations the assumption is made that the nuclei behave as -classical particles, which for light nuclei such as hydrogen is often a -very poor approximation as the effect of zero-point energy (ZPE) and -quantum tunnelling can be large. For example, even at room temperature -the vibrational frequency of an OH stretch in water is over 15 times -larger than the available thermal energy, and so this motion will be -highly quantized. The current state-of-the-art method to include nuclear -quantum effects (NQE) in the calculation of static properties of -condensed phase systems is path integral molecular dynamics (PIMD). - -PIMD generates the quantum-mechanical ensemble of a system of -interacting particles by using MD in an extended phase space. This is -derived from the path integral formalism -:cite:`feyn-hibb65book`, which relates the statistics of a -collection of quantum particles to those of a set of classical ring -polymers, a ring polymer being a number of replicas of a particle -coupled by harmonic springs. This so-called classical isomorphism is -exact in the limit as the number of replicas goes to infinity, but in -practice is converged numerically with only a finite number. - -This then allows quantum phase space averages to be calculated from -classical trajectories, with only about an order of magnitude more -computing time than would be required for standard MD. Also, since PIMD -is simply classical MD in an extended phase space, many of the -techniques developed to improve the scope and efficiency of MD -simulations can be applied straightforwardly to the equivalent PIMD -calculations :cite:`ceri+10jcp,mart+99jcp`. Finally, several -techniques designed specifically for PIMD simulations are now available -to increase the rate of convergence with respect to the number of -replicas used -:cite:`mark-mano08jcp,ceri+11jcp,suzu95pla,chin97pla,ceri+12prsa,pere-tuck11jcp`, -further reducing the computational overhead of the method. All of these -facts mean that it is now feasible to do PIMD simulations with thousands -of molecules, or even to use *ab initio* electronic structure -calculations to propagate the dynamics for small systems. - -Furthermore, the framework used to run PIMD simulations can be adapted -to generate approximate quantum dynamical information -:cite:`cao-voth93jcp,cao-voth94jcp,crai-mano04jcp,braa-mano06jcp`, -and so can also be used to calculate correlation functions. While -real-time quantum coherences cannot be captured, the inclusion of -quantum statistical information and the rapid decoherence observed in -condensed phase systems mean that in many cases very accurate results -can be obtained from such approximate treatments of quantum dynamics -:cite:`habe+13arpc`. - -Implementation --------------- +Program Overview +================ + +i-PI is a force engine that operates with a client-server +paradigm. i-PI acts as a server in command of the evolution of the nuclear positions, while one or more instances +of the client code handle the evaluation of system-specific properties. Designed to be universal, i-PI’s architecture +is agnostic to the indentity of the force providers, with a general and flexible backend that accommodates to a wide range of client codes. + +The code is written in Python 3, a high-level, general-purpose interpreted programming language known for +its emphasis on code readability. This choice facilitates rapid prototyping of new ideas and relatively easy code +maintenance when compared to compiled languages traditionally used in scientific computing. + +i-PI is structured in a modular way that represents the underlying physics of the target simulation as faithfully +as possible. To achieve this, the code is organized around the System class which encodes all the information related +to the physical system, such as the number and identity of atoms, the ensemble to be sampled, the number +of replicas in path integral simulations, the initialization procedure, and the algorithm for evolving the +nuclear positions. Forces are managed through the Forces class, which integrates the individual force components, +each of which is computed following the strategy specified in a Forcefield class. This two-layer approach is particu- +larly advantageous for algorithms where the total forces and energies are obtained by a combination of these +quantities computed at different accuracy levels, or among different system portions. +Simulation techniques that require the evolution of many systems simultaneously make use of the SMotion (Systems Motion) +class. This class enables the definition of evolution steps that combine the (possibly many) different systems, facil- +itating, for example, exchanges between system replicas as done in replica exchange simulations. Finally, +estimators can be defined within the code or computed by the provided post-processing tools or user-generated scripts. + +A schematic representation of the code structure and the server-client communication is presented in Fig. 1. + +.. figure:: ../figures/ipi-structure-v3.* + :width: 90.0% + + Figure 1. Schematic representation of the i-PI code structure and the server-client communication. + + +In Figure 1, the physical system is defined by one or more replicas (beads), and the sampling conditions (e.g. temperature and pressure) by an Ensemble class. The forces acting on the atoms are constructed based on a combination of energy contributions evaluated by one or more instances of the +Forcefield class (three in this example). Each Forcefield instance communicates with a different client sending positions (*q*) and +lattice vectors (*h*), and receiving energy (*V*), forces (*f*), stresses and possible extra properties (X) as a JSON formatted string. +In simulations with multiple replicas, each Forcefield instance can accept connections from several clients, to achieve parallel +evaluation. The Motion class determines the evolution of the atoms (e.g. time integration, or geometry optimization), while +“system motion” classes (SMotion) can act on multiple systems, e.g. to carry out replica exchange simulations. The output +class handles writing the output and restart files + + + +Communication protocol +~~~~~~~~~~~~~~~~~~~~~~ + +Since i-PI is designed to be used with a wide range of codes and +platforms, it has to rely on a simple and robust method for +communicating between the server and client. Even though other choices +are possible, and it should be relatively simple to implement other +means of communication, the preferred approach relies on sockets as the +underlying infrastructure. Both Internet and Unix domain sockets can be +used: the latter allow for fast communication on a single node, whereas +the former make it possible to realise a distributed computing paradigm, +with clients running on different nodes or even on different HPC +facilities. In order to facilitate implementation of the socket +communication in client codes, a simple set of C wrappers to the +standard libraries socket implementation is provided as part of the i-PI +distribution, that can be used in any programming language that can be +linked with C code. + +As far as the communication protocol is concerned, the guiding principle +has been keeping it to the lowest common denominator, and avoiding any +feature that may be code-specific. Only a minimal amount of information +is transferred between the client and the server; the position of the +atoms and cell parameters in one direction, and the forces, virial and +potential in the other. + +For more details about sockets and communication, see +:ref:`distrib`. + + +Force evaluation +~~~~~~~~~~~~~~~~ + +Within i-PI, the evaluation of the forces plays a crucial role, as it is +the step requiring communication with the client code. In order to have +a flexible infrastructure that makes it possible to perform simulations +with advanced techniques, the force evaluation +machinery in i-PI might appear complicated at first, and deserves a +brief discussion. + +.. figure:: ../figures/ipi-forces.* + :width: 90.0% + + Schematic representation of the different objects that + are involved in the evaluation of the forces. The multiple layers and + complex structure are necessary to give the possibility of + decomposing the evaluation of the forces between multiple different + clients and using different imaginary time partitioning (e.g. one can + compute the bonded interactions using one client, and use a different + client to compute the long-range electrostatic interactions, + contracted on a single bead :cite:`mark-mano08jcp`). + + +This figure provides an overall scheme of the objects involved in the calculation +of the forces. The infrastracture comprises +a force provider class that deals with the actual subdivision of work +among the clients, and a sequence of objects that translate the request +of the overall force of the system into atomic evaluations of one +component of the force +When running path integral simulations, the later refers to the component of an individual bead: +i-PI is built to hide the path integral infrastructure from the client, and so beads must be +transferred individually. + +Let us discuss for clarity a practical example: a calculation of an +empirical water model where the bonded interactions are computed on 32 +beads by the program A, and the non-bonded interactions are computed by +client B, ring-polymer contracted on 8 beads. Each client “type” is +associated with a :ref:`forcefield` object in the input. In the case of a +:ref:`ffsocket` interface, the +forcefield object specifies the address to which a client should +connect, and so multiple clients of type A or B can connect to i-PI at +the same time. Each forcefield object deals with queueing force +evaluation requests and computing them in a first-in-first-out fashion, +possibly executing multiple requests in parallel. + +On the force evaluation side, the task of splitting the request of a +force evaluation into individual components and individual beads is +accomplished by a chain of three objects, Forces, ForceComponent and +ForceBead. is the main force Forces evaluator, that is built from the +prototypes listed within the :ref:`forces` field of the :ref:`system`. +Each `forcecomponent` item within the :ref:`forces` tag +describe one component of the force – in our example one ForceComponent +bound to a forcefield of type A, evaluated on 32 beads, and one +ForceComponent bound to type B, evaluated on 8 beads. Forces contains +the machinery that automatically contracts the actual ring polymer to +the number of beads required by each component, and combines the various +components with the given weights to provide the overall force, energy +and virial where required. Note that in order to support ring polymer +contraction (RPC), the RPC procedure is executed even if no contraction +was required (i.e. even if all clients contain the full amount of +beads). ForceComponent is a very simple helper class that associates +with each bead a ForceBead object, that is the entity in charge of +filing force requests to the appropriate ForceField object and waiting +for completion of the evaluation. + Automated evaluation (depend objects) ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -170,160 +245,25 @@ at runtime, to the value of the other object. A typical usage pattern is myoth.vec[3] = 0 # depend_arrays can be accessed as normal np.ndarray print(myoth.scaled) # prints [0,8,16,0] -Force evaluation -~~~~~~~~~~~~~~~~ - -Within i-PI, the evaluation of the forces plays a crucial role, as it is -the step requiring communication with the client code. In order to have -a flexible infrastructure that makes it possible to perform simulations -with advanced techniques such as ring-polymer -contraction :cite:`mark-mano08jcp`, the force evaluation -machinery in i-PI might appear complicated at first, and deserves a -brief discussion. - -.. figure:: ../figures/ipi-forces.* - :width: 90.0% - - Schematic representation of the different objects that - are involved in the evaluation of the forces. The multiple layers and - complex structure are necessary to give the possibility of - decomposing the evaluation of the forces between multiple different - clients and using different imaginary time partitioning (e.g. one can - compute the bonded interactions using one client, and use a different - client to compute the long-range electrostatic interactions, - contracted on a single bead :cite:`mark-mano08jcp`). - - -This figure provides an overall scheme of the objects involved in the calculation -of the forces. The infrastracture comprises -a force provider class that deals with the actual subdivision of work -among the clients, and a sequence of objects that translate the request -of the overall force of the system into atomic evaluations of one -component of the force for an individual bead: i-PI is built to hide the -path integral infrastructure from the client, and so beads must be -transferred individually. - -Let us discuss for clarity a practical example: a calculation of an -empirical water model where the bonded interactions are computed on 32 -beads by the program A, and the non-bonded interactions are computed by -client B, ring-polymer contracted on 8 beads. Each client “type” is -associated with a :ref:`forcefield` object in the input. In the case of a -:ref:`ffsocket` interface, the -forcefield object specifies the address to which a client should -connect, and so multiple clients of type A or B can connect to i-PI at -the same time. Each forcefield object deals with queueing force -evaluation requests and computing them in a first-in-first-out fashion, -possibly executing multiple requests in parallel. - -On the force evaluation side, the task of splitting the request of a -force evaluation into individual components and individual beads is -accomplished by a chain of three objects, Forces, ForceComponent and -ForceBead. is the main force Forces evaluator, that is built from the -prototypes listed within the :ref:`forces` field of the :ref:`system`. -Each :ref:`forcecomponent` item within the :ref:`forces` tag -describe one component of the force – in our example one ForceComponent -bound to a forcefield of type A, evaluated on 32 beads, and one -ForceComponent bound to type B, evaluated on 8 beads. Forces contains -the machinery that automatically contracts the actual ring polymer to -the number of beads required by each component, and combines the various -components with the given weights to provide the overall force, energy -and virial where required. Note that in order to support ring polymer -contraction (RPC), the RPC procedure is executed even if no contraction -was required (i.e. even if all clients contain the full amount of -beads). ForceComponent is a very simple helper class that associates -with each bead a ForceBead object, that is the entity in charge of -filing force requests to the appropriate ForceField object and waiting -for completion of the evaluation. - -Communication protocol -~~~~~~~~~~~~~~~~~~~~~~ - -Since i-PI is designed to be used with a wide range of codes and -platforms, it has to rely on a simple and robust method for -communicating between the server and client. Even though other choices -are possible, and it should be relatively simple to implement other -means of communication, the preferred approach relies on sockets as the -underlying infrastructure. Both Internet and Unix domain sockets can be -used: the latter allow for fast communication on a single node, whereas -the former make it possible to realise a distributed computing paradigm, -with clients running on different nodes or even on different HPC -facilities. In order to facilitate implementation of the socket -communication in client codes, a simple set of C wrappers to the -standard libraries socket implementation is provided as part of the i-PI -distribution, that can be used in any programming language that can be -linked with C code. - -As far as the communication protocol is concerned, the guiding principle -has been keeping it to the lowest common denominator, and avoiding any -feature that may be code-specific. Only a minimal amount of information -is transferred between the client and the server; the position of the -atoms and cell parameters in one direction, and the forces, virial and -potential in the other. - -For more details about sockets and communication, see -:ref:`distrib`. Licence and credits ------------------- -Most of this code is distributed under the GPL licence. For more details -see `www.gnu.org/licences/gpl.html `__. -So that they can easily be incorporated in other codes, the files in the -directory “drivers” are all held under the MIT licence. For more details -see https://fedoraproject.org/wiki/Licensing:MIT. +The code is distributed under the dual GPL and MIT licence. For more details +see `www.gnu.org/licences/gpl.html `__ and +https://fedoraproject.org/wiki/Licensing:MIT. If you use this code in any future publications, please cite this using -:cite:`ceri+14cpc` for v1 and +:cite:`ceri+14cpc` for v1, :cite:`Kapil:2019ju` for v2. +:cite:`litman2024ipi` for v3. Contributors ~~~~~~~~~~~~ i-PI was originally written by M. Ceriotti and J. More at Oxford -University, together with D. Manolopoulos. Several people contributed to -its further development. Developers who implemented a specific feature -are acknowledged above. - -On-line resources ------------------ - -Python resources -~~~~~~~~~~~~~~~~ - -For help with Python programming, see -`www.python.org `__. For information about the NumPy -mathematical library, see `www.numpy.org `__, and for -worked examples of its capabilities see -`www.scipy.org/Tentative_NumPy_Tutorial `__. -Finally, see http://hgomersall.github.io/pyFFTW/ for documentation on -the Python FFTW library that is currently implemented with i-PI. - -.. _librarywebsites: - -Client code resources -~~~~~~~~~~~~~~~~~~~~~ - -Several codes provide out-of-the-box an i-PI interface, including CP2K, -DFTB+, Lammps, Quantum ESPRESSO, Siesta, FHI-aims, Yaff, deMonNano, TBE. -If you are interested in interfacing your code to i-PI please get in -touch, we are always glad to help! - -There are several Fortran and C libraries that most client codes will -probably need to run, such as FFTW, BLAS and LAPACK. These can be found -at `www.fftw.org `__, -`www.netlib.org/blas `__ and -`www.netlib.org/lapack `__ respectively. - -These codes do not come as part of the i-PI package, and must be -downloaded separately. See chapter :ref:`clientinstall` for more -details of how to do this. - -i-PI resources -~~~~~~~~~~~~~~ +University, together with D. Manolopoulos. The updated list of developers and +contributors can be found +`here `__ -For more information about i-PI and to download the source code go to -http://ipi-code.org/. -In http://gle4md.org/ one can also obtain colored-noise parameters to -run Path Integral with Generalized Langevin Equation thermostat -(PI+GLE/PIGLET) calculations. diff --git a/docs/src/onlinereso.rst b/docs/src/onlinereso.rst new file mode 100644 index 000000000..dbd622d7d --- /dev/null +++ b/docs/src/onlinereso.rst @@ -0,0 +1,56 @@ +.. _librarywebsites: +On-line resources +================= + +i-PI resources +~~~~~~~~~~~~~~ + +For more information about i-PI and to download the source code go to +http://ipi-code.org/. + +In http://gle4md.org/ one can also obtain colored-noise parameters to +run Path Integral with Generalized Langevin Equation thermostat +(PI+GLE/PIGLET) calculations. + +Python resources +~~~~~~~~~~~~~~~~ + +For help with Python programming, see +`www.python.org `__. For information about the NumPy +mathematical library, see `www.numpy.org `__, and for +worked examples of its capabilities see +`www.scipy.org/Tentative_NumPy_Tutorial `__. +Finally, see http://hgomersall.github.io/pyFFTW/ for documentation on +the Python FFTW library that is currently implemented with i-PI. + + +Client code resources +~~~~~~~~~~~~~~~~~~~~~ + +Several codes provide out-of-the-box an i-PI interface, including +ASE, +CASTEP, +CP2K, +DFTB+, +elphmod, +ffsGDML, +FHI-aims, +LAMMPS, +librascal, +Quantum ESPRESSO, +Siesta, +Yaff. + +If you are interested in interfacing your code to i-PI please get in +touch, we are always glad to help! + +There are several Fortran and C libraries that most client codes will +probably need to run, such as FFTW, BLAS and LAPACK. These can be found +at `www.fftw.org `__, +`www.netlib.org/blas `__ and +`www.netlib.org/lapack `__ respectively. + +These codes do not come as part of the i-PI package, and must be +downloaded separately. See chapter :ref:`clientinstall` for more +details of how to do this. + diff --git a/docs/src/references.bib b/docs/src/references.bib index 50157fa62..3dce45b11 100644 --- a/docs/src/references.bib +++ b/docs/src/references.bib @@ -1,3 +1,11 @@ +@misc{litman2024ipi, + title={i-PI 3.0: a flexible, efficient framework for advanced atomistic simulations}, + author={Yair Litman and Venkat Kapil and Yotam M. Y. Feldman and Davide Tisi and Tomislav Begušić and Karen Fidanyan and Guillaume Fraux and Jacob Higer and Matthias Kellner and Tao E. Li and Eszter S. Pós and Elia Stocco and George Trenins and Barak Hirshberg and Mariana Rossi and Michele Ceriotti}, + year={2024}, + eprint={2405.15224}, + archivePrefix={arXiv}, +} + @article{10.1021/acs.jctc.6b00684, author = {Brieuc, Fabien and Bronstein, Yael and Dammak, Hichem and Depondt, Philippe and Finocchi, Fabio and Hayoun, Marc}, journal = {J. Chem. Theory Comput.},