SAFARI Sample Input Files

These files are generally whitespace separated. The location and name of these files is specified via the -i argument, or is specified on the first line of a file safari.input in the run directory.

Main Input File

The fields in the input file are whitespace separated, with the input lines being read in a specific order. Lines beginning with a #, or entirely consisting of whitespace are ignored for the purposes of the indexed order while reading.

Boolean values are specified via t for true, and anything else for false, usually a f is used in this case. Floating point values use atof, so any input valid for that format is accepted. Integer values use atoi.

Commented Input File

Here is a sample input file for SAFARI, it is an extended one including comments.

  1# This is a sample input file for Sea-Safari.
  2# Lines starting with # are comment lines, otherwise
  3# All lines must follow the order found here,
  4# blank lines are ignored also.
  5# 
  6# For boolean flags:
  7#   t : true
  8#   f : false (or anything not t)
  9
 10# Units used:
 11#
 12# Distances are in Angstroms, unless specified otherwise.
 13# Masses are in AMU
 14# Energies are in eV
 15# Angles are in Degrees
 16# Times are in Angstrom * sqrt(AMU / eV)
 17
 18# Beam Parameters:
 19# E0, Theta0, Phi0, atomic mass, atomic symbol
 20#
 21250.0 45.0 0.00 22.989 Na
 22
 23# Most of these are currently unused at present
 24# EMIN,EMAX,ERES,ARES
 25#
 26# EMIN - anything below this will not count as a hit in the detector
 27# ERES - if not 0, will "thermalize" the ion as well (not currently implememnted)
 28# EMAX - unused
 29# ARES - unused
 30#
 310.5 250 2.5 0.5
 32
 33# Detector Type and optional cull flag
 34#  <type> <cull flag|optional>
 35#
 36#   If <type> is not 0, then only trajectories within phi of 10
 37#   if PHI0 will be added to the data file, this trims out
 38#   the trajectories which are out of bounds of the detector.
 39#
 40#   if <cull flag> is f, then trajectories which fail will not
 41#   be included in the data file, they will only be included
 42#   in the final error counts in the debug output file.
 43#
 441 f
 45
 46# Detector parameters, the number of these depends on Detector Type
 47#
 48# Currently, only 1 detector is implemented, it takes the arugments 
 49# in the following order:
 50#
 51# Detector Theta, Theta size, Phi size
 52#
 5345.0 45.0 10.0
 54
 55# Integration Parameters
 56# time steps
 57#
 581e-08 10.0
 59#
 60# Error parameters
 61#
 620.3 0.0 1e-06
 63
 64# max number of atoms to interact with
 65#
 6612
 67
 68# this one should always be true.
 69# This is whether the surface recoils on impact.
 70#
 71t
 72
 73#Initial Z for the ions, this is also when it leaves
 74#
 755.0
 76
 77# Number of allowed integration steps before failing.
 78#
 794000
 80
 81# These are search related, max distances and table steps
 82#
 83# for r:
 84#
 8510.0 0.002
 86#
 87# for z: (not yet implemented)
 88#
 890.0 0.0003
 90
 91# These are more search and failure conditions.
 92# max distance to search, threshold for failing due to energy change
 93# Max distance is in "cells", each of which is roughly 5 angstroms across
 94#
 95# The energy change error for each hit is listed in the data file, this
 96# can be used to determine a good value for this second parameter
 97#
 982 5
 99
