ipi 2.6.0__tar.gz

ipi-2.6.0/PKG-INFO

@@ -0,0 +1,138 @@
+Metadata-Version: 2.1
+Name: ipi
+Version: 2.6.0
+Summary: A Python interface for ab initio path integral molecular dynamics simulations
+Home-page: http://ipi-code.org
+Author: The i-PI developers
+Author-email: ipi.managers@gmail.com
+Project-URL: Documentation, https://ipi-code.org/i-pi
+Project-URL: Repository, https://github.com/i-pi/i-pi
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: POSIX :: Linux
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.6
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Python: >=3.6
+Description-Content-Type: text/x-rst
+License-File: licenses/license_GPL.txt
+License-File: licenses/license_MIT.txt
+Requires-Dist: numpy
+
+i-PI: a Universal Force Engine
+==============================
+
+A Python interface for ab initio path integral molecular dynamics simulations.
+i-PI is composed of a Python server (i-pi itself, that does not need to be
+compiled but only requires a relatively recent version of Python and Numpy)
+that apply an algorithm that updates the positions of the nuclei, and of an external
+code that acts as a client and computes the electronic energy and forces.
+
+This is typically a patched version of an electronic structure code, but a
+simple self-contained Fortran driver that implements several simple interatomic
+potentials is included for test purposes.
+
+i-PI was originally developed to simulate the quantum mechanical nature of light
+nuclei by performing path integral molecular dynamics simulations,
+and it implements most of the state-of-the-art methods to accelerate this kind of 
+calculations. It has since grown to also provide all sorts of simulation 
+strategies, from replica exchange to geometry optimization. 
+
+Quick Setup and Test
+--------------------
+
+To use i-PI with an existing driver, install and update using Pip:
+
+Last version::
+```bash
+python -m pip install git+https://github.com/i-pi/i-pi.git
+```
+
+Last Release::
+```bash
+pip install -U i-PI
+```
+
+Test with Pytest::
+```bash
+pip install pytest
+pytest --pyargs ipi.tests
+```
+
+Full installation
+-----------------
+
+To develop i-PI or test it with the self-contained driver, follow these
+instructions. It is assumed that i-PI will
+be run from a Linux environment, with a recent version of Python, Numpy and
+gfortran, and that the terminal is initially in the i-pi package directory (the
+directory containing this file), which you can obtain by cloning the repository
+
+```bash
+git clone https://github.com/i-pi/i-pi.git
+```
+
+Source the environment settings file `env.sh` as `source env.sh` or `.
+env.sh`.  It is useful to put this in your `.bashrc` or other settings file if
+you always want to have i-PI available.
+
+
+### Compile the driver code
+
+```bash
+cd drivers/f90
+make
+cd ../..
+```
+
+### Examples and demos
+
+The `examples` and `demos` folders contain inputs for many different types of
+calculations based on i-PI. Examples are typically minimal use-cases of specific
+features, while demos are more structured, tutorial-like examples that show how
+to realize more complex setups, and also provide a brief discussion of the 
+underlying algorithms.
+
+To run these examples, you should typically start i-PI, redirecting the output to
+a log file, and then run a couple of instances of the driver code. The progress
+of the wrapper is followed by monitoring the log file with the `tail` Linux command.
+
+Optionally, you can make a copy of the directory with the example somewhere
+else if you want to keep the i-PI directory clean. For example
+
+```bash
+cd demos/para-h2-tutorial/tutorial-1/
+i-pi tutorial-1.xml > log &
+i-pi-driver -h localhost -p 31415 -m sg -o 15 &
+i-pi-driver -h localhost -p 31415 -m sg -o 15 &
+tail -f log
+```
+
+The monitoring can be interrupted with CTRL+C when the run has finished (5000 steps).
+
+
+### Run the automatic test suite
+
+The automatic test suite can be run by calling the i-pi-test script.
+You need to have the `pytest` package installed
+
+```
+i-pi-test
+```
+
+See more details in the README file inside the ipi_tests folder.
+
+Contributing
+------------
+
+If you have new features you want to implement into i-PI, your contributions are much welcome.
+See `CONTRIBUTING.md` for a brief set of style guidelines and best practices. Before embarking
+into a substantial project, it might be good to get in touch with the developers, e.g. by opening
+a wishlist issue.

ipi-2.6.0/README.md

