Initial commit

.gitignore

@@ -0,0 +1,12 @@
+#ignored patterns
+
+bin/*
+*.pyc
+*.pyo
+*.x
+*.mod
+*.out
+*.o
+*.tex
+*.pdf
+*~

.vimrc

@@ -0,0 +1,4 @@
+set tabstop=3
+set softtabstop=3
+set shiftwidth=3
+set expandtab

MANIFEST.in

@@ -0,0 +1 @@
+include README.rst

README.rst

@@ -0,0 +1,42 @@
+i-PI V1.0
+--------
+
+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 propagates the (path integral) dynamics of the nuclei, and of an external
+code that acts as 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 Lennard-Jones and 
+Silveira-Goldman potentials is included for test purposes.
+
+
+Quick Installation and Test 
+---------------------------
+
+Follow these instruction to test i-PI. These assume to 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).
+
+* Generate the driver code
+
+$ cd driver
+$ make
+$ cd ..
+
+* Run one of the examples
+
+This will first start the wrapper in the background, redirecting the output on 
+a log file, then run a couple of instances of the driver code and then follow
+the progress of the wrapper by monitoring the log file
+
+$ cd examples/tutorial/tutorial-1/
+$ ../../../i-pi tutorial-1.xml > log &
+$ ../../../drivers/driver.x -h localhost -p 31415 -m sg -o 15 &
+$ ../../../drivers/driver.x -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)
+

TODO

@@ -0,0 +1,112 @@
+A list of things that should be fixed or improved
+Format of "bug-reports":
+
+PRIORITY  Title of bug (REPORTER) (ASSIGNEE)
+Longer description....
+
+PRIORITY:
+*    Can wait
+**   Should be done before release
+***  High priority
+**** Code broken! Must fix now!
+The person who "reports" a bug should indicate his initials in the title.
+If one decides to actively work on one issue, it should indicate it on the title line.
+
+
+DONE **   Clean up help (MC) (JM)
+New dynamic attributes should be properly included in the documentation. 
+
+DONE **   Clean up help (MC) (JM)
+The whole input generation method should be documented with comments in the code.
+
+**   Clean up help (MC)
+The whole input generation method should be bug-checked.
+
+DONE **   Robust input defaults (MC) (JM)
+In many places the default value of a storage class is set by defining 
+fields = { "tag" : ( Class, { "default" : EngineClass(default paramenters) } ) }
+This is bad, because the class is generated at parse time, and 
+just one default object will be returned by any instance of the 
+container Input class. 
+Defaults which are not immutable (strings, ints or floats) should be defined by
+overloading the __init__ class and calling the parent class with the appropriate default, e.g.
+InputSimulation.__init__(self, .... default=None, ....):
+   if (default is None): default=WhateverClass(parameters)
+   super(InputSimulation,self).__init__(..... default=default ...)
+
+DONE **** Make the new NM thing actually work (MC) (MC)
+
+DONE ***  Move the synchro business out of Beads and into NormalModes (MC) (MC)
+
+DONE ***  Fix PDB output NOT to use Atom interface, that is horribly slow (MC) (JM)
+
+DONE **   Fix (or remove) "springs" trajectory output. Not really needed anymore... (MC)
+
+DONE *** More in general, rationalize and clean up the available properties and trajectories. The help strings and function documentation often don't match, often which arguments are supposed to be passed to the function aren't given in the help string, some properties have tensorial equivalents and some don't, some are also trajectories and some aren't. This really needs to be tidied up. (MC/JM) (JM) 
+
+DONE (MC) *** Should NOT use the Cholesky decomposition in initializing GLE. Use symmetric decomposition instead (MC) (MC)
+
+DONE ***  Benchmark the new property implementation. (MC) (JM)
+Completely revamped properties and trajectories scheme. 
+Now it is possible to specify units and a short help string.
+
+DONE * Multiforce object should be implemented. (JM) (JM)
+
+DONE *** Write a very clean driver for LJ and SG for examples (JM) (JM)
+DONE *** Test NPT on the pH2 system (JM) (JM)
+
+*   Implement NST (MC) (MC)
+
+DONE ** Find out why NPT and NST ensembles both appear to give jumps in the 
+conserved quantity (JM)
+I have made some progress with this. I got it to stop and go back one step 
+and print a restart file whenever there was a jump. Restarting from this file
+did not reproduce the jump, suggesting that there was a problem with the 
+neighbour lists, not the wrapper.
+I then made it redo the neighbour list at each time step. This appeared to 
+reduce the frequency and magnitude of the energy jumps, but not eliminate them.
+The effect is much larger with a NST than with a NPT ensemble, in fact the 
+jumps appear to be very rare with the NPT ensemble.
+
+DONE * Figure out how to use FFTW with python for the normal-mode 
+transformations. (JM) (JM)
+
+DONE ** Add help strings to all the trajectories and properties in the property
+list (JM) (JM)
+
+DONE *** Take care that all the arguments for the properties, are being converted to the correct type. (JM) (JM)
+I'm pretty sure that at the moment we're using strings as index variables 
+rather than integers.
+
+DONE * It might be useful to have some kind of standardized error message format
+(JM) (JM)
+
+DONE ** In both engine and inputs directories, we need to document initializer, 
+normalmodes, forces and outputs (JM) (JM)
+
+DONE *** Rework the cell class, and the NPT ensemble (JM)
+
+DONE ** Add property and trajectory help string to the manual (JM) (JM)
+
+DONE *** Re-write the input files for all the test directories. (JM) (JM)
+
+DONE ** Add read cell from (A, B, C) and (alpha, beta, gamma) (JM) (JM)
+
+* Merge the io_xyz.py, io_binary.py and io_pdb.py files (JM)
+
+DONE * In the manual, the attributes of the trajectory, properties and
+checkpoint tags in the code snippets of 4.5 and 4.6 are now out-of-date. (JM) (JM)
+
+DONE ** Write the paper (JM) (MC)
+** Finish writing the manual (JM) (JM)
+
+DONE ** Implement warning() and info() everywhere (For example, it is missing
+from normalmodes.py) (JM) (JM)
+
+** Implement a more robust walltime clock limit mechanism. (MC)
+
+** Alternative communication mechanisms not relying on sockets (MC)
+
+*** Fix the 'dummy' thermostat/barostat options. At the moment, forgetting
+to set the barostat style doesn't give an error, and then you get a
+fairly unhelpful error message to go with it. (JM)

doc/Makefile

@@ -0,0 +1,35 @@
+# Makefile for the help files
+# 
+# Copyright (C) 2013, Joshua More and Michele Ceriotti
+# 
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+# 
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
+# GNU General Public License for more details.
+# 
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <http.//www.gnu.org/licenses/>.
+
+.PHONY : all distclean clean aux
+all : manual.pdf
+
+aux:
+	python create_man.py
+	rm -f *.pyc
+
+manual.pdf: aux
+	pdflatex manual
+	bibtex manual
+	pdflatex manual
+	pdflatex manual
+
+clean: 
+	bash -c "rm -rf input_docs manual.{aux,bbl,blg,brf,idx,log,lof,out,toc}"
+
+distclean: clean
+	rm -f manual.pdf manual.xml

doc/README

@@ -0,0 +1,46 @@
+ -- Documentation directory --
+
+ * This gives all the documentation for the program.
+
+ * Directories:
+   - figures: Holds the figures used in the manual.
+   - input_docs: Generated by the Makefile to hold the automatically generated
+      input reference sections of the manual.
+
+ * Files:
+   - create_man.py: python script which automatically generates latex help files
+      for all the classes, for use in the manual.
+   - help_list.py: python script which can generate custom help files for
+      the output classes, for use in the manual.
+   - help.py: python script which can generate custom help files for
+      each of the input classes, for use in the manual.
+   - Makefile: The makefile for the automatically generated manual.
+   - manual.tex: TeX file giving the manual template.
+   - mybib.bib: Bibliography file for the manual.
+   - elsarticle-num-names.bst: Bibliography style file.
+   - etoolbox.sty: LaTeX package which is used by manual.tex.
+
+ * Some of the above files are used to automatically generate sections of the
+   user manual, and to create an xml showing the class hierarchy. The sections 
+   of the user manual are created in a directory input_docs.
+   The user manual itself is created in two files, manual.pdf and manual.xml.
+   These are:
+      - manual.pdf: The user manual file. This explains how to run the code,
+         the input and output file syntax, and the design paradigm for ipi.
+         Also contains a tutorial which goes step by step through an example
+         calculation.
+      - manual.xml: This is an xml file that contains all the input names
+         along with a description of their purpose and what values are
+         expected for each of them.
+
+ * To make the help files use:
+
+$ make
+
+ * To remove the input reference sections and LaTeX compiled files, use:
+
+$ make clean
+
+ * To remove all the generated files, use:
+
+$ make distclean

doc/create_man.py

@@ -0,0 +1,43 @@
+"""Help script which automatically generates the manual files.
+
+Copyright (C) 2013, Joshua More and Michele Ceriotti
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program. If not, see <http.//www.gnu.org/licenses/>.
+
+
+Creates a latex file, corresponding to a section of the manual, for each of
+the classes specified in help.py. It uses help.py to generate information 
+about the tags for each class, and will include cross-references so that the
+title of each tag corresponding to a different class will also be a hyperlink
+in the manual to the section corresponding to that class.
+
+Note that any new input class type must be added to the objects 
+dictionary in help.py and the latex help file must be added to the end of 
+the manual.lyx file for it to be included in the automatic help generation.
+
+Also creates an xml file with the full list of all the tags.
+"""
+
+import os
+from help import help, objects
+from help_list import help_list, list_objects
+
+if not os.path.exists("input_docs"):
+   os.mkdir("input_docs")
+
+help(xml=True, prefix="manual")
+for opt in objects:
+   help(latex=True, levels=1, option=opt, prefix=("input_docs/" + opt), standalone=False)
+for opt in list_objects:
+   help_list(option=opt, prefix=("input_docs/" + opt), standalone=False)