This is a minimal user's manual for P. Visscher's micromagnetics program, currently called AlaMag. Contents: ****** 1. Downloading ****** 2. Running; script files ****** 3. Saving data files for graphs ****** 4. Saving and displaying trajectories ****** 5. Keyboard commands ****** 6. Units (SI) ****** 7. Controlling field displays ****** 8. Magnetostatic interactions (FMM) ****** 9. Setting initial magnetizations ****** 1. Downloading To use AlaMag, you need to create a directory and put 5 files in it: alamag.exe (executable) default.script (instructions read and followed by alamag.exe) 111.ker (stored magnetostatic kernels) coin2d.dll, sowin1d.dll (COIN libraries) (The animation is done with an open-source package called COIN, and these libraries are freely distributable under the GNU Public License.) ****** 2. Running; script files To run the default script, just double-click AlaMag.exe. You can have many script files. Modify default.script and save it as runID.script, where runID is any identifier. To do this, open it in Notepad (or WordPad, if line breaks don't display correctly in Notepad.) There are several ways to run AlaMag.exe using a script file as input: 1. In Windows Explorer, drag the script file to AlaMag.exe. If it just closes without doing anything, try: 2. Make a shortcut to AlaMag.exe, and drag the script file to the shortcut. For some reason that sometimes works better. 3. Register AlaMag.exe as the application to be used to open files with the suffix .script. This can be done from the Start menu: Control Panel|Folder Options|File Types -- add file type SCRIPT, and select "Advanced" to add a "run" option leading to Alamag.exe. Sometimes this can be done by right-clicking runID.script, selecting "Open With" and browsing for AlaMag.exe. Then whenever you double click on any script in the future, it will be opened in AlaMag.exe. Not all of these methods work on all systems -- if one method doesn't work, try another. A common problem is that it is looking for input files like *.ker or *.img in the wrong default directory. Debugging Hint: If the program just crashes right away without giving you an error message, look in the directory you are running in for an error file (name like error.log). If you don't know what directory you are running in, search for error.log. This may give you a hint about why it crashed (necessary file not present or incorrectly named, etc.) The program opens two windows, a console (text) window and a graphics window. You can mostly ignore the text window -- it tells you the time and various debugging information (you can minimize it). The graphics window has a number of icons around the edge, including thumb wheels for rotating and zooming the display and some icons at the right for changing the appearance. The top two control the "mode" of the mouse. The top one ("select" mode) looks like an arrow and the one below it looks like a hand and puts you in a "rotate" mode. By default the window starts in the "rotate" mode and by dragging a point of the display with the mouse you can rotate it. Before you can control the simulation, you must put it into "select" mode (click the arrow icon) and then left-click inside the graphics window to make it active. Then the keyboard acts like a VCR control: the right arrow starts the simulation, the down arrow stops it. Whether the simulation is already running when the window opens is controlled by the script file (line beginning "W"ait). If it steps forward by one time step each time you press the right arrow, you are in "pause" mode -- pressing "p" toggles you in or out of pause mode. When you are out of pause mode, the simulation runs continuously when you press the right arrow. You can change the external bias field during the simulation with the keypad arrows (and + and - for the z direction, out of the screen). On a laptop, these are U,K,O,8. The script file is supposed to be self-explanatory, but is still (and will likely remain) under construction. The general format is that each line describes some information you want to give the program or some task you want it to perform. Lines beginning with '#' are comments and have no effect. The way the program reads a line is determined entirely by its first character (ignoring blanks and tabs). Thus, the line beginning "H_bias" would be treated the same if it began "H". After the first blank, the program looks for numbers (the three components of H, in this case). There can be no blanks inside the initial string (i.e. "H bias" wouldn't work). Everything after the # is ignored. Some other possible commands: hPulse: 1 1 .06 .06 0 0.01 0 0 2 # field pulse (Note the program is case-sensitive!) The line just below it explains what these numbers are. The program allows at most two pulses, and the first number (1 or 2) tells which this is. The second number is the pulse type. At the moment this is type 1, a trapezoidal pulse characterized by its maximum field (the next three numbers are Hx, Hy, Hz -- see below for units), its start time, rise time, fall time, and duration. Some of the commands are grouped into "blocks": there is a "Display block" (beginning with D) in which you can set it to display a clock. "Run block" (beginning with R) giving things like dt and total time, a "Spin wave block" giving wavevector and amplitude of spin wave initial condition, and a "Watched cell block" gives the position of one cell for which more information is given, and lists which fields are to be displayed there (anisotropy, exchange, magnetostatic, etc.) "Geometry block" describes the system geometry. Within a block the initial character has a different meaning (so in effect, the number of possible commands is 26*26 instead of 26). Each block ends with a line beginning "!" The geometry of the system is described hierarchically within the geometry block. The children of each node are indented more than the parent. The system must be made up of rectangular boxes with edges along the coordinate axes, each built by a "RectBuild" command. They are combined into a single hierarchy by NonRectangular nodes build by "NonRectBuild". Each rectangle is specified by its minimum coordinates x,y,z (i.e., "lower left rear"), its maximum x,y,z ("upper right front"), its material properties Ms, A, alpha, Hk, and its easy axis (the present code does not allow for random easy axes). The end of the description of each node is indicated by a line beginning with "!". Hk may be non-uniform, and is specified as a power law by giving the exponent and Hk at the left and right ends. The XchangeCoupling line gives the coupling between the current rectangle and the previous one (i.e. thin film layers), whether or not they are in the same NonRectangular node. The program can solve the Langevin form of the LL equation, i.e. it can add a random term to dM/dt. This is controlled by the temperature variable. Presently this is the second number in the "&" line -- make sure this is zero if you want a deterministic simulation. There is a complete list of script file commands (in Excel) on the beta web site; these will be better documented later. ****** 3. Saving data files for graphs In the script file, a line beginning E (for Export) indicates the export block. The exported data file is called runID.data (where runID is the base of the script file name, for example "default"). Each line contains the time, and other data requested in the export block by a line beginning H (external field) or M (magnetization of the watched cell). It is also possible to save a snapshot (i.e. M for each cell at a fixed time, for graphing M(x), for example) by pressing "e" while the display window is active [i.e. whenever right-arrow (play) and down-arrow (stop) work]. On some systems it is hard to find the output files -- they are saved in the user's home directory (often a subdirectory of C:Documents and Settings), which the user may not often look at. It is the parent of the user's "My Documents" directory. ****** 4. Saving and displaying trajectories AlaMag can save the computed trajectory and display it later ("replay mode") without having to compute it -- this is useful for simulations of large systems that are too slow to watch in real time. It wil be documented later. ****** 5. Keyboard commands (not case sensitive, full list in commands.xls) "e" - write snapshot of M's for Excel plot "P" - pause/not pause after each frame (allows stepping through); "Q" - exit the program; "Home" - restart the stored trajectory from the beginning; "Right_arrow" - Start the simulation (standard mode) or read the trajectory in forward direction (replay mode); "Left_arrow" - read the trajectory in backward direction (replay mode only); "Down_arrow" - pause the simulation or replay; ">" - increase the speed of playing the trajectory; "<" - decrease the speed of playing the trajectory; "keypad(far right)+" - move selected object +z "keypad -" - move selected object -z Keypad arrows: move in +- x or y directions (Note that keypad requires turning NumLock on. On a laptop without the keypad, use 8,U,O,K,/,; to move) "-" - decrease the transparency of the faces; "+" - increase the transparency of the faces; ****** 6. Units (SI) The program uses modified MKS units, modified so the numbers are of order one: time in nanoseconds, distance in nanometers, magnetic field in kA/m, energy unit 10^-27 joules. On input, exchange constant A is in j/m (converted to 10^-27 J/nm in the code). Interlayer exchange constant is specified by giving (in nm) a thickness t_J=(exchange energy)/(magnetostatic energy) = (exchange energy/area)/(mu_0*M_s*M_s) (Physical meaning of t_J: a perpendicularly pinned layer would force a coupled isotropic free layer perpendicular if its thickness is less than 2*t_J.) ****** 7. Controlling field displays The magnetization is displayed at every cell; several magnetic fields can be displayed at a "watched cell". This is determined in the "watched cell block", in which one line specifies the position of the watched cell ("P: 2.3 3.4 4.5" chooses the cell containing the point (2.3, 3.4, 4.5). Other lines turn on the display of the total magnetic field H (line bginning "T"), the field without anisotropy and exchange (line beginning "H"), the anisotropy field ("A"), magnetostatic field ("M"), and exchange field ("X"). The scale of the magnetization display is set so that the length of the saturation magnetization M_s is 0.45 of the cell width. The scale of the field displays are the same by default, but can be scaled up by the script command beginning "B": BignessOfField: 3.0 # field scale, relative to M scale. 3.0 means a 100 kA/m H-field is the same length as M = 300 kA/m. ****** 8. Magnetostatic interactions (FMM) The program uses the Fast Multipole Method (FMM) to calculate magnetostatic fields. The field controlling the dynamics at a cell is the average over that cell of the field due to the magnetization of all the other cells (assumed uniform within each cell). The parameters controlling this calculation are specified in the script line beginning "f": fmm_params.... For details of what these parameters mean, see (p)reprints at bama.ua.edu/~visscher/mumag. This line also gives the name of a file (*.ker) that contains the kernels (interactions between cells that are too close for the multipole method to be accurate) and a file Images.dat that gives the interactions between copies of a periodic system. The kernels depend only on the aspect ratio of the cells, so there is a kernel file for each aspect ratio -- the one for cubes is 111.ker. The kernel file for 5x5x1 cells is called 551.ker. Often it is useful to turn off magnetostatic interactions -- this can be done by commenting out this line: # fmm_params ..... Also, sometimes one wants to look at a single cell with specific demagnetization factors. This can be done using the "demag 1 0 0" line in the rectangle description (1 0 0 would be a film with its normal in the x direction). This demag factor then applies to all rectangles of that size. Demag can also be included by using a *.ker file with the correct demag factors (actually 1/2 the usual demag factors -- look at film.ker for an example -- essentially you are "fooling" the program into doing a calculation for an ellipsoid by putting its demag factor into the kernel file.) This can also be done for a system with a few cells (e.g., SAF MRAM with two magnetic layers), in which you assume you know the magnetostatic interactions between the cells. In MRAM.script, this is done in the limit in which the width is much greater than the thickness, so thin-film demag factors (with only z components) are used. To use more complicated demag factors, we must look at the format of the kernel file. MRAM.script nominally assumes 5x5x1 cells (although because we input the demag factors directly, it doesn't matter whether the real system is 5x5x1). Each line of the kernel file gives the average field in a cell produced by a unit magnetic charge spread over a face. This depends only on the vector separation between the cell center and the face center, which we refer to as a "key" (it is in units of half the smallest cell size, which we refer to as the "quantum" of distance). We can determine the orientation of the face from the parity of its position coordinates (a face with coordinates 001 relative to a cell center must be parallel to the xy plane, for example, and this is true of any face whose coordinates are even,even,odd respectively.) If the key is (-5,0,0) (meaning -2.5 quanta to the left of the center of the 5x5x1 cell) and the field is (in units of the magnetic charge per unit area) 0.1,0,0, then the corresponding line in the kernel file is key -5 0 0 Kernel 0.1 0.0 0.0 Because there is another equal and opposite charge at (5,0,0), the actual demag factor is twice this, or 0.2 (times 4pi in em units). We can account for the stray field at a cell due to a face of another cell in the same way. For film.ker, a film normal to the z direction, the demag factor has its maximum value of 1, so the field in the file (from each face) is 0.5. ****** 9. Setting initial magnetizations (spin waves) In the Geometry block, when a rectangle is defined, the magnetization in that rectangle can be initialized to a spin wave. This is done with two lines (perhaps later combined on one line): W: kx ky kz # gives the wave vector k, each component in units of 2pi/L where L is the total length of the rectangle in that direction (so k = 1 gives wavelength L, so there is just one cycle). A: Ax Ay phase # where Ax and Ay are the (angular) amplitudes in the x and y direction of a general elliptically polarized wave. For small amplitude, the magnetization vector is [Ax*cos(k.r+phase), Ay*sin(k.r+phase), 1]*M_s where k.r means the dot product. For large amplitude this is not normalized, so we actually construct M by rotating (0,0,1) around the axis (Ax*cos, -Ax*cos,0) by an angle equal to the length of this vector (angle^2 = Ax^2+Ay^2). For small amplitudes this is equivalent to the form given previously, but this gives sensible results for large angles as well. For example, if Ax=Ay=pi/2, this gives a magnetization in the xy plane that rotates about the z axis as r changes.