@@ -0,0 +1,110 @@
+i-PI: a Universal Force Engine
+==============================
+
+A Python interface for ab initio path integral molecular dynamics simulations.
+i-PI is composed of a Python server (i-pi itself, that does not need to be
+compiled but only requires a relatively recent version of Python and Numpy)
+that apply an algorithm that updates the positions of the nuclei, and of an external
+code that acts as a client and computes the electronic energy and forces.
+
+This is typically a patched version of an electronic structure code, but a
+simple self-contained Fortran driver that implements several simple interatomic
+potentials is included for test purposes.
+
+i-PI was originally developed to simulate the quantum mechanical nature of light
+nuclei by performing path integral molecular dynamics simulations,
+and it implements most of the state-of-the-art methods to accelerate this kind of 
+calculations. It has since grown to also provide all sorts of simulation 
+strategies, from replica exchange to geometry optimization. 
+
+Quick Setup and Test
+--------------------
+
+To use i-PI with an existing driver, install and update using Pip:
+
+Last version::
+```bash
+python -m pip install git+https://github.com/i-pi/i-pi.git
+```
+
+Last Release::
+```bash
+pip install -U i-PI
+```
+
+Test with Pytest::
+```bash
+pip install pytest
+pytest --pyargs ipi.tests
+```
+
+Full installation
+-----------------
+
+To develop i-PI or test it with the self-contained driver, follow these
+instructions. It is assumed that i-PI will
+be run from a Linux environment, with a recent version of Python, Numpy and
+gfortran, and that the terminal is initially in the i-pi package directory (the
+directory containing this file), which you can obtain by cloning the repository
+
+```bash
+git clone https://github.com/i-pi/i-pi.git
+```
+
+Source the environment settings file `env.sh` as `source env.sh` or `.
+env.sh`.  It is useful to put this in your `.bashrc` or other settings file if
+you always want to have i-PI available.
+
+
+### Compile the driver code
+
+```bash
+cd drivers/f90
+make
+cd ../..
+```
+
+### Examples and demos
+
+The `examples` and `demos` folders contain inputs for many different types of
+calculations based on i-PI. Examples are typically minimal use-cases of specific
+features, while demos are more structured, tutorial-like examples that show how
+to realize more complex setups, and also provide a brief discussion of the 
+underlying algorithms.
+
+To run these examples, you should typically start i-PI, redirecting the output to
+a log file, and then run a couple of instances of the driver code. The progress
+of the wrapper is followed by monitoring the log file with the `tail` Linux command.
+
+Optionally, you can make a copy of the directory with the example somewhere
+else if you want to keep the i-PI directory clean. For example
+
+```bash
+cd demos/para-h2-tutorial/tutorial-1/
+i-pi tutorial-1.xml > log &
+i-pi-driver -h localhost -p 31415 -m sg -o 15 &
+i-pi-driver -h localhost -p 31415 -m sg -o 15 &
+tail -f log
+```
+
+The monitoring can be interrupted with CTRL+C when the run has finished (5000 steps).
+
+
+### Run the automatic test suite
+
+The automatic test suite can be run by calling the i-pi-test script.
+You need to have the `pytest` package installed
+
+```
+i-pi-test
+```
+
+See more details in the README file inside the ipi_tests folder.
+
+Contributing
+------------
+
+If you have new features you want to implement into i-PI, your contributions are much welcome.
+See `CONTRIBUTING.md` for a brief set of style guidelines and best practices. Before embarking
+into a substantial project, it might be good to get in touch with the developers, e.g. by opening
+a wishlist issue.

