<HTML>
<CENTER><A HREF = "https://sparta.github.io">SPARTA WWW Site</A> - <A HREF = "Manual.html">SPARTA Documentation</A> - <A HREF = "Section_commands.html#comm">SPARTA Commands</A> 
</CENTER>






<HR>

<H3>species command 
</H3>
<P><B>Syntax:</B>
</P>
<PRE>species file ID1 ID2 ... keyword value ... 
</PRE>
<UL><LI>file = filename with species info 

<LI>ID1, ID2, ... = one or more species names listed in file 

<LI>multi-species abbreviations can also be used (see below) 

<LI>zero or more keyword/value pairs may be appended 

<LI>keyword = <I>vibfile</I> 

<PRE>  <I>vibfile</I> value = vfile = filename for extra vibrational info 
</PRE>

</UL>
<P><B>Examples:</B>
</P>
<PRE>species air.species air
species ar.species Ar
species air.species air CO2 CO vibfile co2.species.vib
species myfile H+ Cl- HCl 
</PRE>
<P><B>Description:</B>
</P>
<P>Define one or more particle species to use in the simulation.  This
command can be used as many times as desired to add species to the
list of species that the simulation recognizes.
</P>
<P>The specified <I>file</I> is the name of a file containing definitions for
a list of species, not all of which need to specified in this command,
or used in a simulation.  Only those requested by ID will be extracted
from the file and they must be present in the file.  The format of the
species file is discussed below.  The data directory in the SPARTA
distribution contains several species files, all with the suffix
".species".
</P>
<P>Each <I>ID</I> is a character string used to identify the species, such as
N or O2 or NO or D or Fe-.  The string can be any combination of
alphanumeric characters or "+", "-", or underscore.
</P>
<P>Instead of specifying IDs for single species, one of several
pre-defined multi-species names can be used, each of which is expanded
into a list of several individual species IDs.  The list of currently
recognized abbreviations is as follows:
</P>
<UL><LI>air = N, O, NO 
</UL>
<P>These abbreviations can be used in combination with single-species IDs
as in the 3rd example above.
</P>
<HR>

<P>The format of a species file is as follows.  Comments or blank lines
are allowed in the file.  Comment lines start with a "#" character.
All other lines must have the following format with values separated
by whitespace:
</P>
<PRE>species-ID prop1 prop2 ... prop9 prop10 
</PRE>
<P>The species-ID is a string that will be matched against the requested
species-ID, as described above.  The properties are as follows:
</P>
<UL><LI>prop1 = molecular weight (atomic mass units, e.g. 16 for oxygen)
<LI>prop2 = molecular mass (mass units)
<LI>prop3 = rotational degrees of freedom (integer, unitless)
<LI>prop4 = inverse rotational relaxtion number (unitless)
<LI>prop5 = vibrational degrees of freedom (integer, unitless)
<LI>prop6 = inverse vibrational relaxation number (unitless)
<LI>prop7 = vibrational temperature (temperature units)
<LI>prop8 = species weight (unitless)
<LI>prop9 = multiple of electon charge (1 for a proton) 
</UL>
<P>The allowed values for rotational degrees of freedom (rotdof = prop3)
are 0,2,3.  Typically, 0 = monatomic species, 2 = diatomic, 3 =
anything else.
</P>
<P>The allowed values for vibrational degrees of freedom (vibdof = prop5)
are 0,2,4,6,8.  The associated number of vibrational modes is vibdof
divided by 2.  Typically, 0 modes = monatomic species, 1 mode =
diatomic, 2/3/4 modes = triatomic or larger molecules.
</P>
<P>Note that all the listed rotational and vibrational values must be
specified for each species, but in cases where they are not used by
SPARTA, they can simply be specified as 0.0.  Whether or not the
values are used for a species depends on the value of rotdof and
vibdof.  Whether the values are used in a simulation also depends on
the settings specified for the <I>rotation</I> and <I>vibration</I> keywords of
the <A HREF = "collide_modify.html">collide_modify</A> command.
</P>
<P>Specifically, if prop3 for rotdof = 0, then prop4 is ignored.  If
prop5 for vibdof = 0, then prop6 and prop7 are ignored.
</P>
<P>If vibdof = 4,6,8, then information for 2,3,4 vibrational modes can be
specified for the species in a separate file using the optional
<I>vibfile</I> keyword, as discussed below.  If the <A HREF = "collide_modify.html">collide_modify
vibration</A> command is used with a setting of
<I>discrete</I>, then this vibrational mode info must be specified for each
species with a vibdof = 4,6,8.  Note that the <A HREF = "fix_vibmode.html">fix
vibmode</A> command must also be used to allocate
per-particle storage for these additional modes.
</P>
<P>NOTE: By default the maximum allowed number of vibrational modes is 4
(dof = 8). If you have a model with species which need more, you can
change the settings at the top of src/particle.h in the enum command
for MAXVIBMODE=4 to a larger value and re-compile the code.  The
format of the <I>vibfile</I>, as described next, is then enhanced
accordingly.
</P>
<HR>

<P>The optional <I>vibfile</I> keyword can be used to specify additional
vibrational information in the specified <I>vfile</I>.  If this option is
used, then an entry must appear in <I>vfile</I> for every species in this
command with a vibdof value = 4,6,8.  Note that even if this
vibrational info is read, it is ignored by SPARTA unless the
<A HREF = "collide_modify.html">collide_modify vibrate</A> setting is specified as
<I>discrete</I>.
</P>
<P>The format of a species vibrational file is as follows.  See
data/co2.species.vib for an example. Comments or blank lines are
allowed in the file.  Comment lines start with a "#" character.  All
other lines must have the following format with values separated by
whitespace:
</P>
<PRE>species-ID N temp1 relax1 degen1 temp2 relax2 degen2 ... tempN relaxN degenN 
</PRE>
<P>The species-ID is a string that will be matched against the requested
species-ID, as described above.  N is the number of vibrational modes
that follow, which must be either 2,3,4, and must match the
corresponding vibdof value = 4,6,8 (divided by two) used in the
species file.
</P>
<P>For each of the N modes, 3 values are listed:
</P>
<UL><LI>tempI = vibrational temperature of mode I (temperature units)
<LI>relaxI = inverse vibrational relaxation number of mode I (unitless)
<LI>degenI = degeneracy of mode I (integer, unitless) 
</UL>
<P>These quantities are used during collisions if vibrational energy is
modeled in discrete levels.
</P>
<P>Note that the values for temp1 and relax1 override the same values
defined in the species file (prop7 and prop6) when they are listed for
the same species in the <I>vibfile</I>.
</P>
<HR>

<P><B>Restrictions:</B> none
</P>
<P><B>Related commands:</B> none
</P>
<P><B>Default:</B> none
</P>
</HTML>
