From e7f6cb064ac843152fd152cdda4cb56be411b155 Mon Sep 17 00:00:00 2001 From: Yair Litman Date: Fri, 14 Jun 2024 17:38:38 +0100 Subject: [PATCH 1/6] test some changes --- .github/workflows/examples.yml | 3 ++- docs/src/index.rst | 15 +++++---------- 2 files changed, 7 insertions(+), 11 deletions(-) diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml index af1af1c3c..9b6a11fba 100644 --- a/.github/workflows/examples.yml +++ b/.github/workflows/examples.yml @@ -2,7 +2,8 @@ name: pytest for examples on: pull_request: - branches: [ master ] + # branches: [ master ] + branches: [ master,gh_page_update ] jobs: build: diff --git a/docs/src/index.rst b/docs/src/index.rst index e2b6180ee..497d0fb14 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -2,10 +2,8 @@ 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 +Python 3. The main goal is to decouple the problem of evolving the +ionic positions 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 @@ -21,13 +19,10 @@ 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 +instances of an external code, acting as clients. 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. +excessive I/O it can be used to run empirical forcefields or machine learning +interatomic potentials with tens of thousands of atoms with only a small overhead. This documentation is structured as follows: From 12ccf442da67a8c154d6b5a2007903a0308fbdde Mon Sep 17 00:00:00 2001 From: Yair Litman Date: Fri, 14 Jun 2024 17:45:38 +0100 Subject: [PATCH 2/6] a new test --- .github/workflows/examples.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml index 9b6a11fba..5d2bffa06 100644 --- a/.github/workflows/examples.yml +++ b/.github/workflows/examples.yml @@ -3,7 +3,7 @@ name: pytest for examples on: pull_request: # branches: [ master ] - branches: [ master,gh_page_update ] + branches: [ master ] jobs: build: From 820aee1ff32405f844dcb52e4d8f0c42c0ff47bb Mon Sep 17 00:00:00 2001 From: Yair Litman Date: Fri, 14 Jun 2024 18:59:22 +0100 Subject: [PATCH 3/6] update introduction and on-line resources --- docs/figures/ipi-structure-v3.pdf | Bin 0 -> 53317 bytes docs/figures/ipi-structure-v3.svg | 4415 +++++++++++++++++++++++++++++ docs/src/index.rst | 31 +- docs/src/introduction.rst | 350 +-- docs/src/onlinereso.rst | 55 + docs/src/references.bib | 8 + 6 files changed, 4637 insertions(+), 222 deletions(-) create mode 100644 docs/figures/ipi-structure-v3.pdf create mode 100644 docs/figures/ipi-structure-v3.svg create mode 100644 docs/src/onlinereso.rst diff --git a/docs/figures/ipi-structure-v3.pdf b/docs/figures/ipi-structure-v3.pdf new file mode 100644 index 0000000000000000000000000000000000000000..ea88801f495c05ecd5542268e6fe4a2d87b896f8 GIT binary patch literal 53317 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
hi0j@hPYxBnKOx%&=sAS`1C*r~G@z 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 dr~s=(wsH)l6KV9V3^6EZg + + + + + 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/index.rst b/docs/src/index.rst index 497d0fb14..524b25e6a 100644 --- a/docs/src/index.rst +++ b/docs/src/index.rst @@ -1,27 +1,23 @@ Welcome to i-PI's documentation! ================================ -i-PI is a interface for advanced molecular simulations written in -Python 3. The main goal is to decouple the problem of evolving the -ionic positions 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. 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 or machine learning +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: @@ -30,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..e1cd8dffe --- /dev/null +++ b/docs/src/onlinereso.rst @@ -0,0 +1,55 @@ +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. + +.. _librarywebsites: + +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, +VASP, Yaff, VASP. +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.}, From 8a1c2d8916e7bcdd938d9e0dde6e92278504bd8a Mon Sep 17 00:00:00 2001 From: Yair Litman Date: Fri, 14 Jun 2024 20:05:10 +0100 Subject: [PATCH 4/6] updating getting-started --- docs/src/getting-started.rst | 182 +++++++++++------------------------ docs/src/onlinereso.rst | 2 +- 2 files changed, 59 insertions(+), 125 deletions(-) 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/onlinereso.rst b/docs/src/onlinereso.rst index e1cd8dffe..82772ec2f 100644 --- a/docs/src/onlinereso.rst +++ b/docs/src/onlinereso.rst @@ -1,3 +1,4 @@ +.. _librarywebsites: On-line resources ================= @@ -22,7 +23,6 @@ worked examples of its capabilities see 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 ~~~~~~~~~~~~~~~~~~~~~ From 46e7103b9969c035e282fe62f60a091aff48917c Mon Sep 17 00:00:00 2001 From: Yair Litman Date: Sat, 15 Jun 2024 07:41:49 +0100 Subject: [PATCH 5/6] delete VASP from list out of the box drivers --- docs/src/onlinereso.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/src/onlinereso.rst b/docs/src/onlinereso.rst index 82772ec2f..dbd622d7d 100644 --- a/docs/src/onlinereso.rst +++ b/docs/src/onlinereso.rst @@ -35,11 +35,12 @@ DFTB+, elphmod, ffsGDML, FHI-aims, -Lammps, +LAMMPS, librascal, Quantum ESPRESSO, Siesta, -VASP, Yaff, VASP. +Yaff. + If you are interested in interfacing your code to i-PI please get in touch, we are always glad to help! From c1087e1c3aea4d39b77a4a9ba98f0779ec6b45e2 Mon Sep 17 00:00:00 2001 From: Yair Litman Date: Sat, 15 Jun 2024 07:43:16 +0100 Subject: [PATCH 6/6] delete comment in workflows/examples.yml --- .github/workflows/examples.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/examples.yml b/.github/workflows/examples.yml index 5d2bffa06..af1af1c3c 100644 --- a/.github/workflows/examples.yml +++ b/.github/workflows/examples.yml @@ -2,7 +2,6 @@ name: pytest for examples on: pull_request: - # branches: [ master ] branches: [ master ] jobs: