--- trunk/oopsePaper/oopsePaper.tex 2004/04/26 21:05:03 1134 +++ trunk/oopsePaper/oopsePaper.tex 2004/05/12 19:32:47 1168 @@ -25,7 +25,8 @@ Engine for Molecular Dynamics} \title{{\sc oopse}: An Open Source Object-Oriented Parallel Simulation Engine for Molecular Dynamics} -\author{Matthew A. Meineke, Charles F. Vardeman II, Teng Lin, Christopher J. Fennell and J. Daniel Gezelter\\ +\author{Matthew A. Meineke, Charles F. Vardeman II, Teng Lin,\\ + Christopher J. Fennell and J. Daniel Gezelter\\ Department of Chemistry and Biochemistry\\ University of Notre Dame\\ Notre Dame, Indiana 46556} @@ -35,10 +36,9 @@ package ({\sc oopse}) that can perform molecular dynam \begin{abstract} We detail the capabilities of a new open-source parallel simulation -package ({\sc oopse}) that can perform molecular dynamics simulations -on atom types that are missing from other popular packages. In -particular, {\sc oopse} is capable of performing orientational -dynamics on dipolar systems, and it can handle simulations of metallic +progrm for MD ({\sc oopse}) that can work with atom types that are missing from other popular packages. In +particular, {\sc oopse} is capable of performing efficient orientational +dynamics on dipolar or rigid body systems, and it can handle simulations of metallic systems using the embedded atom method ({\sc eam}). \end{abstract} @@ -88,20 +88,21 @@ lastly, Sec.~\ref{oopseSec:conclusion} concludes the c considerations are presented in Sec.~\ref{oopseSec:design}. And lastly, Sec.~\ref{oopseSec:conclusion} concludes the chapter. -\section{\label{oopseSec:empiricalEnergy}The Empirical Energy Functions} +\section{\label{oopseSec:IOfiles}Concepts \& Files} -\subsection{\label{oopseSec:atomsMolecules}Atoms, Molecules and Rigid Bodies} +\subsection{{\sc bass} and Model Files} -The basic unit of an {\sc oopse} simulation is the atom. The -parameters describing the atom are generalized to make the atom as -flexible a representation as possible. They may represent specific -atoms of an element, or be used for collections of atoms such as -methyl and carbonyl groups. The atoms are also capable of having -directional components associated with them (\emph{e.g.}~permanent -dipoles). Charges, permanent dipoles, and Lennard-Jones parameters for -a given atom type are set in the force field parameter files. +Every {\sc oopse} simulation begins with a Bizarre Atom Simulation +Syntax ({\sc bass}) file. {\sc bass} 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 wish 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 +Scheme~\ref{sch:bassExample}. -\begin{lstlisting}[float,caption={[Specifier for molecules and atoms] A sample specification of an Ar molecule},label=sch:AtmMole] +\begin{lstlisting}[float,caption={[An example of a complete {\sc bass} file] An example showing a complete {\sc bass} file.},label={sch:bassExample}] + molecule{ name = "Ar"; nAtoms = 1; @@ -110,16 +111,92 @@ molecule{ position( 0.0, 0.0, 0.0 ); } } + +nComponents = 1; +component{ + type = "Ar"; + nMol = 108; +} + +initialConfig = "./argon.init"; + +forceField = "LJ"; +ensemble = "NVE"; // specify the simulation ensemble +dt = 1.0; // the time step for integration +runTime = 1e3; // the total simulation run time +sampleTime = 100; // trajectory file frequency +statusTime = 50; // statistics file frequency + \end{lstlisting} +Within the \texttt{.bass} file it is necessary 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 +inconvenient to duplicate the simulation at the beginning 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. Returning to the example in +Scheme~\ref{sch:bassExample}, the \texttt{.mdl} file's contents would +be Scheme~\ref{sch:mdlExample}, and the new \texttt{.bass} file would +become Scheme~\ref{sch:bassExPrime}. +\begin{lstlisting}[float,caption={An example \texttt{.mdl} file.},label={sch:mdlExample}] + +molecule{ + name = "Ar"; + nAtoms = 1; + atom[0]{ + type="Ar"; + position( 0.0, 0.0, 0.0 ); + } +} + +\end{lstlisting} + +\begin{lstlisting}[float,caption={Revised {\sc bass} example.},label={sch:bassExPrime}] + +#include "argon.mdl" + +nComponents = 1; +component{ + type = "Ar"; + nMol = 108; +} + +initialConfig = "./argon.init"; + +forceField = "LJ"; +ensemble = "NVE"; +dt = 1.0; +runTime = 1e3; +sampleTime = 100; +statusTime = 50; + +\end{lstlisting} + +\subsection{\label{oopseSec:atomsMolecules}Atoms, Molecules and Rigid Bodies} + +The basic unit of an {\sc oopse} simulation is the atom. The +parameters describing the atom are generalized to make the atom as +flexible a representation as possible. They may represent specific +atoms of an element, or be used for collections of atoms such as +methyl and carbonyl groups. The atoms are also capable of having +directional components associated with them (\emph{e.g.}~permanent +dipoles). Charges, permanent dipoles, and Lennard-Jones parameters for +a given atom type are set in the force field parameter files. + Atoms can be collected into secondary structures such as rigid bodies or molecules. The molecule is a way for {\sc oopse} to keep track of the atoms in a simulation in logical manner. Molecular units store the identities of all the atoms and rigid bodies associated with themselves, and are responsible for the evaluation of their own internal interactions (\emph{i.e.}~bonds, bends, and torsions). Scheme -\ref{sch:AtmMole} shows how one creates a molecule in a ``model'' or +\ref{sch:mdlExample} shows how one creates a molecule in a ``model'' or \texttt{.mdl} file. The position of the atoms given in the declaration are relative to the origin of the molecule, and is used when creating a system containing the molecule. @@ -132,7 +209,7 @@ motion have been much worse than those available for t included in most simulation packages because of the algorithmic complexity involved in propagating orientational degrees of freedom. Until recently, integrators which propagate orientational -motion have been much worse than those available for translational +motion have had energy conservation problems when compared to those available for translational motion. Moving a rigid body involves determination of both the force and @@ -174,11 +251,9 @@ definition of a rigid body can be seen in Scheme entire nine parameter rotation matrix. Further discussion on this choice can be found in Sec.~\ref{oopseSec:integrate}. An example definition of a rigid body can be seen in Scheme -\ref{sch:rigidBody}. The positions in the atom definitions are the -placements of the atoms relative to the origin of the rigid body, -which itself has a position relative to the origin of the molecule. +\ref{sch:rigidBody}. -\begin{lstlisting}[float,caption={[Defining rigid bodies]A sample definition of a rigid body},label={sch:rigidBody}] +\begin{lstlisting}[float,caption={[Defining rigid bodies]A sample definition of a molecule containing a rigid body},label={sch:rigidBody}] molecule{ name = "TIP3P"; nAtoms = 3; @@ -200,9 +275,215 @@ molecule{ nMembers = 3; members(0, 1, 2); } +} +\end{lstlisting} + +\subsection{\label{sec:miscConcepts}Putting a Script Together} + +The actual creation of a {\sc bass} script requires several key components. The first part of the script needs to be the declaration of all of the molecule prototypes used in the simulation. This is typically done through the inclusion of {\tt .mdl} files. Only the molecules actually present in the simulation need to be declared, however {\sc bass} allows for the declaration of more molecules than are needed. This gives the user the ability to build up a library of commonly used molecules into a single {\tt .mdl} file. + +Once all prototypes are declared, the ordering of the rest of the script is less stringent. Typically, the next to follow the molecular prototypes are the component statements. These statements specify which molecules are present within the simulation. The number of components must first be declared before the first component block statement (an example is seen in Sch.~\ref{sch:bassExPrime}). The component blocks tell {\sc oopse} the number of molecules that will be in the simulation, and the order in which the components blocks are declared sets the ordering of the real atoms within the simulation as well as in the output files. + +The remainder of the script then sets the various simulation parameters for the system of interest. The required set of parameters that must be present in all simulations is given in Table~\ref{table:reqParams}. The {\tt ensemble} statement is responsible for selecting the integration method used for the calculation of the equations of motion. An in depth discussion of the various methods available in {\sc oopse} can be found in Sec.~\ref{oopseSec:mechanics}. The {\tt forceField} statement is important for the selection of which forces will be used in the course of the simulation. {\sc oopse} supports several force fields, as outlined in Sec.~\ref{oopseSec:empericalEnergy}. The force fields are interchangeable between simulations, with the only requirement being that all atoms needed by the simulation are defined within the selected force field. The time step between force evaluations is set with the {\tt dt} parameter, and {\tt runTime} will set the time length of the simulation. Note, that {\tt runTime} is an absolute time, meaning if the simulation is started at t = 10.0~ns with a {\tt runTime} of 25.0~ns, the simulation will only run for an additional 15.0~ns. The final required parameter, is the {\tt initialConfig} statement. This will set the initial coordinates for the system, as well as the initial time if the {\tt useInitalTime = true;} flag is given. The format of the file specified in {\tt initialConfig}, is given in Sec.~\ref{oopseSec:coordFiles}. Additional parameters are summarized in Table~\ref{table:genParams}. + +\begin{table} +\caption{The Global Keywords: Required Parameters} +\label{table:reqParams} +\begin{center} +% Note when adding or removing columns, the \hsize numbers must add up to the total number +% of columns. +\begin{tabularx}{\linewidth}% + {>{\setlength{\hsize}{1.00\hsize}}X% + >{\setlength{\hsize}{0.4\hsize}}X% + >{\setlength{\hsize}{1.2\hsize}}X% + >{\setlength{\hsize}{1.4\hsize}}X} + +{\bf keyword} & {\bf units} & {\bf use} & {\bf remarks} \\ \hline + +{\tt forceField} & string & Sets the force field. & Possible force fields are "DUFF", "LJ", and "EAM". \\ +{\tt ensemble} & string & Sets the ensemble. & Possible ensembles are "NVE", "NVT", "NPTi", "NPTf", and "NPTxyz".\\ +{\tt dt} & fs & Sets the time step. & Selection of {\tt dt} should be small enough to sample the fastest motion of the simulation. \\ +{\tt nComponents} & integer & Sets the number of components. & Needs to appear before the first {\tt Component} block. \\ +{\tt initialConfig} & string & Sets the file containing the initial configuration. & Can point to any file containing the configuration in the correct order. \\ +{\tt runTime} & fs & Sets the time at which the simulation should end. & This is an absolute time, and will end the simulation when the current time meets or exceeds the {\tt runTime}. \\ + + +\end{tabularx} +\end{center} +\end{table} + +\begin{table} +\caption{The Global Keywords: General Parameters} +\label{table:genParams} +\begin{center} +% Note when adding or removing columns, the \hsize numbers must add up to the total number +% of columns. +\begin{tabularx}{\linewidth}% + {>{\setlength{\hsize}{1.00\hsize}}X% + >{\setlength{\hsize}{0.4\hsize}}X% + >{\setlength{\hsize}{1.2\hsize}}X% + >{\setlength{\hsize}{1.4\hsize}}X} + +{\bf keyword} & {\bf units} & {\bf use} & {\bf remarks} \\ \hline + +{\tt finalConfig} & string & Option to set the name of the final output file. & Useful when stringing simulations together. Defaults to the {\tt .bass} file with an {\tt .eor} extension. \\ +{\tt useInitialTime} & logical & Sets whether the initial time is taken from the {\tt .init} file. & Useful when recovering a simulation from a crashed processor. Default is false. \\ +{\tt sampleTime} & fs & Sets the frequency at which the {\tt .dump} file is written. & Default sets the frequency to the {\tt runTime}. \\ +{\tt statusTime} & fs & Sets the frequency at which the {\tt .stat} file is written. & Defaults sets the frequency to the {\tt sampleTime}. \\ +{\tt LJrcut} & $\mbox{\AA}$ & Manually sets the Lennard-Jones cutoff. & Defaults to $2.5\sigma_L$, where $\sigma_L$ is the largest LJ $\sigma$ in the simulation. \\ +{\tt electrostaticCutoffRadius}& & & \\ + & $\mbox{\AA}$ & Manually sets the cutoff used by the electrostatic potentials. & Defaults to $15\mbox{\AA}$ \\ +{\tt electrostaticSkinThickness} & & & \\ + & $\mbox{\AA}$ & Manually sets the skin thickness for the electrostatic switching function. & Defaults to 5~\% of the {\tt electrostaticSkinThickness}. \\ +{\tt useReactionField} & logical & Turns the reaction field correction on/off. & Default is "false". \\ +{\tt dielectric} & unitless & Sets the dielectric constant for reaction field. & If {\tt useReactionField} is true, then {\tt dielectric} must be set. \\ +{\tt usePeriodicBoundaryConditions} & & & \\ + & logical & Turns periodic boundary conditions on/off. & Default is "true". \\ +{\tt seed } & integer & Sets the seed value for the random number generator. & The seed needs to be at least 9 digits long. The default is to take the seed from the CPU clock. + +\end{tabularx} +\end{center} +\end{table} + + + +\subsection{\label{oopseSec: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 +Scheme~\ref{sch:dumpFormat}. 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. One important note, although the +simulation propagates the complete rotation matrix, directional +entities are written out using quanternions, to save space in the +output files. + +\begin{lstlisting}[float,caption={[The format of the coordinate files]Shows the format of the coordinate files. The fist line is the number of atoms. The second line begins with the time stamp followed by the three $\mathsf{H}$ column vectors. It is important to note, that for extended system ensembles, additional information pertinent to the integrators may be stored on this line as well. The next lines are the atomic coordinates for all atoms in the system. First is the name followed by position, velocity, quanternions, and lastly, body fixed angular momentum.},label=sch:dumpFormat] + +nAtoms +time; Hxx Hyx Hzx; Hxy Hyy Hzy; Hxz Hyz Hzz; +Name1 x y z vx vy vz q0 q1 q2 q3 jx jy jz +Name2 x y z vx vy vz q0 q1 q2 q3 jx jy jz +etc... + +\end{lstlisting} + + +There are three major files used by {\sc oopse} written in the +coordinate format, they are as follows: the initialization file +(\texttt{.init}), the simulation trajectory file (\texttt{.dump}), and +the final coordinates of the simulation (\texttt{.eor}). The initialization file is +necessary for {\sc oopse} to start the simulation with the proper +coordinates, and is generated before the simulation run. 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 with the +\texttt{sampleTime} flag. The final coordinate file is the end of run file. The +\texttt{.eor} file stores the final configuration of the 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 a +simulation or recover one from a processor that has crashed during the +course of the run. + +\subsection{\label{oopseSec:initCoords}Generation of Initial Coordinates} + +As was stated in Sec.~\ref{oopseSec:coordFiles}, an initialization +file is needed to provide the starting coordinates for a +simulation. Several helper programs are provided with {\sc oopse} to illustrate possible build routes. However, as each simulation is different, system creation is left to the end user. The {\tt .init} file must list the atoms in the correct order or {\sc oopse} will give an atom mismatch error. + +The correct ordering of the atoms relies on the ordering of atoms and molecules within the model and {\sc bass} scripts. {\sc oopse} expects the order to comply with the following guidelines: +\begin{enumerate} +\item All of the molecules of the first declared component are given before proceeding to the molecules of the second component, and so on for all declared components. +\item The ordering of the atoms for each molecule follows the order declared in the molecule's declaration within the model file. +\end{enumerate} +An example is given in Scheme~\ref{sch:initEx1} resulting in the {\tt .init} file shown in Scheme~\ref{sch:initEx2}. + +\begin{lstlisting}[float,caption={This scheme illustrates the declaration of the $\text{I}_2$ molecule and the HCl molecule. The two molecules are then included into a simulation.}, label=sch:initEx1] + +molecule{ + name = "I2"; + nAtoms = 2; + atom[0]{ + type = "I"; + } + atom[1]{ + type = "I"; + } + nBonds = 1; + bond[0]{ + members( 0, 1); + } +} + +molecule{ + name = "HCl" + nAtoms = 2; + atom[0]{ + type = "H"; + } + atom[1]{ + type = "Cl"; + } + nBonds = 1; + bond[0]{ + members( 0, 1); + } +} + +nComponents = 2; +component{ + type = "HCl"; + nMol = 4; +} +component{ + type = "I2"; + nMol = 1; } + +initialConfig = "mixture.init"; + \end{lstlisting} +\begin{lstlisting}[float,caption={This is the contents of the {\tt mixture.init} file matching the declarations in Scheme~\ref{sch:initEx1}. Note that even though $\text{I}_2$ is declared before HCl, the {\tt .init} file follows the order in which the components were included.},label=sch:initEx2] + +10 +0.0; 10.0 0.0 0.0; 0.0 10.0 0.0; 0.0 0.0 10.0; +H ... +Cl ... +H ... +Cl ... +H ... +Cl ... +H ... +Cl ... +I ... +I ... + +\end{lstlisting} + + +\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 with the +\texttt{statusTime} keyword. The file allows the user to observe the +system variables as a function of 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. + + +\section{\label{oopseSec:empiricalEnergy}The Empirical Energy Functions} + +\ \subsection{\label{sec:LJPot}The Lennard Jones Force Field} The most basic force field implemented in {\sc oopse} is the @@ -280,10 +561,7 @@ range interactions from $\frac{1}{r}$ to $\frac{1}{r^3 charges. Charge-neutral distributions were replaced with dipoles, while most atoms and groups of atoms were reduced to Lennard-Jones interaction sites. This simplification cuts the length scale of long -range interactions from $\frac{1}{r}$ to $\frac{1}{r^3}$, and allows -us to avoid the computationally expensive Ewald sum. Instead, we can -use neighbor-lists and cutoff radii for the dipolar interactions, or -include a reaction field to mimic larger range interactions. +range interactions from $\frac{1}{r}$ to $\frac{1}{r^3}$, removing the need for the computationally expensive Ewald sum. Instead, we Verlet neighbor-lists and cutoff radii are used for the dipolar interactions, or a reaction field is added to mimic longer range interactions. As an example, lipid head-groups in {\sc duff} are represented as point dipole interaction sites. By placing a dipole at the head @@ -293,7 +571,7 @@ reparameterization of the soft sticky dipole (SSD) mod site is located at the pseudoatom's center of mass. The model is illustrated by the red atom in Fig.~\ref{oopseFig:lipidModel}. The water model we use to complement the dipoles of the lipids is our -reparameterization of the soft sticky dipole (SSD) model of Ichiye +reparameterization\cite{fennell04} of the soft sticky dipole (SSD) model of Ichiye \emph{et al.}\cite{liu96:new_model} \begin{figure} @@ -316,7 +594,7 @@ TraPPE also constrains all bonds to be of fixed length $\text{CH}_2$ do not change depending on what species are bonded to it. -TraPPE also constrains all bonds to be of fixed length. Typically, +TraPPE and {\sc duff} also constrain all bonds to be of fixed length. Typically, bond vibrations are the fastest motions in a molecular dynamic simulation. Small time steps between force evaluations must be used to ensure adequate energy conservation in the bond degrees of freedom. By @@ -346,7 +624,7 @@ forceField = "DUFF"; \end{lstlisting} -\subsection{\label{oopseSec:energyFunctions}{\sc duff} Energy Functions} +\subsubsection{\label{oopseSec:energyFunctions}{\sc duff} Energy Functions} The total potential energy function in {\sc duff} is \begin{equation} @@ -475,7 +753,7 @@ cutoff. The switching thickness can be set in the \tex is the taper radius some given thickness less than the electrostatic cutoff. The switching thickness can be set in the \texttt{.bass} file. -\subsection{\label{oopseSec:SSD}The {\sc duff} Water Models: SSD/E and SSD/RF} +\subsubsection{\label{oopseSec:SSD}The {\sc duff} Water Models: SSD/E and SSD/RF} In the interest of computational efficiency, the default solvent used by {\sc oopse} is the extended Soft Sticky Dipole (SSD/E) water @@ -593,12 +871,9 @@ There are Molecular Dynamics packages which have the \subsection{\label{oopseSec:eam}Embedded Atom Method} -There are Molecular Dynamics packages which have the -capacity to simulate metallic systems, including some that have -parallel computational abilities\cite{plimpton93}. Potentials that -describe bonding transition metal -systems\cite{Finnis84,Ercolessi88,Chen90,Qi99,Ercolessi02} have an -attractive interaction which models ``Embedding'' +{\sc oopse} implements a potential that +describes bonding transition metal +systems\cite{Finnis84,Ercolessi88,Chen90,Qi99,Ercolessi02} and has attractive interaction which models ``Embedding'' a positively charged metal ion in the electron density due to the free valance ``sea'' of electrons created by the surrounding atoms in the system. A mostly-repulsive pairwise part of the potential @@ -690,232 +965,9 @@ the inter-atomic forces. In this way, particles are allowed to diffuse freely in $\mathbf{r}$, but their minimum images, $\mathbf{r}^{\prime}$ are used to compute the inter-atomic forces. - - -\section{\label{oopseSec:IOfiles}Input and Output Files} - -\subsection{{\sc bass} and Model Files} - -Every {\sc oopse} simulation begins with a Bizarre Atom Simulation -Syntax ({\sc bass}) file. {\sc bass} 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 wish 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 -Scheme~\ref{sch:bassExample}. - -\begin{lstlisting}[float,caption={[An example of a complete {\sc bass} file] An example showing a complete {\sc bass} file.},label={sch:bassExample}] - -molecule{ - name = "Ar"; - nAtoms = 1; - atom[0]{ - type="Ar"; - position( 0.0, 0.0, 0.0 ); - } -} - -nComponents = 1; -component{ - type = "Ar"; - nMol = 108; -} - -initialConfig = "./argon.init"; - -forceField = "LJ"; -ensemble = "NVE"; // specify the simulation ensemble -dt = 1.0; // the time step for integration -runTime = 1e3; // the total simulation run time -sampleTime = 100; // trajectory file frequency -statusTime = 50; // statistics file frequency - -\end{lstlisting} - -Within the \texttt{.bass} file it is necessary 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 -inconvenient to duplicate the simulation at the beginning 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. Returning to the example in -Scheme~\ref{sch:bassExample}, the \texttt{.mdl} file's contents would -be Scheme~\ref{sch:mdlExample}, and the new \texttt{.bass} file would -become Scheme~\ref{sch:bassExPrime}. - -\begin{lstlisting}[float,caption={An example \texttt{.mdl} file.},label={sch:mdlExample}] - -molecule{ - name = "Ar"; - nAtoms = 1; - atom[0]{ - type="Ar"; - position( 0.0, 0.0, 0.0 ); - } -} - -\end{lstlisting} - -\begin{lstlisting}[float,caption={Revised {\sc bass} example.},label={sch:bassExPrime}] - -#include "argon.mdl" - -nComponents = 1; -component{ - type = "Ar"; - nMol = 108; -} - -initialConfig = "./argon.init"; -forceField = "LJ"; -ensemble = "NVE"; -dt = 1.0; -runTime = 1e3; -sampleTime = 100; -statusTime = 50; -\end{lstlisting} -\subsection{\label{oopseSec: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 -Scheme~\ref{sch:dumpFormat}. 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. One important note, although the -simulation propagates the complete rotation matrix, directional -entities are written out using quanternions, to save space in the -output files. - -\begin{lstlisting}[float,caption={[The format of the coordinate files]Shows the format of the coordinate files. The fist line is the number of atoms. The second line begins with the time stamp followed by the three $\mathsf{H}$ column vectors. It is important to note, that for extended system ensembles, additional information pertinent to the integrators may be stored on this line as well. The next lines are the atomic coordinates for all atoms in the system. First is the name followed by position, velocity, quanternions, and lastly, body fixed angular momentum.},label=sch:dumpFormat] - -nAtoms -time; Hxx Hyx Hzx; Hxy Hyy Hzy; Hxz Hyz Hzz; -Name1 x y z vx vy vz q0 q1 q2 q3 jx jy jz -Name2 x y z vx vy vz q0 q1 q2 q3 jx jy jz -etc... - -\end{lstlisting} - - -There are three major files used by {\sc oopse} written in the -coordinate format, they are as follows: the initialization file -(\texttt{.init}), the simulation trajectory file (\texttt{.dump}), and -the final coordinates of the simulation (\texttt{.eor}). The initialization file is -necessary for {\sc oopse} to start the simulation with the proper -coordinates, and is generated before the simulation run. 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 with the -\texttt{sampleTime} flag. The final coordinate file is the end of run file. The -\texttt{.eor} file stores the final configuration of the 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 a -simulation or recover one from a processor that has crashed during the -course of the run. - -\subsection{\label{oopseSec:initCoords}Generation of Initial Coordinates} - -As was stated in Sec.~\ref{oopseSec:coordFiles}, an initialization -file is needed to provide the starting coordinates for a -simulation. Several helper programs are provided with {\sc oopse} to illustrate possible build routes. However, as each simulation is different, system creation is left to the end user. The {\tt .init} file must list the atoms in the correct order or {\sc oopse} will give an atom mismatch error. - -The correct ordering of the atoms relies on the ordering of atoms and molecules within the model and {\sc bass} scripts. {\sc oopse} expects the order to comply with the following guidelines: -\begin{enumerate} -\item All of the molecules of the first declared component are given before proceeding to the molecules of the second component, and so on for all declared components. -\item The ordering of the atoms for each molecule follows the order declared in the molecule's declaration within the model file. -\end{enumerate} -An example is given in Scheme~\ref{sch:initEx1} resulting in the {\tt .init} file shown in Scheme~\ref{sch:initEx2}. - -\begin{lstlisting}[float,caption={This scheme illustrates the declaration of the $\text{I}_2$ molecule and the HCl molecule. The two molecules are then included into a simulation.}, label=sch:initEx1] - -molecule{ - name = "I2"; - nAtoms = 2; - atom[0]{ - type = "I"; - } - atom[1]{ - type = "I"; - } - nBonds = 1; - bond[0]{ - members( 0, 1); - } -} - -molecule{ - name = "HCl" - nAtoms = 2; - atom[0]{ - type = "H"; - } - atom[1]{ - type = "Cl"; - } - nBonds = 1; - bond[0]{ - members( 0, 1); - } -} - -nComponents = 2; -component{ - type = "HCl"; - nMol = 4; -} -component{ - type = "I2"; - nMol = 1; -} - -initialConfig = "mixture.init"; - -\end{lstlisting} - -\begin{lstlisting}[float,caption={This is the contents of the {\tt mixture.init} file matching the declarations in Scheme~\ref{sch:initEx1}. Note that even though $\text{I}_2$ is declared before HCl, the {\tt .init} file follows the order in which the components were included.},label=sch:initEx2] - -10 -0.0; 10.0 0.0 0.0; 0.0 10.0 0.0; 0.0 0.0 10.0; -H ... -Cl ... -H ... -Cl ... -H ... -Cl ... -H ... -Cl ... -I ... -I ... - -\end{lstlisting} - - -\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 with the -\texttt{statusTime} keyword. The file allows the user to observe the -system variables as a function of 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. - \section{\label{oopseSec:mechanics}Mechanics} \subsection{\label{oopseSec:integrate}Integrating the Equations of Motion: the