ipi-2.6.0/bin/i-pi

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+
+"""Main script from which the simulation is run.
+
+Deals with creation of the simulation object, reading the input file and
+initialising the system.
+
+Run using:
+      i-pi input_file.xml
+
+Where 'input_file.xml' should be replaced by the name of the xml input file
+from which the system data will be read. For a description of how the input
+file should be formatted, see the reference manual.
+"""
+
+# This file is part of i-PI.
+# i-PI Copyright (C) 2014-2015 i-PI developers
+# See the "licenses" directory for full license information.
+
+
+import sys
+import os
+
+# Check that we have the import path for this i-PI set and if not, add it.
+dir_root = os.path.realpath(
+    os.path.join(os.path.dirname(os.path.realpath(__file__)), '..'))
+if not dir_root in sys.path:
+    sys.path.insert(0, dir_root)
+
+from ipi.utils.softexit import softexit
+from ipi.engine.simulation import Simulation
+
+def profile_exit(prefix="profile"):
+    # write out the outputs of the profiler
+    import yappi            
+    yappi.stop()
+    yappi.get_thread_stats().print_all()
+    yfs = yappi.get_func_stats()
+    yfs.save(prefix+".kgrind", type="callgrind")
+    ypo = open(prefix+".yappi", "w")
+    yfs.print_all(out=ypo)
+    ypo.close()
+
+
+def main(fn_input, options):
+    """Loads and runs the simulation stored in `fn_input`."""
+
+    # optionally profile this run - set up
+    if options.do_yappi:
+        try:
+            import yappi
+            yappi.set_clock_type(options.yappi_clock)
+            yappi.start(builtins=True, profile_threads=True)
+            # register the output function for the profiler so it is 
+            # called whatever the way i-PI ends
+            softexit.register_function(profile_exit, prefix=options.yappi_prefix)
+        except ImportError:
+            raise ImportError('Profiling requires the `yappi` package.')            
+
+    # construct simulation based on input file
+    simulation = Simulation.load_from_xml(fn_input, request_banner=True, custom_verbosity=options.verbosity)
+
+    # run the simulation
+    simulation.run()
+
+    # It seems that checkpoints are written by the following.
+    # TODO: Have them written when simulation.run() finishes instead.
+    # It should be sufficient to run `self.softexit() at the end of
+    # `Simulation.run()`. Anything else missing?
+    softexit.trigger(status="success", message=" @ SIMULATION: Exiting cleanly.")
+
+
+if __name__ == '__main__':
+
+    # TODO: Use argparse once we move to Python 2.7.
+
+    from optparse import OptionParser
+
+    parser = OptionParser(usage='%prog [options] <input file>',
+                          description='The main i-PI executable used to run '
+                                      'a simulation, given an XML input file.'
+                          )
+
+    parser.add_option('-p', '--profile',
+                      action='store_true', dest='do_yappi', default=False,
+                      help='Profile this run using yappi.')
+
+    parser.add_option('--profiler-clock', dest='yappi_clock', default="cpu",
+                      choices=['cpu', 'wall'],
+                      help='Type of profiling timing: `wall` for wall-clock timing, and `cpu` for CPU timing.')
+    
+    parser.add_option('--profiler-output', dest='yappi_prefix', default="profile",                      
+                      help='Prefix for profiler files.')
+
+    parser.add_option('-V', '--verbosity', dest='verbosity', default=None,
+                      choices=['quiet', 'low', 'medium', 'high', 'debug'],
+                      help='Define the verbosity level.')
+
+    options, args = parser.parse_args()
+
+    # make sure that we have exactly one input file and it exists
+    if len(args) == 0:
+        parser.error('No input file name provided.')
+    elif len(args) > 1:
+        parser.error('Provide only one input file name.')
+    else:
+        fn_in = args[0]
+        if not os.path.exists(fn_in):
+            parser.error('Input file not found: {:s}'.format(fn_in))
+
+    # Everything is ready. Go!
+    main(args[0], options)

ipi-2.6.0/bin/i-pi-committee-reweight

