trunk/oopsePaper/IOfiles.tex


\section{Input and Output Files}

\subsection{{\sc bass} and Model Files}

Every {\sc oopse} simuation begins with a {\sc bass} file. {\sc bass}
(\underline{B}izarre \underline{A}tom \underline{S}imulation
\underline{S}yntax) is a script syntax that is parsed by {\sc oopse} at
runtime. The {\sc bass} file allows for the user to completely describe the
system they are to simulate, as well as tailor {\sc oopse}'s behavior during
the simulation. {\sc bass} files are denoted with the extension
\texttt{.bass}, an example file is shown in
Fig.~\ref{fig:bassExample}.

\begin{figure}

\centering
\framebox[\linewidth]{\rule{0cm}{0.75\linewidth}I'm a {\sc bass} file!}
\caption{Here is an example \texttt{.bass} file}
\label{fig:bassExample}
\end{figure}

Within the \texttt{.bass} file it is neccassary to provide a complete
description of the molecule before it is actually placed in the
simulation. The {\sc bass} syntax was originally developed with this goal in
mind, and allows for the specification of all the atoms in a molecular
prototype, as well as any bonds, bends, or torsions. These
descriptions can become lengthy for complex molecules, and it would be
inconvient to duplicate the simulation at the begining of each {\sc bass}
script. Addressing this issue {\sc bass} allows for the inclusion of model
files at the top of a \texttt{.bass} file. These model files, denoted
with the \texttt{.mdl} extension, allow the user to describe a
molecular prototype once, then simply include it into each simulation
containing that molecule.

\subsection{\label{subSec:coordFiles}Coordinate Files}

The standard format for storage of a systems coordinates is a modified
xyz-file syntax, the exact details of which can be seen in
App.~\ref{appCoordFormat}. As all bonding and molecular information is
stored in the \texttt{.bass} and \texttt{.mdl} files, the coordinate
files are simply the complete set of coordinates for each atom at a
given simulation time.

There are three major files used by {\sc oopse} written in the coordinate
format, they are as follows: the initialization file, the simulation
trajectory file, and the final coordinates of the simulation. The
initialization file is neccassary for {\sc oopse} to start the simulation
with the proper coordinates. It is typically denoted with the
extension \texttt{.init}. The trajectory file is created at the
beginning of the simulation, and is used to store snapshots of the
simulation at regular intervals. The first frame is a duplication of
the \texttt{.init} file, and each subsequent frame is appended to the
file at an interval specified in the \texttt{.bass} file. The
trajectory file is given the extension \texttt{.dump}. The final
coordinate file is the end of run or \texttt{.eor} file. The
\texttt{.eor} file stores the final configuration of teh system for a
given simulation. The file is updated at the same time as the
\texttt{.dump} file. However, it only contains the most recent
frame. In this way, an \texttt{.eor} file may be used as the
initialization file to a second simulation in order to continue or
recover the previous simulation.

\subsection{Generation of Initial Coordinates}

As was stated in Sec.~\ref{subSec:coordFiles}, an initialization file
is needed to provide the starting coordinates for a simulation. The
{\sc oopse} package provides a program called \texttt{sysBuilder} to aid in
the creation of the \texttt{.init} file. \texttt{sysBuilder} is {\sc bass}
aware, and will recognize arguments and parameters in the
\texttt{.bass} file that would otherwise be ignored by the
simulation. The program itself is under contiunual development, and is
offered here as a helper tool only.

\subsection{The Statistics File}

The last output file generated by {\sc oopse} is the statistics file. This
file records such statistical quantities as the instantaneous
temperature, volume, pressure, etc. It is written out with the
frequency specified in the \texttt{.bass} file. The file allows the
user to observe the system variables as a function od simulation time
while the simulation is in progress. One useful function the
statistics file serves is to monitor the conserved quantity of a given
simulation ensemble, this allows the user to observe the stability of
the integrator. The statistics file is denoted with the \texttt{.stat}
file extension.
Revision:	818
Committed:	Fri Oct 24 21:27:59 2003 UTC (20 years, 8 months ago) by gezelter
Content type:	application/x-tex
File size:	4347 byte(s)
Log Message:	Formatting changes to get out of RevTex nonsense
#	User	Rev	Content
1	mmeineke	806
2			\section{Input and Output Files}
3
4	gezelter	818	\subsection{{\sc bass} and Model Files}
5	mmeineke	806
6	gezelter	818	Every {\sc oopse} simuation begins with a {\sc bass} file. {\sc bass}
7	mmeineke	806	(\underline{B}izarre \underline{A}tom \underline{S}imulation
8	gezelter	818	\underline{S}yntax) is a script syntax that is parsed by {\sc oopse} at
9			runtime. The {\sc bass} file allows for the user to completely describe the
10			system they are to simulate, as well as tailor {\sc oopse}'s behavior during
11			the simulation. {\sc bass} files are denoted with the extension
12	mmeineke	806	\texttt{.bass}, an example file is shown in
13			Fig.~\ref{fig:bassExample}.
14
15			\begin{figure}
16
17			\centering
18	gezelter	818	\framebox[\linewidth]{\rule{0cm}{0.75\linewidth}I'm a {\sc bass} file!}
19	mmeineke	806	\caption{Here is an example \texttt{.bass} file}
20			\label{fig:bassExample}
21			\end{figure}
22
23			Within the \texttt{.bass} file it is neccassary to provide a complete
24			description of the molecule before it is actually placed in the
25	gezelter	818	simulation. The {\sc bass} syntax was originally developed with this goal in
26	mmeineke	806	mind, and allows for the specification of all the atoms in a molecular
27			prototype, as well as any bonds, bends, or torsions. These
28			descriptions can become lengthy for complex molecules, and it would be
29	gezelter	818	inconvient to duplicate the simulation at the begining of each {\sc bass}
30			script. Addressing this issue {\sc bass} allows for the inclusion of model
31	mmeineke	806	files at the top of a \texttt{.bass} file. These model files, denoted
32			with the \texttt{.mdl} extension, allow the user to describe a
33			molecular prototype once, then simply include it into each simulation
34			containing that molecule.
35
36			\subsection{\label{subSec:coordFiles}Coordinate Files}
37
38			The standard format for storage of a systems coordinates is a modified
39			xyz-file syntax, the exact details of which can be seen in
40			App.~\ref{appCoordFormat}. As all bonding and molecular information is
41			stored in the \texttt{.bass} and \texttt{.mdl} files, the coordinate
42			files are simply the complete set of coordinates for each atom at a
43			given simulation time.
44
45	gezelter	818	There are three major files used by {\sc oopse} written in the coordinate
46	mmeineke	806	format, they are as follows: the initialization file, the simulation
47			trajectory file, and the final coordinates of the simulation. The
48	gezelter	818	initialization file is neccassary for {\sc oopse} to start the simulation
49	mmeineke	806	with the proper coordinates. It is typically denoted with the
50			extension \texttt{.init}. The trajectory file is created at the
51			beginning of the simulation, and is used to store snapshots of the
52			simulation at regular intervals. The first frame is a duplication of
53			the \texttt{.init} file, and each subsequent frame is appended to the
54			file at an interval specified in the \texttt{.bass} file. The
55			trajectory file is given the extension \texttt{.dump}. The final
56			coordinate file is the end of run or \texttt{.eor} file. The
57			\texttt{.eor} file stores the final configuration of teh system for a
58			given simulation. The file is updated at the same time as the
59			\texttt{.dump} file. However, it only contains the most recent
60			frame. In this way, an \texttt{.eor} file may be used as the
61			initialization file to a second simulation in order to continue or
62			recover the previous simulation.
63
64			\subsection{Generation of Initial Coordinates}
65
66			As was stated in Sec.~\ref{subSec:coordFiles}, an initialization file
67			is needed to provide the starting coordinates for a simulation. The
68	gezelter	818	{\sc oopse} package provides a program called \texttt{sysBuilder} to aid in
69			the creation of the \texttt{.init} file. \texttt{sysBuilder} is {\sc bass}
70	mmeineke	806	aware, and will recognize arguments and parameters in the
71			\texttt{.bass} file that would otherwise be ignored by the
72			simulation. The program itself is under contiunual development, and is
73			offered here as a helper tool only.
74
75			\subsection{The Statistics File}
76
77	gezelter	818	The last output file generated by {\sc oopse} is the statistics file. This
78	mmeineke	806	file records such statistical quantities as the instantaneous
79			temperature, volume, pressure, etc. It is written out with the
80			frequency specified in the \texttt{.bass} file. The file allows the
81			user to observe the system variables as a function od simulation time
82			while the simulation is in progress. One useful function the
83			statistics file serves is to monitor the conserved quantity of a given
84			simulation ensemble, this allows the user to observe the stability of
85			the integrator. The statistics file is denoted with the \texttt{.stat}
86			file extension.