\section{Specifying the particle set}
\label{sec:particleset}
The \texttt{particleset} blocks specify the particles in the QMC simulations: their types, attributes (mass, charge, valence), and positions.
\subsection{Input specification}
\begin{table}[h]
\begin{center}
\begin{tabularx}{\textwidth}{l l l l l l }
\hline
\multicolumn{6}{l}{\texttt{particleset} element} \\
\hline
\multicolumn{2}{l}{parent elements:} & \multicolumn{4}{l}{\texttt{simulation}}\\
\multicolumn{2}{l}{child elements:} & \multicolumn{4}{l}{\texttt{group, attrib}}\\
\multicolumn{2}{l}{attribute :} & \multicolumn{4}{l}{}\\
& \bfseries name & \bfseries datatype & \bfseries values & \bfseries default & \bfseries description \\
& \texttt{name}/\texttt{id} & text & \textit{any} & e & Name of particle set \\
& \texttt{size}$^o$ & integer & \textit{any} & 0 & Number of particles in set \\
& \texttt{random}$^o$ & text & yes/no & no & Randomize starting positions \\
& \texttt{randomsrc}/ & text & \texttt{particleset.name} & \textit{none} & Particle set to randomize \\
& \texttt{random\_source}$^o$ & & & & \\
% & \texttt{role} & text & MC/none & none & (obsolete) \\
\hline
\end{tabularx}
\end{center}
\end{table}
\begin{table}[h]
\begin{center}
\begin{tabularx}{\textwidth}{l l l l l l }
\hline
\multicolumn{6}{l}{\texttt{group} element} \\
\hline
\multicolumn{2}{l}{parent elements:} & \multicolumn{4}{l}{\texttt{particleset}}\\
\multicolumn{2}{l}{child elements:} & \multicolumn{4}{l}{\texttt{parameter, attrib}}\\
\multicolumn{2}{l}{attribute :} & \multicolumn{4}{l}{}\\
& \bfseries name & \bfseries datatype & \bfseries values & \bfseries default & \bfseries description \\
& \texttt{name} & text & \textit{any} & e & Name of particle set \\
& \texttt{size}$^o$ & integer & \textit{any} & 0 & Number of particles in set \\
& \texttt{mass}$^o$ & real & \textit{any} & 1 & Mass of particles in set \\
& \texttt{unit}$^o$ & text & au/amu & au & Units for mass of particles \\
\multicolumn{2}{l}{parameters} & \multicolumn{4}{l}{}\\
& \bfseries name & \bfseries datatype & \bfseries values & \bfseries default & \bfseries description \\
& \texttt{charge} & real & \textit{any} & 0 & Charge of particles in set \\
& \texttt{valence} & real & \textit{any} & 0 & Valence charge of particles in set \\
& \texttt{atomicnumber} & integer & \textit{any} & 0 & Atomic number of particles in set \\
\hline
\hline
\end{tabularx}
\end{center}
\end{table}
\begin{table}[h]
\begin{center}
\begin{tabularx}{\textwidth}{l l l l l l }
\hline
\multicolumn{6}{l}{\texttt{attrib} element} \\
\hline
\multicolumn{2}{l}{parent elements:} & \multicolumn{4}{l}{\texttt{particleset,group}}\\
\multicolumn{2}{l}{attribute :} & \multicolumn{4}{l}{}\\
& \bfseries name & \bfseries datatype & \bfseries values & \bfseries default & \bfseries description \\
& \texttt{name} & string & \textit{any} & \textit{none} & Name of attrib \\
& \texttt{datatype} & string & intArray, realArray, & \textit{none} & Type of data in attrib \\
& & & posArray, stringArray & & \\
& \texttt{size}$^o$ & string & \textit{any} & \textit{none} & Size of data in attrib \\
\hline
\hline
\end{tabularx}
\end{center}
\end{table}
\subsection{Detailed attribute description}
\subsubsection{particleset required attributes}
\begin{itemize}
\item \texttt{name}/\texttt{id} \\
Unique name for the particle set. Default is ``e" for electrons. ``i" or ``ion0" is typically used for ions.
\end{itemize}
% Line 192 in ParticleIO/XMLParticleIO.cpp
% Lines 144-145 in QMCApp/ParticleSetPool.cpp
\subsubsection{particleset optional attributes}
\begin{itemize}
\item \texttt{size} \\
Number of particles in set
\end{itemize}
% Line 191 in ParticleIO/XMLParticleIO.cpp
%\begin{itemize}
%\item \texttt{role} \\
%What the particles do in the simulation
%\end{itemize}
% Line 146 in QMCApp/ParticleSetPool.cpp
\begin{itemize}
\item \texttt{random} \\
Randomize starting positions of particles. Each component of each particle's position is randomized independently in the range of the simulation cell in that component's direction.
\end{itemize}
% Line 190 in ParticleIO/XMLParticleIO.cpp
% Line 147 in QMCApp/ParticleSetPool.cpp
\begin{itemize}
\item \texttt{randomsrc}/\texttt{random\_source} \\
Specify source particle set around which to randomize the initial positions of this particle set.
\end{itemize}
% Lines 148-149 in QMCApp/ParticleSetPool.cpp
\subsubsection{name required attributes}
\begin{itemize}
\item \texttt{name}/\texttt{id} \\
Unique name for the particle set group. Typically, element symbols are used for ions and ``u" or ``d" for spin-up and spin-down electron groups, respectively.
\end{itemize}
% Line 192 in ParticleIO/XMLParticleIO.cpp
% Lines 144-145 in QMCApp/ParticleSetPool.cpp
\subsubsection{group optional attributes}
\begin{itemize}
\item \texttt{mass} \\
Mass of particles in set.
\end{itemize}
% Line 190 in Particle/ParticleSet.cpp
\begin{itemize}
\item \texttt{unit} \\
Units for mass of particles in set (au[$m_e$ = 1] or amu[$\frac{1}{12}m_{\rm ^{12}C}$ = 1]).
\end{itemize}
% Line 66 in ParticleIO/XMLParticleIO.cpp
%condition appears to be future functionality for different unit types on the position array
%condition must be an integer
% Line 407 in ParticleIO/XMLParticleIO.cpp (reads condition in)
% Line 402 in ParticleIO/XMLParticleIO.cpp (declares utype integer)
\subsection{Example use cases}
\begin{minipage}{\linewidth}
\begin{lstlisting}[caption=particleset elements for ions and electrons randomizing electron start positions.]
3.000000
3.000000
3.000000
1.000000
1.000000
1.000000
0.0 0.0 0.0
0.5 0.5 0.5
Li H
-1
-1
\end{lstlisting}
\end{minipage}
\begin{minipage}{\linewidth}
\begin{lstlisting}[caption=particleset elements for ions and electrons specifying electron start positions]
-1
2.9151687332e-01 -6.5123272502e-01 -1.2188463918e-01
5.8423636048e-01 4.2730406357e-01 -4.5964306231e-03
3.5228575807e-01 -3.5027014639e-01 5.2644808295e-01
-5.1686250912e-01 -1.6648002292e+00 6.5837023441e-01
-1
3.1443445436e-01 6.5068682609e-01 -4.0983449009e-02
-3.8686061749e-01 -9.3744432997e-02 -6.0456005388e-01
2.4978241724e-02 -3.2862514649e-02 -7.2266047173e-01
-4.0352404772e-01 1.1927734805e+00 5.5610824921e-01
6
4
8
1
1
1
0.0000000000e+00 0.0000000000e+00 0.0000000000e+00
0.0000000000e+00 -1.4308249289e+00 1.1078707576e+00
0.0000000000e+00 1.4308249289e+00 1.1078707576e+00
O H H
\end{lstlisting}
\end{minipage}
\begin{minipage}{\linewidth}
\begin{lstlisting}[caption=particleset elements for ions specifying positions by ion type]
6
4
8
0.0000000000e+00 0.0000000000e+00 0.0000000000e+00
1
1
1
0.0000000000e+00 -1.4308249289e+00 1.1078707576e+00
0.0000000000e+00 1.4308249289e+00 1.1078707576e+00
\end{lstlisting}
\end{minipage}