@@ -0,0 +1,267 @@
+#!/usr/bin/env python3
+import sys
+import argparse
+import numpy as np
+from ipi.engine.simulation import Simulation
+
+
+def direct_reweight(pot, obs, kbT):
+    """
+    Reweights an observable based on a committee of potentials, at the temperature kT
+    ref:
+    Torrie, Glenn M., and John P. Valleau. "Nonphysical sampling distributions in Monte
+    Carlo free-energy estimation: Umbrella sampling."
+    Journal of Computational Physics 23.2 (1977): 187-199.
+    https://doi.org/10.1016/0021-9991(77)90121-8
+
+    Inputs:
+    pot          : an array (nframes x ncommittee) containing the values of the potentials for each committee
+    obs          : an array containing the values of the observables
+    kbT          : the temperature, in energy units
+
+    Returns:
+    obs_avg_rew  : the observable reweighted for each potential
+    weights      : the weights computed for each model and frame
+    """
+    beta = 1.0 / kbT
+    num_pot_frames = pot.shape[0]
+    num_obs_frames = obs.shape[0]
+    if num_pot_frames != num_obs_frames:
+        raise RuntimeError(
+            "Potential and observable files have different numbers of frames"
+        )
+
+    num_pot_models = pot.shape[1]
+    if obs.ndim == 1:
+        obs = np.expand_dims(obs, axis=1)
+
+    # vectorized evaluation of weights
+    weights = np.array(-beta * (pot.T - np.mean(pot, axis=1)).T, dtype=np.float128)
+    weights = np.exp(weights)
+
+    # 1-d array of lenght num_pot_models: normalization of the weights over frames
+    norm = np.sum(weights, axis=0)
+    for i in range(num_pot_models):
+        weights[:, i] /= norm[i]
+    obs_avg_rew = obs.T @ weights
+
+    return obs_avg_rew, weights
+
+
+def CEA(pot, obs, kbT):
+    """
+    Reweights the quantity by cumulant expansion approximation (CEA)
+    ref:
+    Michele Ceriotti,  Guy A. R. Brain, Oliver Riordan and David E.
+    Manolopoulos 2011 The inefficiency of re-weighted sampling and
+    the curse of system size in high-order path integration
+    Proc. R. Soc. A.4682–17
+    http://doi.org/10.1098/rspa.2011.0413
+
+    Inputs:
+    pot          : an array (nframes x ncommittee) containing the values of the potentials for each committee
+    obs          : an array containing the values of the observables
+    kbT          : the temperature, in energy units
+
+    Returns:
+    obs_avg_rew  : the observable reweighted for each potential
+    weights      : the weights computed for each model and frame
+
+    """
+    beta = 1.0 / kbT
+    num_pot_frames = pot.shape[0]
+    num_obs_frames = obs.shape[0]
+    if num_pot_frames != num_obs_frames:
+        raise RuntimeError(
+            "Potential and observable files have different numbers of frames"
+        )
+    num_pot_models = pot.shape[1]
+    if obs.ndim == 1:
+        obs = np.expand_dims(obs, axis=1)
+    num_obs_models = obs.shape[1]
+
+    # get the h matrix h = beta(V^i - barV)
+    h_matrix = np.zeros((num_pot_frames, num_pot_models))
+    # fast way avoiding double loop
+    h_matrix = beta * (pot.T - np.mean(pot, axis=1)).T
+    # get frame-average of h, h_avg
+    h_avg = np.mean(h_matrix, axis=0)  # 1d-array of length num_pot_models
+    # get frame-average of observable, obs_avg
+    obs_avg = np.mean(obs, axis=0)  # 1d-array of length num_obs_models
+    # get frame-average of the product between the observable and h, obsxh_avg
+    obsxh_avg = (obs.T @ h_matrix) / num_pot_frames
+    # get frame-average of observable, reweighted according to the CEA, obs_avg_CEA
+    obs_avg_CEA = np.zeros((num_obs_models, num_pot_models))
+    for j in range(num_obs_models):
+        for i in range(num_pot_models):
+            obs_avg_CEA[j, i] = obs_avg[j] - obsxh_avg[j, i] + obs_avg[j] * h_avg[i]
+    return obs_avg_CEA, h_matrix
+
+
+def uncertainty_CEA_multiple_models(pot, obs, kbT):
+    """
+    Reweights the quantity by cumulant expansion approximation (CEA) in the case of
+    multiple models used to predict the observable.
+    ref:
+    Michele Ceriotti,  Guy A. R. Brain, Oliver Riordan and David E.
+    Manolopoulos 2011 The inefficiency of re-weighted sampling and
+    the curse of system size in high-order path integration
+    Proc. R. Soc. A.4682–17
+    http://doi.org/10.1098/rspa.2011.0413
+
+    Inputs:
+    pot         : an array (nframes x ncommittee) containing the values of the potentials for each committee
+    obs         : an array containing the values of the observables
+    kbT         : the temperature, in energy units
+
+    Returns:
+    mean_value  : the average value of the observable
+    sigma2_a    : the uncertainty related to the models used to predict the observable
+    sigma2_aV   : the uncertainty related to the use of a committee of potentials driving the dynamics
+    sigma2_tile : the total uncertainty for the observable
+
+    """
+    beta = 1.0 / kbT  # noqa
+    obs_avg = np.mean(obs, axis=0)
+    obs_avg_CEA, _h_matrix = CEA(obs, pot, kbT)
+    fac_a = (pot.shape[1] * (obs.shape[1] - 1)) / (pot.shape[1] * obs.shape[1] - 1)
+    fac_aV = ((pot.shape[1] - 1) * obs.shape[1]) / (pot.shape[1] * obs.shape[1] - 1)
+    sigma2_a = np.var(obs_avg, ddof=1)  # Eq.(27)
+    sigma2_aV = np.mean(np.var(obs_avg_CEA, axis=1, ddof=1))  # Eq.(28)
+    sigma2_tilde = fac_a * sigma2_a + fac_aV * sigma2_aV  # Eq.(26)
+    return np.mean(obs_avg), sigma2_a, sigma2_aV, sigma2_tilde
+
+
+def commitee_reweight(
+    path2ixml, pot_file, obs_file, stride=1, index=-1, direct=False, multi_models=False
+):
+    """
+    Parameters
+    ----------
+    pot_file    :   str, mandatory
+                    The file containing the values of the potential from each model, either in .dat form or as .extra.
+                    Each line contains the potentials for the M models for each frame
+    obs_file    :   str, mandatory
+                    A file containing the value of the observable for each frame.
+                    It is assumed that lines correspond to frames, while columns to properties.
+                    Multiple properties can be reweighted at the same time.
+    stride      :   integer, [1]
+                    The frequency of sampling of pot_file, if different from that of prop_file (e.g. --stride 10 if
+                    the potential was printed 10 times more often than the observable. --stride -10 must be used if
+                    the observable were printed more often than the potential).
+    index       :   integer, optional
+                    Which column of the property file should be used to compute the average and uncertainty.
+                    If it is not given, and there are multiple columns, they will be interpreted as corresponding
+                    to multiple property models
+    direct      :   bool, optional
+                    Activates the direct reweighting, instead of the cumulant expansion approximation.
+                    Use at your own risk! Does not work with multi_models
+    multi_models:   bool, optional
+                    Activates the uncertainty for multiple models, as in Eqs. 26,27,28 of the paper.
+                    It considers each column as a prediction from a single model and returns the
+                    uncertainty of the models together with the uncertainty of the potentials.
+
+    """
+    if index >= 0:
+        obs = np.loadtxt(obs_file, usecols=index)
+    else:
+        obs = np.loadtxt(obs_file)
+
+    if stride > 0:
+        potentials = np.loadtxt(pot_file)[::stride]
+    elif stride < 0:
+        stride = np.abs(stride)
+        obs = obs[::stride]
+    else:
+        raise ValueError("Stride value cannot be zero")
+
+    # Load kbT from i-PI, we could make it into a small function
+    simul = Simulation.load_from_xml(
+        path2ixml, custom_verbosity="quiet", read_only=True
+    )
+    kbT = float(simul.syslist[0].ensemble.temp)
+
+    if multi_models:
+        mean_value, sigma2_a, sigma2_aV, sigma2_tilde = uncertainty_CEA_multiple_models(
+            potentials, obs, kbT
+        )
+        print("#     Mean            Error         sigma_a        sigma_aV")
+        print(
+            "{:.8e}  {:.8e}  {:.8e}  {:.8e}".format(
+                mean_value, np.sqrt(sigma2_tilde), np.sqrt(sigma2_a), np.sqrt(sigma2_aV)
+            )
+        )
+    else:
+        # CEA is the default choice. The weights or h_matrix are
+        if direct:
+            rw_obs, _weights = direct_reweight(potentials, obs, kbT)
+        else:
+            rw_obs, _h_matrix = CEA(potentials, obs, kbT)
+        print(
+            "#     Mean            Error        <committee_1>         ....         <committee_N>"
+        )
+
+        np.savetxt(
+            sys.stdout,
+            np.vstack([rw_obs.mean(axis=1), rw_obs.std(axis=1), rw_obs.T]).T,
+            fmt="% 15.8e ",
+        )
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(
+        description="""This tool exploits a committee of ML models to compute the reweighted  canonical averages of a given observable, in order to quantify its uncertainty at thermodynamic equilibrium.
+    The units for the potentials are assumed to be Hartree.
+    The full methodology is described in: https://doi.org/10.1063/5.0036522"""
+    )
+
+    parser.add_argument(
+        "input_xml",
+        type=str,
+        help="The path to the input file used to run the simulation (usually input.xml)",
+    )
+    parser.add_argument(
+        "pot_file",
+        type=str,
+        help="The file containing the potentials. Rows = frames, columns = potentials",
+    )
+    parser.add_argument(
+        "obs_file",
+        type=str,
+        help="The file containing the properties. Rows = frames, columns = property/ies",
+    )
+    parser.add_argument(
+        "--stride",
+        type=int,
+        default=1,
+        help="The stride ratio used to print the potential and the property. A positive number will take one every n-th value of the potential. A negative number will do the same on the property file.",
+    )
+    parser.add_argument(
+        "--index",
+        type=int,
+        default=-1,
+        help="0-based index of the property that we want to compute",
+    )
+    parser.add_argument(
+        "--direct",
+        action="store_true",
+        help="Call this option to activate direct reweighting. Standard reweighting is the CEA",
+    )
+    parser.add_argument(
+        "--multi-obs",
+        action="store_true",
+        help="Call this option to activate reweighting for multiple observable models. The obs_file is interpreted as having one row per step, and columns correspond to the members of a property committee. It returns both the uncertainty associated with the spread of the observable models, and the one derived from the reweighting due to the potential models",
+    )
+
+    args = parser.parse_args()
+    sys.exit(
+        commitee_reweight(
+            args.input_xml,
+            args.pot_file,
+            args.obs_file,
+            args.stride,
+            args.index,
+            args.direct,
+            args.multi_obs,
+        )
+    )