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