100# This is how many runs to do for Montecarlo or Chainscat modes.
101# If this is 1, it will run a single shot run at x:min y:min.
102#
103# In adaptive grid mode, this number is how many thermal iterations
104# are run, this is only applied if the temperature is not 0
105#
106100000
107
108# Range of the crystal to scatter off
109# Montecarlo mode ignores the step, and chainscat
110# will run from xmin, ymin to xmax, ymax, with the above
111# number of trajectories.
112#
113# Any values after this, will be applied as a mask for the surface
114# These values should be the coordinates of the corners of a polygon
115# In a closed order for that polygon.
116#
117# x:(min, step, max) (Optional polygon)
118#
1190 0.1 4.0786
120# y:(min, step, max) (Optional polygon)
121#
1220 0.1 4.0786
123
124# These flags control the mode of operation (unless single shot mode)
125# SCAT_FLAG of 666 means we are doing normal scattering, anything else
126# is a debug flag for running tests.
127#
128# SCAT_FLAG values:
129#   555 - Run performance test on cached values vs computed ones
130#   666 - Run normal scattering routine, defined by SCAT_TYPE/number
131#   777 - Run tests of lattice copying speeds.
132#   888 - Run tests of reliablity of RNG
133#   999 - Test whether the space mask is working correctly.
134#
135# SCAT_TYPE values:
136#   666 - Montecarlo - N Random shots in the range
137#   777 - Grid Scat - Shots in a grid, with the given steps
138#   888 - Chainscat - N shots in a line from min to max
139#  <100 - Adaptive Grid, with this value being the max depth
140
141# SCAT_FLAG, SCAT_TYPE
142#
143666 666
144
145# These are the number of unit cells to generate for the crystal.
146# These are also used to cull trajectories which leave the crystal
147# The bounds of the crystal are these values multiplied by AX and AY
148#
149# RAX, RAY
150#
1515.0 5.0
152
153# These parameters are for the radial ion-atom potentials
154# The first number is how many parameters there are,
155# The second is the type of potential, currently only 1 is implemented.
156#
157#   1 - double exponential function - has 4 parameters per lattice atom type.
158#       this is of form: a * exp(-b * r) + c * exp(-d * r)
159#       where a, b, c, d are the 4 parameters per lattice atom
160#
161#   [a] = eV
162#   [b] = 1/Angstrom
163#   [c] = eV
164#   [d] = 1/Angstrom
165#
166# The third parameter is the type of inter-lattice forces to use
167#
168#   0 - default if not present, use einstien springs
169#   1 - Use springs between nearest neighbours
170#   2 - Use lennard Jones, in this case, 
171#       needs additional parameters after
172#       the 4 parameters below
173#
1744 1 0
175
176# The parameters for the potentials
177#
178# If the interlattice force option is 2, there then needed
179# to be additional lennard jones parameters added after these
180#
1814153.6 3.625 27017.57 7.286
182
183# These parameters are for the image charge.
184# The first is how many parameters, the second is the type.
185# Only image potential types 0 and 1 are implemented
186#
187#   0 - Entry/Exit only image, only has 2 parameters:
188#       1: z_min, potential is constant v_min below this.
189#       2: v_min, this is the minimum value for the potential
190#
191#   1 - Flat image potential, only has 2 parameters:
192#       1: z_min, potential is constant v_min below this.
193#       2: v_min, this is the minimum value for the potential
194#
1952 0
196
197# The parameters for the image potential
198#
1991.26 2.0
200
201# These are parameters for temperature and randomization.
202# They are: Temperature, Seed, initial ion_index
203# Seed is used for both temperature and Montecarlo mode.
204# Initial Ion Index allows repeating runs done on thermalized surfaces.
205#
206300.0 0.9436337324 1
207
208# This is a flag that controls whether image charge effects are included
209#
210f
211
212# These control failure conditions for the code
213# They are: Stuck Energy, Buried Distance
214#
215# Stuck energy is the amount of total energy for the ion to be considered
216# bound to the surface, and not leaving.
217# Buried Distance is the minimum distance below Z=0 before failing
218#
219-1.5 8.1
220
221# This section controls the lattice to scatter off.
222# First is the basis to generate the lattice from.
223#
224# These 3 values are AX, AY, AZ, the lattice constants for the basis.
225#
2264.0786 4.0786 4.0786
227
228# This line is how many sites are in the basis
2294
230# Below are the above number of lines, each defining a basis site.
231# These are in the format: X, Y, Z, Type.
232# Type corresponds to one of the atoms defined below, and X,Y,Z are
233# the coordinates of this site, to be scaled by AX,AY,AZ.
234# these distances are unitless
235#
2361.0 1.0 1.0 1
2371.0 0.5 0.5 1
2380.5 1.0 0.5 1
2390.5 0.5 1.0 1
240
241# Here we define the atoms in the lattice.
242# First we start with how many atoms there are.
243#
2441
245
246# Next we have pairs of lines, containing the following information:
247# Atomic Mass, Atomic Number, Atomic Symbol
248# Spring Constants (kx, ky, kz)
249#
250196.967 79 Au
2515.0 5.0 5.0
252
253# These control inter-atomic forces
254# 
255# Parameters:
256# 
257# 1. Whether interatomic forces occur at all.
258#
259# 2. k factor for interatomic springs.
260#
261# 3. this is breaking condition for interatomic springs,
262#    if using einstien, this is value in eV for where they break
263#    for interatomic springs, this is scaled by 1/r^2 for the initial
264#    seperation of the lattice sites
265#
266# 4. Number of nearest neighbours to consider for interaction,
267#    This defaults to 1 if the argument is not present.
268#
269t 1.5 10 2
270
271# This line defines the surface face of the crystal to generate.
272# The first three parameters are nessisary, they are the 
273# miller indecies of the surface face of the crystal.
274# If the 4th parameter is t, then an existing crystal will be loaded.
275# The existing crystal needs to be in a file with extension "crys_in", with
276# the same name as the input file.
277# the crystal loading is enabled, then 3 more parameters are also needed.
278# These are to define the surface face of the loaded crystal, to be used
279# to rotate the crystal to the requested surface face.
280#
2810 0 1 f 1 1 1
282
283# The next line is frictional force coefficients.
284# Friction is modelled as |F| = av + bv^2,
285# where v is the velocity of the ion, and the direction of F
286# is opposite to the direction of the velocity
287# 
288# [a] = sqrt(eV * AMU) * Angstrom^2
289# [b] =  AMU * Angstrom^2
290#
291# These are only checked if they are not both 0
292# 
2930 0

