Tutorial

Only two files need to be edited to set up a code run: param-1.00.inc and sami2-1.00.namelist.

The include file param-1.00.inc contains the parameters nz and nf.

nz:	Number of grid points along the geomagnetic field; it must be an odd integer.
nf:	Number of field lines; it must be greater than or equal to 3 (the first and last field lines are boundary cells).

A typical value of nz is 201 although the code will run with a value 101 as long as rmax < 10,000 km. Increasing the number of grid points along the field decreases the time step, and will lead to longer run times. If any of these parameters is changed the code must be recompiled to effect the change.

The namelist file sami2-1.00.namelist contains the geophysical input conditions. The inputs are described in the Source Code Description section. These inputs can be changed without recompiling the code. For basic runs, the user should only need to change the following parameters:

fmtout; hrmax; dthr; hrpr; grad_in; glat_in; glon_in; fejer; rmin; rmax; fbar; f10p7; ap; year; day; nion2; ve01; cqe

Compiling the code

SAMI2 is written in Fortran 77. It has been compiled and run using the following Fortran compilers: Absoft, Lahey, the Portland Group, and Intel. Typical compilation lines for each compiler are as follows where sami2.x is the executable file. Each compilation line is a single line with no carriage return. There is also a makefile included in the distribution that can be used (i.e., makesami2-1.00).

Absoft (v7.5) f77 hwm93.f nrlmsise00.f grid-1.00.f sami2-1.00.f -s -O -N3 -o sami2.x

Absoft (> v9.0) f77 hwm93.f nrlmsise00.f grid-1.00.f sami2-1.00.f -s -O -o sami2.x

Lahey lf95 hwm93.f nrlmsise00.f grid-1.00.f sami2-1.00.f --sav -O -o sami2.x

Portland Group pgf77 -Msave -fast hwm93.f nrlmsise00.f grid-1.00.f sami2-1.00.f -o sami2.x

Intel ifort hwm93.f nrlmsise00.f grid-1.00.f sami2-1.00.f -save -O2 -vec_report0 -o sami2.x

In the above, the options -s, -Msave, -save, --sav save the values of the local variables in subroutines, and the options -O, -fast optimize the program. For Absoft Fortran 77 (v7.5) it is also necessary to use the option -N3 so that unformatted data is written in a form that can be read by the IDL procedure read-u.pro given in the Graphics section.

Note: It is important that SAMI2 be compiled with the save or static option.

Running the code

If the code has compiled successfully, simply type

sami2.x

Example 1

This is a short run for a single field line to see if the code runs 10 or so time steps and outputs the data in the appropriate format.

1. Copy the file example1.namelist to sami2-1.00.namelist.
2. Copy the file example1.param to param-1.00.inc.
3. Compile the code.
4. Run the code.
5. The output to the screen should look something like this. There can be small differences depending on the compiler used.
6. The data files (e.g., denif.dat) should be readable using a text editor.
7. Edit the file sami2-1.00.namelist so that
   fmtout = .false. and rerun the code. The output to the screen should be the same but now the output files are in binary format (e.g., deniu.dat)

Example 2

This is a longer run for the single field line case. It is for the same geophysical conditions as Example 1 but is run for 48 hrs with the data dumped every 15 minutes after the first 24 hours. The default is to output formatted data files.

1. Copy the file example2.namelist to sami2-1.00.namelist.
2. Copy the file example2.param to param-1.00.inc.
3. Compile the code.
4. Run the code. This takes approximately 16 s on a 2.83 GHz Intel chip using Intel fortran.
5. Examples of the output are presented in the Graphics section .

Example 3

This is a much longer run: the number of field lines is nf = 60. The default is to output formatted data files. This run will generate a file denif.dat that is approximately 126 MB. This can be changed by editing the sami2-1.00.namelist and setting fmtout = .false. after Step 1 below. This will generate a file deniu.dat that is approximately 31 MB.

1. Copy the file example3.namelist to sami2-1.00.namelist.
2. Copy the file example3.param to param-1.00.inc.
3. Compile the code.
4. Run the code. This takes approximately 6 min on a 2.83 Intel chip using Intel fortran.
5. Examples of the output are presented in the Graphics section .

Example 4

This example shows how to use the auxiliary code grid-rminrmax.f. SAMI2 sets up the grid using the parameters rmin (the altitude of the lowest field line at its magnetic equator) and rmax (the altitude of the highest field line at its magnetic equator). The purpose of grid-rminrmax.f is to determine these altitudes by specifying the input parameters glat_in, glon_in, grad_in_min, and grad_in_max where grad_in_min and grad_in_max are the minimum and maximum altitudes at a given latitude and longitude of interest.

For instance, say you are interested in doing a simulation relevant to Arecibo observations in the altitude range 100 - 2000 km. The geographic latitude and longitude for Arecibo are 18.3 and 293.25, respectively.

1. Compile the code grid-rminrmax.f
   (e.g., f77 grid-rminrmax.f -o grid-rminrmax.x).
2. Run the code by typing
   grid-rminrmax.x.
3. The following should appear:
   input: grad_in_min,grad_in_max,glat_in,glon_in
4. Enter the following:
   100. 2000. 18.3 293.25
5. The following should appear:
   Input data:
   
   grad_in_min: 100.000
   grad_in_max: 2000.00
   glat_in: 18.3000
   glon_in: 293.250
   
   pvalue: 1.31998
   rmin: 1651.64
   
   pvalue: 1.71185
   rmax: 4149.03
   
6. The values of rmin and rmax are now given. These values can be used in the namelist file. However, it is usually best to set rmin to a much lower value (e.g., 150 km) and rmax to a somewhat large value (e.g., 5000 km) to account for the E x B drift of the plasma.