trunk/oopsePaper/IOfiles.tex


\section{Input and Output Files}

\subsection{BASS and Model Files}

Every OOPSE simuation begins with a BASS file. BASS
(\underline{B}izarre \underline{A}tom \underline{S}imulation
\underline{S}yntax) is a script syntax that is parsed by OOPSE at
runtime. The BASS file allows for the user to completely describe the
system they are to simulate, as well as tailor OOPSE's behavior during
the simulation. 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 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 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 BASS
script. Addressing this issue 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 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 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
OOPSE package provides a program called \texttt{sysBuilder} to aid in
the creation of the \texttt{.init} file. \texttt{sysBuilder} is 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 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:	806
Committed:	Fri Oct 17 05:07:49 2003 UTC (21 years, 6 months ago) by mmeineke
Content type:	application/x-tex
File size:	4245 byte(s)
Log Message:	dded my handwritten pages from 10-16-03
#	User	Rev	Content
1	mmeineke	806
2			\section{Input and Output Files}
3
4			\subsection{BASS and Model Files}
5
6			Every OOPSE simuation begins with a BASS file. BASS
7			(\underline{B}izarre \underline{A}tom \underline{S}imulation
8			\underline{S}yntax) is a script syntax that is parsed by OOPSE at
9			runtime. The BASS file allows for the user to completely describe the
10			system they are to simulate, as well as tailor OOPSE's behavior during
11			the simulation. BASS files are denoted with the extension
12			\texttt{.bass}, an example file is shown in
13			Fig.~\ref{fig:bassExample}.
14
15			\begin{figure}
16
17			\centering
18			\framebox[\linewidth]{\rule{0cm}{0.75\linewidth}I'm a BASS file!}
19			\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			simulation. The BASS syntax was originally developed with this goal in
26			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			inconvient to duplicate the simulation at the begining of each BASS
30			script. Addressing this issue BASS allows for the inclusion of model
31			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			There are three major files used by OOPSE written in the coordinate
46			format, they are as follows: the initialization file, the simulation
47			trajectory file, and the final coordinates of the simulation. The
48			initialization file is neccassary for OOPSE to start the simulation
49			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			OOPSE package provides a program called \texttt{sysBuilder} to aid in
69			the creation of the \texttt{.init} file. \texttt{sysBuilder} is BASS
70			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			The last output file generated by OOPSE is the statistics file. This
78			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.