Important Lines

  • 21 - Initial conditions for the beam

  • 44 - the cull flag can be used to get specific details as to the projectiles which trigger the various failure conditions, and the type can enable producing The .spec file

  • 53 - Detector window

  • 66 - This controls the maximum number of particles to consider for interaction, smaller numbers greatly reduce runtimes

  • 75 - This controls the initial z position of the projectile, adjusting this may be nessisary depending on surface roughness

  • 79 - This controls the maximum number if integration steps, see The .data file more details

  • 106 - Run Number, ignored in Fixed Grid Mode

  • 119 - X Range

  • 122 - Y Range

  • 143 - Scattering Modes and Options

  • 174 - Potential type parameters

  • 219 - Stuck/Buried thresholds

Compact Input File

Here is the same input file, however with the comments removed, this is an example of a compact input file for SAFARI. This is also reproduced in The .dbug file.

 1250.0 45.0 0.00 22.989 Na
 20.5 250 2.5 0.5
 31 f
 445.0 45.0 10.0
 51e-08 10.0
 60.3 0.0 1e-06
 712
 8t
 95.0
102000
1110.0 0.002
120.0 0.0003
132 5
141000
150 0.1 4.0786
160 0.1 4.0786
17666 666
185.0 5.0
194 1 0
204153.6 3.625 27017.57 7.286
212 0
221.26 2.0
23300.0 0.9436337324 1
24f
25-1.5 8.1
264.0786 4.0786 4.0786
274
281.0 1.0 1.0 1
291.0 0.5 0.5 1
300.5 1.0 0.5 1
310.5 0.5 1.0 1
321
33196.967 79 Au
345.0 5.0 5.0
35t 1.5 10 2
360 0 1 f 1 1 1
370 0

External Potentials File

SAFARI calculates potentials and forces by linearly interpolating between values in pre-computed lookup tables. These tables range from r_step to r_max (see line 85 of Commented Input File). They start at r_step, as the potentials are not well defined at 0 separation. The values of r_max and r_step should be chosen such that the particles will never approach r_step as a separation distance (see The .data file for how to determine minimum separation distance), and such that a linear interpolation between points separated by r_step well fits the potential. r_max should be chosen such that the potential at that ditance is sufficiently close to 0, 10Å is generally a good value for this.

It should be noted that the tables in the external potential file are assumed to have the following ranges:

r = r_step -> r_max, where the first point is the value at r_step (generally undefined at 0 anyway).

The values in the table are in the natural order, however no order is required for the different tables.

Below are some examples of organization in a .pots file

 1Na  Au  30750.31988  208950.34829
 2Na  Au  30335.34062  206035.86306
 3Na  Au  29926.14885  203162.75772
 4... several thousand omitted lines
 5Na  Au  0.00000  0.00000
 6Na  Au  0.00000  0.00000
 7Cs  Cu  2257.89007  23793.80587
 8Cu  Cu  2257.89007  23793.80587
 9Cs  Cu  2210.87590  23222.80460
10Cu  Cu  2210.87590  23222.80460
11Cs  Cu  2164.98923  22666.24121
12Cu  Cu  2164.98923  22666.24121
13... several thousand omitted lines
14Cs  Cu  0.00000  0.00000
15Cu  Cu  0.00000  0.00000
16Cs  Cu  0.00000  0.00000
17Cu  Cu  0.00000  0.00000

In the above file, the ... represent omitted rows to make this file more compact for example purposes.

Here it demonstrates including multiple sets of potentials, each pairing of atoms is treated as a separate table, so they can either be separated entirely, such as the first block with Na Au, or they can be interlaced, as in the Cs Cu and Cu Cu cases.

External Crystal File

Surfaces can be specified via an external .crys_in file, below the format for that file will be discussed. A similar file is also produced as an output file, which can be a useful way to generate these files. This file will be loaded if the 4th parameter on line 281 of Commented Input File is t. In this case, it will assume that the provided crystal is oriented according to the last three values on that same line, and will then rotate the crystal to the orientation provided by the first three values. This allows loading in an externally provided surface, and then orienting it to an arbitrary direction.

Each line in the .crys_in file specifes an atom at a location. The atom is specified via atomic number and atomic mass, in the following order:

[X] [Y] [Z] [Atomic Number] [Mass]

Here is an example of such a file:

 10.000000  0.000000  0.000000  29  63.546000
 20.000000  1.300000  -2.600000  29  63.546000
 30.000000  -1.300000  -2.600000  29  63.546000
 40.000000  2.600000  -5.200000  29  63.546000
 50.000000  0.000000  -5.200000  29  63.546000
 60.000000  -2.600000  -5.200000  29  63.546000
 70.000000  3.900000  -7.800000  29  63.546000
 80.000000  1.300000  -7.800000  29  63.546000
 90.000000  -1.300000  -7.800000  29  63.546000
100.000000  -3.900000  -7.800000  29  63.546000