From 47d1e7177695eeea2d36cd7b05980942c478aa47 Mon Sep 17 00:00:00 2001
From: Giovanni Bussi <giovanni.bussi@gmail.com>
Date: Thu, 30 Oct 2014 11:06:48 +0100
Subject: [PATCH] Added notes on file backup/restart/suffix
---
user-doc/Files.txt | 61 +++++++++++++++++++++++++++++++++++++++++++++
user-doc/Misc.txt | 5 ++++
user-doc/extract | 4 ++-
user-doc/go-doxygen | 2 +-
4 files changed, 70 insertions(+), 2 deletions(-)
create mode 100644 user-doc/Files.txt
diff --git a/user-doc/Files.txt b/user-doc/Files.txt
new file mode 100644
index 000000000..571f344fa
--- /dev/null
+++ b/user-doc/Files.txt
@@ -0,0 +1,61 @@
+/**
+
+\page Files Files
+
+We tried to design PLUMED in such a manner that input/output is done consistently
+irrespectively of the file type. Most of the files written or read by PLUMED thus follow
+the very same conventions discussed below.
+
+\section Restart
+
+Whenever the \ref RESTART option is used, all the files written by PLUMED are appended.
+This makes it easy to analyze results of simulations performed as a chain of several sub-runs.
+Notice that most of the PLUMED textual files have a header. The header is repeated at every
+restart. Additionally, several files have time in the first column. PLUMED just takes the value
+of the physical time from the MD engine. As such, you could have that time starts again from zero
+upon restart or not.
+
+An exception from this behavior is given by files which are not growing as the simulation proceeds.
+For example, grids written with \ref METAD with GRID_WFILE are overwritten by default during the simulation.
+As such, when restarting, there is no point in appending the file. Internally, PLUMED opens the file in append
+mode but then rewinds it every time a new grid is dumped.
+
+\section Backup
+
+Whenever the \ref RESTART option is not used, PLUMED tries to write new files. If an old file
+is found in the way, PLUMED takes a backup named "bck.X.filename" where X is a progressive number.
+Notice that by default PLUMED only allows a maximum of 100 backup copies for a file.
+This behavior can be changed by setting the environment variable PLUMED_MAXBACKUP to the desired number
+of copies. E.g. export PLUMED_MAXBACKUP=10 will fail after 10 copies. PLUMED_MAXBACKUP=-1 will never fail - be careful
+since your disk might fill up quickly with this setting.
+
+\section Replica-Suffix Replica suffix
+
+When running with multiple replicas (e.g., with GROMACS, -multi option) PLUMED adds the replica index as a suffix to
+all the files. The following command
+will thus print files named COLVAR.0, COLVAR.1, etc for the different replicas.
+\verbatim
+d: DISTANCE ATOMS=1,2
+PRINT ARG=d FILE=COLVAR
+\endverbatim
+(see also \ref DISTANCE and \ref PRINT).
+
+When reading a file, PLUMED will try to add the suffix. If the file is not found, it will fall back to
+the name without suffix. The most important case is the reading of the plumed input file.
+If you provide a file for each replica (e.g. plumed.dat.0, plumed.dat.1, etc) you will be able to
+setup plumed differently on each replica.
+On the other hand, using a single plumed.dat will make all the replicas read the same file.
+
+\subsection Suffixes-and-file-extension Suffixes and file extension
+
+When PLUMED adds the replica suffix, it recognizes some file extension and add the suffix _before_ the
+extension. The only suffix recognized by PLUMED 2.1 is ".gz". This means that using
+\verbatim
+d: DISTANCE ATOMS=1,2
+PRINT ARG=d FILE=COLVAR.gz
+\endverbatim
+will write files named COLVAR.0.gz, COLVAR.1.gz, etc. This is useful since the preserved extension makes it easy
+to process the files later. In future PLUMED versions this behavior might change and more extensions
+could be recognized.
+
+*/
diff --git a/user-doc/Misc.txt b/user-doc/Misc.txt
index 5bf6d50de..ab1445537 100644
--- a/user-doc/Misc.txt
+++ b/user-doc/Misc.txt
@@ -124,6 +124,11 @@ chosen replicas. This is useful e.g. for bias exchange metadynamics \cite{piana}
\subpage Regex </TD><TD> </TD><TD> POSIX regular expressions can be used to select multiple actions when using ARG (i.e. \ref PRINT).
</TD>
</TR>
+<TR>
+<TD WIDTH="5%">
+\subpage Files </TD><TD> </TD><TD> Dealing with Input/Outpt
+</TD>
+</TR>
</TABLE>
*/
diff --git a/user-doc/extract b/user-doc/extract
index f9fa7041f..d57bdcfa3 100755
--- a/user-doc/extract
+++ b/user-doc/extract
@@ -216,9 +216,11 @@ do
done
-for file in Bias Syntax Colvar Functions Group Installation Intro Analysis Glossary Tutorials Modules Regex Misc Tools
+for f in *.txt
do
+file=${f%.txt}
+
# first replace with the content of the files
# then grep out the special strings
diff --git a/user-doc/go-doxygen b/user-doc/go-doxygen
index 444172ac9..3bf2af804 100755
--- a/user-doc/go-doxygen
+++ b/user-doc/go-doxygen
@@ -17,7 +17,7 @@ fi
LIST="
IntroPP.txt ../CHANGES InstallationPP.txt SyntaxPP.txt ColvarPP.txt GroupPP.txt FunctionsPP.txt AnalysisPP.txt
- BiasPP.txt ToolsPP.txt MiscPP.txt RegexPP.txt ModulesPP.txt TutorialsPP.txt GlossaryPP.txt automatic tutorials"
+ BiasPP.txt ToolsPP.txt MiscPP.txt RegexPP.txt FilesPP.txt ModulesPP.txt TutorialsPP.txt GlossaryPP.txt automatic tutorials"
{
cat Doxyfile
--
GitLab