31 August 1997
14 January 1998
SMC, v 2.5, (c) G.J. Parker, 1996-8
USER MANUAL
this document gives a rather brief overview on how to run the
Simple Monte Carlo (SMC) program. documentation on every variable which can
be set can be found in the accompanying REFERENCE MANUAL.
program control is determined by the variables which are set in the
files "structure.in" and "mc.in". both of which must reside in the directory
from which the program is executed.
In general, "structure.in" defines the problem while "mc.in" controls the
execution of the MC routines. accordingly, we will first talk about "structure.in"
and it's associated data files in section A. section B describes "mc.in" and
it's variables and data files. finally, section C has some frequently asked
questions (FAQs).
A) structure.in
the purpose of this data file is to define the physical problem to be solved.
1) simulation region definition
a) geometry: lcyl_mc, xsym_p
the SMC supports two geometries: Cartesian and cylindrical either in 1-D
or 2-D. if the geometry is cylindrical, then lcyl_mc should be set to true,
otherwise it is set to false for Cartesian geometry. if the geometry is
Cartesian, then any variable which refers to radius (e.g. r_max_mc) actually
refers to the 'x' coordinate. furthermore if xysm_p is true then there
exists a plane of symmetry at x=0. otherwise x=0 is an absorbing wall.
b) dimensions: nr_mc, nz_mc, r_max_mc (cm), z_max_mc (cm)
the number of spatial dimensions is determined by nr_mc and nz_mc which tell
the number of cells in the r (or x in Cartesian) and z direction, respectively.
if both are equal to 1, then the simulation is 0-D (no spatial dependence) and
the geometry resorts to Cartesian. if only one is set equal to 1, then the
simulation is 1-D in the other dimension. if both are set to values greater
then the simulation is 2-D. z_max_mc (r_max_mc) is the maximum z (r or x)
value. the mesh runs from 0 to z_max_mc (r_max_mc). if the corresponding
number of cells is one, the value is irrelevant but must be positive. the
mesh is uniformly spaced in each direction.
c) structure: maskfile
the structures inside of the simulation region (walls and such) are specified
by the data file maskfile. if maskfile doesn't exist, the code will assume that
the entire simulation region has no walls except around the simulation region.
if cylindrical geometry or Cartesian w./ xsym_p being true, then r (x) = 0
is an axis (plane) of symmetry. otherwise x=0 is also an absorbing wall. if
maskfile does exist then the computational mesh is represented by a matrix
of integers. '0' is an vacuum (or plasma) cell and any other integer represents
an absorbing surface. the data file is scanned until a new line with at least
four (4) '>' occurs. then the mask data structure is read. the highest z cells
are read starting the lowest r (x) cell to the largest r (x) cell. then the next lowest
z row is read until all of the cells in the simulation region have been read.
2) physical parameters
a) particle densities: nspec_mc, specn_mc, denfile
one or more non-electron species must exist in the simulation region. nspec_mc
is the number of such species. for each nspec_mc, specn_mc(...) is the name
of each species which will be used in various output files and used to find
the corresponding cross section in the mc.in data files (see below). denfile
is a data file which contains the number density (cm^3) profile for each nspec_mc
species. each species must exist in this data file. each entry is started when
at least four (4) '>' is found on a new line. the next line contains the name
which matches one of the specn_mc(...) names (spaces and capitalization are
ignored when making the match). then the density profile is represented by a
matrix of real numbers of size nr_max_mc by nz_max_mc. the first line starts
at the largest z value and runs from the smallest r (x) to the largest r (x)
cell. this is repeated for the next largest z value until all of the cells are
read. neutral densities must be defined even for non-'0' cells as defined in
the maskfile data structure. the actual value irrelevant though should not be
a maximum value.
b) static fields: e_n_0d (Td), phifile (V), read_e_p, erxfile (V/cm), ezfile (V/cm),
bplrxfile (gauss), bplthyfile (gauss), bplzfile (gauss)
for 0-D simulations, the reduced field E/N (E is the electric field, N is
the total neutral density) (Td) is set by e_n_0d. otherwise e_n_0d is ignored.
the electrostatic potential spatial profile is specified in data file phifile. the
potential is defined at cell centers. after a new line which starts w/ at least
four (4) '>', the potential is defined by a matrix of real numbers of size
nr_max_mc+2 by nz_max_mc+2. the extra cells represent the 'ghost cells' on each
end of each direction. the first line is for the maximum z cell starting at the
ghost cell less than the r (x) = 0 running through the maximum r (x) cell plus one
cell for the ghost cell. this is repeated for each z cell in descending order.
the electric fields are then computed from the electrostatic potential by simple
numerical derivatives. in the SMC, the electric fields are assumed to vary linearly
between these points.
alternatively, if read_e_p is true and either or both of the data files erxfile and
ezfile exists, then the electric fields (Er/Ex and Ez, respectively) are read in
instead of being computed. in these data files, the electric fields are defined to be
at corners of the computational cells and therefore are defined by a real matrix
of size nr_max_mc+1 by nz_max_mc+1. after a new line which begins with at least four
(4) '>' starting at z = zmax_mc, and reading the electric field at r (x) = 0 through
to r (x) = r_max_mc. the next z row is then read until all of the cell corners are
assigned a value.
static magnetic fields can also be specified. each three components of the fields are
specified in their respective files: r (x) in bplrxfile, theta (y) in bplthyfile and
z in bplzfile. in these data files, the magnetic fields (in gauss) are defined to be
at corners of the computational cells and therefore are defined by a real matrix
of size nr_max_mc+1 by nz_max_mc+1. after a new line which begins with at least four
(4) '>' starting at z = zmax_mc, and reading the magnetic field at r (x) = 0 through
to r (x) = r_max_mc. the next z row is then read until all of the cell corners are
assigned a value. if any file does not exit, the corresponding field is zero. for the
magnetic fields to be implemented, b_fieldsp (in mc.in, see below) must also be true.
c) wall boundary conditions: sheathfile
if the confining potential for electrons is sharply varying across one cell, then
the particle integration may not be very accurate. in this case instead of trying
to include a rapidly varying electric field, one can specify a instantaneous change
in potential at the boundary between a vacuum/plasma cell and an absorbing surface.
this is done by using the sheathfile and sheath_potential0 in mc.in. if this is used,
then the electrostatic potential (phifile) and electric fields (erxfile, ezfile) should
NOT include this instantaneous jump in potential, otherwise it will be over counting the
electric field. a sheath can ONLY exist at a boundary between a plasma/vacuum cell
and a non-plasma/vacuum cell, which may be a ghost cell. if sheathfile exists then it's
a real matrix of size nr_max+k by nz_max+2, where k = 1 if cylindrical geometry or
Cartesian but with xsym_p being true (ie x=0 is a plane of symmetry). the file is
scanned until a new line beginning with at least four (4) '>' is found. then starting
in the largest z ghost cell, the required jump in potential (positive number represent
a energetic barrier, non-positive values are not barriers and will allow particles
flow out if they reach the boundary). only non-zero values are allowed in cells which
have a mask value other than '0' (ghost cells, by definition have non-'0' mask values).
for example, say nr_max_mc = 5, nz_max_mc = 4, lcyl_mc = true, then
>>>>
0. 0. 0. 0. 0. 1.
0. 0. 0. 0. 0. 1.
0. 0. 0. 0. 0. 1.
0. 0. 0. 0. 0. 1.
0. 0. 0. 0. 0. 1.
0. 0. 0. 0. 0. 1.
would allow electrons to flow freely out of simulation region in the axial direction,
but to leave in the radial direction, they would have to have 1eV directed in the
radial direction to overcome the "sheath potential". this is in addition it any field
that may have been opposing the electron motion through the last radial cell up to the
outer boundary.
WARNING: if in mc.in sheath_potential0 is positive, then the values read in from
the sheathfile will be MULTIPLIED by sheath_potential0. so, if sheath_potential0 is
12, then instead of 1eV of directed energy in the previous example, the electrons
would need 12eV to escape to the boundary! if sheath_potential0 is non-positive,
then all values will be zeroed!
d) initial conditions: te0 (eV), uniform_s_p, elaunchfile (#)
one needs to specify how the electrons should be initially launched. electrons
can be launched either in the volume or from surface cells or from both. if elaunch file
doesn't exist or uniform_s_p is true, then electrons are launched uniformly in the
volume of the discharge. te0 is the 'characteristic energy' these electrons have when
they are launched. either they will have precisely the energy of te0 or they will
be launched with a Maxwellian distribution at temperature te0. this is decided by
the ext_max_p variable in mc.in.
if uniform_s_p is false and elaunchfile exists, then the launching profile is determined
by a real matrix of size nr_max+k by nz_max+2, where k = 1 if cylindrical geometry or
Cartesian but with xsym_p being true (ie x=0 is a plane of symmetry). only those
cells which are in the volume or those which border volume cells can have non-zero
numbers. the number represents the actual number of electrons which should be launched
in or from that cell. the actual number of electrons which will be followed is determined
by n_traj variable found in mc.in, so these numbers are scaled so that the total number
comes out approximately correct.
e) harmonic fields: rf_freq_mc, eh_rxfile, eh_thyfile, eh_zfile, bh_rxfile, bh_thyfile, bh_zfile
in addition to static fields, harmonic fields can also be specified. harmonic fields are
defined by a complex amplitude, A, so that the instantaneous fields are given by
real( A * exp( -i * 2 * pi * rf_freq_mc)), where rf_freq_mc is the frequency (Hz) of the
harmonic. the three components of the electric fields are given in separate files: r (x)
in eh_rxfile (V/cm), theta (y) in eh_thyfile (V/cm) and z in eh_zfile. the three components of
the magnetic fields are given in separate files: r (x) in bh_rxfile (gauss), theta (y) in
eh_thyfile (gauss) and z in eh_zfile (gauss). all of these field amplitudes must be complex
numbers. if any file does not exit, correspond field is zero. for each file, the fields are
defined to be at corners of the computational cells and therefore are defined by a complex
matrix of size nr_max_mc+1 by nz_max_mc+1. after a new line which begins with at least four
(4) '>' starting at z = zmax_mc, and reading the magnetic field at r (x) = 0 through
to r (x) = r_max_mc. the next z row is then read until all of the cell corners are
assigned a value. if any file does not exit, the corresponding field is zero. for the
harmonic fields to be implemented, harmonic_p (in mc.in, see below) must also be true.
furthermore, for the magnetic fields to be implemented, b_fieldsp (in mc.in, see below)
must also be true.
B) mc.in
the purpose of this data file is to control the execution of the SMC routine.
1) input/output
a) electron collisions: q_tot_data, q_dcs_data (input)
these two strings define file names which contain data which describe electron
collisions with every nspec species defined in structure.in. in fact, each species
defined MUST appear in q_tot_data. q_tot_data contains the total cross sections for
electron-neutral collisions and require the same format as an ELENDIF (tm) cross
section file. detail can be found in the REFERENCE MANUAL. for every collision defined
in q_tot_data, there can be an entry in the q_dcs_data file. this file specifies the
angular distribution of the scattered electron (d sigma / d omega). if a collision
is NOT defined in this file but is defined in q_tot_data, then the electron is assumed
to scatter isotropically. q_dcs_data is optional.
b) output files: run_label, dumpfile_p
run_label contains a string which the output data files will be called. typically
three output data files will be created. these files are:
run_label//'.0': normalized eedf (eV**-1.5) at user specified (see nfe below) positions
run_label//'.1': histogram of #/energy bin for each type of mask value
run_label//'.7': general information on how the SMC was run and some parameters
if dumpfile_p is true, then a series of auxiliary output files will be created:
v_sigma.k: average collision rate (cm**3/s) as a function of (r, z, collision)
den.k: non-electron particle densities (1/cm^3) as a function of (r,z)
gpt.k: density of electrons (arb/cm^3) as a function of (r, z)
tt.k: total time electrons spent (sec) as a function of (r,z) (prop. to # of electrons)
vr.k: average radial velocity (cm/s) if lcyl_p is true as functions of(r,z)
vth.k: average azimuthal velocity (cm/s) if lcyl_p is true as functions of(r,z)
vx.k: average x velocity (cm/s) if lcyl_p is false as functions of(r,z)
vy.k: average y velocity (cm/s) if lcyl_p is false as functions of(r,z)
vz.k: average axial velocity (cm/s) as functions of(r,z)
ingold.k: numerous 0d transport coefficients. if not a 0d run, averaged eedf is used.
shp.k: sheath potential (v) as a function of (r,z)
loss.k: count of where electrons trajectories ended as function of (r,z)
gain.k: count of where electrons are created - lost as function of (r,z)
mask.k: mask structure matrix used in simulation.
energy.k: average electron energy (eV) as function of (r,z)
ez.k: static axial electric field (v/cm) as function of (r,z) [no file => zero field]
er.k: static radial electric field (v/cm) if lcyl_p is true as function of (r,z) [no file => zero field]
ex.k: static x electric field (v/cm) if lcyl_p is false as function of (r,z) [no file => zero field]
bz.k: static axial magnetic field (gauss) as function of (r,z) [no file => zero field]
br.k: static radial magnetic field (gauss) if lcyl_p is true as function of (r,z) [no file => zero field]
bx.k: static x magnetic field (gauss) if lcyl_p is false as function of (r,z) [no file => zero field]
ez.k: harmonic axial electric field (v/cm) as function of (r,z) [no file => zero field]
er.k: harmonic radial electric field (v/cm) if lcyl_p is true as function of (r,z) [no file => zero field]
ex.k: harmonic x electric field (v/cm) if lcyl_p is false as function of (r,z) [no file => zero field]
bz.k: harmonic axial magnetic field (gauss) as function of (r,z) [no file => zero field]
br.k: harmonic radial magnetic field (gauss) if lcyl_p is true as function of (r,z) [no file => zero field]
bx.k: harmonic x magnetic field (gauss) if lcyl_p is false as function of (r,z) [no file => zero field]
phi.k: electrostatic potential (V) as function of (r,z)
c) user specified eedf output: nfe, zfe(...), rfe(...), full_eedf_p, nmu_mc, nphi_mc
the SMC automatically produces the spatially averaged eedf and is in run_label//'.7'.
it also produces an energy resolved integrated eedf (# vs energy) for each mask value
and is in run_label//'.1'. to get specific eedf at a certain spatial cell setting this
variables will allow this. first if nfe is set to a negative value, then the eedf
as a function of space and kinetic energy will be outputted to run_label//'.0' for every
spatial cell. the other parameters are ignored. otherwise, nfe should be set to the
number of spatial locations where the eedf is requested. then zfe(1...nfe) and
rfe(1...nfe) (cm) should be set to the spatial location where the eedf should be sampled.
if full_eedf_p is false, then the eedf will be a function of energy and space (the
velocity angles are effectively averaged over). otherwise the eedf will be a function
of energy, space, and spherical angles, phi (azimuthal angle) and mu = cos(theta)
(cosine of the polar angle). nmu_mc and nphi_mc tells the number of uniformly spaced
bins for mu and phi, respectively. data structures may not be defined large enough to
accommodate many full eedfs. in this case, the SMC will reduce num_mc and nphi_mc and
output a warning.
2) run parameters
a) energy scale: ee_max, sheath_potential0
ee_max (eV) is the maximum kinetic energy which eedf will be tracked. electrons are
allowed to have higher energies, but they will not contribute to the eedf.
sheath_potential0 (V) multiplies the matrix defined by the sheathfile. if non-positive,
then sheathfile is overwritten with entire zeros. otherwise values are multiplied by
sheath_potential0.
b) simulation time: t_min, t_max, t_min_region(0), m_ave_time
these parameters determine how long electrons are simulated for and when statistics
will be recorded. if t_max (s) is positive, then it's the maximum time that electrons
will be followed. if it's negative, then it's set equal to the minimum collision time
times m_ave_time and t_min is scaled so that the ratio of |t_min/t_max| stays the
same. t_min is the time statistics will start to be recorded after launching an
electron. until this time, no progeny electrons will be followed either. if
t_min_region(0) is set to a positive value, then it overrides what t_min is.
c) n_traj, push_order, del_xt, del_bf, ext_max_p, random_seed
n_traj is the number, approximately, of the actual simulated electrons to be followed.
this does NOT include prodigy electrons! push_order (either 2 or 4) tells which order
Runge-Kutta integrator to use (second or fourth). 2 is usually faster and fine if field
profiles are not too steep. del_xt is the maximum fraction of a computational cell to
cross (irrelevant in 0d!). should be 1 or less. if magnetic fields are present, del_bf
is the maximum fraction of the local gyroperiod that the time step is allowed to be.
ext_max_p is false, then electrons launched in volume cells are isotropic in velocity
angles and at an energy given by 3*te0/2. otherwise they are isotropic in velocity but
from a Maxwellian distribution at temperature te0. random_seed is the seed value of the
random number generator. different values of this integer will generate a different
quasi-random number sequence. constant values across runs will generate the same sequence.
d) ionization: secondary_p, ion_equal_e_p, accum_t_p
these two parameters control ionization events. if secondary_p is false, then progeny
electrons are NOT followed and ion_equal_e_p is ignored. otherwise they are. if
ion_equal_e_p is .true. then the energy is shared equally between the two electrons.
if false and the species names are NOT Ne, Xe, He, or Ar, then energy is shared
uniformly between them. otherwise the energy is shared according to an semi-analytic
expression for the specific species. setting accum_t_p to false means that progeny
electron's simulation time is reset to zero and then are followed for the full required
time (see b above). if true, the progeny electron inherits it's parents elapsed simulation
time.
e) field parameters: harmonic_p, b_fieldsp
if harmonic fields have been specified, they will only be used if harmonic_p is true.
setting harmonic_p to be true when all harmonic field profiles are zero will dramatically
increase run time. if magnetic fields are present (either static or harmonic), they will
only be used if b_fieldsp is true. setting b_fieldsp to be true when all magnetic field
profiles are zero will dramatically increase run time.
3) not used parameters
a) e_min, min_energy, spec_t, spec_tm, spec_tq, fe_last_p, trapped_p, see_p_mc
these parameters are not used in the SMC and should be set to the following values.
failure to do so may result in incorrect/unpredictable execution:
e_min = not used in SMC [eV]
harmonic_p = must be false for SMC [boolean]
b_fieldsp = must be false for SMC [boolean]
min_energy = not used in SMC [eV]
spec_t = must be 0 for SMC [real]
spec_tm = not used in SMC [real]
spec_tq = not used in SMC [real]
fe_last_p = must be false for SMC [boolean]
trapped_p = must be false for SMC [boolean]
see_p_mc = must be false for SMC [boolean]
C) FAQ
1) how do i do 0-D simulations?
in structure.in set nr_max_mc = 1, nz_max_mc = 1, denfile to the data file
which holds the neutral density(ies) and e_n_0d to the value of E/N (Td)
which is wanted. r_max_mc and z_max_mc can be set to any positive value.
the rest of the variables in structure.in are ignored. no specific in mc.in are
necessary. however, if secondary electrons are followed (secondary_p = .true.)
then the code may have a difficult time stopping. in this case make sure accum_t_p
is also set equal to true.
2) can i use ELENDIF(tm) cross section files?
yes. the electron cross section files are specified by the ELENDIF(tm) cross section
file data structures. see the REFERENCE MANUAL for the requirements of cross section
files for SMC.
3) how do i launch electrons uniformly at one axial cell in cylindrical geometry?
in structure.in, set uniform_s_p to false and make a datafile with the name specified
by elaunchfile. since the numbers in this data file represents the number (#) of
electrons to be launched and the volume of the radial cells increase w/ radius, the
numbers must also increase in radius so that the density (# / volume) is constant.
for example, nr_max_mc = 5, nz_max_mc = 4, and you're launching electrons at the
first z volume cell, then elaunchfile would look like this:
>>>>
0. 0. 0. 0. 0. 0.
0. 0. 0. 0. 0. 0.
0. 0. 0. 0. 0. 0.
0. 0. 0. 0. 0. 0.
1. 3. 5. 7. 9. 0.
0. 0. 0. 0. 0. 0.
4) when i have magnetic fields the results depend on the value of del_bf i use. what's up?
when magnetic fields are present, a fourth order Runge-Kutta should be used (push_order = 4)
though this may not be enough by itself. decreasing del_bf until the results don't
change will eventually give accurate results. it's not uncommon in fusion research, for
instance, to use 8th or higher order integrators.
EOF