[ViewVC] Diff of: group/trunk/oopsePaper/oopsePaper.tex

Comparing trunk/oopsePaper/oopsePaper.tex (file contents):
Revision 1134 by mmeineke, Mon Apr 26 21:05:03 2004 UTC vs.
Revision 1155 by mmeineke, Tue May 11 19:36:28 2004 UTC

+\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}
+\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}
+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{{\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:atomsMolecules}Atoms, Molecules and Rigid Bodies}
+The basic unit of an {\sc oopse} simulation is the atom. The
+\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}).
-+
-+
+\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]
-+
-+
-+
+.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
+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]
-–
-–
-–
+.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

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing trunk/oopsePaper/oopsePaper.tex (file contents): Revision 1134 by mmeineke, Mon Apr 26 21:05:03 2004 UTC vs. Revision 1155 by mmeineke, Tue May 11 19:36:28 2004 UTC

Diff Legend

Comparing trunk/oopsePaper/oopsePaper.tex (file contents):
Revision 1134 by mmeineke, Mon Apr 26 21:05:03 2004 UTC vs.
Revision 1155 by mmeineke, Tue May 11 19:36:28 2004 UTC