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 thetype
can enable producing The .spec file53 - 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