OOMMF Users Guide October 30, 2002 This manual documents release 1.2a3.

WARNING: In this alpha release, the documentation may not be up to date.

Abstract This manual describes OOMMF (Object Oriented Micromagnetic Framework), a public domain micromagnetics program developed at the National Institute of Standards and Technology. The program is designed to be portable, exible, and extensible, with a user-friendly graphical interface. The code is written in C++ and Tcl/Tk. Target systems include a wide range of Unix platforms, Windows NT, and Windows 9X.

Contents
Disclaimer 1 Overview of OOMMF 2 Installation 2.1 Requirements . . . . . . . . . . . . . . . . . 2.2 Basic Installation . . . . . . . . . . . . . . . 2.2.1 Download . . . . . . . . . . . . . . . 2.2.2 Check Your Platform Conguration . 2.2.3 Compiling and Linking . . . . . . . . 2.2.4 Installing . . . . . . . . . . . . . . . 2.2.5 Using OOMMF Software . . . . . . . 2.2.6 Reporting Problems . . . . . . . . . 2.3 Advanced Installation . . . . . . . . . . . . . 2.3.1 Reducing Disk Space Usage . . . . . 2.3.2 Local Customizations . . . . . . . . . 2.3.3 Optimization . . . . . . . . . . . . . 2.3.4 Managing OOMMF Platform Names 2.3.5 Microsoft Windows Options . . . . . 3 Quick Start: Example OOMMF Session 4 OOMMF Architecture Overview 5 Command Line Launching 6 OOMMF Launcher/Control Interface: mmLaunch 7 OOMMF eXtensible Solver 7.1 OOMMF eXtensible Solver Interactive Interface: Oxsii 7.2 OOMMF eXtensible Solver Batch Interface: boxsi . . . 7.3 Standard Oxs Ext Child Classes . . . . . . . . . . . . . 7.3.1 Atlases . . . . . . . . . . . . . . . . . . . . . . . 7.3.2 Meshes . . . . . . . . . . . . . . . . . . . . . . . 7.3.3 Energies . . . . . . . . . . . . . . . . . . . . . . 7.3.4 Evolvers . . . . . . . . . . . . . . . . . . . . . . 7.3.5 Drivers . . . . . . . . . . . . . . . . . . . . . . . 7.3.6 Field Objects . . . . . . . . . . . . . . . . . . . 7.3.7 MIF Support Classes . . . . . . . . . . . . . . . 8 Micromagnetic Problem Editor: mmProbEd iv 1 3 3 4 4 5 8 9 9 9 9 9 10 10 11 12 16 21 23 26 28 28 32 35 36 41 41 53 59 63 67 68

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

. . . . . . . . . .

9 Micromagnetic Problem File Source: FileSource 10 The 2D Micromagnetic Solver 10.1 The 2D Micromagnetic Interactive Solver: mmSolve2D . . . 10.2 OOMMF 2D Micromagnetic Solver Batch System . . . . . . 10.2.1 2D Micromagnetic Solver Batch Interface: batchsolve 10.2.2 2D Micromagnetic Solver Batch Scheduling System . 11 Data Table Display: mmDataTable 12 Data Graph Display: mmGraph 13 Vector Field Display: mmDisp 14 Data Archive: mmArchive 15 Documentation Viewer: mmHelp 16 Command Line Utilities 16.1 Bitmap File Format Conversion: any2ppm . . . . . . 16.2 Making Data Tables from Vector Fields: avf2odt . . . 16.3 Vector Field File Format Conversion: avf2ovf . . . . . 16.4 Making Bitmaps from Vector Fields: avf2ppm . . . . 16.5 Vector Field File Dierence: avfdi . . . . . . . . . . 16.6 Calculating H Fields from Magnetization: mag2held 16.7 MIF Format Conversion: mifconvert . . . . . . . . . 16.8 ODT Column Extraction: odtcols . . . . . . . . . . . 16.9 Platform-Independent Make: pimake . . . . . . . . . 17 Problem Specication File Formats (MIF) 17.1 MIF 2.1 . . . . . . . . . . . . . . . . . . . 17.1.1 MIF 2.1 Extension Commands . . . 17.1.2 Specify Conventions . . . . . . . . 17.1.3 Variable Substitution . . . . . . . . 17.1.4 Sample MIF 2.1 File . . . . . . . . 17.2 MIF 1.1 . . . . . . . . . . . . . . . . . . . 17.2.1 Material parameters . . . . . . . . 17.2.2 Demag specication . . . . . . . . . 17.2.3 Part geometry . . . . . . . . . . . . 17.2.4 Initial magnetization . . . . . . . . 17.2.5 Experiment parameters . . . . . . . 17.2.6 Output specication . . . . . . . . 17.2.7 Miscellaneous . . . . . . . . . . . .

70 72 72 78 79 82 91 94 98 108 110 112 112 113 114 115 120 122 123 123 124 127 127 127 133 140 141 144 145 147 147 148 149 151 152

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

. . . . . . . . . . . . .

ii

18 Data Table File Format (ODT) 19 Vector Field File Format (OVF) 19.1 The OVF 1.0 format . . . . . . 19.1.1 Segment Header block . 19.1.2 Data block . . . . . . . . 19.2 The OVF 0.0 format . . . . . . 20 Troubleshooting 21 References 22 Credits

153 154 155 156 157 160 162 165 166

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

. . . .

iii

Disclaimer
This software was developed at the National Institute of Standards and Technology by employees of the Federal Government in the course of their ocial duties. Pursuant to Title 17, United States Code, Section 105, this software is not subject to copyright protection and is in the public domain. OOMMF is an experimental system. NIST assumes no responsibility whatsoever for its use by other parties, and makes no guarantees, expressed or implied, about its quality, reliability, or any other characteristic. We would appreciate acknowledgement if the software is used. When referencing OOMMF software, we recommend citing the NIST technical report, M. J. Donahue and D. G. Porter, OOMMF Users Guide, Version 1.0, NISTIR 6376, National Institute of Standards and Technology, Gaithersburg, MD (Sept 1999). Commercial equipment and software referred to on these pages are identied for informational purposes only, and does not imply recommendation of or endorsement by the National Institute of Standards and Technology, nor does it imply that the products so identied are necessarily the best available for the purpose.

iv

Overview of OOMMF

The goal of the OOMMF1 (Object Oriented Micromagnetic Framework) project in the Information Technology Laboratory (ITL) at the National Institute of Standards and Technology (NIST) is to develop a portable, extensible public domain micromagnetic program and associated tools. This code will form a completely functional micromagnetics package, but will also have a well documented, exible programmers interface so that people developing new code can swap their own code in and out as desired. The main contributors to OOMMF are Mike Donahue and Don Porter. In order to allow a programmer not familiar with the code as a whole to add modications and new functionality, we feel that an object oriented approach is critical, and have settled on C++ as a good compromise with respect to availability, functionality, and portability. In order to allow the code to run on a wide variety of systems, we are writing the interface and glue code in Tcl/Tk. This enables our code to operate across a wide range of Unix platforms, Windows NT, and Windows 9X. The code may be modied at 3 distinct levels. At the top level, individual programs interact via well-dened protocols across network sockets. One may connect these modules together in various ways from the user interface, and new modules speaking the same protocol can be transparently added. The second level of modication is at the Tcl/Tk script level. Some modules allow Tcl/Tk scripts to be imported and executed at run time, and the top level scripts are relatively easy to modify or replace. At the lowest level, the C++ source is provided and can be modied, although at present the documentation for this is incomplete (cf. the OOMMF Programming Manual). The rst portion of OOMMF released was a magnetization le display program called mmDisp. A working release2 of the complete OOMMF project was rst released in October, 1998. It included a problem editor, a 2D micromagnetic solver, and several display widgets, including an updated version of mmDisp. The solver can be controlled by an interactive interface (Sec. 10.1), or through a sophisticated batch control system (Sec. 10.2). This solver was originally based on a micromagnetic code that Mike Donahue and Bob McMichael had previously developed. It utilizes a Landau-Lifshitz ODE solver to relax 3D spins on a 2D mesh of square cells, using FFTs to compute the self-magnetostatic (demag) eld. Anisotropy, applied eld, and initial magnetization can be varied pointwise, and arbitrarily shaped elements can be modeled. The current development version, OOMMF 1.2, includes Oxs, the OOMMF eXtensible Solver. Oxs oers users of OOMMF the ability to extend Oxs with their own modules. The details of programming an Oxs extension module are found in the OOMMF Programming Manual 3 . The extensible nature of the Oxs solver means that its capabilities may be varied as necessary for the problem to be solved. Oxs modules distributed as part of OOMMF support full 3D simulations suitable for modeling layered materials.
1 2

http://math.nist.gov/oommf/ http://math.nist.gov/oommf/software.html 3 http://math.nist.gov/oommf/doc/

If you want to receive e-mail notication of updates to this project, register your e-mail address with the MAG Announcement mailing list: http://www.ctcms.nist.gov/rdm/email-list.html. The OOMMF developers are always interested in your comments about OOMMF. See the Credits (Sec. 22) for instructions on how to contact them, and for information on referencing OOMMF.

2
2.1

Installation
Requirements

OOMMF software is written in C++ and Tcl. It uses the Tcl-based Tk Windowing Toolkit to create graphical user interfaces that are portable to many varieties of Unix as well as Microsoft Windows 9X/NT. Tcl and Tk must be installed before installing OOMMF. Tcl and Tk are available for free download 4 from the Tcl Developer Xchange5 . We recommend the latest stable versions of Tcl and Tk concurrent with this release of OOMMF. OOMMF requires at least Tcl version 7.5 and Tk version 4.1 on Unix platforms, and requires at least Tcl version 8.0 and Tk version 8.0 on Microsoft Windows platforms. OOMMF software does not support any alpha or beta versions of Tcl/Tk, and each release of OOMMF may not work with later releases of Tcl/Tk. Check the release dates of both OOMMF and Tcl/Tk to ensure compatibility. A Tcl/Tk installation includes two shell programs. The names of these programs may vary depending on the Tcl/Tk version and the type of platform. The rst shell program contains an interpreter for the base Tcl language. In the OOMMF documentation we refer to this program as tclsh. The second shell program contains an interpreter for the base Tcl language extended by the Tcl commands supplied by the Tk toolkit. In the OOMMF documentation we refer to this program as wish. Consult your Tcl/Tk documentation to determine the actual names of these programs on your platform (for example, tclsh83.exe or wish8.0). OOMMF applications communicate via TCP/IP network sockets. This means that OOMMF requires support for networking, even on a stand-alone machine. At a minimum, OOMMF must be able to access the loopback interface so that the host can talk to itself using TCP/IP. OOMMF applications that use Tk require a windowing system and a valid display. On Unix systems, this means that an X server must be running. If you need to run OOMMF applications on a Unix system without display hardware or software, you may need to start the application with command line option -tk 0 (see Sec. 5) or use the Xvfb6 virtual frame buer. The OOMMF source distribution unpacks into a directory tree containing about 800 les and directories, occupying approximately 10 MB of storage. The amount of disk space needed for compiling and linking varies greatly between platforms; allow an additional 15 MB to 80 MB for the build. Removing intermediate object modules (cf. the pimake objclean target, in Reducing Disk Space Usage, Sec. 2.3.1, below ) reduces the nal space requirement for source + binary executables to between 15 MB and 25 MB. The OOMMF distribution containing Windows executables unpacks into a directory tree occupying about 15 MB of storage. Note: On a non-compressed FAT16 le system on a large disk, OOMMF may
4 5

http://purl.org/tcl/home/software/tcltk/choose.html http://purl.org/tcl/home/ 6 http://www.itworld.com/AppDev/1461/UIR000330xvfb/

take up much more disk space. This is because on such systems, the minimum size of any le is large, as much as 32 KB. Since this is much larger than many les in the OOMMF distribution require, a great deal of disk space is wasted. To build OOMMF software from source code, you will need a C++ compiler capable of handling C++ templates, C++ exceptions, and (for the OOMMF eXtensible Solver) the C++ Standard Template Library. You will need other software development utilities for your platform as well. We do development and test builds on the following platforms, although porting to others should not be dicult: Platform AIX Alpha/Linux Alpha/Windows NT Intel/Linux Intel/Windows NT, 95, 98 MIPS/IRIX 6 (SGI) SPARC/Solaris System Notes: Windows: Versions of the Microsoft Visual C++ compiler earlier than 5.0 will not build the Oxs (3D) solver. HP-UX: The older HP cfront compiler will not build the Oxs (3D) solver. Compilers VisualAge C++ (xlC), Gnu gcc Compaq C++, Gnu gcc Microsoft Visual C++ Gnu gcc Microsoft Visual C++, Intel C++, Cygwin gcc, Borland C++ MIPSpro C++, Gnu gcc Sun Workshop C++, Gnu gcc

2.2

Basic Installation

Follow the instructions in the following sections, in order, to prepare OOMMF software for use on your computer. 2.2.1 Download

The latest release of the OOMMF software may be retrieved from the OOMMF download page7 . Each release is available in two formats. The rst format is a gzipped tar le containing an archive of all the OOMMF source code. The second format is a .zip compressed archive containing source code and pre-compiled executables for Microsoft Windows 9X/NT running on an x86-based microprocessor system. Each Windows binary distribution is compatible with only a particular sequence of releases of Tcl/Tk. For example, a Windows binary release for Tcl/Tk 8.3.x is compatible with Tcl/Tk 8.3.0, 8.3.1, . . . . Other release formats, e.g., pre-compiled executables for Microsoft Windows NT running on a Compaq Alpha Systems RISC-based microprocessor system, and/or compatible with older versions of Tcl/Tk, may be made available upon request.
7

http://math.nist.gov/oommf/software.html

For the rst format, unpack the distribution archive using gunzip and tar: gunzip -c oommf12a3_20021029.tar.gz | tar xvf For the other format(s), you will need a utility program to unpack the .zip archive. This program must preserve the directory structure of the les in the archive, and it must be able to generate les with names not limited to the old MSDOS 8.3 format. Some very old versions of the pkzip utility do not have these properties. One utility program which is known to work is UnZip8 . Using your utility, unpack the .zip archive, e.g. unzip oommf12a3_20021029_84.zip For either distribution format, the unpacking sequence creates a subdirectory oommf which contains all the les and directories of the OOMMF distribution. If a subdirectory named oommf already existed (say, from an earlier OOMMF release), then les in the new distribution overwrite those of the same name already on the disk. Some care may be needed in that circumstance to be sure that the resulting mix of les from an old and a new OOMMF distribution combine to create a working set of les. 2.2.2 Check Your Platform Conguration

After downloading and unpacking the OOMMF software distribution, all the OOMMF software is contained in a subdirectory named oommf. Start a command line interface (a shell on Unix, or the MS-DOS Prompt on Microsoft Windows), and change the working directory to the directory oommf. Find the Tcl shell program installed as part of your Tcl/Tk installation. In this manual we call the Tcl shell program tclsh, but the actual name of the executable depends on the release of Tcl/Tk and your platform type. Consult your Tcl/Tk documentation. In the root directory of the OOMMF distribution is a le named oommf.tcl. It is the bootstrap application (Sec. 5) which is used to launch all OOMMF software. With the command line argument +platform, it will print a summary of your platform conguration when it is evaluated by tclsh. This summary describes your platform type, your C++ compiler, and your Tcl/Tk installation. As an example, here is the typical output on a Linux/Alpha system: $ tclsh oommf.tcl +platform oommf.tcl 1.2.0.3 info: OOMMF release 1.2.0.3 Platform Name: linalp Tcl name for OS: Linux 2.2.20 C++ compiler: /usr/bin/g++ Tcl configuration file: /usr/local/lib/tclConfig.sh
8

http://www.info-zip.org/pub/infozip/UnZip.html

tclsh: /usr/local/bin/tclsh8.4 Tcl release: 8.4.1 (config) 8.4.1 (running) Tk configuration file: /usr/local/lib/tkConfig.sh wish: /usr/local/bin/wish8.4 Tk release: 8.4.1 (config) 8.4.1 (running) If oommf.tcl +platform doesnt print a summary similar to the above, it should instead print an error message describing why it cant. For example, if your Tcl installation is older than release 7.5, the error message will report that fact. Follow the instructions provided and repeat until oommf.tcl +platform successfully prints a summary of the platform conguration information. The rst line of the example summary reports that OOMMF recognizes the platform by the name linalp. OOMMF software recognizes many of the more popular computing platforms, and assigns each a platform name. The platform name is used by OOMMF in index and conguration les and to name directories so that a single OOMMF installation can support multiple platform types. If oommf.tcl +platform reports the platform name to be unknown, then you will need to add some conguration les to help OOMMF assign a name to your platform type, and associate with that name some of the key features of your computer. See the section on Managing OOMMF platform names (Sec. 2.3.4) for further instructions. The second line reports what C++ compiler will be used to build OOMMF from its C++ source code. If you downloaded an OOMMF release with pre-compiled binaries for your platform, you may ignore this line. Otherwise, if this line reports none selected, or if it reports a compiler other than the one you wish to use, then you will need to tell OOMMF what compiler to use. To do that, you must edit the appropriate conguration le for your platform. Continuing the example above, one would edit the le config/cache/linalp.tcl. Editing instructions are contained within the le. On other platforms the name linalp in config/cache/linalp.tcl should be replaced with the platform name OOMMF reports for your platform. For example, on a Windows machine using an x86 processor, the corresponding conguration le is config/cache/wintel.tcl. The next three lines describe the Tcl conguration OOMMF nds on your platform. The rst line reports the name of the conguration le installed as part of Tcl, if any. Conventional Tcl installations on Unix systems and within the Cygwin environment on Windows have such a le, usually named tclConfig.sh. The Tcl conguration le records details about how Tcl was built and where it was installed. On Windows platforms, this information is recorded in the Windows registry, so it is normal to have oommf.tcl +platform report none found. If oommf.tcl +platform reports none found, but you know that an appropriate Tcl conguration le is present on your system, you can tell OOMMF where to nd the le by setting the environment variable OOMMF TCL CONFIG to its absolute lename. (For information about setting environment variables, see your operating system documentation.) In unusual circumstances, OOMMF may nd a Tcl conguration le which doesnt correctly describe your Tcl installation. In that case, use the environment variable OOMMF TCL CONFIG to instruct OOMMF to use a dierent le that you specify, and 6

edit that le to include a correct description of your Tcl installation. The second line describing your Tcl installation reports the absolute pathname of the tclsh program. If this diers from the tclsh you used to evaluate oommf.tcl +platform, there may be something wrong with your Tcl conguration le. Note that the same tclsh program might be known by several absolute pathnames if there are symbolic links in your Tcl installation. If oommf.tcl +platform reports that it cannot nd a tclsh program, yet you know where an appropriate one is installed on your system, you can tell OOMMF where to nd the tclsh program by setting the environment variable OOMMF TCLSH to its absolute location. The third line describing your Tcl installation reports its release number according to two sources. First is the release number recorded in the Tcl conguration le. Second is the release number of the tclsh program used to evaluate oommf.tcl +platform. If these numbers do not match, it may indicate something is wrong with your Tcl conguration le. If you have multiple releases of Tcl installed under a common root directory on your computer, there can be only one Tcl conguration le. It is important that you use the Tcl release that corresponds to the Tcl conguration le. The next three lines describe the Tk conguration OOMMF nds on your platform. They are analogous to the three lines describing the Tcl conguration. The environment variables OOMMF TK CONFIG and OOMMF WISH may be used to tell OOMMF where to nd the Tk conguration le and the wish program, respectively. Finally, the output of oommf.tcl +platform may include warnings about possible problems with your Tcl/Tk installation. For example, if you are missing important header les, or if your Tcl/Tk installation is thread-enabled (which OOMMF does not support). If oommf.tcl +platform indicates problems with your Tcl/Tk installation, it may be easiest to re-install Tcl/Tk taking care to perform a conventional installation. OOMMF deals best with conventional Tcl/Tk installations. If you do not have the power to re-install an existing broken Tcl/Tk installation (perhaps you are not the sysadmin of your machine), you might still install your own copy of Tcl/Tk in your own user space. In that case, if your private Tcl/Tk installation makes use of shared libraries, take care that you do whatever is necessary on your platform to be sure that your private tclsh and wish nd and use your private shared libraries instead of those from the system Tcl/Tk installation. This might involve setting an environment variable (such as LD LIBRARY PATH). If you use a private Tcl/Tk installation, you also want to be sure that there are no environment variables like TCL LIBRARY or TK LIBRARY that still refer to the system Tcl/Tk installation. Other Conguration Issues A few other congurations should be checked on Windows platforms. First, note that absolute lenames on Windows makes use of the backslash (\) to separate directory names. On Unix and within Tcl the forward slash (/) is used to separate directory names in an absolute lename. In this manual we usually use the Tcl convention of forward slash as separator. In portions of the manual pertaining only to MS Windows we use the backslash as separator. There may be instructions in this manual which do not work exactly as written on Windows platforms. You may need to replace forward slashes 7

with backward slashes in pathnames when working on Windows. OOMMF software needs networking support that recognizes the host name localhost. It may be necessary to edit a le which records that localhost is a synonym for the loopback interface (127.0.0.1). If a le named hosts exists in your system area (for example, C:\Windows\hosts), be sure it includes an entry mapping 127.0.0.1 to localhost. If no hosts le exists, but a hosts.sam le exists, make a copy of hosts.sam with the name hosts, and edit the copy to have the localhost entry. In recent releases of Tcl/Tk (version 8.0.3 and later) the directory which holds the tclsh and wish programs also holds several *.dll les that OOMMF software needs to nd to run properly. Normally when the OOMMF bootstrap application (Sec. 5) or mmLaunch (Sec. 6) is used to launch OOMMF programs, they take care of making sure the necessary *.dll les can be found. As an additional measure, you might want to add the directory which holds the tclsh and wish programs to the list of directories stored in the PATH environment variable. All the directories in the PATH are searched for *.dll les needed when starting an executable. 2.2.3 Compiling and Linking

If you downloaded a distribution with pre-compiled executables, you may skip this section. When building OOMMF software from source code, be sure the C++ compiler reported by oommf.tcl +platform is properly congured. In particular, if you are running on a Windows system, please read carefully the notes in Advanced Installation, Sec. 2.3.5, pertaining to your compiler. The compiling and linking of the C++ portions of OOMMF software are guided by the application pimake (Sec. 16.9) (Platform Independent Make) which is distributed as part of the OOMMF release. To begin building OOMMF software with pimake, rst change your working directory to the root directory of the OOMMF distribution: cd .../path/to/oommf If you unpacked the new OOMMF release into a directory oommf which contained an earlier OOMMF release, use pimake to build the target upgrade to clear away any source code les which were in a former distribution but are not part of the latest distribution: tclsh oommf.tcl pimake upgrade Next, build the target distclean to clear away any old executables and object les which are left behind from the compilation of the previous distribution: tclsh oommf.tcl pimake distclean Next, to build all the OOMMF software, run pimake without specifying a target: tclsh oommf.tcl pimake

On some platforms, you cannot successfully compile OOMMF software if there are OOMMF programs running. Check that all OOMMF programs have terminated (including those in the background) before trying to compile and link OOMMF. When pimake calls on a compiler or other software development utility, the command line is printed, so that you may monitor the build process. Assuming a proper conguration for your platform, pimake should be able to compile and link all the OOMMF software without error. If pimake reports errors, please rst consult Troubleshooting (Sec. 20) to see if a x is already documented. If not, please send both the complete output from pimake and the output from oommf.tcl +platform to the OOMMF developers when you e-mail to ask for help. 2.2.4 Installing

The current OOMMF release does not support an installation procedure. For now, simply run the executables from the directories in which they were unpacked/built. 2.2.5 Using OOMMF Software

To start using OOMMF software, run the OOMMF bootstrap application (Sec. 5). This may be launched from the command line interface: tclsh oommf.tcl If you prefer, you may launch the OOMMF bootstrap application oommf.tcl using whatever graphical point and click interface your operating system provides. By default, the OOMMF bootstrap application will start up a copy of the OOMMF application mmLaunch (Sec. 6) in a new window. If you publish material created with the aid of OOMMF, please refer to Credits (Sec. 22) for citation information. 2.2.6 Reporting Problems

If you encounter problems when installing or using OOMMF, please report them to the OOMMF developers. See Troubleshooting (Sec. 20) for detailed instructions.

2.3

Advanced Installation

The following sections provide instructions for some additional installation options. 2.3.1 Reducing Disk Space Usage

To delete the intermediate les created when building the OOMMF software from source code, use pimake (Sec. 16.9) to build the target objclean in the root directory of the OOMMF distribution. 9

tclsh oommf.tcl pimake objclean Running your platform strip utility on the OOMMF executable les should also reduce their size somewhat. 2.3.2 Local Customizations

OOMMF software supports local customization of some of its features. All OOMMF programs load the le config/options.tcl, which contains customization commands as well as editing instructions. As it is distributed, config/options.tcl directs programs to also load the le config/local/options.tcl, if it exists. Because future OOMMF releases may overwrite the le config/options.tcl, permanent customizations should be made by copying config/options.tcl to config/local/options.tcl and editing the copy. It is recommended that you leave in the le config/local/options.tcl only the customization commands necessary to change those options you wish to modify. Remove all other options so that overwrites by subsequent OOMMF releases are allowed to change the default behavior. Notable available customizations include the choice of which network port the host service directory application (Sec. 4) uses, and the choice of what program is used for the display of help documentation. By default, OOMMF software uses the application mmHelp (Sec. 15), which is included in the OOMMF release, but the help documentation les are standard HTML, so any web browser (for example, Netscape Navigator or Microsoft Internet Explorer) may be used instead. Complete instructions are in the le config/options.tcl. 2.3.3 Optimization

In the interest of successful compilation of a usable software package out of the box, the default conguration for OOMMF does not attempt to achieve much in terms of optimization. However, in each platforms conguration le (for example, config/cache/wintel.tcl), there are alternative values for the congurations optimization ags, available as comments. If you are familiar with your compilers command line options, you may experiment with other choices as well. You can edit the platform conguration le to replace the default selection with another choice that provides better computing performance. For example, in config/cache/wintel.tcl, alternative optimization ags for the MSVC++ compiler are dened with the line: $config SetValue program_compiler_c++_option_opt {format "/G5 /Ox"} The extensible solver, Oxs, can be compiled with debugging support for extensive runtime code checks. This will signicantly reduce computation performance. In the standard OOMMF distributions, these checks should be disabled. You may verify this by checking that the following line appears in the le config/options.tcl: Oc_Option Add * Platform cflags {-def NDEBUG} 10

To enable these checks, either comment/remove this line, or else add to the config/local/options.tcl le a cags option line without -def NDEBUG, such as Oc_Option Add * Platform cflags {-warn 1} The config/local/options.tcl le may be created if it does not already exist. 2.3.4 Managing OOMMF Platform Names

OOMMF software classies computing platforms into dierent types using the scripts in the directory config/names relative to the root directory of the OOMMF distribution. Each type of computing platform is assigned a unique name. These names are used as directory names and in index and conguration les so that a single OOMMF installation may contain platform-dependent sections for many dierent types of computing platforms. To learn what name OOMMF software uses to refer to your computing platform, run tclsh oommf.tcl +platform in the OOMMF root directory. Changing the name OOMMF assigns to your platform First, use pimake (Sec. 16.9) to build the target distclean to clear away any compiled executables built using the old platform name. tclsh oommf.tcl pimake distclean Then, to change the name OOMMF software uses to describe your platform from foo to bar, simply rename the le config/names/foo.tcl and config/cache/foo.tcl to config/cache/bar.tcl. to config/names/bar.tcl

After renaming your platform type, you should recompile your executables using the new platform name. Adding a new platform type If oommf.tcl +platform reports the platform name unknown, then none of the scripts in config/names/ recognizes your platform type. As an example, to add the platform name foo to OOMMFs vocabulary of platform names, create the le config/names/foo.tcl. The simplest way to proceed is to copy an existing le in the directory config/names and edit it to recognize your platform. The les in config/names include Tcl code like this:

11

Oc_Config New _ \ [string tolower [file rootname [file tail [info script]]]] { # In this block place the body of a Tcl proc which returns 1 # if the machine on which the proc is executed is of the # platform type identified by this file, and which returns 0 # otherwise. # # The usual Tcl language mechanism for discovering details # about the machine on which the proc is running is to # consult the global Tcl variable tcl_platform. See the # existing files for examples, or contact the OOMMF # developers for further assistance. } After creating the new platform name le config/names/foo.tcl, you also need to create a new platform cache le config/cache/foo.tcl. A reasonable starting point is to copy the le config/cache/unknown.tcl for editing. Contact the OOMMF developers for assistance. Please consider contributing your new platform recognition and conguration les to the OOMMF developers for inclusion in future releases of OOMMF software. Resolving platform name conicts If the script oommf.tcl +platform reports Multiple platform names are compatible with your computer, then there are multiple les in the directory config/names/ that return 1 when run on your computer. For each compatible platform name reported, edit the corresponding le in config/names/ so that only one of them returns 1. Experimenting using tclsh to probe the Tcl variable tcl platform should assist you in this task. If that fails, you can explicitly assign a platform type corresponding to your computing platform by matching its hostname. For example, if your machines host name is foo.bar.net: Oc_Config New _ \ [string tolower [file rootname [file tail [info script]]]] { if {[string match foo.bar.net [info hostname]]} { return 1 } # Continue with other tests... } Contact the OOMMF developers if you need further assistance. 2.3.5 Microsoft Windows Options

This section lists installation options for Microsoft Windows. 12

Using Microsoft Visual C++ If you are building OOMMF software from source using the Microsoft Visual C++ command line compiler, cl.exe, it is necessary to run vcvars32.bat to set up the path and some environment variables. This le is distributed as part of Visual C++. You may want to set up your system so this batch le gets run automatically when you boot the system, or open a command prompt. See your compiler and system documentation for details. Using the Cygwin toolkit The Cygwin Project9 is a free port of the GNU development environment to Windows NT and 9X, which includes the GNU C++ compiler gcc and a port of Tcl/Tk. OOMMF has been successfully built and tested within the Cygwin environment, and sample config/names/cygtel.tcl and config/cache/cygtel.tcl les are included in the OOMMF distribution. Use cygtclsh as your tclsh program when conguring, building, and launching OOMMF software. Note that OOMMF software determines whether it is running with the Cygwin versions of Tcl/Tk by examining the environment variables OSTYPE and TERM. If either is set to a value beginning with cygwin, the Cygwin environment is assumed. If you are using the Cygwin environment with a dierent values for both OSTYPE and TERM, you will have to modify config/names/cygtel.tcl accordingly. Using Borland C++ OOMMF has been successfully built and tested using the Borland C++ command line compiler10 version 5.5. However, a couple preparatory steps are necessary before building OOMMF with this compiler. 1. Properly complete bcc55 compiler installation. Be sure to read the readme.txt le in the BCC55 subdirectory of the Borland install directory. In particular, check that the bcc32.cfg and ilink32.cfg conguration les exist in the BIN directory, and have appropriate contents. If you omit this step you will get error messages during the OOMMF build process relating to the inability of the Borland compiler to nd system header les and libraries. 2. Create Borland compatible Tcl and Tk libraries. The import libraries distributed with Tcl/Tk, release 8.0.3 and later, are not compatible with the Borland C++ linker. However, the command line utilities impdef and implib, which are distributed with the Borland compiler, can be used to create suitable libraries from the Tcl/Tk DLLs. In the Tcl/Tk library directory (typically C:\Tcl\lib or "C:\Program Files\Tcl\lib"), issue the following commands impdef -a tcl83bc.def ..\bin\tcl83.dll implib tcl83bc.lib tcl83bc.def
9 10

http://sourceware.cygnus.com/cygwin/ http://www.inprise.com/bcppbuilder/freecompiler/

13

to create the Borland compatible import library tcl83bc.lib. Repeat with tk in place of tcl to create tk83bc.lib. The -a switch requests impdef to add a leading underscore to function names. This is sucient for the DLLs shipped with Tcl/Tk 8.3, but other releases may require additional tweaking. The module denition le output by impdef, e.g., tcl83bc.def above, is a plain text le. You may need to edit this le to add or modify entries. 3. Edit config\cache\wintel.tcl At a minimum, you will have to change the program compiler c++ value to point to the Borland C++ compiler. The sample wintel.tcl cache le assumes the librarian tlib and the linker ilink32 are in the execution path, and that the Borland compatible import libraries made above are in the Tcl/Tk library directory. If this is not the case then you will have to make the additional modications. Also, you may need to add the -o switch to the linker command to force ordinal usage of the Borland compatible Tcl/Tk libraries produced in the previous step. After this, continue with the instructions in Sec. 2.2.3, Compiling and Linking. Setting the TCL LIBRARY environment variable If you encounter diculties during OOMMF start up, you may need to set the environment variable TCL LIBRARY. On Windows NT Bring up the Control Panel (e.g., by selecting Settings|Control Panel o the Start menu), and select System. Go to the Environment tab, and enter TCL LIBRARY as the Variable, and the name of the directory containing init.tcl for the Value, e.g., %SystemDrive%\Program Files\Tcl\lib\tcl8.0 Click Set and OK to nish. On Windows 9x Edit the le autoexec.bat. Add a line such as the following: set TCL_LIBRARY=C:\Program Files\Tcl\lib\tcl8.0 Checking .tcl le association on Windows NT As part of the Tcl/Tk installation, les with the .tcl extension are normally associated with the wish application. This allows Tcl scripts to be launched from Windows Explorer by double-clicking on their icon, or from the NT command line without specifying the tclsh or wish shells. If this is not working, you may check your installation from the NT command line as follows. First, run the command assoc .tcl. This should return the le type associated with the .tcl extension, e.g., TclScript. Next, use the ftype command to check the command line associated with that le type, e.g.,

14

C:\> ftype TclScript "C:\Program Files\Tcl\bin\wish84.exe" "%1" %2 %3 %4 %5 %6 %7 %8 %9 Note that the quotes are required as shown to protect spaces in pathnames. If either assoc or ftype are incorrect, view the command line help information (assoc /? and ftype /?) for details on making changes. Adding an OOMMF shortcut to your desktop Right mouse click on the desktop to bring up the conguration dialog, and select New|Shortcut. Enter the command line necessary to bring up OOMMF, e.g., tclsh84 c:\oommf\oommf.tcl Click Next> and enter OOMMF for the shortcut name. Select Finish. At this point the shortcut will appear on your desktop with either the tclsh or wish icons. Right mouse click on the icon and select Properties. Select the ShortCut tab, and bring up Change Icon. . . Under File Name: enter the OOMMF icon le, e.g., C:\oommf\oommf.ico Click OK. Back on the Shortcut tab, change the Run: selection to Minimized. Click OK to exit the Properties dialog box. Double clicking on the OOMMF icon should now bring up the OOMMF application mmLaunch.

15

Quick Start: Example OOMMF Session

At the command prompt, when you are in the OOMMF root directory, type tclsh oommf.tcl (The name of the Tcl shell, rendered here as tclsh, may vary between systems. This matter is discussed in Sec. 2.1.) Alternatively, you may launch oommf.tcl using whatever point and click interface is provided by your operating system. This will bring up a small window labeled mmLaunch. It will come up in background mode, so you will get another prompt in your original window, even before the mmLaunch window appears.

STEP 1: Start up the mmLaunch window.

STEP 2: Gain access to other useful windows. On the mmLaunch window, check the localhost box, causing a menu of user account boxes to appear. Check the box corresponding to the account you want to compute on. (On Windows 9X systems, the user account list may consist of only the faux oommf user account.) This gives a menu of options: mmArchive: to auto-save scalar and vector eld data mmDataTable: to display current values of scalar outputs mmDisp: to display vector elds mmGraph: to form x-y plots mmProbEd: to grab/modify a problem for mmSolve2D mmSolve2D: to control the 2D solver Oxsii: to control the 3D solver

Click on mmDisp, mmGraph, and/or mmDataTable, depending on what form of output you want. Use mmArchive to save data to disk. STEP 3a: Run a 2D problem. Load problem: On the mmLaunch window, click on the mmProbEd button. On the mmProbEd window, make menu selection File|Open. . . An Open File dialog window will appear. On this window: Double click in the Path subwindow to change directories. Several sample problems can be found in the directory oommf/app/mmpe/examples. To load a problem, double click on a *.mif le (e.g., prob1.mif) from the list above the Filter: subwindow.

16

 Modify the problem as desired by clicking on buttons from the main mmProbEd window (e.g., Material Parameters), and ll out the pop-up forms. A completely new problem may be dened this way. Initialize solver: On the mmLaunch window, click on the mmSolve2D button to launch an instance of the program mmSolve2D. Wait for the new solver instance to appear in the Threads column in the mmLaunch window. Check the box next to the mmSolve2D entry in the Threads column. A window containing an mmSolve2D interface will appear. On the mmSolve2D window: Check Problem Description under Inputs. Check mmProbEd under Source Threads. Click LoadProblem. A status line will indicate the problem is loading. When the problem is fully loaded, more buttons appear. Check Scheduled Outputs. For each desired output (TotalField, Magnetization, and/or DataTable), specify the frequency of update: 1. Check desired output. This will exhibit the possible output destinations under the Destination Threads heading. Output applications such as mmDisp, mmGraph, and/or mmDataTable must be running to appear in this list. 2. Check the box next to the desired Destination Thread. This will exhibit Schedule options. 3. Choose a schedule: Iteration: ll in number and check the box. ControlPoint: ll in number and check the box. Interactive: whenever you click corresponding Interactive output button. Start calculation: On the mmSolve2D window, start the calculation with Run (which runs until problem completion) or Relax (which runs until the next control point is reached). If you requested mmDataTable output, check the boxes for the desired quantities on the mmDataTable window under the Data menu, so that they appear and are updated as requested in your schedule. Similarly, check the box for the desired X, Y1, and Y2 quantities on the mmGraph window(s) under the X, Y1 and Y2 menus. Save results: 17

 Vector eld data (magnetization and eective eld) may be interactively written to disk using mmDisp, or may be automatically saved via scheduled output to mmArchive. For example, to save the magnetization state at each control point, start up an instance of mmArchive and select the ControlPoint check box for mmArchive on the Magnetization schedule in the solver. This may be done before starting the calculation. (Control points are points in the simulation where the applied eld is stepped. These are typically equilibrium states, but depending on the input *.mif le, may be triggered by elapsed simulation time or iteration count.) DataTable data may be saved by sending scheduled output from the solver to mmArchive, which will automatically save all the data it receives. Alternatively, mmGraph can perform this function. Schedule output to mmGraph as desired, and use either the interactive or automated save functionality of mmGraph (Sec. 12). You can setup the solver data scheduling before the calculation is started, but must wait for the rst data point to congure mmGraph before saving any data. As a workaround, you may congure mmGraph by sending it the initial solver state interactively, and then use the Options|clear Data menu item in mmGraph to remove the initializing data point. Midcourse control: On the mmSolve2D window, buttons can stop and restart the calculation: Reset: Return to beginning of problem. LoadProblem: Restart with a new problem. Run: Apply a sequence of elds until all complete. Relax: Run the ODE at the current applied eld until the next control point is reached. Pause: Click anytime to stop the solver. Continue simulation from paused point with Run or Relax. Field: Apply the previous eld again. Field+: Apply the next eld in the list. Output options can be changed and new output windows opened. STEP 3b: Run a 3D problem. Launch solver: On the mmLaunch window, click on the Oxsii button to launch an instance of the program Oxsii. Wait for the new solver instance to appear in the Threads column in the mmLaunch window. Check the box next to the Oxsii entry in the Threads column. A window containing an Oxsii interface will appear. 18

Load problem: On the Oxsii window, select the File|Load. . . menu option. A Load Problem dialog box will appear. On this window: Double click in the Path subwindow to change directories. Several sample problems can be found in the directory oommf/app/oxs/examples. To load a problem, double click on a *.mif le (e.g., stdprob1.mif) from the list above the Filter: subwindow. There is currently no analogue to mmProbEd for the 3D solver, so the input les must be composed by hand. For details, see the MIF 2.1 (Sec. 17.1) and Oxs Ext Child Class (Sec. 7.3) documentation. Note that MIF 1.x (i.e., 2D problem) les are not readable by Oxsii. The status line in the Oxsii interface window will indicate the problem is loading. When the problem is fully loaded, the status line will show Pause, and the top row of buttons (Reload, Reset, . . . ) will become active. Also, the Output list will ll with available outputs. Set up scheduled outputs. For each desired output 1. Select the source from the Output list. 2. Select the receiver from the Destination list. 3. Specify the frequency of update: Step: ll in number and check the box. Stage: ll in number and check the box. The items in the Output list will vary depending on the problem that was loaded. The items in the Destination list reect the OOMMF data display and archiving programs currently running. Start calculation: On the Oxsii window, start the calculation with Run, Relax, or Step. If you requested mmDataTable output, check the boxes for the desired quantities on the mmDataTable window under the Data menu, so that they appear and are updated as requested in your schedule. Similarly, check the box for the desired X, Y1, and Y2 quantities on the mmGraph window(s) under the X, Y1 and Y2 menus. Save results: Vector eld data (magnetization and eective eld) may be interactively written to disk using mmDisp, or may be automatically saved via scheduled output to mmArchive. For example, to save the magnetization state at the end of each problem stage, start up an instance of mmArchive and select the Stage check box for the Magnetization output, mmArchive destination pair. (Stages denote points in the simulation where some signicant event occurs, such as when an 19

equilibrium is reached or some preset simulation time index is met. These criteria are set by the input MIF le.) Tabular data may be saved by sending scheduled output from the solver to mmArchive, which will automatically save all the data it receives. Alternatively, mmGraph can perform this function. Schedule output to mmGraph as desired, and use either the interactive or automated save functionality of mmGraph (Sec. 12). You can setup the solver data scheduling before the calculation is started, but must wait for the rst data point to congure mmGraph before saving any data. As a workaround, you may congure mmGraph by sending it the initial solver state interactively, and then use the Options|clear Data menu item in mmGraph to remove the initializing data point. Midcourse control: On the Oxsii window, buttons can stop and restart the calculation: Reload: Reload the same le from disk. Reset: Return to problem start. Run: Step through all stages until all complete. Relax: Run until the current stage termination criteria are met. Step: Do one solver iteration and then pause. Pause: Click anytime to stop the solver. Continue simulation from paused point with Run, Relax or Step. Stage: Interactively change the current stage index by either typing the desired stage number (counting from 0) into the Stage entry box or by moving the associated slider. Output options can be changed and new output windows opened. The Send button in the Oxsii Schedule subwindow is used to interactively send output to the selected Output + Destination pair. STEP 4: Exit OOMMF. Individual OOMMF applications can be terminated by selecting the File|Exit menu item from their interface window. Selecting File|Exit on the mmLaunch window will close the mmLaunch window, and also the interface windows for any mmArchive, mmSolve2D, and Oxsii applications. However, those applications will continue to run in the background, and their interfaces may be re-displayed by starting a new mmLaunch instance. To automatically kill all OOMMF applications, select the File|Exit All OOMMF option from the mmLaunch menu bar.

20

OOMMF Architecture Overview

Before describing each of the applications which comprise the OOMMF software, it is helpful to understand how these applications work together. OOMMF is not structured as a single program. Instead it is a collection of programs, each specializing in some task needed as part of a micromagnetic simulation system. An advantage of this modular architecture is that each program may be improved or even replaced without a need to redesign the entire system. The OOMMF programs work together by providing services to one another. The programs communicate over Internet (TCP/IP) connections, even when the programs are running on a common host. An advantage of this design is that distributed operation of OOMMF programs over a networked collection of hosts is supported in the basic design, and will be available in a future release. When two OOMMF applications are in the relationship that one is requesting a service from the other, it is convenient to introduce some clarifying terminology. Let us refer to the application that is providing a service as the server application and the application requesting the service as the client application. Note that a single application can be both a server application in one service relationship and a client application in another service relationship. Each server application provides its services on a particular Internet port, and needs to inform potential client applications how to obtain its service. Each client application needs to be able to look up possible providers of the service it needs. The intermediary which brings server applications and client applications together is another application called the account service directory. There may be at most one account service directory application running under the user ID of each user account on a host. Each account service directory keeps track of all the services provided by OOMMF server applications running under its user account on its host and the corresponding Internet ports at which those services may be obtained. OOMMF server applications register their services with the corresponding account service directory application. OOMMF client applications look up service providers running under a particular user ID in the corresponding account server directory application. The account service directory applications simplify the problem of matching servers and clients, but they do not completely solve it. OOMMF applications still need a mechanism to nd out how to obtain the service of the account service directory! Another application, called the host service directory serves this function. Only one copy of the host service directory application runs on each host. Its sole purpose is to tell OOMMF applications where to obtain the services of account service directories on that host. Because only one copy of this application runs per host, it can provide its service on a well-known port which is congured into the OOMMF software. By default, this is port 15136. OOMMF software can be customized (Sec. 2.3.2) to use a dierent port number. The account service directory applications perform another task as well. They launch other programs under the user ID for which they manage service registration. The user controls the launching of programs through the interface provided by the application mm21

Launch (See Sec. 6), but it is the account service directory application that actually spawns a subprocess for the new application. Because of this architecture, most OOMMF applications are launched as child processes of an account service directory application. These child processes inherit their environment from their parent account service directory application, including their working directory, and other key environment variables, such as DISPLAY. Each account service directory application sets its working directory to the root directory of the OOMMF distribution. Future releases of OOMMF software will likely be based on a revised architecture which alleviates these restrictions. These service directory applications are vitally important to the operation of the total OOMMF micromagnetic simulation system. However, it would be easy to overlook them. They act entirely behind the scenes without a user interface window. Furthermore, they are never launched by the user. When any server application needs to register its service, if it nds that these service directory applications are not running, it launches new copies of them. In this way the user can be sure that if any OOMMF server applications are running, then so are the service directory applications needed to direct clients to its service. After all server applications terminate, and there are no longer any services registered with a service directory application, it terminates as well. Similarly, when all service directory applications terminate, the host service directory application exits. In the sections which follow, the OOMMF applications are described in terms of the services they provide and the services they require.

22

Command Line Launching

Some of the OOMMF applications are platform-independent Tcl scripts. Some of them are Tcl scripts that require special platform-dependent interpreters. Others are platformdependent, compiled C++ applications. It is likely that some of them will change status in later releases of OOMMF. Each of these types of application requires a dierent command line for launching. Rather than require all OOMMF users to manage this complexity, we provide a pair of programs that provide simplied interfaces for launching OOMMF applications. The rst of these is used to launch OOMMF applications from the command line. Because its function is only to start another program, we refer to this program as the bootstrap application. The bootstrap application is the Tcl script oommf.tcl. In its simplest usage, it takes a single argument on the command line, the name of the application to launch. For example, to launch mmGraph (Sec. 12), the command line is: tclsh oommf.tcl mmGraph The search for an application matching the name is case-insensitive. (Here, as elsewhere in this document, the current working directory is assumed to be the OOMMF root directory. For other cases, adjust the pathname to oommf.tcl as appropriate.) As discussed in Sec. 2.1, the name of the Tcl shell, rendered here as tclsh, may vary between systems. If no command line arguments are passed to the bootstrap application, by default it will launch the application mmLaunch (Sec. 6). Any command line arguments to the bootstrap application that begin with the character + modify its behavior. For a summary of all command line options recognized by the bootstrap application, run: tclsh oommf.tcl +help The command line arguments +bg and +fg control how the bootstrap behaves after launching the requested application. It can exit immediately after launching the requested application in background mode (+bg), or it can block until the launched application exits (+fg). Each application registers within the OOMMF system whether it prefers to be launched in foreground or background mode. If neither option is requested on the command line, the bootstrap launches the requested application in its preferred mode. The rst command line argument that does not begin with the character + is interpreted as a specication of which application should be launched. As described above, this is usually the simple name of an application. When a particular version of an application is required, though, the bootstrap allows the user to include that requirement as part of the specication. For example: tclsh oommf.tcl "mmGraph 1.1" will guarantee that the instance of the application mmGraph it launches is of at least version 1.1. If no copy of mmGraph satisfying the version requirement can be found, an error is reported. 23

The rest of the command line arguments that are not recognized by the bootstrap are passed along as arguments to the application the bootstrap launches. Since the bootstrap recognizes command line arguments that begin with + and most other applications recognize command line arguments that begin with -, confusion about which options are provided to which programs can be avoided. For example, tclsh oommf.tcl +help mmGraph prints out help information about the bootstrap and exits without launching mmGraph. However, tclsh oommf.tcl mmGraph -help launches mmGraph with the command line argument -help. mmGraph then displays its own help message. All OOMMF applications accept the standard options listed below. Some of the OOMMF applications accept additional arguments when launched from the command line, as documented in the corresponding sections of this manual. When an option argument is specied as <0|1>, 0 typically means o, no or disable, and 1 means on, yes or enable. -version Display the version of the application and exit. -help Display a help message and exit. -tk <0|1> Disable or enable Tk. Tk must be enabled for an application to display graphical widgets. However, when Tk is enabled, on Unix platforms the application is dependent on an X Windows server. If the X Windows server dies, it will kill the application. Long-running applications that do not inherently use display widgets support disabling of Tk with -tk 0. Other applications that must use display widgets are unable to run with the option -tk 0. To run applications that require -tk 1 on a Unix system with no display, one might use Xvfb11 . -cwd directory Set the current working directory of the application. -console Display a console widget in which Tcl commands may be interactively typed into the application. Useful for debugging. In addition, those applications which enable Tk accept additional Tk options, such as -display. See the Tk documentation for details. The bootstrap application should be infrequently used by most users. The application mmLaunch (Sec. 6) provides a more convenient graphical interface for launching applications. The main uses for the bootstrap application are launching mmLaunch, launching pimake, launching programs which make up the OOMMF Batch System (Sec. 10.2) and other programs that are inherently command line driven, and in circumstances where the user wishes to precisely control the command line arguments passed to an OOMMF application or the environment in which an OOMMF application runs.
11

http://www.itworld.com/AppDev/1461/UIR000330xvfb/

24

Platform Issues
On most Unix platforms, if oommf.tcl is marked executable, it may be run directly, i.e., without specifying tclsh. This works because the rst few lines of the oommf.tcl Tcl script are: #!/bin/sh # \ exec tclsh "$0" ${1+"$@"} When run, the rst tclsh on the execution path is invoked to interpret the oommf.tcl script. If the Tcl shell program cannot be invoked by the name tclsh on your computer, edit the rst lines of oommf.tcl to use the correct name. Better still, use symbolic links or some other means to make the Tcl shell program available by the name tclsh. The latter solution will not be undone by le overwrites from OOMMF upgrades. If in addition, the directory .../path/to/oommf is in the execution path, the command line can be as simple as: oommf.tcl appName from any working directory. On Windows platforms, because oommf.tcl has the le extension .tcl, it is normally associated by Windows with the wish interpreter. The oommf.tcl script has been specially written so that either tclsh or wish is a suitable interpreter. This means that simply double-clicking on an icon associated with the le oommf.tcl (say, in Windows Explorer) will launch the bootstrap application with no arguments. This will result in the default behavior of launching the application mmLaunch, which is suitable for launching other OOMMF applications. (If this doesnt work, refer back to the Windows Options section in the installation instructions, Sec. 2.3.5.)

25

OOMMF Launcher/Control Interface: mmLaunch

Overview
The application mmLaunch launches, monitors, and controls other OOMMF applications. It is the OOMMF application which is most closely connected to the account service directory and host service directory applications that run behind the scenes. It also provides user interfaces to any applications, notably Oxsii (Sec. 7.1) and mmSolve2D (Sec. 10.1), that do not have their own user interface window.

Launching
mmLaunch should be launched using the bootstrap application (Sec. 5). The command line is tclsh oommf.tcl mmLaunch [standard options]

Controls
Upon startup, mmLaunch displays a panel of checkbuttons, one for each host service directory to which it is connected. In the current release of OOMMF there is only one checkbuttonlocalhost. Future releases of mmLaunch will be able to connect to remote

26

hosts as well. If there is no host service directory running on the localhost when mmLaunch is launched, mmLaunch will start one. In that circumstance, there may be some delay before the localhost check button appears. Toggling the localhost checkbutton toggles the display of an interface to the host service directory. The host service directory interface consists of a row of checkbuttons, one for each account service directory registered with the host service directory. Each checkbutton is labeled with the user ID of the corresponding account service directory. For most users, there will be only one checkbutton, labeled with the users own account ID, except on Windows 9X, where the dummy account ID oommf may be displayed instead. If there is no account service directory running for the account under which mmLaunch was launched, mmLaunch will start one. In that circumstance, there may be some delay before the account checkbutton appears. Toggling an account checkbutton toggles the display of an interface to the corresponding account service directory. The account service directory interface consists of two columns. The Programs column contains buttons labeled with the names of OOMMF applications that may be launched under the account managed by this account service directory. Clicking on one of these buttons launches the corresponding application. Only one click is needed, though there will be some delay before the launched application displays a window to the user. Multiple clicks will launch multiple copies of the application. Note: The launching is actually handled by the account service directory application (Sec. 4), which sets the initial working directory to the OOMMF root directory. The Threads column is a list of all the OOMMF applications currently running under the account that are registered with the account service directory. The list includes both the application name and an ID number by which multiple copies of the same application may be distinguished. This ID number is also displayed in the title bar of the corresponding applications user interface window. When an application exits, its entry is automatically removed from the Threads list. Any of the running applications that do not provide their own interface window will be displayed in the Threads list with a checkbutton. The checkbutton toggles the display of an interface which mmLaunch provides on behalf of that application. The only OOMMF applications currently using this service are the 3D solvers Oxsii and Boxsi (Sec. 7), the 2D solvers mmSolve2D and batchsolve (Sec. 10), and the archive application mmArchive (Sec. 14). These interfaces are described in the documentation for the corresponding applications. The menu selection File|Exit terminates the mmLaunch application, and the File|Exit All OOMMF selection terminates all applications in the Threads list, and then exits mmLaunch. The menu Help provides the usual help facilities.

27

OOMMF eXtensible Solver

The Oxs (OOMMF eXtensible Solver) is an extensible micromagnetic computation engine capable of solving problems dened on three-dimensional grids of rectangular cells holding three-dimensional spins. There are two interfaces provided to Oxs: the interactive interface Oxsii (Sec. 7.1) intended to be controlled primarily through a graphical user interface, and the batch mode Boxsi (Sec. 7.2), which has extended command line controls making it suitable for use in shell scripts. Problem denition for Oxs is accomplished using input les in the MIF 2.1 format (Sec. 17.1). This is an extensible format; the standard OOMMF modules are documented in Sec. 7.3 below. Note on Tk dependence: Some MIF 2 problem descriptions rely on external image les; examples include those using the Oxs ImageAtlas class Sec. 7.3.1, or those using the MIF 2 ReadFile command with the image translation specication Sec. 17.1.1. If the image le is not in the PPM P3 (text) format, then the any2ppm application may be launched to read and convert the le. Since any2ppm requires Tk, at the time the image le is read a valid display must be available. See the any2ppm documentation (Sec. 16.1) for details.

7.1

OOMMF eXtensible Solver Interactive Interface: Oxsii

Overview
The application Oxsii is the graphical, interactive user interface to the Oxs micromagnetic computation engine. Within the OOMMF architecture (see Sec. 4), Oxsii is both a server and a client application. Oxsii is a client of data table display and storage applications, and vector eld display and storage applications. Oxsii is the server of a solver control service for which the only client is mmLaunch (Sec. 6). It is through this service that mmLaunch provides a user interface window (shown above) on behalf of Oxsii.

28

A micromagnetic problem is communicated to Oxsii via a MIF 2.1 le, which denes a collection of Oxs Ext objects that comprise the problem model. The problem description includes a segmentation of the lifetime of the simulation into stages. Stages mark discontinuous changes in model attributes, such as applied elds, and also serve to mark coarse grain simulation progress. Oxsii provides controls to advance the simulation, stopping between iterations, between stages, or only when the run is complete. Throughout the simulation, the user may save and display intermediate results, either interactively or via scheduling based on iteration and stage counts.

Launching
Oxsii may be started either by selecting the Oxsii button on mmLaunch, or from the command line via tclsh oommf.tcl oxsii [standard options] [-parameters params] \ [-pause <0|1>] [-nice <0|1>] [-exitondone <0|1>] [miffile] where -parameters params Sets MIF 2.1 format (Sec. 17.1) le parameters. The params argument should be a list with an even number of arguments, corresponding to name + value pairs. This list must be quoted so it is presented to Oxsii as a single item on the command line. The quoting mechanism is shell/operating system specic. Refer to your system documentation for details. -nice <0|1> If enabled (i.e., 1), then the program will drop its scheduling priority after startup. The default is 1, i.e., to yield scheduling priority to other applications. -pause <0|1> If enabled (i.e., 1), then the program automatically pauses after loading the specied mile. The default is 0, i.e., to automatically move into Run mode once the problem is loaded. This switch has no eect if mile is not specied. -exitondone <0|1> Whether to exit after solution of the problem is complete. Default is to simply await the interactive selection of another problem to be solved. mile Load and solve the problem found in mile, which must be in the MIF 2.1 format. Optional. All the above switches are optional. Since Oxsii does not present any user interface window of its own, it depends on mmLaunch to provide an interface on its behalf. The entry for an instance of Oxsii in the Threads column of any running copy of mmLaunch has a checkbutton next to it. This button toggles the presence of a user interface window through which the user may control that instance of Oxsii.

29

Inputs
Unlike mmSolve2D (Sec. 10.1), Oxsii loads problem specications directly from disk (via the File|Load... menu selection), rather than through mmProbEd (Sec. 8) or FileSource (Sec. 9). Also, input les for Oxsii must be in the MIF 2.1 (Sec. 17.1) format, as opposed to the older MIF 1.1 format used by the 2D solver. There are sample MIF 2.1 les in the directory oommf/app/oxs/examples. The command line tool mifconvert (Sec. 16.7) can be used as an aid for converting MIF 1.1 les to the MIF 2.1 format. MIF les may be edited with any plain text editor.

Outputs
Once a problem has been loaded, the scroll box under the Output heading will ll with a list of available outputs. The contents of this list will depend upon the Oxs Ext objects specied in the input MIF le. Refer to the documentation for those objects for specic details (Sec. 7.3). To send output from Oxsii to another OOMMF application, highlight the desired selection under the Output heading, make the corresponding selection under the Destination heading, and then specify the output timing under the Schedule heading. Outputs may be scheduled by the step or stage, and may be sent out interactively by pressing the Send button. The initial output conguration is set by Destination and Schedule commands in the input MIF le (Sec. 17.1.1). Outputs fall under two general categories: scalar (single-valued) outputs and vector eld outputs. The scalar outputs are grouped together as the DataTable entry in the Output scroll box. Scalar outputs include such items as total and component energies, average magnetization, stage and iteration counts, max torque values. When the DataTable entry is selected, the Destination box will list all OOMMF applications accepting datatable-style input, i.e., all currently running mmDataTable (Sec. 11), mmGraph (Sec. 12), and mmArchive (Sec. 14) processes. The vector eld outputs include pointwise magnetization, various total and partial magnetic elds, and torques. Unlike the scalar outputs, the vector eld outputs are listed individually in the Output scroll box. Allowed destinations for vector eld output are running instances of mmDisp (Sec. 13) and mmArchive (Sec. 14). Caution is advised when scheduling vector eld output, especially with large problems, because the output may run many megabytes.

Controls
The File menu button holds 5 entries: Load, Show Console, Close Interface, Clear Schedule and Exit Oxsii. File|Load. . . launches a dialog box that allows the user to select an input MIF problem description le. File|Show Console brings up a Tcl shell console running o the Oxsii interface Tcl interpreter. This console is intended primary for debugging purposes. In particular, output from MIF Report commands (Sec. 17.1.1) may be viewed here. File|Close Interface will remove the interface window from the display, but leaves the 30

solver running. This eect may also be obtained by deselecting the Oxsii interface button in the Threads list in mmLaunch. File|Clear Schedule will disable all currently active output schedules, exactly as if the user clicked through the interactive schedule interface one output and destination at a time and disabled each schedule-enabling checkbutton. The nal entry, File|Exit Oxsii, terminates the Oxsii solver and closes the interface window. The Help menu provides the usual help facilities. The row of buttons immediately below the menu bar provides simulation progress control. These buttons become active once a problem has been loaded. The rst button, Reload, re-reads the most recent problem MIF input le, re-initializes the solver, and pauses. Reset is similar, except the le is not re-read. The remaining four buttons, Run, Relax, Step and Pause place the solver into one of four run-states. In the Pause state, the solver sits idle awaiting further instructions. If Step is selected, then the solver will move forward one iteration and then Pause. In Relax mode, the solver takes at least one step, and then runs until it reaches a stage boundary, at which point the solver is paused. In Run mode, the solver runs until the end of the problem is reached. Interactive output is available in all modes; the scheduled outputs occur appropriately as the step and stage counts advance. Directly below the progress control buttons are two display lines, showing the name of the input MIF le and the current run-state. Below the run-state Status line is the stage display and control bar. The simulation stage may be changed at any time by dragging the scroll bar or by typing the desired stage number into the text display box to the left of the scroll bar. Valid stage numbers are integers from 0 to N 1, where N is the number of stages specied by the MIF input le.

Details
The simulation model construction is governed by the Specify blocks in the input MIF le. Therefore, all aspects of the simulation are determined by the specied Oxs Ext classes (Sec. 7.3). Refer to the appropriate Oxs Ext class documentation for simulation and computational details.

Known Bugs
A bug in the network trac handling code of Tcl on Windows 9X systems can sometimes interfere with communications between the control interface of Oxsii and the actual computation engine. If Oxsii is sending out data to two or more data display services every iteration, the network trac from that data can crowd out the receipt of control messages from the control interface. You may observe this as a long delay between the time you click the Pause button and the time the solver stops iterating. This bug rst appeared in Tcl release 8.0.3, and remained through Tcl release 8.1.1. It is xed in Tcl releases 8.2 and later, which we recommend for OOMMF users on Windows 9X systems. Other platforms do not have this problem.

31

7.2

OOMMF eXtensible Solver Batch Interface: boxsi

Overview
The application Boxsi provides a batch mode interface to the Oxs micromagnetic computation engine. A restricted graphical interface is provided, but Boxsi is primarily intended to be controlled by command line arguments, and launched by the user either directly from the shell prompt or from inside a batch le. Within the OOMMF architecture (see Sec. 4), Boxsi is both a server and a client application. It is a client of data table display and storage applications, and vector eld display and storage applications. Boxsi is the server of a solver control service for which the only client is mmLaunch (Sec. 6). It is through this service that mmLaunch provides a user interface window (shown above) on behalf of Boxsi. A micromagnetic problem is communicated to Boxsi through a MIF 2.1 le specied on the command line and loaded from disk.

Launching
Boxsi must be started from the command line. The syntax is tclsh oommf.tcl boxsi [standard options] [-parameters params] \ [-pause <0|1>] [-nice <0|1>] [-exitondone <0|1>] [-kill tags] miffile where -parameters params Sets MIF 2.1 format (Sec. 17.1) le parameters. The params argument should be a list with an even number of arguments, corresponding to name + value pairs. This list must be quoted so it is presented to Boxsi as a single item on the command line. The quoting mechanism is shell/operating system specic. Refer to your system documentation for details. 32

-nice <0|1> If enabled (i.e., 1), then the program will drop its scheduling priority after startup. The default is 0, i.e., to retain its original scheduling priority. -pause <0|1> If enabled (i.e., 1), then the program automatically pauses after loading the specied problem le. The default is 0, i.e., to automatically move into Run mode once the problem is loaded. -exitondone <0|1> Whether to exit after solution of the problem is complete, or to await the interactive selection of the File|Exit command. The default is 1, i.e., automatically exit when done. -kill tags On termination, sends requests to other applications to shutdown too. The tags argument should be either a list of destination tags (which are declared by Destination commands, Sec. 17.1.1) from the input MIF le, or else the keyword all, which is interpreted to mean all the destination tags. mile Load and solve the problem found in mile, which must be in the MIF 2.1 format. Required. Although Boxsi cannot be launched by mmLaunch, nonetheless a limited graphical interactive interface for Boxsi is provided through mmLaunch, in the same manner as is done for Oxsii. Each running instance of Boxsi is included in the Threads list of mmLaunch, along with a checkbutton. This button toggles the presence of a user interface window.

Inputs
Boxsi loads problem specications directly from disk as requested on the command line. The format for these les is the MIF 2.1 (Sec. 17.1) format, the same as used by the Oxsii interactive interface. The older MIF 1.1 (Sec. 17.2) used by the 2D solver mmSolve2D cannot be read by Boxsi, but the command line tool mifconvert (Sec. 16.7) can be used as an aid for converting MIF 1.1 les to the MIF 2.1 format. Sample MIF 2.1 les can be found in the directory oommf/app/oxs/examples.

Outputs
The lower panel of the Boxsi interactive interface presents Output, Destination, and Schedule sub-windows that display the current output conguration and allow interactive modication of that conguration. These controls are identical to those in the Oxsii user interface; refer to the Oxsii documentation (Sec. 7.1) for details. The only dierence between Boxsi and Oxsii with respect to outputs is that in practice Boxsi tends to rely primarily on Destination and Schedule commands in the input MIF le (Sec. 17.1.1) to setup the output conguration. The interactive output interface is used for incidental runtime monitoring of the job. 33

Controls
The runtime controls provided by the Boxsi interactive interface are a restricted subset of those available in the Oxsii interface. If the runtime controls provided by Boxsi are found to be insucient for a given task, consider using Oxsii instead. The File menu holds 4 entries: Show Console, Close Interface, Clear Schedule, and Exit Oxsii. File|Show Console brings up a Tcl shell console running o the Boxsi interface Tcl interpreter. This console is intended primary for debugging purposes. File|Close Interface will remove the interface window from the display, but leaves the solver running. This eect may also be obtained by deselecting the Boxsi interface button in the Threads list in mmLaunch. File|Clear Schedule will disable all currently active output schedules, exactly as if the user clicked through the interactive schedule interface one output and destination at a time and disabled each schedule-enabling checkbutton. The nal entry, File|Exit Boxsi, terminates the Boxsi solver and closes the interface window. Note that there is no File|Load. . . menu item; the problem specication le must be declared on the Boxsi command line. The Help menu provides the usual help facilities. The row of buttons immediately below the menu bar provides simulation progress control. These buttonsRun, Relax, Step and Pausebecome active once the micromagnetic problem has been initialized. These buttons allow the user to change the run state of the solver. In the Pause state, the solver sits idle awaiting further instructions. If Step is selected, then the solver will move forward one iteration and then Pause. In Relax mode, the solver takes at least one step, and then runs until it reaches a stage boundary, at which point the solver is paused. In Run mode, the solver runs until the end of the problem is reached. When the problem end is reached, the solver will either pause or exit, depending upon the setting of the -exitondone command line option. Normally the solver progresses automatically from problem initialization into Run mode, but this can be changed by the -pause command line switch. Interactive output is available in all modes; the scheduled outputs occur appropriately as the step and stage counts advance. Directly below the run state control buttons are three display lines, showing the name of the input MIF le, the current run-state, and the current stage number/maximum stage number. Both stage numbers are 0-indexed.

Details
As with Oxsii, the simulation model construction is governed by the Specify blocks in the input MIF le, and all aspects of the simulation are determined by the specied Oxs Ext classes (Sec. 7.3). Refer to the appropriate Oxs Ext class documentation for simulation and computational details.

34

Known Bugs
Boxsi suers from the same Windows 9X Tcl network trac bug as Oxsii. OOMMF users on Windows 9X systems are encouraged to upgrade to Tcl 8.2 or later.

7.3

Standard Oxs Ext Child Classes

An Oxs simulation is built as a collection of Oxs Ext (Oxs Extension) objects. These are dened via Specify blocks in the input MIF 2.1 le (Sec. 17.1). The reader will nd the information and sample MIF le, Fig. 5, provided in that section to be a helpful adjunct to the material presented below. This section describes the Oxs Ext classes available in the standard OOMMF distribution, including documentation of their Specify block initialization strings. The standard Oxs Ext objects, i.e., those that are distributed with OOMMF, can be identied by the Oxs prex in their names. Additional Oxs Ext classes may be available on your system. Check local documentation for details. In the following presentation, the Oxs Ext classes are organized into 8 categories: atlases, meshes, energies, evolvers, drivers, scalar eld objects, vector eld objects, and MIF support classes. The following Oxs Ext classes are currently available: Atlases Oxs BoxAtlas Oxs MultiAtlas Meshes Oxs RectangularMesh Energies Oxs CubicAnisotropy Oxs Exchange6Ngbr Oxs FixedZeeman Oxs ScriptUZeeman Oxs StageZeeman Oxs TwoSurfaceExchange Oxs UniformExchange Evolvers Oxs CGEvolve Drivers Oxs MinDriver Scalar Field Objects Oxs AtlasScalarField Oxs RandomScalarField Oxs UniformScalarField Oxs Oxs Oxs Oxs Oxs Oxs Oxs Demag ExchangePtwise RandomSiteExchange SimpleDemag TransformZeeman UniaxialAnisotropy UZeeman Oxs ImageAtlas Oxs ScriptAtlas

Oxs EulerEvolve Oxs TimeDriver Oxs LinearScalarField Oxs ScriptScalarField

35

 Vector Field Objects Oxs AtlasVectorField Oxs PlaneRandomVectorField Oxs ScriptVectorField MIF Support Classes Oxs LabelValue 7.3.1 Atlases

Oxs FileVectorField Oxs RandomVectorField Oxs UniformVectorField

Geometric volumes of spaces are specied in Oxs via atlases, which divide their domain into one or more disjoint subsets called regions. Each atlas denition also species a bounding box, i.e., an axes parallel rectangular parallelepiped that contains all the regions. The most commonly used atlases are the simple Oxs BoxAtlas and the compound Oxs MultiAltas. Oxs BoxAtlas: An axes parallel rectangular parallelepiped, containing a single region that is coterminous with the atlas itself. The specify block has the form Specify Oxs BoxAtlas:atlasname { xrange { xmin xmax } yrange { ymin ymax } zrange { zmin zmax } name regionname } where xmin, xmax, . . . are coordinates in meters, specifying the extents of the volume being dened. The regionname label species the name assigned to the region contained in the atlas. The name entry is optional; if not specied then the region name is taken from the object instance name, i.e., atlasname. Oxs ImageAtlas: This class is designed to allow an image le to be used to dene regions in terms of colors in the image. It is intended for use in conjunction with the Oxs AtlasScalarField and Oxs AtlasVectorField classes in circumstances where a small number of distinct species (materials) are being modeled. This is a generalization of the mask le functionality of the 2D solver (Sec. 17.2.3). For situations requiring continuous variation in material parameters, the script eld classes should be used in conjunction with the ReadFile MIF extension command. See the ColorField sample proc in the ReadFile documentation in Sec. 17.1.1 for an example of this technique. The Oxs ImageAtlas Specify block has the following form: Specify Oxs ImageAtlas:name { xrange { xmin xmax } yrange { ymin ymax } 36

zrange { zmin zmax } viewplane view image pic colormap { color-1 region name color-2 region name ... color-n region name } matcherror max color distance } The xrange, yrange, zrange entries specify the extent of the atlas, in meters. The viewplane view value should be one of the 3 two-letter codes xy, zx or yz, which specify the mapping of the horizontal and vertical axes of the image respectively to axes in the simulation. The image is scaled as necessary along each dimension to match the atlas extents along the corresponding axes. The image is overlaid through the entire depth of the perpendicular dimension, i.e., along the axis absent from the viewplane specication. The Oxs ImageAtlas class can be used inside a Oxs MultiAtlas object to specify regions in a multilayer structure. The image entry species the name of the image le to use. If the le path is relative, then it will be taken with respect to the directory containing the MIF le. The image format may be any of those recognized by any2ppm (Sec. 16.1). The le will be read directly by Oxs if it is in the P3 or P6 PPM formats, otherwise any2ppm will be automatically launched to perform the conversion. The colormap value is an even length list of color + region name pairs. The colors may be specied in any of several ways. The most explicit is to use one of the Tk numeric formats, #rgb, #rrggbb, #rrrgggbbb or #rrrrggggbbbb, where each r, g, and b is one hex digit (i.e., 0-9 or A-F) representing the red, green and blue components of the color, respectively. For example, #F00 is bright (full-scale) red, #800 would be a darker red, while #FF0 and #FFFF00 would both be bright yellow. Refer to the Tk GetColor documentation for details. For shades of gray the special notation grayD or greyD is available, where D is a decimal value between 0 and 100, e.g., grey0 is black and grey100 is white. Alternatively, one may use any of the symbolic names dened in the oommf/config/colors.def le, such as red, white and skyblue. When comparing symbolic names, spaces and capitalization are ignored. The list of symbolic names can be extended by adding additional les to the Color filename option in the options.tcl customization le (Sec. 2.3.2). Finally, one color in the colormap list may optionally be the special keyword default, which essentially represents all colors not in the colormap list. Each of the specied colors should be distinct, but the region names are allowed to be repeated as desired. The region names may be chosen arbitrarily, except the special 37

keyword universe is reserved for points not in any of the regions. This includes all points outside the atlas bounding box dened by the xrange, yrange, zrange entries, but may also include points inside that boundary. Pixels in the image are assigned to regions by comparing the color of the pixel to the list of colors specied in colormap. If the pixel color is closer to a colormap color than max color distance, then the colors are considered matched. If a pixel color matches exactly one colormap color, then the pixel is assigned to the corresponding region. If a pixel color matches more than one colormap color, the pixel is assigned to the region corresponding to the closest match. If a pixel color doesnt match any of the colormap colors, then it is assigned to the default region, which is the region paired with the default keyword. If default does not explicitly appear in the colormap colors list, then universe is made the default region. To calculate the distance between two colors, each color is rst converted to a scaled triplet of oating point red, green, and blue values, (r, g, b), where each component lies in the interval [0, 1], with (0, 0, 0) representing black and (1, 1, 1) representing white. For example, (0, 0, 1) is bright blue. Given two colors in this representation, the distance is computed using the standard Euclidean norm with uniform weights, i.e., the distance between (r1 , g1 , b1 ) and (r2 , g2 , b2 ) and is (r1 r2 )2 + (g1 g2 )2 + (b1 b2 )2 . Since the dierence in any one component is at most 1, the distance between any two colors is at most 3. As explained above, two colors are considered to match if the distance between them is less than the specied matcherror value. If max color distance is suciently small, then it may easily happen that a pixels color does not match any of the specied region colors, so the pixel would be assigned to the default region. On the other hand, if max color distance is larger than 3, then all colors will match, and no pixels will be assigned to the default region. If matcherror is not specied, then the default value for max color distance is 3, which means all colors match. The following example should help clarify these matters. Specify Oxs_ImageAtlas:atlas { xrange { 0 400e-9 } yrange { 0 200e-9 } zrange { 0 20e-9 } image mypic.gif viewplane "xy" colormap { blue cobalt red permalloy green universe 38

default cobalt } matcherror .1 } Blue pixels get mapped to the cobalt region and red pixels to the permalloy region. Green pixels are mapped to the universe non-region, which means they are considered to be outside the atlas entirely. This is a ne point, but comes into play when atlases with overlapping bounding boxes are brought together inside an Oxs MultiAtlas. To which region would an orange pixel be assigned? The scaled triplet representation for orange is (1, 0.647, 0), so the distance to blue is 1.191, the distance to red is 0.647, and the distance to green is 1.06. Thus the closest color is red, but 0.647 is outside the matcherror setting of 0.1, so orange doesnt match any of the colors and is hence assigned to the default region, which in this case is cobalt. On the other hand, if matcherror had been set to say 1, then orange and red would match and orange would be assigned to the permalloy region. Pixels with colors that are equidistant to and match more than one color in the colormap will be assigned to one of the closest color regions. The user should not rely on any particular selection, that is to say, the explicit matching procedure in this case is not dened. Oxs MultiAtlas: This atlas is built up as an ordered list of other atlases. The set of regions dened by the Oxs MultiAtlas is the union of the regions of all the atlases contained therein. The sub-atlases need not be disjoint, however each point is assigned to the region in the rst sub-atlas in the list that contains it, so the regions dened by the Oxs MultiAtlas are eectively disjoint. The Oxs MultiAtlas specify block has the form Specify Oxs MultiAtlas:name { atlas atlas 1 spec atlas atlas 2 spec ... xrange { xmin xmax } yrange { ymin ymax } zrange { zmin zmax } } Each atlas spec may be either a reference to an atlas dened earlier and outside the current Specify block, or else an inline, embedded atlas denition. The bounding box xrange, yrange and zrange specications are each optional. If not specied the corresponding range for the atlas bounding box is taken from the minimal bounding box containing all the sub-atlases.

39

If the atlases are not disjoint, then the regions as dened by an Oxs MultiAtlas can be somewhat dierent from those of the individual component atlases. For example, suppose regionA is a rectangular region in atlasA with corner points (5,5,0) and (10,10,10), and regionB is a rectangular region in atlasB with corner points (0,0,0) and (10,10,10). When composed in the order atlasA, atlasB inside an Oxs MultiAtlas, regionA reported by the Oxs MultiAtlas will be the same as regionA reported by atlasA, but regionB as reported by the Oxs MultiAtlas will be the L shaped volume of those points in atlasBs regionB not inside regionA. If the Oxs MultiAtlas is constructed with atlasB rst and atlasA second, then regionB as reported by the Oxs MultiAtlas would agree with that reported by atlasB, but regionA would be empty. NOTE: The attributes key label (cf. Sec. 17.1.2.5) is not supported by this class. Oxs ScriptAtlas: An atlas where the regions are dened via a Tcl script. The specify block has the form Specify Oxs ScriptAtlas:name { xrange { xmin xmax } yrange { ymin ymax } zrange { zmin zmax } regions { rname 1 rname 2 . . . rname n } script args { args request } script Tcl script } Here xmin, xmax, . . . are coordinates in meters, specifying the extents of the axesparallel rectangular parallelepiped enclosing the total volume being identied. This volume is subdivided into n sub-regions, using the names as given in the regions list. The script is used to assign points to the various regions. Appended to the script are the arguments requested by script args, in the manner explained in the User Dened Support Procedures section (Sec. 17.1.2.6) of the MIF 2.1 le format documentation. The value args request should be a subset of {relpt rawpt minpt maxpt span}. If script args is not specied, the default value relpt is used. When executed, the return value from the script should be an integer in the range 1 to n, indicating the user-dened region in which the point lies, or else 0 if the point is not in any of the n regions. Region index 0 is reserved for the implicit universe region, which is allencompassing. The following example may help clarify the discussion: proc Octs { cellsize x y z xmin ymin zmin xmax ymax zmax } { global RegionArray set xindex [expr {int(floor(($x-$xmin)/$cellsize))}] set yindex [expr {int(floor(($y-$ymin)/$cellsize))}] set zindex [expr {int(floor(($z-$zmin)/$cellsize))}] 40

set octant [expr {1+$xindex+2*$yindex+4*$zindex}] if {$octant<1 || $octant>8} { return 0 } return $octant } Specify Oxs_ScriptAtlas:octant { xrange {-20e-9 20e-9} yrange {-20e-9 20e-9} zrange {-20e-9 20e-9} regions { VIII V VII VI IV I III II } script_args { rawpt minpt maxpt } script { Octs 20e-9 } } This atlas divides the rectangular volume between (20, 20, 20) and (20, 20, 20) (nm) into eight regions, corresponding to the standard octants, I through VIII. The Octs Tcl procedure returns a value between 1 and 8, with 1 corresponding to octant VIII and 8 to octant II. The canonical octant ordering starts with I as the +x, +y, +z space, proceeds counterclockwise in the +z half-space, and concludes in the z halfspace with V directly beneath I, VI beneath II, etc. The ordering computed algorithmically in Octs starts with 1 for the x, y, z space, 2 for the +x, y, z space, 3 for the x, +y, z space, etc. The conversion between the two systems is accomplished by the ordering of the regions list. 7.3.2 Meshes

Meshes dene the discretization impressed on the simulation. There should be exactly one mesh declared in a MIF 2.1 le. The only standard mesh available at present is Specify Oxs RectangularMesh:name { cellsize { xstep ystep zstep } atlas atlas spec } This creates an axes parallel rectangular mesh across the entire space covered by atlas. The mesh sample rates along each axis are specied by cellsize (in meters). The mesh is cell-based, with the center of the rst cell one half step in from the minimal extremal point (xmin,ymin,ymax) for atlas spec. The name is commonly set to mesh, in which case the mesh object may be referred to by other Oxs Ext objects by the short name :mesh. 7.3.3 Energies

The following subsections describe the available energy terms. In order to be included in the simulation energy and eld calculations, each energy term must be declared in its own, 41

top-level Specify block, i.e., energy terms should not be declared inline inside other Oxs Ext objects. There is no limitation on the number of energy terms that may be specied in the input MIF le. Many of these terms have spatially varying parameters that are initialized via eld object spec entries (Sec. 7.3.6) in their Specify initialization block (see Sec. 17.1.2.2). Outputs: For each magnetization conguration, two standard outputs are provided by all energy terms: the scalar output Energy, which is the total energy in joules contributed by this energy term, and the vector eld output Field, which is the pointwise eld in A/m. If the code was compiled with the macro NDEBUG not dened, then there will be an additional scalar output, Calc count, which counts the number of times the term has been calculated in the current simulation. This is intended for debugging purposes only; this number should agree with the Energy calc count value provided by the evolver. Anisotropy Energy Oxs UniaxialAnisotropy: Uniaxial magneto-crystalline anisotropy. Specify block takes 2 parameters, crystalline anisotropy constant K1 (in J/m3 ) and anisotropy direction axis. The axis direction is an easy axis if K1>0, or is the normal to the easy plane if K1 < 0. Both may be varied cellwise across the mesh. The anisotropy constant is initialized with a scalar eld object, and the axis direction with an vector eld object. The axis directions should be unit vectors. The energy computed by this term is non-negative in all cases. Oxs CubicAnisotropy: Cubic magneto-crystalline anisotropy. Specify block takes 3 parameters, crystalline anisotropy constant K1 (in J/m3 ) and anisotropy directions axis1 and axis2. The third anisotropy axis is computed as the vector product, axis1 axis2. The axis directions are easy axes if K1>0, or hard axes if K1<0. All may be varied cellwise across the mesh. K1 is initialized with a scalar eld object, and the axis directions with vector eld objects. The axis directions should be unit vectors. The second axis, axis2, will be adjusted if necessary to be orthogonal to axis1. For each cell, if K1>0 then the computed energy will be non-negative, else if K1<0 then the computed energy will be non-positive. Exchange Energy Oxs Exchange6Ngbr: Standard 6-neighbor exchange energy. The exchange energy density contribution from cell i is given by Ei =
jNi

Aij

mi (mi mj ) 2 ij

(1)

where Ni is the set consisting of the 6 cells nearest to cell i, Aij is the exchange coecient between cells i and j in J/m, and ij is the discretization step size between cell i and cell j (in meters). The Specify block for this term has the form 42

Specify Oxs Exchange6Ngbr:name { default A value atlas atlas spec A { region-1 region-1 A11 region-1 region-2 A12 ... region-m region-n Amn } } The A block species Aij values on a region by region basis, where the regions are labels declared by atlas spec. This allows for specication of A both inside a given region (e.g., Aii ) and along interfaces between regions (e.g., Aij ). By symmetry, if Aij is specied, then the same value is automatically assigned to Aji as well. The default A value is applied to any otherwise unassigned Aij . Although one may specify Aij for any pair of regions i and j, it is only required and only active if the region pair are in contact. If long-range exchange interaction is required, use Oxs TwoSurfaceExchange. Oxs UniformExchange: Similar to Oxs Exchange6Ngbr, except the exchange constant A is uniform across all space. The Specify block is very simple, consisting of the label A with the desired exchange coecient value in J/m. Since A is not spatially varying, it is initialized with a simple constant (as opposed to a scalar eld object). Oxs ExchangePtwise: The exchange coecient Ai is specied on a point-by-point (or cell-by-cell) basis, as opposed to the pairwise specication model used by Oxs Exchange6Ngbr. The exchange energy at a cell i is computed across its nearest 6 neighbors, Ni , using the formula Ei =
jNi

Aij,e

mi (mi mj ) 2 ij

where ij is the discretization step size from cell i to cell j in meters, and Aij,e = 2Ai Aj , Ai + A j

with Aij,e = 0 if Ai and Aj are 0. Note that Aij,e satises the following properties: Aij,e = Aji,e Aij,e = Ai if Ai = Aj lim Aij,e = 0. 43

Ai 0

Additionally, if Ai and Aj are non-negative, min(Ai , Aj ) Aij,e max(Ai , Aj ). Evaluating the exchange energy with this formulation of Aij,e is equivalent to nding the minimum possible exchange energy between cells i and j under the assumption that Ai is constant in each of the two cells. Similar considerations are made in computing the exchange energy for a 2D variable thickness model [13]. The Specify block for Oxs ExchangePtwise has the form Specify Oxs ExchangePtwise:name { A scalareld spec } where scalareld spec is an arbitrary scalar eld object (Sec. 7.3.6) returning the desired exchange coecient in J/m. Oxs TwoSurfaceExchange: Provides long-range bilinear and biquadratic exchange. Typically used to simulate RKKY-style coupling across non-magnetic spacers in spinvalves. The specify block has the form Specify Oxs TwoSurfaceExchange:name { sigma value sigma2 value surface1 { atlas atlas spec region region label scalarfield scalareld spec scalarvalue eldvalue scalarside sign } surface2 { atlas atlas spec region region label scalarfield scalareld spec scalarvalue eldvalue scalarside sign } } Here sigma and sigma2 are the bilinear and biquadratic surface (interfacial) exchange energies, in J/m2 . Either is optional, with default value 0. The surface1 and surface2 sub-blocks describe the two interacting surfaces. Each description consists of 5 name-values pairs, which must be listed in the order shown. In each sub-block, atlas spec species an atlas, and region label species a region in that atlas. These bound the extent of the desired surface. The 44

following scalareld, scalarvalue and scalarside entries dene a discretized surface inside the bounding region. Here scalareld spec references a scalar eld object, eldvalue should be a oating point value, and sign should be a single character, either or +. If sign is , then any point for which the scalar eld object takes a value less than or equal to the scalarvalue value is considered to be inside the surface. Conversely, if sign is +, then any point for which the scalar eld object has value greater than or equal to the scalarvalue value is considered to be inside the surface. The discretized surface determined is the set of all points on the problem mesh that are in the bounding region, are either on the surface or lie on the inside side of the surface, and have a neighbor that is on the outside side of the surface. In this way, 2 discrete lists of cells representing the two surfaces are obtained. Each cell from the rst list (representing surface1) is then matched with the closest cell from the second list (i.e., from surface2). Note the asymmetry in this matching process: each cell from the rst list is included in exactly one match, but there may be cells in the second list that are included in many match pairs, or in none. If the two surfaces are of dierent sizes, then in practice typically the smaller will be made the rst surface, because this will usually lead to fewer multiply-matched cells, but this designation is not required. The resulting exchange energy density at cell i on one surface from matching cell j on the other is given by Eij = [1 mi mj ] + 2 1 (mi mj )2 ij

where and 2 , respectively, are the bilinear and biquadratic surface exchange coecients between the two surfaces, in J/m2 , mi and mj are the normalized, unit spins (i.e., magnetization directions) at cells i and j, and ij is the discretization cell size in the direction from cell i towards cell j, in meters. Note that if is negative, then the surfaces will be anti-ferromagnetically coupled. Likewise, if 2 is negative, then the biquadratic term will favor orthogonal alignment. The following example produces an antiferromagnetic exchange coupling between the lower surface of the top layer and the upper surface of the bottom layer, across a middle spacer layer. The simple Oxs LinearScalarField object is used here to provide level surfaces that are planes orthogonal to the z-axis. In practice this example might represent a spinvalve, where the top and bottom layers would be composed of ferromagnetic material and the middle layer could be a copper spacer. Specify Oxs_MultiAtlas:atlas { atlas { Oxs_BoxAtlas { name top xrange {0 500e-9} 45

yrange {0 250e-9} zrange {6e-9 9e-9} } } atlas { Oxs_BoxAtlas { name spacer xrange {0 500e-9} yrange {0 250e-9} zrange {3e-9 6e-9} } } atlas { Oxs_BoxAtlas { name bottom xrange {0 500e-9} yrange {0 250e-9} zrange {0 3e-9} } } } Specify Oxs_LinearScalarField:zheight { vector {0 0 1} norm 1.0 } Specify Oxs_TwoSurfaceExchange:AF { sigma -1e-4 surface1 { atlas :atlas region bottom scalarfield :zheight scalarvalue 3e-9 scalarside } surface2 { atlas :atlas region top scalarfield :zheight scalarvalue 6e-9 scalarside + } } Oxs RandomSiteExchange: A randomized exchange energy. The Specify block has the form Specify Oxs RandomSiteExchange:name { 46

linkprob probability Amin A lower bound Amax A upper bound } Each adjacent pair of cells i, j, is given linkprob probability of having a non-zero exchange coecient Aij . Here two cells are adjacent if they lie in each others 6neighborhood. If a pair is found to have a non-zero exchange coecient, then Aij is drawn uniformly from the range [Amin, Amax]. The exchange energy is computed using (1), the formula used by the Oxs Exchange6Ngbr energy object. The value Aij for each pair of cells is determined during problem initialization, and is held xed thereafter. The limits A lower bound and A upper bound may be any real numbers; negative values may be used to weaken the exchange interaction arising from other exchange energy terms. The only restriction is that A lower bound must not be greater than A upper bound. The linkprob value probability must lie in the range [0, 1]. Self-Magnetostatic Energy Oxs Demag: Standard demagnetization energy term, which is built on the assumption that the magnetization is constant in each cell, and computes the average demagnetization eld through the cell using formulae from [2, 12] and convolution via the Fast Fourier Transform. The Specify initialization string should be an empty string, typically denoted by {}. Oxs SimpleDemag: This is the same as the Oxs Demag object, except that the implementation does not use any of the of the symmetries inherent in the demagnetization kernel, or special properties of the Fourier Transform when applied to a real (non-complex) function. As a result, the source code for this implementation is considerably simpler than for Oxs Demag, but the run time performance and memory usage are poorer. Oxs SimpleDemag is included for validation checks, and as a base for user-dened demagnetization implementations. The Specify initialization string for Oxs SimpleDemag is an the empty string, i.e., {}. Zeeman Energy Oxs UZeeman: Uniform (homogeneous) applied eld energy. The specify block for this term takes an optional multiplier entry, and a required eld range list Hrange. The eld range list should be a compound list, with each sublist consisting of 7 elements: the rst 3 denote the start eld for the range, the next 3 denote the end eld for the range, and the last element species the number of (linear) steps through the range. If the step count is 0, then the range consists of the start eld only. If the step count is bigger than 0, then the start eld is skipped over if and only if it is the same eld that ended the previous range (if any). 47

The elds specied in the range entry are nominally in A/m, but these values are multiplied by multiplier, which may be used to eectively change the units. For example, Specify Oxs UZeeman { multiplier 795.77472 Hrange { { 0 0 0 10 0 0 2 } { 10 0 0 0 0 0 1 } } } The applied eld steps between 0 mT, 5 mT, 10 mT and back to 0 mT. (Note that 795.77472=0.001/0 .) Oxs FixedZeeman: Non-uniform, non-time varying applied eld. This can be used to simulate a biasing eld. The specify block takes one required parameter, which denes the eld, and one optional parameter, which species a multiplication factor. Specify Oxs FixedZeeman:name { field vector eld spec multiplier multiplier } The default value for multiplier is 1. Oxs ScriptUZeeman: Spatially uniform applied eld, potentially varying as a function of time and stage, determined by a Tcl script. The Specify block has the form Specify Oxs ScriptUZeeman:name { script args { args request } script Tcl script multiplier multiplier } Here script indicates the Tcl script to use. The script is called once each iteration. Appended to the script are the arguments requested by script args, in the manner explained in the User Dened Support Procedures section (Sec. 17.1.2.6) of the MIF 2.1 le format documentation. The value args request should be a subset of {stage stage time total time}. If script args is not specied, the default argument list is the complete list in the aforementioned order. The units for the time arguments are seconds. The return value from the script should be a 6-tuple of numbers, {Hx, Hy, Hz, dHx, dHy, dHz}, representing the applied eld and the time derivative of the applied eld. The eld as a function of time must be dierentiable for the duration of each stage. Discontinuities are permitted between stages. 48

The eld and its time derivative are multiplied by the multiplier value before use. The nal eld value should be in A/m; if the Tcl script returns the eld in T, then a multiplier value of 1/0 (approx. 795774.72) should be applied to convert the Tcl result into A/m. The default value for multiplier is 1. The following example produces a sinusoidally varying eld of frequency 1 GHz and amplitude 800 A/m, directed along the x-axis. Specify Oxs_ScriptUZeeman { script_args total_time script SineField } proc SineField { total_time } { set PI [expr {4*atan(1.)}] set Amp 800.0 set Freq [expr {1e9*(2*$PI)}] set Hx [expr {$Amp*sin($Freq*$total_time)}] set dHx [expr {$Amp*$Freq*cos($Freq*$total_time)}] return [list $Hx 0 0 $dHx 0 0] } Oxs TransformZeeman: Essentially a combination of the Oxs FixedZeeman and Oxs ScriptUZeeman classes, where an applied eld is produced by applying a spatially uniform, but time and stage varying linear transform to a spatially varying but temporally static eld. The transform is specied by a Tcl script. The Specify block has the form Specify Oxs TransformZeeman:name { field vector eld spec type transform type script Tcl script script args { args request } multiplier multiplier } The eld specied by vector eld spec is evaluated during problem initialization and held throughout the life of the problem. On each iteration, the specied Tcl script is called once. Appended to the script are the arguments requested by script args, as explained in the User Dened Support Procedures section (Sec. 17.1.2.6) of the MIF 2.1 le format documentation. The value for script args should be a subset of {stage stage time total time}. The default value for script args is the complete list in the aforementioned order. The time arguments are specied in seconds. The script return value should dene a 3x3 linear transform and its time derivative. The transform must be dierentiable with respect to time throughout each 49

stage, but is allowed to be discontinuous between stages. The transform is applied pointwise to the xed eld obtained from vector eld spec, which is additionally scaled by multiplier. The multiplier entry is optional, with default value 1.0. The type transform type value declares the format of the result returned from the Tcl script. Recognized formats are identity, diagonal, symmetric and general. The most exible is general, which indicates that the return from the Tcl script is a list of 18 numbers, dening a general 3x3 matrix and its 3x3 matrix of time derivatives. The matrices are specied in row-major order, i.e., M1,1 , M1,2 , M1,3 , M2,1 , M2,2 , . . . . Of course, this is a long list to construct; if the desired transform is symmetric or diagonal, then the type may be set accordingly to reduce the size of the Tcl result string. Scripts of the symmetric type return 12 numbers, the 6 upper diagonal entries in row-major order, i.e., M1,1 , M1,2 , M1,3 , M2,2 , M2,3 , M3,3 , for both the transformation matrix and its time derivative. Use the diagonal type for diagonal matrices, in which case the Tcl script result should be a list of 6 numbers. The simplest transform type is identity, which is the default. This identies the transform as the identity matrix, which means that eectively no transform is applied, aside from the multiplier option which is still active. For the identity transform type, script and script args should not be specied, and Oxs TransformZeeman becomes a clone of the Oxs FixedZeeman class. The following example produces a 1000 A/m eld that rotates in the xy-plane at a frequency of 1 GHz: Specify Oxs_TransformZeeman { type general script {Rotate 1e9} field {0 1000. 0} } proc Rotate { freq stage stagetime totaltime } { global PI set w [expr {$freq*2*$PI}] set ct [expr {cos($w*$totaltime)}] set mct [expr {-1*$ct}] ;# "mct" is "minus set st [expr {sin($w*$totaltime)}] set mst [expr {-1*$st}] ;# "mst" is "minus return [list $ct $mst 0 \ $st $ct 0 \ 0 0 1 \ [expr {$w*$mst}] [expr {$w*$mct}] [expr {$w*$ct}] [expr {$w*$mst}] 0 0 } 50

cosine (w)t" sine (w)t"

0 \ 0 \ 0]

This particular eect could be obtained using the Oxs ScriptUZeeman class, because the field is uniform. But the eld was taken uniform only to simplify the example. The vector eld spec may be any Oxs vector eld object (Sec. 7.3.6). For example, the base eld could be large in the center of the sample, and decay towards the edges. In that case, the above example would generate an applied rotating eld that is concentrated in the center of the sample. Oxs StageZeeman: The Oxs StageZeeman class provides spatially varying applied elds that are updated once per stage. In its general form, the eld at each stage is provided by an Oxs vector eld object (Sec. 7.3.6) determined by a user supplied Tcl script. There is also a simplied interface that accepts a list of vector eld les (Sec. 19), one per stage, that are used to specify the applied eld. The Specify block takes the form Specify Oxs StageZeeman:name { script Tcl script files { list of les } stage count number of stages multiplier multiplier } The initialization string should specify either script or files, but not both. If a script is specied, then each time a new stage is started in the simulation, a Tcl command is formed by appending to Tcl script the 0-based integer stage number. This command should return a reference to an Oxs VectorField object, as either the instance name of an object dened via a top-level Specify block elsewhere in the MIF le, or as a two item list consisting of the name of an Oxs VectorField class and an appropriate initialization string. In the latter case the Oxs VectorField object will be created as a temporary object via an inlined Specify call. The following example should help clarify the use of the script parameter. Specify Oxs_StageZeeman { script SlidingFieldSpec stage_count 11 } proc SlidingFieldSpec { stage } { set xcutoff [expr {double($stage)/10.}] set spec Oxs_ScriptVectorField lappend spec [subst { atlas :atlas script {SlidingField $xcutoff} }] return $spec 51

} proc SlidingField { xcutoff xrel yrel zrel } { if {$xrel>$xcutoff} { return [list 0. 0. 0.] } return [list 2e4 0. 0.] } The SlidingFieldSpec proc is used to generate the initialization string for an Oxs ScriptVectorField vector eld object, which in turn uses the SlidingField proc to specify the applied eld on a position-by-position basis. The resulting eld will be 2 104 A/m in the positive x-direction at all points with relative x-coordinate larger than $stage/10., and 0 otherwise. $stage is the stage index, which here is one of 0, 1, . . . , 10. For example, if $stage is 5, then the left half of the sample will see a 2 104 A/m eld directed to the right, and the right half of the sample will see none. The return value from SlidingFieldSpec in this case will be Oxs_ScriptVectorField { atlas :atlas script {SlidingField 0.5} } The :atlas reference is to an Oxs Atlas object dened elsewhere in the MIF le. The stage count parameter lets the Oxs Driver (Sec. 7.3.5) know how many stages the Oxs StageZeeman object wants. A value of 0 indicates that the object is prepared for any range of stages. Zero is the default value for stage count when using the Tcl script interface. The example above made use of two scripts, one to specify the Oxs VectorField object, and one used internally by the Oxs ScriptVectorField object. But any Oxs VectorField class may be used, as in the next example. Specify Oxs_StageZeeman { script FileField stage_count 3 } proc FileField { stage } { set filelist { field-a.ohf field-b.ohf field-c.ohf } set spec Oxs_FileVectorField lappend spec [subst { atlas :atlas file [lindex $filelist $stage] }] return $spec } 52

The FileField proc yields a specication for an Oxs FileVectorField object that loads one of three les, field-a.ohf, field-b.ohf, or field-c.ohf, depending on the stage number. Specifying applied elds from a sequence of les is common enough to warrant a simplied interface. This is the purpose of the les parameter: Specify Oxs_StageZeeman { files { field-a.ohf field-b.ohf field-c.ohf } } This is essentially equivalent to the preceding example, with two dierences. First, stage count is not needed because Oxs StageZeeman knows the length of the list of les. You may specify stage count, but the default value is the length of the files list. This is in contrast to the default value of 0 when using the script interface. If stage count is set larger than the le list, then the last le is repeated as necessary to reach the specied size. The second dierence is that no Oxs Atlas is specied when using the files interface. The Oxs FileVectorField object spatially scales the eld read from the le to match a specied volume. Typically a volume is specied by explicit reference to an atlas, but with the files interface to Oxs StageZeeman the le elds are implicitly scaled to match the whole of the meshed simulation volume. This is the most common case; to obtain a dierent spatial scaling use the script interface as illustrated above with a dierent atlas or an explicit x/y/z-range specication. The list of les value is interpreted as a grouped list. See the notes in Sec. 17.1.2.3 for details on grouped lists. The remaining Oxs StageZeeman parameter is multiplier. The value of this parameter is applied as a scale factor to the eld magnitude on a point-by-point basis. For example, if the eld returned by the Oxs VectorField object were in Oe, instead of the required A/m, then multiplier could be set to 79.5775 to perform the conversion. The direction of the applied eld can be reversed by supplying a negative multiplier value. 7.3.4 Evolvers

Evolvers are responsible for updating the magnetization conguration from one step to the next. There are two types of evolvers, time evolvers, which track Landau-Lifshitz-Gilbert dynamics, and minimization evolvers, which locate local minima in the energy surface through direct minimization techniques. Evolvers are controlled by drivers (Sec. 7.3.5), and must be matched with the appropriate driver type, i.e., time evolvers must be paired with time drivers, and minimization evolvers must be paired with minimization drivers. The drivers hand a magnetization conguration to the evolvers with a request to advance the conguration by one step (also called an iteration). It is the role of the drivers, not the evolvers, to 53

determine when a simulation stage or run is complete. Specify blocks for evolvers contain parameters to control all aspects of individual stepwise evolution, but stopping criteria are communicated in the Specify block of the driver, not the evolver. There is currently one representative of each type of evolver in the standard OOMMF distribution, time evolver Oxs EulerEvolve and minimization evolver Oxs CGEvolve. Oxs EulerEvolve: Time evolver implementing a simple rst order forward Euler method with step size control on the Landau-Lifshitz ODE [7, 9]: dM | | = | | M He M (M He ) , (2) dt Ms where M is the magnetization, He is the eective eld, is the Landau-Lifshitz gyromagnetic ratio, and is the damping constant. The Gilbert form dM dM = || M He + M , dt Ms dt (3)

where is the Gilbert gyromagnetic ratio, is mathematically equivalent to the LandauLifshitz form under the relation = (1 + 2 ) . The Specify block has the form Specify Oxs EulerEvolve:name { alpha gamma LL gamma G do precess precess min timestep minimum stepsize max timestep maximum stepsize fixed spins { atlas spec region1 region2 . . . } start dm m error rate rate absolute step error abs error relative step error rel error step headroom headroom } All the entries have default values, but the ones most commonly adjusted are listed rst. The options alpha, gamma LL and gamma G are as in the Landau-Lifshitz-Gilbert ODE (2,3), where the units on and are m/As and is dimensionless. At most one 54

of and should be specied. If neither is specied, then the default is = 2.211105 . (Because of the absolute value convention adopted on and in (2,3), the sign given to the value of gamma LL or gamma G in the Specify block is irrelevant.) The default value for is 0.5, which is large compared to experimental values, but allows simulations to converge to equilibria in a reasonable time. However, for accurate dynamic studies it is important to assign an appropriate value to . The do precess value should be either 1 or 0, and determines whether or not the precession term in the Landau-Lifshitz ODE (i.e., the rst term on the righthand side in (2)) is used. If precess is 0, then precession is disabled and the simulation evolves towards equilibrium along a steepest descent path. The default value is 1. The min timestep and max timestep parameters provide soft limits on the size of steps taken by the evolver. The minimum value may be overridden by the driver if a smaller step is needed to meet time based stopping criteria. The maximum value will be ignored if a step of that size would produce a magnetization state numerically indistinguishable from the preceding state. The units for min timestep and max timestep are seconds. Default values are 0 and 1010 respectively. The optional xed spins entry allows the magnetization in selected regions of the simulation to be frozen in its initial conguration. The value portion of the entry should be a list, with the rst element of the list being either an inline atlas denition (grouped as a single item), or else the name of a previously dened atlas. The remainder of the list are names of regions in that atlas for which the magnetization is to be be xed, i.e., M(t) = M(0) for all time t for all points in the named regions. Fields and energies are computed and reported normally across these regions. Although any atlas may be used, it is frequently convenient to set up an atlas with special regions dened expressly for this purpose. The stepsize for the rst candidate iteration in the problem run is selected so that the maximum change in the normalized (i.e., unit) magnetization m is the value specied by start dm. The units are degrees, with default value 0.01. The four remaining entries, error rate, absolute step error, relative step error, and step headroom, control ne points of stepsize selection, and are intended for advance use only. Given normalized magnetization mi (t) at time t and position i, and candidate magnetization mi (t + t) at time t + t, the error at position i is estimated to be Errori = |mi (t + t) mi (t)| t / 2, where the derivative with respect to time, m, is computed using the Landau-Lifshitz ODE (2). First order methods essentially assume that m is constant on the interval [t, t + t]; the above formula uses the dierence in m at the endpoints of the interval to estimate (guess) how untrue that assumption is. A candidate step is accepted if the maximum error across all positions i is smaller than absolute step error, error rate t, and relative step error |mmax |t, 55

 where |mmax | is the maximum value of |mi | across all i at time t. If the step is rejected, then a smaller stepsize is computed that appears to pass the above tests, and a new candidate step is proposed using that smaller stepsize times step headroom. Alternatively, if the step is accepted, then the error information is used to determine the stepsize for the next step, modied in the same manner by step headroom. The error calculated above is in terms of unit magnetizations, so the natural units are radians or radians/second. Inside the Specify block, however, the error rate and absolute step error are specied in degrees/nanosecond and degrees, respectively; they are converted appropriately inside the code before use. The relative step error is a dimensionless quantity, representing a proportion between 0 and 1. The error check controlled by each of these three quantities may be disabled by setting the quantity value to -1. They are all optional, with default values of -1 for error rate, 0.2 for absolute step error, and 0.2 for relative step error. The headroom quantity should lie in the range (0, 1), and controls how conservative the code will be in stepsize selection. If headroom is too large, then much computation time will be lost computing candidate steps that fail the error control tests. If headroom is small, then most candidate steps will pass the error control tests, but computation time may be wasted calculating more steps than are necessary. The default value for headroom is 0.85. In addition to the above error control tests, a candidate step will also be rejected if the total energy, after adjusting for eects due to any time varying external eld, is found to increase. In this case the next candidate stepsize is set to one half the rejected stepsize. The Oxs EulerEvolve module provides ve scalar outputs and three vector eld outputs. The scalar outputs are Max dm/dt: maximum |dm/dt|, in degrees per nanosecond; m is the unit magnetization direction. Total energy: in joules. Delta E: change in energy between last step and current step, in joules. dE/dt: derivative of energy with respect to time, in joules per second. Energy calc count: number of times total energy has been calculated. The vector eld outputs are Total eld: total eective eld H in A/m. mxH: torque in A/m; m is the unit magnetization direction, H is the total eective eld. dm/dt: derivative of spin m with respect to time, in radians per second.

56

Oxs CGEvolve: The minimization evolver is Oxs CGEvolve, which is an in-development conjugate gradient minimizer with no preconditioning. The Specify block has the form Specify Oxs CGEvolve:name { gradient reset count count minimum bracket step minbrack maximum bracket step maxbrack line minimum relwidth relwidth fixed spins { atlas spec region1 region2 . . . } } All entries have default values. The evolution to an energy minimum precedes by a sequence of line minimizations. Each line represents a one dimensional ane subspace in the 3N dimensional space of possible magnetization congurations, where N is the number of spins in the simulation. Once a minimum has been found along a line, a new direction is chosen that is ideally orthogonal to all preceding directions, but related to the gradient of the energy taken with respect to the magnetization. In practice the line direction sequence cannot be extended indenitely; the parameter gradient reset count controls the maximum number of line directions selected before resetting the process. The default value for count is 42. Because the rst line in the sequence is selected along the gradient direction, setting count to 1 eectively turns the algorithm into a steepest descent minimization method. Once a minimization direction has been selected, the rst stage of the line minimization is to bracket the minimum energy on that line, i.e., given a start point on the line the location of the minimum from the previous line minimizationnd another point on the line such that the energy minimum lies between those two points. As one moves along the line, the spins in the simulation rotate, with one spin rotating faster than (or at least as fast as) all the others. If the start point was not the result of a successful line minimization from the previous stage, then the rst bracket attempt step is sized so that the fastest moving spin rotates through the angle specied by minimum bracket step. In the more usual case that the start point is a minimum from the previous line minimization stage, the initial bracket attempt step size is set to the distance between the current start point and the start point of the previous line minimization stage. The energy and gradient of the energy are examined at the candidate bracket point to test if an energy minimum lies in the interval. If not, the interval is extended, based on the size of the rst bracket attempt interval and the derivatives of the energy at the

57

interval endpoints. This process is continued until either a minimum is bracketed or the fastest moving spin rotates through the angle specied by maximum bracket step. If the bracketing process is successful, then a one dimensional minimization is carried out in the interval, using both energy and energy derivative information. Each step in this process reduces the width of the bracketing interval. This process is continued until the width of the interval relative to the distance of the interval from the start point (i.e., the stop point from the previous line minimization process) is less than line minimum relwidth. The stop point, i.e., the eective minimum, is then taken to be the endpoint of the nal interval with smallest energy. If the bracketing process is unsuccessful, i.e., the check for bracketed energy minimum failed at the maximum bracket interval size allowed by maximum bracket step, then the maximum bracket endpoint is accepted as the next point in the minimization iteration. Once the line minimum stop point has been selected, the next iteration begins with selection of a new line direction, as described above, except in the case where the stop point was not obtained as an actual minimum, but rather by virtue of satisfying the maximum bracket step constraint. In that case the orthogonal line sequence is reset, in the same manner as when the gradient reset count switch is triggered, and the next line direction is taken directly from the energy gradient. There are several factors to bear in mind when selecting values for the parameters minimum bracket step, maximum bracket step, and line minimum relwidth. If minimum bracket step is too small, then it may take a great many steps to obtain an interval large enough to bracket the minimum. If minimum bracket step is too large, then the bracket interval will be unnecessarily generous, and many steps may be required to locate the minimum inside the bracketing interval. However, this value only comes into play when resetting the line minimization direction sequence, so the setting is seldom critical. It is specied in degrees, with default value 0.05. If maximum bracket step is too small, then the minima will be mostly not bracketed, and the minimization will degenerate into a type of steepest descent method. On the other hand, if maximum bracket step is too large, then the line minimizations may draw the magnetization far away from a local energy minimum (i.e., one on the full 3N dimensional magnetization space), eventually ending up in a dierent, more distant minimum. The value for maximum bracket step is specied in degrees, with default value 10. The line minimum relwidth value determines the precision of the individual line minimizations, not the total minimization procedure, which is governed by the stopping criteria specied in the drivers Specify block. However, the line minimum relwidth value is important because the precision of the line minimizations aects the the line direction sequence orthogonality. If line minimum relwidth is too coarse, then the selected line directions will quickly drift away from mutual orthogonality. Conversely, selecting line minimum relwidth too ne will produce additional line minimization steps that do nothing to improve convergence towards the energy minimum in the full 58

3N dimensional magnetization space. The default value for line minimum relwidth is 106 . Referring back to the Oxs CGEvolve Specify block, the xed spins entry performs the same function as for the Oxs EulerEvolve class. The Oxs CGEvolve module provides seven scalar outputs and two vector eld outputs. The scalar outputs are Max mxHxm: maximum |m H m|, in A/m; m is the unit magnetization direction. Total energy: in joules. Delta E: change in energy between last step and current step, in joules. Energy calc count: number of times total energy has been calculated. Bracket count: total number of attempts required to bracket energy minimum during rst phase of line minimization procedures. Line min count: total number of minimization steps during second phase of line minimization procedures (i.e., steps after minimum has been bracketed). Cycle count: number of line direction selections. The vector eld outputs are H: total eective eld in A/m. mxHxm: in A/m; m is the unit magnetization direction. 7.3.5 Drivers

While evolvers (Sec. 7.3.4) are responsible for moving the simulation forward in individual steps, drivers coordinate the action of the evolver on the simulation as a whole, by grouping steps into tasks, stages and runs. Tasks are small groups of steps that can be completed without adversely aecting user interface responsiveness. Stages are larger units specied by the MIF problem description; in particular, problem parameters are not expected to change in a discontinuous manner inside a stage. The run is the complete sequence of stages, from problem start to nish. The driver detects when stages and runs are nished, using criteria specied in the MIF problem description, and can enforce constraints, such as making sure stage boundaries respect time stopping criteria. There are two drivers in Oxs, Oxs TimeDriver for controlling time evolvers such as Oxs EulerEvolve, and Oxs MinDriver for controlling minimization evolvers like Oxs CGEvolve. Oxs TimeDriver: The Oxs time driver is Oxs TimeDriver. The specify block has the form

59

Specify Oxs TimeDriver:name { evolver evolver spec mesh mesh spec Ms scalar eld spec m0 vector eld spec stopping dm dt torque criteria stopping time time criteria stage iteration limit stage iteration count total iteration limit total iteration count stage count number of stages stage count check test basename base le name scalar output format format vector field output format { style precision } } The rst four parameters, evolver, mesh, Ms and m0 provide references to a time evolver, a mesh, a scalar eld and a vector eld, respectively. Here Ms is the pointwise saturation magnetization in A/m, and m0 is the initial conguration for the magnetization unit spins, i.e., |m| = 1 at each point. These four parameters are required. The next group of 3 parameters control stage stopping criteria. The stopping dm dt value, in degrees per nanosecond, species that a stage should be considered complete when the maximum |dm/dt| across all spins drops below this value. Similarly, the stopping time value species the maximum Simulation time, i.e., the LandauLifshitz-Gilbert ODE (2,3) time, allowed per stage. For example, if time criteria is 109 , then no stage will evolve for more than 1 ns. If there were a total of 5 stages in the simulation, then the total simulation time would be not more than 5 ns. The third way to terminate a stage is with a stage iteration limit. This is a limit on the number of successful evolver steps allowed per stage. A stage is considered complete when any one of these three criteria are met. Each of the criteria may be either a single value, which is applied to every stage, or else a grouped list (Sec. 17.1.2.3) of values. If the simulation has more stages than a criteria list has entries, then the last criteria value is applied to all additional stages. These stopping criteria all provide a default value of 0, meaning no constraint, but usually at least one is specied since otherwise there is no automatic stage termination control. For quasi-static simulations, a stopping dm dt value in the range of 1.0 to 0.01 is reasonable; the numerical precision of the energy calculations usually makes in not possible to obtain |dm/dt| much below 0.001 degree per nanosecond. The total iteration limit, stage count and stage count check parameters involve simulation run completion conditions. The default value for the rst is 0, interpreted as no limit, but one may limit the total number of steps performed in a simulation by specifying a positive integer value here. The more usual run completion condition 60

is based on the stage count. If a positive integer value is specied for stage count, then the run will be considered complete when the stage count reaches that value. If stage count is not specied, or is given the value 0, then the eective number of stages value is computed by examining the length of the stopping criteria lists, and also any other Oxs Ext object that has stage length expectations, such as Oxs UZeeman. The longest of these is taken to be the stage limit value. Typically these lengths, along with stage count if specied, will all be the same, and any dierences indicate an error in the MIF le. Oxs will automatically test this condition, provided stage count check is set to 1, which is the default value. Stage length requests of 0 or 1 are ignored in this test, since those lengths are commonly used to represent sequences of arbitrary length. At times a short sequence is intentionally specied that is meant to be implicitly extended to match the full simulation stage length. In this case, the stage count check can be disabled by setting test to 0. The value associated with basename is used as a prex for output lename construction by some of the data output routines. It may represent either an absolute path (i.e., one with a leading /), or else a relative path taken with respect to the directory containing the MIF le. This an optional eld with default value oxs. The value assigned to scalar output format should be a C-style printf string specifying the output format for DataTable output (this includes output sent to mmDataTable (Sec. 11), mmGraph (Sec. 12), and mmArchive (Sec. 14)). This is optional, with default value %.17g. The value associated with vector eld output format should be a two element list, specifying the style and precision for vector eld output sent to mmDisp (Sec. 13) and mmArchive (Sec. 14). The rst element in the list should be one of binary or text, specifying the output style. If binary output is selected, then the second element specifying precision should be either 4 or 8, denoting the individual eld component binary output length in bytes. For text output, the second element should be a C-style printf string like that used by scalar output format. The default value for vector field output format is binary 8. Oxs TimeDriver provides seven scalar outputs and two vector eld outputs. The scalar outputs are Stage: current stage number, counting from 0. Stage iteration: number of successful evolver steps in the current stage. Iteration: number of successful evolver steps in the current simulation. Simulation time: Landau-Lifshitz-Gilbert evolution time, in seconds. Mx: magnetization component in the x direction, averaged across the entire simulation, in A/m. My: magnetization component in the y direction, averaged across the entire simulation, in A/m. Mz: magnetization component in the z direction, averaged across the entire simulation, in A/m. 61

The vector eld outputs are Magnetization: magnetization vector M, in A/m. Spin: unit magnetization m. This output ignores the vector field output format precision setting, instead always exporting at full precision. Oxs MinDriver: The Oxs driver for controlling minimization evolvers is Oxs MinDriver. The specify block has the form Specify Oxs MinDriver:name { evolver evolver spec mesh mesh spec Ms scalar eld spec m0 vector eld spec stopping mxHxm torque criteria stage iteration limit stage iteration count total iteration limit total iteration count stage count number of stages stage count check test basename base le name scalar output format format vector field output format { style precision } } These parameters are the same as those described for the Oxs TimeDriver, except that stopping mxHxm replaces stopping dm dt, and there is no analogue to stopping time. The value for stopping mxHxm is in A/m, and may be a grouped list (Sec. 17.1.2.3). This is a required value. Choice depends on the particulars of the simulation, but typical values are in the range 10 to 0.1. Limits in the numerical precision of the energy calculations usually makes it not possible to obtain |m H m| below about 0.01 A/m. Oxs MinDriver provides six scalar outputs and two vector eld outputs. The scalar outputs are Stage: current stage number, counting from 0. Stage iteration: number of successful evolver steps in the current stage. Iteration: number of successful evolver steps in the current simulation. Mx: magnetization component in the x direction, averaged across the entire simulation, in A/m. My: magnetization component in the y direction, averaged across the entire simulation, in A/m. 62

 Mz: magnetization component in the z direction, averaged across the entire simulation, in A/m. The vector eld outputs are Magnetization: magnetization vector M, in A/m. Spin: unit magnetization m. This output ignores the vector field output format precision setting, instead always exporting at full precision. 7.3.6 Field Objects

Field objects return values (either scalar or vector) as a function of position. These are frequently used as embedded objects inside Specify blocks of other Oxs Ext objects to initialize spatially varying quantities, such as material parameters or initial magnetization spin congurations. Units on the returned values will be dependent upon the context in which they are used. Scalar eld objects are documented rst. Vector eld objects are considered farther below. Oxs UniformScalarField: Returns the same constant value regardless of the import position. The Specify block takes one parameter, value, which is the returned constant value. Oxs AtlasScalarField: Denes values that are constant across individual regions of an Oxs Atlas. The Specify block looks like Specify Oxs AtlasScalarField:value { atlas atlas spec default value value values { region1 label value1 region2 label value2 ... } } The specied atlas is used to map cell locations to regions, and the corresponding value from the values sub-block is assigned to that cell. The default value entry is optional; if specied, and if a cells region is not included in the values sub-block, then the default value value is used. If default value is not specied, then missing regions will raise an error. Oxs LinearScalarField: Returns a value that varies linearly with position. The Specify block has the form: 63

Specify Oxs LinearScalarField:name { vector { vx vy vz } norm value } If optional value norm is specied, then the given vector is rst scaled to the requested size. For any given point (x, y, z), the scalar function value returned by this object will be xvx + yvy + zvz . Oxs RandomScalarField: Denes a scalar eld that varies spatially in a random fashion. The value at each position is drawn uniformly from the range declared by the two Specify block required parameters, range min and range max. Oxs ScriptScalarField: Produces a eld dependent on a Tcl script. The Specify block has the form Specify Oxs ScriptScalarField:name { script Tcl script script args { args request } atlas atlas spec xrange { xmin xmax } yrange { ymin ymax } zrange { zmin zmax } } For each position in the mesh, the specied script is called with the arguments requested by script args appended to the command, as explained in the User Dened Support Procedures section (Sec. 17.1.2.6) of the MIF 2.1 le format documentation. The value for script args should be a subset of {relpt rawpt minpt maxpt span}. If script args is not specied, the default value relpt is used. A bounding box must also be specied, by either referencing an atlas specication, or by explicitly stating the range via the three entries xrange, yrange, zrange (in meters). The following example uses the explicit range method. See the Oxs ScriptVectorField documentation below for an example using an atlas specication. proc Ellipsoid { xrel yrel zrel } { set xrad [expr {$xrel - 0.5}] set yrad [expr {$yrel - 0.5}] set zrad [expr {$zrel - 0.5}] set test [expr {$xrad*$xrad+$yrad*$yrad+$zrad*$zrad}] if {$test>0.25} {return 0} return 8.6e5 }

64

Specify Oxs_ScriptScalarField { script Ellipsoid xrange { 0 1e-6 } yrange { 0 250e-9 } zrange { 0 50e-9 } } This Oxs ScriptScalarField object returns 8.6 105 if the import (x,y,z) lies within the ellipsoid inscribed inside the axes parallel parallelepiped dened by (xmin=0, ymin=0, zmin=0) and (xmax=1e-6, ymax=250e-9, zmax=50e-9), and 0 otherwise. See also the discussion of the ReadFile MIF extension command in Sec. 17.1.1 for an example using an imported image le for similar purposes. The available vector eld objects are: Oxs UniformVectorField: Returns the same constant value regardless of the import position. The Specify block takes one required parameter, vector, which is a 3-element list of the vector to return, and one optional parameter, norm, which if specied adjusts the size of export vector to the specied magnitude. For example, Specify Oxs UniformVectorField { norm 1 vector { 1 1 1 } } This object returns the unit vector (a, a, a), where a = 1/ 3, regardless of the import position. Oxs AtlasVectorField: Denes vector values that are constant across individual regions of an Oxs Atlas. The Specify block has the form Specify Oxs AtlasVectorField:name { atlas atlas spec default value { vx vy vz } values { region1 label { v1x v1y v1z } region2 label { v2x v2y v2z } ... } } Interpretation is analogous to the Oxs AtlasScalarField specify block, except here the output values are 3 dimensional vectors rather than scalars.

65

Oxs ScriptVectorField: Conceptually similar to the Oxs ScriptScalarField scalar eld object, except that the script should return a vector (as a 3 element list) rather than a scalar. In addition to the script, script args, and xrange/yrange/zrange or atlas parameters, the Specify string for Oxs ScriptVectorField also accepts an optional parameter norm. If specied, the return values from the script are size adjusted to the specied magnitude. The following example produces a vortex-like unit vector eld, with an interior core region pointing parallel to the z-axis. Here the scaling region is specied using an atlas reference to an object named :atlas, which is presumed to be dened earlier in the MIF le. See the Oxs ScriptScalarField sample Specify block for an example using the explicit range option. proc Vortex { xrel yrel zrel } { set xrad [expr {$xrel-0.5}] set yrad [expr {$yrel-0.5}] set normsq [expr {$xrad*$xrad+$yrad*$yrad}] if {$normsq <= 0.025} {return "0 0 1"} return [list [expr {-1*$yrad}] $xrad 0] } Specify Oxs_ScriptVectorField { script Vortex norm 1 atlas :atlas } See also the discussion of the ReadFile MIF extension command in Sec. 17.1.1 for an example using an imported image le for similar purposes. Oxs FileVectorField: Provides a le-specied vector eld. Required values in the Specify block are the name of the input vector eld le and the desired scaling parameters. The lename is specied via the le entry, which names a le containing a vector eld in one of the formats recognized by avf2ovf (Sec. 16.3). The le will be scaled and sub-sampled as necessary to t the scaling region. The scaling region is specied in the same manner as for the Oxs ScriptScalarField and Oxs ScriptVectorField classes, by either an explicit range specication or an atlas reference. The magnitude of the eld can be modied by the optional norm and multiplier options. If the norm parameter is given, then each vector in the eld will be renormalized to the specied magnitude. If the multiplier parameter is given, then each vector in the eld will be multiplied by the given scalar value. If the multiplier value is negative, the eld direction will be reversed. If both norm and multiplier are given, then the eld vectors are renormalized before being scaled by the multiplier value. Oxs RandomVectorField: Denes a vector eld that varies spatially in a random fashion. The Specify block takes two required parameters, min norm and max norm. 66

The vectors produced will have magnitude between these two specied values. If min norm = max norm, then the samples are uniformly distributed on the sphere of radius = min norm. Otherwise, rst a uniformly distributed sample is chosen on the unit sphere, and then the magnitude is adjusted to a size drawn uniformly from the interval [min norm,max norm]. Oxs PlaneRandomVectorField: Similar to Oxs RandomVectorField, except that all samples are drawn from a plane rather than 3-space. In addition to min norm and max norm, the Specify block for Oxs PlaneRandomVectorField also requires the parameter plane normal. This parameter takes as its value a list of 3 elements, representing a vector orthogonal to the plane from which the random vectors are to be drawn. 7.3.7 MIF Support Classes

Oxs LabelValue: A convenience object that holds label + value pairs. Oxs LabelValue objects may be referenced via the standard attributes eld in other Specify blocks, as in this example: Specify Oxs_LabelValue:probdata { alpha 0.5 start_dm 0.01 } Specify Oxs_EulerEvolve { attributes :probdata } The Specify block string for Oxs LabelValue objects is an arbitrary Tcl list with an even number of elements. The rst element in each pair is interpreted as a label, the second as the value. The attribute option causes this list to be dropped verbatim into the surrounding object. This technique is most useful if the label + value pairs in the Oxs LabelValue object are used in multiple Specify blocks, either inside the same MIF le, or across several MIF les into which the Oxs LabelValue block is imported using the ReadFile MIF extension command. Refer to Sec. 17.1 for details on the base MIF 2.1 format specication.

67

Micromagnetic Problem Editor: mmProbEd

Overview
The application mmProbEd provides a user interface for creating and editing micromagnetic problem descriptions in the Micromagnetic Input Format (MIF 1.1) (Sec. 17.2). mmProbEd also acts as a server, supplying problem descriptions to running mmSolve2D micromagnetic solvers.

Launching
mmProbEd may be started either by selecting the mmProbEd button on mmLaunch, or from the command line via tclsh oommf.tcl mmProbEd [standard options] [-net <0|1>] -net <0|1> Disable or enable a server which provides problem descriptions to other applications. By default, the server is enabled. When the server is disabled, mmProbEd is only useful for editing problem descriptions and saving them to les.

Inputs
The menu selection File|Open... displays a dialog box for selecting a le from which to load a MIF problem description. Several example les are included in the OOMMF release in the directory oommf/app/mmpe/examples. At startup, mmProbEd loads the problem 68

contained in oommf/app/mmpe/init.mif as an initial problem. Note: When loading a le, mmProbEd discards comments and moves records it does not understand to the bottom of its output le. Use the FileSource application (Sec.9) to serve unmodied problem descriptions.

Outputs
The menu selection File|Save as... displays a dialog box for selecting/entering a le in which the problem description currently held by mmProbEd is to be saved. Because the internal data format use by mmProbEd is an unordered array that does not include comments (or unrecognized records), the simple operation of reading in a MIF le and then writing it back out may alter the le. Each instance of mmProbEd contains exactly one problem description at a time. When the option -net 1 is active (the default), each also services requests from client applications (typically solvers) for the problem description it contains.

Controls
The main panel in the mmProbEd window contains buttons corresponding to the sections in a MIF 1.1 problem description. Selecting a button brings up another window through which the contents of that section of a problem description may be edited. The MIF sections and the elements they contain are described in detail in the MIF 1.1 (Sec. 17.2) documentation. Only one editing window is displayed at a time. The windows may be navigated in order using their Next or Previous buttons. PLEASE NOTE: The material parameter values provided for the symbolic material types of Iron, Nickel, etc., should not be taken as standard reference values for these materials. These values are only approximate. They are included for convenience, and as examples for users who wish to supply their own material types with symbolic names. To introduce additional material types, edit the le oommf/app/mmpe/materials, appending your new entries in the same format as the example materials. The menu selection File|Exit terminates the mmProbEd application. The menu Help provides the usual help facilities.

69

Micromagnetic Problem File Source: FileSource

Overview
The application FileSource provides the same service as mmProbEd (Sec. 8), supplying MIF 1.1 problem descriptions to running mmSolve2D micromagnetic solvers. As the MIF specication evolves, mmProbEd may lag behind. There may be new elds in the MIF specication that mmProbEd is not capable of editing, or which mmProbEd may not pass on to solvers after loading them in from a le. To make use of such elds, a MIF le may need to be edited by hand using a general purpose text editor. FileSource may then be used to supply the MIF problem description contained in a le to a solver without danger of corrupting its contents.

Launching
FileSource must be launched from the command line. You may specify on the command line the MIF problem description le it should serve to client applications. The command line is tclsh oommf.tcl FileSource [standard options] [filename] Although FileSource does not appear on the list of Programs that mmLaunch oers to launch, running copies do appear on the list of Threads since they do provide a service registered with the account service directory.

Inputs
FileSource takes its MIF problem description from the le named on the command line, or from a le selected through the File|Open dialog box. No checking of the le contents against the MIF specication is performed. The le contents are passed uncritically to any client application requesting a problem description. Those client applications should raise errors when presented with invalid problem descriptions.

Outputs
Each instance of FileSource provides the contents of exactly one le at a time. The le name is displayed in the FileSource window to help the user associate each instance of 70

FileSource with the data le it provides. Each instance of FileSource accepts and services requests from client applications (typically solvers) for the contents of the le it exports. The contents of the le are read at the time of the client request, so if the contents of a le change between the time of the FileSource le selection and the arrival of a request from a client, the new contents will be served to the client application.

Controls
The menu selection File|Exit terminates the FileSource application. The Help menu provides the usual help facilities.

71

10

The 2D Micromagnetic Solver

The OOMMF 2D micromagnetic computation engine, mmSolve, is capable of solving problems dened on a two-dimensional grid of square cells with three-dimensional spins. This solver is older, less exible and less extensible than the Oxs (Sec. 7) solver. Users are encouraged to migrate to Oxs where possible. There are two interfaces provided to mmSolve, the interactive mmSolve2D (Sec. 10.1) interface and the command line driven batchsolve (Sec. 10.2.1) interface which can be used in conjunction with the OOMMF Batch System (Sec. 10.2). Problem denition for mmSolve is accomplished using input les in the MIF 1.1 format (Sec. 17.2). Please note that this format is incompatible with the newer MIF 2.x format used by the Oxs solver. However, the command line utility mifconvert (Sec. 16.7) can be used to aid conversion from the MIF 1.1 format to MIF 2.1. Note on Tk dependence: If a problem is loaded that uses a bitmap mask le (Sec. 17.2.3), and if that mask le is not in the PPM P3 (text) format, then mmSolve2D will launch any2ppm (Sec. 16.1) to convert it into the PPM P3 format. Since any2ppm requires Tk, at the time the mask le is read a valid display must be available. See the any2ppm documentation for details.

10.1

The 2D Micromagnetic Interactive Solver: mmSolve2D

Overview The application mmSolve2D is a micromagnetic computation engine capable of solving problems dened on two-dimensional square grids of three-dimensional spins. Within the OOMMF architecture (see Sec. 4), mmSolve2D is both a server and a client application. mmSolve2D is a client of problem description server applications, data table display and

72

storage applications, and vector eld display and storage applications. mmSolve2D is the server of a solver control service for which the only client is mmLaunch (Sec. 6). It is through this service that mmLaunch provides a user interface window (shown above) on behalf of mmSolve2D. Launching mmSolve2D may be started either by selecting the mmSolve2D button on mmLaunch, or from the command line via tclsh oommf.tcl mmSolve2D [standard options] [-restart <0|1>] -restart <0|1> Aects the behavior of the solver when a new problem is loaded. Default value is 0. When launched with -restart 1, the solver will look for basename.log and basename*.omf les to restart a previous run from the last saved state (where basename is the Base Output Filename specied in the input MIF 1.1 problem specication le (Sec. 17.2)). If these les cannot be found, then a warning is issued and the solver falls back to the default behavior (-restart 0) of starting the problem from scratch. The specied -restart setting holds for all problems fed to the solver, not just the rst. (There is currently no interactive way to change the value of this switch.) Since mmSolve2D does not present any user interface window of its own, it depends on mmLaunch to provide an interface on its behalf. The entry for an instance of mmSolve2D in the Threads column of any running copy of mmLaunch has a checkbutton next to it. This button toggles the presence of a user interface window through which the user may control that instance of mmSolve2D. The user interface window is divided into panels, providing user interfaces to the Inputs, Outputs, and Controls of mmSolve2D. Inputs The top panel of the user interface window may be opened and closed by toggling the Inputs checkbutton. When open, the Inputs panel reveals two subpanels. The left subpanel contains a list of the inputs required by mmSolve2D. There is only one item in the list: ProblemDescription. When ProblemDescription is selected, the right subpanel (labeled Source Threads) displays a list of applications that can supply a problem description. The user selects from among the listed applications the one from which mmSolve2D should request a problem description. Outputs When mmSolve2D has outputs available to be controlled, a Scheduled Outputs checkbutton appears in the user interface window. Toggling the Scheduled Outputs checkbutton causes a bottom panel to open and close in the user interface window. When open, the 73

Scheduled Outputs panel contains three subpanels. The Outputs subpanel is lled with a list of the types of output mmSolve2D can generate while solving the loaded problem. The three elements in this list are TotalField, for the output of a vector eld representing the total eective eld, Magnetization, for the output of a vector eld representing the current magnetization state of the grid of spins, and DataTable, for the output of a table of data values describing other quantities of interest calculated by mmSolve2D. Upon selecting one of the output types from the Outputs subpanel, a list of applications appears in the Destination Threads subpanel which provide a display and/or storage service for the type of output selected. The user may select from this list those applications to which the selected type of output should be sent. For each application selected, a nal interface is displayed in the Schedule subpanel. Through this interface the user may set the schedule according to which the selected type of data is sent to the selected application for display or storage. The schedule is described relative to events in mmSolve2D. An Iteration event occurs at every step in the solution of the ODE. A ControlPoint event occurs whenever the solver determines that a control point specication is met. (Control point specs are discussed in the Experiment parameters paragraph in the MIF 1.1 documentation (Sec. 17.2), and are triggered by solver equilibrium, simulation time, and iteration count conditions.) An Interactive event occurs for a particular output type whenever the corresponding Interactive Outputs button is clicked in the Runtime Control panel. The Interactive schedule gives the user the ability to interactively force data to be delivered to selected display and storage applications. For the Iteration and ControlPoint events, the granularity of the output delivery schedule is under user control. For example, the user may elect to send vector eld data describing the current magnetization state to an mmDisp instance for display every 25 iterations of the ODE, rather than every iteration. The quantities included in DataTable output produced by mmSolve2D include: Iteration: The iteration count of the ODE solver. Field Updates: The number of times the ODE solver has calculated the eective eld. Sim Time (ns): The elapsed simulated time. Time Step (ns): The interval of simulated time spanned by the last step taken in the ODE solver. Step Size: The magnitude of the last step taken by the ODE solver as a normalized value. (This is currently the time step in seconds, multiplied by the gyromagnetic ratio times the damping coecient times Ms .) Bx, By, Bz (mT): The x, y, and z components of the nominal applied eld (see Sec. 17.2.5). B (mT): The magnitude of the nominal applied eld (always non-negative). 74

2 |m x h|: The maximum of the point-wise quantity M He /Ms over all the spins. This torque value is used to test convergence to an equilibrium state (and raise control point torque events).

Mx/Ms, My/Ms, Mz/Ms: The x, y, and z components of the average magnetization of the magnetically active elements of the simulated part. Total Energy (J/m3 ): The total average energy density for the magnetically active elements of the simulated part. Exchange Energy (J/m3 ): The component of the average energy density for the magnetically active elements of the simulated part due to exchange interactions. Anisotropy Energy (J/m3 ): The component of the average energy density for the magnetically active elements of the simulated part due to crystalline and surface anisotropies. Demag Energy (J/m3 ): The component of the average energy density for the magnetically active elements of the simulated part due to self-demagnetizing elds. Zeeman Energy (J/m3 ): The component of average energy density for the magnetically active elements of the simulated part due to interaction with the applied eld. Max Angle: The maximum angle (in degrees) between the magnetization orientation of any pair of neighboring spins in the grid. (The neighborhood of a spin is the same as that dened by the exchange energy calculation.) In addition, the solver automatically keeps a log le that records the input problem specication and miscellaneous runtime information. The name of this log le is basename.log, where basename is the Base Output Filename specied in the input problem specication. If this le already exists, then new entries are appended to the end of the le. Controls The middle section of the user interface window contains a series of buttons providing user control over the solver. After a problem description server application has been selected, the LoadProblem button triggers a fetch of a problem description from the selected server. The LoadProblem button may be selected at any time to (re-)load a problem description from the currently selected server. After loading a new problem the solver goes automatically into a paused state. (If no problem description server is selected when the LoadProblem button is invoked, nothing will happen.) The Reset button operates similarly, except that the current problem specications are used. Once a problem is loaded, the solver can be put into any of three states: run, relax and pause. Selecting Relax puts the solver into the relax state, where it runs until a 75

control point is reached, after which the solver pauses. If the Relax button is reselected after reaching a control point, then the solver will simply re-pause immediately. The Field+ or Field button must be invoked to change the applied eld state. (Field state schedules are discussed below.) The Run selection diers in that when a control point is reached, the solver automatically steps the nominal applied eld to the next value, and continues. In run mode the solver will continue to process until there are no more applied eld states in the problem description. At any time the Pause button may be selected to pause the solver. The solver will stay in this state until the user reselects either Run or Relax. The current state of the solver is indicated in the Status line in the center panel of the user interface window. The problem description (in MIF 1.1 format) species a xed applied eld schedule (see Sec. 17.2.5). This schedule denes an ordered list of applied elds, which the solver in run mode steps through in sequence. The Field and Field+ buttons allow the user to interactively adjust the applied eld sequence. Each click on the Field+ button advances forward one step through the specied schedule, while Field reverses that process. In general, the step direction is not related to the magnitude of the applied eld. Also note that hitting these buttons does not generate a ControlPoint event. In particular, if you are manually accelerating the progress of the solver through a hysteresis loop, and want to send non-ControlPoint data to a display or archive widget before advancing the eld, then you must use the appropriate Interactive Output button. The second row of buttons in the interaction control panel, TotalField, Magnetization and DataTable, allow the user to view the current state of the solver at any time. These buttons cause the solver to send out data of the corresponding type to all applications for which the Interactive schedule button for that data type has been selected, as discussed in the Outputs section above. At the far right of the solver controls is the Exit button, which terminates mmSolve2D. Simply closing the user interface window does not terminate mmSolve2D, but only closes the user interface window. To kill the solver the Exit button must be pressed. Details Given a problem description, mmSolve2D integrates the Landau-Lifshitz equation [7, 9] dM | | = | | M He M (M He ) , dt Ms where M He is is is is the the the the pointwise magnetization (A/m), pointwise eective eld (A/m), Landau-Lifshitz gyromagnetic ratio (m/(As)), damping coecient (dimensionless). (4)

(Compare to (2), page 54.) 76

The eective eld is dened as He = 1 0 E . M

The average energy density E is a function of M specied by Browns equations [4], including anisotropy, exchange, self-magnetostatic (demagnetization) and applied eld (Zeeman) terms. The micromagnetic problem is impressed upon a regular 2D grid of squares, with 3D magnetization spins positioned at the centers of the cells. Note that the constraint that the grid be composed of square elements takes priority over the requested size of the grid. The actual size of the grid used in the computation will be the nearest integral multiple of the grids cell size to the requested size. It is important when comparing the results from grids with dierent cell sizes to account for the possible change in size of the overall grid. The anisotropy and applied eld energy terms are calculated assuming constant magnetization in each cell. The exchange energy is calculated using the eight-neighbor bilinear interpolation described in [5], with Neumann boundary conditions. The more common fourneighbor scheme is available as a compile-time option. Details can be found in the source-code le oommf/app/mmsolve/magelt.cc. The self-magnetostatic eld is calculated as the convolution of the magnetization against a kernel that describes the cell to cell magnetostatic interaction. The convolution is evaluated using fast Fourier transform (FFT) techniques. Several kernels are supported; these are selected as part of the problem description in MIF format; for details see Sec. 17.2.2: Demag specication. Each kernel represents a dierent interpretation of the discrete magnetization. The recommended model is ConstMag, which assumes the magnetization is constant in each cell, and computes the average demagnetization eld through the cell using formulae from [12] and [2]. The Landau-Lifshitz ODE (4) is integrated using a second order predictor-corrector technique of the Adams type. The right side of (4) at the current and previous step is extrapolated forward in a linear fashion, and is integrated across the new time interval to obtain a quadratic prediction for M at the next time step. At each stage the spins are renormalized to Ms before evaluating the energy and eective elds. The right side of (4) is evaluated at the predicted M, which is then combined with the value at the current step to produce a linear interpolation of dM/dt across the new interval. This is then integrated to obtain the nal estimate of M at the new step. The local (one step) error of this procedure should be O(t3 ). The step is accepted if the total energy of the system decreases, and the maximum error between the predicted and nal M is smaller than a nominal value. If the step is rejected, then the step size is reduced and the integration procedure is repeated. If the step is accepted, then the error between the predicted and nal M is used to adjust the size of the next step. No xed ratio between the previous and current time step is assumed. A fourth order Runge-Kutta solver is used to prime the predictor-corrector solver, and is used as a backup in case the predictor-corrector fails to nd a valid step. The Runge-Kutta 77

solver is not selectable as the primary solver at runtime, but may be so selected at compile time by dening the RUNGE KUTTA ODE macro. See the le oommf/app/mmsolve/grid.cc for all details of the integration procedure. For a given applied eld, the integration continues until a control point (cf. Experiment parameters, Sec. 17.2.5) is reached. A control point event may be raised by the ODE iteration 2 count, elapsed simulation time, or by the maximum value of MHe /Ms dropping below a specied control point torque value (implying an equilibrium state has been reached). Depending on the problem size, mmSolve2D can require a good deal of working memory. The exact amount depends on a number of factors, but a reasonable estimate is 5 MB + 1500 bytes per cell. For example, a 1 m 1 m part discretized with 5 nm cells will require approximately 62 MB. Known Bugs mmSolve2D requires the damping coecient to be non-zero. See the MIF 1.1 documentation (Sec. 17.2) for details on specifying the damping coecient. When multiple copies of mmLaunch are used, each can have its own interface to a running copy of mmSolve2D. When the interface presented by one copy of mmLaunch is used to set the output schedule in mmSolve2D, those settings are not reected in the interfaces presented by other copies of mmLaunch. For example, although the rst interface sets a schedule that DataTable data is to be sent to an instance of mmGraph every third Iteration, there is no indication of that schedule presented to the user in the second interface window. It is unusual to have more than one copy of mmLaunch running simultaneously. However, this bug also appears when one copy of mmLaunch is used to load a problem and start a solver, and later a second copy of mmLaunch is used to monitor the status of that running solver. A bug in the network trac handling code of Tcl on Windows 9X systems can sometimes interfere with communications between the control interface of mmSolve2D and the actual computation engine. If mmSolve2D is sending out data to two or more data display services every iteration, the resulting network trac can crowd out the receipt of control messages from the control interface. You may observe this as a long delay between the time you click the Pause button and the time the solver stops iterating. This bug rst appeared in Tcl release 8.0.3, and remained through Tcl release 8.1.1. It is xed in Tcl releases 8.2 and later, which we recommend for OOMMF users on Windows 9X systems. Other platforms do not have this problem.

10.2

OOMMF 2D Micromagnetic Solver Batch System

The OOMMF Batch System (OBS) provides a scriptable interface to the same micromagnetic solver engine used by mmSolve2D (Sec. 10.1), in the form of three Tcl applicatons (batchmaster, batchslave, and batchsolve) that provide support for complex job scheduling. All OBS script les are in the OOMMF distribution directory app/mmsolve/scripts.

78

Unlike much of the OOMMF package, the OBS is meant to be driven primarily from the command line or shell (batch) script. OBS applications are launched from the command line using the bootstrap application (Sec. 5). 10.2.1 2D Micromagnetic Solver Batch Interface: batchsolve

Overview The application batchsolve provides a simple command line interface to the OOMMF 2D micromagnetic solver engine. Launching The application batchsolve is launched by the command line: tclsh oommf.tcl batchsolve [standard options] [-end_exit <0|1>] [-end_paused] [-interface <0|1>] \ [-restart <0|1>] [-start_paused] [file] where -end exit <0|1> Whether or not to explicitly call exit at bottom of batchsolve.tcl. When launched from the command line, the default is to exit after solving the problem in file. When sourced into another script, like batchslave.tcl, the default is to wait for the caller script to provide further instructions. -interface <0|1> Whether to register with the account service directory application, so that mmLaunch (Sec. 6), can provide an interactive interface. Default = 1 (do register), which will automatically start account service directory and host service directory applications as necessary. -start paused Pause solver after loading problem. -end paused Pause solver and enter event loop at bottom of batchsolve.tcl rather than just falling o the end (the eect of which will depend on whether or not Tk is loaded). -restart <0|1> Determines solver behavior when a new problem is loaded. If 1, then the solver will look for basename.log and basename*.omf les to restart a previous run from the last saved state (where basename is the Base Output Filename specied in the input problem specication). If these les cannot be found, then a warning is issued and the solver falls back to the default behavior (equivalent to -restart 0) of starting the problem from scratch. The specied -restart setting holds for all problems fed to the solver, not just the rst. le Immediately load and run the specied MIF 1.1 le.

79

The input le file should contain a Micromagnetic Input Format 1.1 (Sec. 17.2) problem description, such as produced by mmProbEd (Sec. 8). The batch solver searches several directories for this le, including the current working directory, the data and scripts subdirectories, and parallel directories relative to the directories app/mmsolve and app/mmpe in the OOMMF distribution. Refer to the mif path variable in batchsolve.tcl for the complete list. If -interface is set to 1 (enabled), batchsolve registers with the account service directory application, and mmLaunch will be able to provide an interactive interface. Using this interface, batchsolve may be controlled in a manner similar to mmSolve2D (Sec. 10.1). The interface allows you to pause, un-pause, and terminate the current simulation, as well as to attach data display applications to monitor the solvers progress. If more interactive control is needed, mmSolve2D should be used. If -interface is 0 (disabled), batchsolve does not register, leaving it without an interface, unless it is sourced into another script (e.g., batchslave.tcl) that arranges for an interface on the behalf of batchsolve. Use the -start_paused switch to monitor the progress of batchsolve from the very start of a simulation. With this switch the solver will be paused immediately after loading the specied MIF le, so you can bring up the interactive interface and connect display applications before the simulation begins. Start the simulation by selecting the Run command from the interactive interface. This option cannot be used if -interface is disabled. The -end_paused switch insures that the solver does not automatically terminate after completing the specied simulation. This is not generally useful, but may nd application when batchsolve is called from inside a Tcl-only wrapper script. Note on Tk dependence: If a problem is loaded that uses a bitmap mask le (Sec. 17.2.3), and if that mask le is not in the PPM P3 (text) format, then batchsolve will launch any2ppm (Sec. 16.1) to convert it into the PPM P3 format. Since any2ppm requires Tk, at the time the mask le is read a valid display must be available. See the any2ppm documentation for details. Output The output may be changed by a Tcl wrapper script (see Sec. 10.2.1), but the default output behavior of batchsolve is to write tabular text data and the magnetization state at the control point for each applied eld step. The tabular data are appended to the le basename.odt, where basename is the Base Output Filename specied in the input MIF 1.1 le. See the routine GetTextData in batchsolve.tcl for details, but at present the output consists of the solver iteration count, nominal applied eld B, reduced average magnetization m, and total energy. This output is in the ODT le format. The magnetization data are written to a series of OVF (OOMMF Vector Field) les, basename.fieldnnnn.omf, where nnnn starts at 0000 and is incremented at each applied eld step. (The ASCII text header inside each le records the nominal applied eld at that step.) These les are viewable using mmDisp (Sec. 13).

80

The solver also automatically appends the input problem specication and miscellaneous runtime information to the log le basename.log. Programmers interface In addition to directly launching batchsolve from the command line, batchsolve.tcl may also be sourced into another Tcl script that provides additional control structures. Within the scheduling system of OBS, batchsolve.tcl is sourced into batchslave, which provides additional control structures that support scheduling control by batchmaster. There are several variables and routines inside batchsolve.tcl that may be accessed and redened from such a wrapper script to provide enhanced functionality. Global variables mif A Tcl handle to a global mms mif object holding the problem description dened by the input MIF 1.1 le. solver A Tcl handle to the mms solver object. search path Directory search path used by the FindFile proc (see below). Refer to the source code and sample scripts for details on manipulation of these variables. Batchsolve procs The following Tcl procedures are designed for external use and/or redenition: SolverTaskInit Called at the start of each task. BatchTaskIterationCallback Called after each iteration in the simulation. BatchTaskRelaxCallback Called at each control point reached in the simulation. SolverTaskCleanup Called at the conclusion of each task. FindFile Searches the directories specied by the global variable search path for a specied le. The default SolverTaskInit proc uses this routine to locate the requested input MIF le. SolverTaskInit and SolverTaskCleanup accept an arbitrary argument list (args), which is copied over from the args argument to the BatchTaskRun and BatchTaskLaunch procs in batchsolve.tcl. Typically one copies the default procs (as needed) into a task script, and makes appropriate modications. You may (re-)dene these procs either before or after sourcing batchsolve.tcl. See Sec. 10.2.2.4 for example scripts.

81

10.2.2

2D Micromagnetic Solver Batch Scheduling System

Overview The OBS supports complex scheduling of multiple batch jobs with two applications, batchmaster and batchslave. The user launches batchmaster and provides it with a task script. The task script is a Tcl script that describes the set of tasks for batchmaster to accomplish. The work is actually done by instances of batchslave that are launched by batchmaster. The task script may be modeled after the included simpletask.tcl or multitask.tcl sample scripts (Sec. 10.2.2.4). The OBS has been designed to control multiple sequential and concurrent micromagnetic simulations, but batchmaster and batchslave are completely general and may be used to schedule other types of jobs as well. 10.2.2.1 Master Scheduling Control: batchmaster The application batchmaster is launched by the command line: tclsh oommf.tcl batchmaster [standard options] task_script \ [host [port]] task script is the user dened task (job) denition Tcl script, host species the network address for the master to use (default is localhost), port is the port address for the master (default is 0, which selects an arbitrary open port). When batchmaster is run, it sources the task script. Tcl commands in the task script should modify the global object $TaskInfo to inform the master what tasks to perform and optionally how to launch slaves to perform those tasks. The easiest way to create a task script is to modify one of the example scripts in Sec. 10.2.2.4. More detailed instructions are in Sec. 10.2.2.3. After sourcing the task script, batchmaster launches all the specied slaves, initializes each with a slave initialization script, and then feeds tasks sequentially from the task list to the slaves. When a slave completes a task it reports back to the master and is given the next unclaimed task. If there are no more tasks, the slave is shut down. When all the tasks are complete, the master prints a summary of the tasks and exits. When the task script requests the launching and controlling of jobs o the local machine, with slaves running on remote machines, then the command line argument host must be set to the local machines network name, and the $TaskInfo methods AppendSlave and ModifyHostList will need to be called from inside the task script. Furthermore, OOMMF does not currently supply any methods for launching jobs on remote machines, so a task script which requests the launching of jobs on remote machines requires a working rsh command or equivalent. See Sec. 10.2.2.3 for details.

82

10.2.2.2 Task Control: batchslave The application batchslave may be launched by the command line: tclsh oommf.tcl batchslave [standard options] \ host port id password [auxscript [arg ...]] host, port Host and port at which to contact the master to serve. id, password ID and password to send to the master for identication. auxscript arg ... The name of an optional script to source (which actually performs the task the slave is assigned), and any arguments it needs. In normal operation, the user does not launch batchslave. Instead, instances of batchslave are launched by batchmaster as instructed by a task script. Although batchmaster may launch any slaves requested by its task script, by default it launches instances of batchslave. The function of batchslave is to make a connection to a master program, source the auxscript and pass it the list of arguments aux arg .... Then it receives commands from the master, and evaluates them, making use of the facilities provided by auxscript. Each command is typically a long-running one, such as solving a complete micromagnetic problem. When each command is complete, the batchslave reports back to its master program, asking for the next command. When the master program has no more commands batchslave terminates. Inside batchmaster, each instance of batchslave is launched by evaluating a Tcl command. This command is called the spawn command, and it may be redened by the task script in order to completely control which slave applications are launched and how they are launched. When batchslave is to be launched, the spawn command might be: exec tclsh oommf.tcl batchslave -tk 0 -- $server(host) $server(port) \ $slaveid $passwd batchsolve.tcl -restart 1 & The Tcl command exec is used to launch subprocesses. When the last argument to exec is &, the subprocess runs in the background. The rest of the spawn command should look familiar as the command line syntax for launching batchslave. The example spawn command above cannot be completely provided by the task script, however, because parts of it are only known by batchmaster. Because of this, the task script should dene the spawn command using percent variables which are substituted by batchmaster. Continuing the example, the task script provides the spawn command: exec %tclsh %oommf batchslave -tk 0 %connect_info \ batchsolve.tcl -restart 1

83

batchmaster replaces %tclsh with the path to tclsh, and %oommf with the path to the OOMMF bootstrap application. It also replaces %connect info with the ve arguments from -- through $password that provide batchslave the hostname and port where batchmaster is waiting for it to report to, and the ID and password it should pass back. In this example, the task script instructs batchslave to source the le batchsolve.tcl and pass it the arguments -restart 1. Finally, batchmaster always appends the argument & to the spawn command so that all slave applications are launched in the background. The communication protocol between batchmaster and batchslave is evolving and is not described here. Check the source code for the latest details. 10.2.2.3 Batch Task Scripts The application batchmaster creates an instance of a BatchTaskObj object with the name $TaskInfo. The task script uses method calls to this object to set up tasks to be performed. The only required call is to the AppendTask method, e.g., $TaskInfo AppendTask A "BatchTaskRun taskA.mif" This method expects two arguments, a label for the task (here A) and a script to accomplish the task. The script will be passed across a network socket from batchmaster to a slave application, and then the script will be interpreted by the slave. In particular, keep in mind that the le system seen by the script will be that of the machine on which the slave process is running. This example uses the default batchsolve.tcl procs to run the simulation dened by the taskA.mif MIF 1.1 le. If you want to make changes to the MIF problem specications on the y, you will need to modify the default procs. This is done by creating a slave initialization script, via the call $TaskInfo SetSlaveInitScript { <insert script here> } The slave initialization script does global initializations, and also usually redenes the SolverTaskInit proc; optionally the BatchTaskIterationCallback, BatchTaskRelaxCallback and SolverTaskCleanup procs may be redened as well. At the start of each task SolverTaskInit is called by BatchTaskRun (in batchsolve.tcl), after each iteration BatchTaskIterationCallback is executed, at each control point BatchTaskRelaxCallback is run, and at the end of each task SolverTaskCleanup is called. SolverTaskInit and SolverTaskCleanup are passed the arguments that were passed to BatchTaskRun. A simple SolverTaskInit proc could be proc SolverTaskInit { args } { global mif basename outtextfile set A [lindex $args 0] set outbasename "$basename-A$A" $mif SetA $A $mif SetOutBaseName $outbasename set outtextfile [open "$outbasename.odt" "a+"] 84

puts $outtextfile [GetTextData header \ "Run on $basename.mif, with A=[$mif GetA]"] } This proc receives the exchange constant A for this task on the argument list, and makes use of the global variables mif and basename. (Both should be initialized in the slave initialization script outside the SolverTaskInit proc.) It then stores the requested value of A in the mif object, sets up the base lename to use for output, and opens a text le to which tabular data will be appended. The handle to this text le is stored in the global outtextfile, which is closed by the default SolverTaskCleanup proc. A corresponding task script could be $TaskInfo AppendTask "A=13e-12 J/m" "BatchTaskRun 13e-12" which runs a simulation with A set to 13 1012 J/m. This example is taken from the multitask.tcl script in Sec. 10.2.2.4. (For commands accepted by mif objects, see the le mmsinit.cc. Another object than can be gainfully manipulated is solver, which is dened in solver.tcl.) If you want to run more than one task at a time, then the $TaskInfo method AppendSlave will have to be invoked. This takes the form $TaskInfo AppendSlave <spawn count> <spawn command> where <spawn command> is the command to launch the slave process, and <spawn count> is the number of slaves to launch with this command. (Typically <spawn count> should not be larger than the number of processors on the target system.) The default value for this item (which gets overwritten with the rst call to $TaskInfo AppendSlave) is 1 {Oc_Application Exec batchslave -tk 0 %connect_info batchsolve.tcl} The Tcl command Oc Application Exec is supplied by OOMMF and provides access to the same application-launching capability that is used by the OOMMF bootstrap application (Sec. 5). Using a <spawn command> of Oc Application Exec instead of exec %tclsh %oommf saves the spawning of an additional process. The default <spawn command> launches the batchslave application, with connection information provided by batchmaster, and using the auxscript batchsolve.tcl. Before evaluating the <spawn command>, batchmaster applies several percent-style substitutions useful in slave launch scripts: %tclsh, %oommf, %connect info, %oommf root, and %%. The rst is the Tcl shell to use, the second is an absolute path to the OOMMF bootstrap program on the master machine, the third is connection information needed by the batchslave application, the fourth is the path to the OOMMF root directory on the master machine, and the last is interpreted as a single percent. batchmaster automatically appends the argument & to the <spawn command> so that the slave applications are launched in the background. To launch batchslave on a remote host, use rsh in the spawn command, e.g., 85

# FILE: simpletask.tcl # # This is a sample batch task file. Usage example: # # tclsh oommf.tcl batchmaster simpletask.tcl # # Form task list $TaskInfo AppendTask A "BatchTaskRun taskA.mif" $TaskInfo AppendTask B "BatchTaskRun taskB.mif" $TaskInfo AppendTask C "BatchTaskRun taskC.mif" Figure 1: Sample task script simpletask.tcl. $TaskInfo AppendSlave 1 {exec rsh foo tclsh oommf/oommf.tcl \ batchslave -tk 0 %connect_info batchsolve.tcl} This example assumes tclsh is in the execution path on the remote machine foo, and OOMMF is installed o of your home directory. In addition, you will have to add the machine foo to the host connect list with $TaskInfo ModifyHostList +foo and batchmaster must be run with the network interface specied as the server host (instead of the default localhost), e.g., tclsh oommf.tcl batchmaster multitask.tcl bar where bar is the name of the local machine. This may seem a bit complicated, but the examples in the next section should make things clearer. 10.2.2.4 Sample task scripts The rst sample task script (Fig. 1) is a simple example that runs the 3 micromagnetic simulations described by the MIF 1.1 les taskA.mif, taskB.mif and taskC.mif. It is launched with the command tclsh oommf.tcl batchmaster simpletask.tcl This example uses the default slave launch script, so a single slave is launched on the current machine, and the 3 simulations will be run sequentially. Also, no slave initialization script is given, so the default procs in batchsolve.tcl are used. Output will be magnetization states and tabular data at each control point, stored in les on the local machine with base names as specied in the MIF les. The second sample task script (Fig. 2) builds on the previous example by dening BatchTaskIterationCallback and BatchTaskRelaxCallback procedures in the slave init 86

script. The rst set up to write tabular data every 10 iterations, while the second writes tabular data on each control point event. The data is written to the output le specied by the Base Output Filename entry in the input MIF les. Note that there is no magnetization vector eld output in this example. This task script is launched the same way as the previous example: tclsh oommf.tcl batchmaster octrltask.tcl The third task script (Fig. 3) is a more complicated example running concurrent processes on two machines. This script should be run with the command tclsh oommf.tcl batchmaster multitask.tcl bar where bar is the name of the local machine. Near the top of the multitask.tcl script several Tcl variables (RMT MACHINE through A list) are dened; these are used farther down in the script. The remote machine is specied as foo, which is used in the $TaskInfo AppendSlave and $TaskInfo ModifyHostList commands. There are two AppendSlave commands, one to run two slaves on the local machine, and one to run a single slave on the remote machine (foo). The latter changes to a specied working directory before launching the batchslave application on the remote machine. (For this to work you must have rsh congured properly. In the future it may be possible to launch remote commands using the OOMMF account server application, thereby lessening the reliance on system commands like rsh.) Below this the slave initialization script is dened. The Tcl regsub command is used to place the task script dened value of BASEMIF into the init script template. The init script is run on the slave when the slave is rst brought up. It rst reads the base MIF le into a newly created mms mif instance. (The MIF le needs to be accessible by the slave process, irrespective of which machine it is running on.) Then replacement SolverTaskInit and SolverTaskCleanup procs are dened. The new SolverTaskInit interprets its rst argument as a value for the exchange constant A. Note that this is dierent from the default SolverTaskInit proc, which interprets its rst argument as the name of a MIF 1.1 le to load. With this task script, a MIF le is read once when the slave is brought up, and then each task redenes only the value of A for the simulation (and corresponding changes to the output lenames and data table header). Finally, the Tcl loop structure foreach A $A_list { $TaskInfo AppendTask "A=$A" "BatchTaskRun $A" } is used to build up a task list consisting of one task for each value of A in A list (dened at the top of the task script). For example, the rst value of A is 10e-13, so the rst task will have the label A=10e-13 and the corresponding script is BatchTaskRun 10e-13. The 87

# FILE: octrltask.tcl # # This is a sample batch task file, with expanded output control. # Usage example: # # tclsh oommf.tcl batchmaster octrltask.tcl # # "Every" output selection count set SKIP_COUNT 10 # Initialize solver. This is run at global scope set init_script { # Text output routine proc MyTextOutput {} { global outtextfile puts $outtextfile [GetTextData data] flush $outtextfile } # Change control point output proc BatchTaskRelaxCallback {} { MyTextOutput } # Add output on iteration events proc BatchTaskIterationCallback {} { global solver set count [$solver GetODEStepCount] if { ($count % __SKIP_COUNT__) == 0 } { MyTextOutput } } } # Substitute $SKIP_COUNT in for __SKIP_COUNT__ in above "init_script" regsub -all -- __SKIP_COUNT__ $init_script $SKIP_COUNT init_script $TaskInfo SetSlaveInitScript $init_script # Form task list $TaskInfo AppendTask A "BatchTaskRun taskA.mif" $TaskInfo AppendTask B "BatchTaskRun taskB.mif" $TaskInfo AppendTask C "BatchTaskRun taskC.mif" Figure 2: Task script with iteration output octrltask.tcl.

88

value 10e-13 is passed on by BatchTaskRun to the SolverTaskInit proc, which has been redened to process this argument as the value for A, as described above. There are 6 tasks in all, and 3 slave processes, so the rst three tasks will run concurrently in the 3 slaves. As each slave nishes it will be given the next task, until all the tasks are complete. # FILE: multitask.tcl # # This is a sample batch task file. Usage example: # # tclsh oommf.tcl batchmaster multitask.tcl hostname [port] # # Task script configuration set RMT_MACHINE foo set RMT_TCLSH tclsh set RMT_OOMMF "/path/to/oommf/oommf.tcl" set RMT_WORK_DIR "/path/to/oommf/app/mmsolve/data" set BASEMIF taskA set A_list { 10e-13 10e-14 10e-15 10e-16 10e-17 10e-18 } # Slave launch commands $TaskInfo ModifyHostList +$RMT_MACHINE $TaskInfo AppendSlave 2 "exec %tclsh %oommf batchslave -tk 0 \ %connect_info batchsolve.tcl" $TaskInfo AppendSlave 1 "exec rsh $RMT_MACHINE \ cd $RMT_WORK_DIR \\\;\ $RMT_TCLSH $RMT_OOMMF batchslave -tk 0 %connect_info batchsolve.tcl" # Slave initialization script (with batchsolve.tcl proc # redefinitions) set init_script { # Initialize solver. This is run at global scope set basename __BASEMIF__ ;# Base mif filename (global) mms_mif New mif $mif Read [FindFile ${basename}.mif] # Redefine TaskInit and TaskCleanup procs proc SolverTaskInit { args } { global mif outtextfile basename set A [lindex $args 0] set outbasename "$basename-A$A" $mif SetA $A $mif SetOutBaseName $outbasename set outtextfile [open "$outbasename.odt" "a+"] 89

puts $outtextfile [GetTextData header \ "Run on $basename.mif, with A=[$mif GetA]"] flush $outtextfile } proc SolverTaskCleanup { args } { global outtextfile close $outtextfile } } # Substitute $BASEMIF in for __BASEMIF__ in above script regsub -all -- __BASEMIF__ $init_script $BASEMIF init_script $TaskInfo SetSlaveInitScript $init_script # Create task list foreach A $A_list { $TaskInfo AppendTask "A=$A" "BatchTaskRun $A" } Figure 3: Advanced sample task script multitask.tcl.

90

11

Data Table Display: mmDataTable

Overview
The application mmDataTable provides a data display service to its client applications. It accepts data from clients which are displayed in a tabular format in a top-level window. Its typical use is to display the evolving values of quantities computed by micromagnetic solver programs.

Launching
mmDataTable may be started either by selecting the mmDataTable button on mmLaunch, or from the command line via tclsh oommf.tcl mmDataTable [standard options] [-net <0|1>] -net <0|1> Disable or enable a server which allows the data displayed by mmDataTable to be updated by another application. By default, the server is enabled. When the server is disabled, mmProbEd is only useful if it is embedded in another application. 91

Inputs
The client application(s) that send data to mmDataTable for display control the ow of data. The user, interacting with the mmDataTable window, controls how the data is displayed. Upon launch, mmDataTable displays only a menubar. Upon user request, a display window below the menubar displays data values. Each message from a client contains a list of (name, value, units) triples containing data for display. For example, one element in the list might be {Magnetization 800000 A/m}. mmDataTable stores the latest value it receives for each name. Earlier values are discarded when new data arrives from a client.

Outputs
mmDataTable does not support any data output or storage facilities. To save tabular data, use the mmGraph (Sec. 12) or mmArchive (Sec. 14) applications.

Controls
The Data menu holds a list of all the data names for which mmDataTable has received data. Initially, mmDataTable has received no data from any clients, so this menu is empty. As data arrives from clients, the menu lls with the list of data names. Each data name on the list lies next to a checkbutton. When the checkbutton is toggled from o to on, the corresponding data name and its value and units are displayed at the bottom of the display window. When the checkbutton is toggled from on to o, the corresponding data name is removed from the display window. In this way, the user selects from all the data received what is to be displayed. Selecting the dashed rule at the top of the Data menu detaches it so the user may easily click multiple checkbuttons. Displayed data values can be individually selected (or deselected) with a left mouse button click on the display entry. Highlighting is used to indicated which data values are currently selected. The Options menu also contains commands to select or deselect all displayed values. The selected values can be copied into the cut-and-paste (clipboard) buer with the CTRL-c key combination, or the Options|Copy menu command. The data value selection mechanism is also used for data value formatting control. The Options|Format menu command brings up a Format dialog box to change the justication and format specication string. The latter is the conversion string passed to the Tcl format command, which uses the C printf format codes. If the Adjust:Selected radiobutton is active, then the specication will be applied to only the currently selected (highlighted) data values. Alternately, if Adjust:All is active, then the specication will be applied to all data values, and will additionally become the default specication. A right mouse button click on a display entry will select that entry, and bring up the Format dialog box with the justication and format specications of the selected entry. These specications, with any revisions, may then be applied to all of the selected entries.

92

If a value cannot be displayed with the selected format specication string, e.g., if a %d integer format were applied to a string containing a decimal point, then the value will be printed in red in the form as received by mmDataTable, without any additional formatting. The menu selection File|Reset reinitializes the mmDataTable application to its original state, clearing the display and the Data menu. The reset operation is also automatically invoked upon receipt of new data following a data set close message from a solver application. The menu selection File|Exit terminates the application. The menu Help provides the usual help facilities.

93

12

Data Graph Display: mmGraph

Overview
The application mmGraph provides a data display service similar to that of mmDataTable (Sec. 11). The usual data source is a running solver, but rather than the textual output provided by mmDataTable, mmGraph produces 2D line plots. mmGraph also stores the data it receives, so it can produce multiple views of the data and can save the data to disk. Postscript output is also supported.

Launching
mmGraph may be started either by selecting the mmGraph button on mmLaunch or from the command line via tclsh oommf.tcl mmGraph [standard options] [-net <0|1>] -net <0|1> Disable or enable a server which allows the data displayed by mmGraph to be updated by another application. By default, the server is enabled. When the server is disabled, mmGraph may only input data from a le.

94

Inputs
Input to mmGraph may come from either a le in the ODT format (Sec. 18), or when -net 1 (the default) is active, from a client application (typically a running solver). The File|Open. . . dialog box is used to select an input le. Receipt of data from client applications is the same as for mmDataTable (Sec. 11). In either case, input data are appended to any previously held data. Curve breaks (i.e., separation of a curve into disjoint segments) are recorded in the data storage buer via curve break records. These records are generated whenever a Table Start or a Table End record is read from an ODT le, when a data set close message is received from a client application, or when requested by the user using the mmGraph Options|Break menu option.

Outputs
Unlike mmDataTable, mmGraph internally stores the data sent to it. These data may be written to disk via the File|Save As... dialog box. If the le specied already exists, then mmGraph output is appended to that le. The output is in the tabular ODT format described in Sec. 18. The data are segmented into separate Table Start/Table End blocks across each curve break record. By default, all data currently held by mmGraph is written, but the Save: Selected Data option presented in the File|Save As... dialog box causes the output to be restricted to those curves currently selected for display. In either case, the graph display limits do not aect the output. The save operation writes records that are held by mmGraph at the time the File|Save As... dialog box OK button is invoked. Additionally, the Auto Save option in this dialog box may be used to automatically append to the specied le each new data record as it is received by mmGraph. The appended elds will be those chosen at the time of the save operation, i.e., subsequent changing of the curves selected for display does not aect the automatic save operation. The automatic save operation continues until either a new output le is specied, the Options|Stop autosave control is invoked, or mmGraph is terminated. The File|Print... dialog is used to produce a Postscript le of the current graph. On Unix systems, the output may be sent directly to a printer by lling the Print to: entry with the appropriate pipe command, e.g., |lpr. (The exact form is system dependent.)

Controls
Graphs are constructed by selecting any one item o the X-axis menu, and any number of items o the Y1-axis and Y2-axis menus. The y1-axis is marked on the left side of the graph; the y2-axis on the right. These menus may be detached by selecting the dashed rule at the top of the list. Sample results are shown in the gure at the start of this section. When mmGraph is rst launched, all the axis menus are empty. They are dynamically built based on the data received by mmGraph. By default, the graph limits and labels are 95

automatically set based on the data. The x-axis label is set using the selected item data label and measurement unit (if any). The y-axes labels are the measurement unit of the rst corresponding y-axis item selected. The Options|Congure... dialog box allows the user to override default settings. To change the graph title, simply enter the desired title into the Title eld. To set the axis labels, deselect the Auto Label option in this dialog box, and ll in the X Label, Y1 Label and Y2 Label elds as desired. The axis limits can be set in a similar fashion. In addition, if an axis limit is left empty, a default value (based on all selected data) will be used. The size of the margin surrounding the plot region is computed automatically. Larger margins may be specied by lling in the appropriate elds in the Margin Requests section. Units are pixels. Requested values smaller than the computed (default) values are ignored. As mentioned earlier, mmGraph stores in memory all data it receives. Over the course of a long run, the amount of data stored can grow to many megabytes. This storage can be limited by specifying a positive (> 0) value for the Point buer size entry in the Options|Congure... dialog box. The oldest records are removed as necessary to keep the total number of records stored under the specied limit. A zero value for Point buer size is interpreted as no limit. (The storage size of an individual record depends upon several factors, including the number of items in the record and the version of Tcl being used.) Data erasures may not be immediately reected in the graph display. At any time, the point buer storage may be completely emptied with the Options|clear Data command. The Options|stop Autosave selection will turn o the auto save feature, if currently active. Also on this menu is Options|Rescale, which autoscales the graph axis limits from the selected data. This command ignores but does not reset the Auto Scale settings in the Options|Congure... dialog box. The Options|Break item inserts a curve break record into the point buer, causing a break in each curve after the current point. This option may be useful if mmGraph is being fed data from multiple sources. The Options|Key selection toggles the key (legend) display on and o. The key may also be repositioned by dragging with the left mouse button. If curves are selected o both the y1 and y2 menus, then a horizontal line in the key separates the two sets of curves, with the labels for the y1 curves on top. The last command on the options menu is Options|Smooth. If smoothing is disabled, then the data points are connected by straight line segments. If enabled, then each curve is rendered as a set of parabolic splines, which do not in general pass through the data points. This is implemented using the --smooth 1 option to the Tcl canvas create line command; see that documentation for details. The width of the lines may be changed by the usual method of local customization (Sec. 2.3.2). The default setting in config/options.tcl is Oc_Option Add mmGraph Ow_GraphWin curve_width 2 which makes the line segments 2 pixels wide. This can be set to any positive integer value. Curves will be rendered more quickly, especially on Windows, if curve width is set to 1.

96

A few other controls are also available only through the mouse. If the mouse pointer is positioned over a drawn item in the graph, holding down the left mouse button will bring up the coordinates of that point, with respect to the y1-axis. Similarly, depressing the right mouse button, or alternatively holding down the shift key while pressing the left mouse button will bring up the coordinates of the point with respect to the y2-axis. The coordinates displayed are the coordinates of a point on a drawn line, which are not necessarily the coordinates of a plotted data point. (The data points are plotted at the endpoints of each line segment.) The coordinate display is cleared when the mouse button is released. One vertical and one horizontal rule (line) are also available. Initially, these rules are tucked and hidden against the left and bottom graph axes, respectively. Either may be repositioned by dragging with the left or right mouse button. The menu selection File|Exit terminates the mmGraph application. The menu Help provides the usual help facilities.

Details
The axes menus are congured based on incoming data. As a result, these menus are initially empty. If a graph widget is scheduled to receive data only upon control point or stage done events in the solver, it may be a long time after starting a problem in the solver before the graph widget can be congured. Because mmGraph keeps all data up to the limit imposed by the Point buffer size, data loss is usually not a problem. Of more importance is the fact that automatic data saving can not be set up until the rst data point is received. As a workaround, the solver initial state may be sent interactively as a dummy point to initialize the graph widget axes menus. Select the desired quantities o the axes menus, and use the Options|clear Data command to remove the dummy point from mmGraphs memory. The File|Save As... dialog box may then be usedwith the Auto Save option enabledto write out an empty table with proper column header information. Subsequent data will be written to this le as they arrive.

97

13

Vector Field Display: mmDisp

Overview
The application mmDisp displays two-dimensional spatial distributions of three-dimensional vectors (i.e., vector elds). It can load vector elds from les in a variety of formats, or it can accept vector eld data from a client application, typically a running solver. mmDisp oers a rich interface for controlling the display of vector eld data, and can also save the data to a le and produce Postscript print output.

Launching
mmDisp may be started either by selecting the mmDisp button on mmLaunch, or from the command line via tclsh oommf.tcl mmDisp [standard options] [-net <0|1>] [filename] -net <0|1> Disable or enable a server which allows the data displayed by mmDisp to be updated by another application. By default, the server is enabled. When the server is disabled, mmDisp may only input data from a le. If a lename is supplied on the command line, mmDisp takes it to be the name of a le containing vector eld data for display. That le will be opened on startup.

98

Inputs
Input to mmDisp may come from either a le or from a client application (typically a running solver), in any of the vector eld formats described in Sec. 19. Other le formats can also be supported if a translation lter program is available. Client applications that send data to mmDisp control the ow of data. The user, interacting with the mmDisp window, determines how the vector eld data are displayed. File input is initiated through the File|Open. . . dialog box. Several example les are included in the OOMMF release in the directory app/mmdisp/examples. When the Browse button is enabled, the Open File dialog box will remain open after loading a le, so that multiple les may be displayed in sequence. The Auto conguration box determines whether the vector subsampling, data scale, zoom and slice settings should be determined automatically (based on the data in the le and the current display window size), or whether their values should be held constant while loading the le. mmDisp permits local customization allowing for automatic translation from other le formats into one of the vector eld formats (Sec. 19) that mmDisp recognizes. When loading a le, mmDisp compares the le name to a list of glob-style patterns. These patterns typically match on the lename extension. An example pattern is *.gz. The assumption is that the pattern identies les containing data in a particular format. For each pattern in the list, there is a corresponding translation program. mmDisp calls on that program as a lter which takes data in one format from standard input and writes to standard output the same data in one of the formats supported by mmDisp. In its default conguration, mmDisp recognizes the pattern *.gz and invokes the translation program gzip -dc to perform the translation. In this way, support for reading gzip compressed les is built in to mmDisp on any platform where the gzip program is installed. New patterns and translation programs may be added to mmDisp by the usual method of local customization (Sec. 2.3.2). The command to add to the customization le is of the form Oc_Option Add mmDisp Input filters {{*.gz {gzip -dc}}} The nal argument in this command is a list of pairs. The rst element in each pair is the lename pattern. The second element in each pair is the command line for launching the corresponding translation program. If a program foo were known to translate a le format identied by the extension .bar into the OVF le format, that program could be made known to mmDisp by changing the above customization command to: Oc_Option Add mmDisp Input filters {{*.gz {gzip -dc}} {*.bar foo}}

Outputs
The vector eld displayed by mmDisp may be saved to disk via the File|Save As. . . dialog box. The output is in the OVF format (Sec. 19.1). The OVF le options may be set by 99

selecting the appropriate radio buttons in the OVF File Options panel. The Title and Desc elds may be edited before saving. Enabling the Browse button allows for saving multiple les without closing the Save File dialog box. The File|Print. . . dialog is used to produce a Postscript le of the current display. On Unix systems, the output may be sent directly to a printer by lling the Print to: entry with the appropriate pipe command, e.g., |lpr. (The exact format is system dependent.) To produce bitmap output, save the le to disk in the OVF format, and use the avf2ppm (Sec. 16.4) utility to do the conversion.

Controls
The menu selection File|Clear clears the display window. The menu selection File|Exit terminates the mmDisp application. The menu Help provides the usual help facilities. The View menu provides high-level control over how the vector eld is placed in the display window. The menu selection View|Wrap Display resizes the display window so that it just contains the entire vector eld surrounded by a margin. View|Fill Display resizes the vector eld until it lls the current size of the display window. If the aspect ratio of the display window does not match the aspect ratio of the vector eld, a larger than requested margin appears along one edge to make up the dierence. View|Rotate ccw and View|Rotate cw rotate the display one quarter turn counter-clockwise and clockwise respectively. The display window also rotates, so that the portion of the vector eld seen and any margins are preserved (unless the display of the control bar forces the display window to be wider). View|reDraw allows the user to invoke a redrawing of the display window. The View|Viewpoint tearable submenu supports rotation of the vector eld out of the plane of the display, so that it may be viewed from along a dierent axis. The menu selection Options|Congure. . . brings up a dialog box through which the user may control many features of the vector eld display. Vectors in the vector eld may be displayed as arrows, pixels, or both. The Arrow and Pixel buttons in the Plot type column on the left of the dialog box enable each type of display. Columns 24 in the Congure dialog box control the use of color. Both arrows and pixels may be independently colored to indicate some quantity. The Color Quantity column controls which scalar quantity the color of the arrow or pixel represents. Available color quantities include vector x, y, and z components, total vector magnitude, slice depth, and angles as measured in-plane from a xed axis. On regularly gridded data the vector eld divergence is also available for display. The assignment of a color to a quantity value is determined by the Colormap selected. Colormaps are labeled by a sequence of colors that are mapped across the range of the selected quantity. For example, if the Red-Black-Blue colormap is applied to the Color Quantity z, then vectors pointing into the xy-plane (z < 0) are colored red, those lying in the plane (z = 0) are colored black, and those pointing out of the plane (z > 0) are colored blue. Values between the extremes are colored with intermediate colors, selected using a discretization determined by the # of Colors value. This value governs the use of 100

potentially limited color resources, and can be used to achieve some special coloring eects. (Note: The in-plane angle quantities are generally best viewed with a colormap that begins and ends with the same color, e.g., Red-Green-Blue-Red.) The ordering of the colormap can be reversed by selecting the Reverse checkbox. For example, this would change the Red-Black-Blue colormap to eectively Blue-Black-Red. Below the Reverse checkbutton in the pixel plot type row is a Opaque checkbutton. If this is selected then arrows below the top row in the pixel slice range (see slice discussion below) will be hidden by the pixel object. If disabled, then the pixel object is translucent, so objects further below are partially visible. When there are many vectors in a vector eld, a display of all of them may be more confusing than helpful. The Subsample column allows the user to request that only a sampling of vectors from the vector eld be displayed. The Subsample value is roughly the number of vectors along one spatial dimension of the vector eld which map to a single displayed vector (arrow or pixel). Each vector displayed is an actual vector in the vector eldthe selection of vectors for display is a sampling process, not an averaging or interpolation process. The subsample rates for arrows and pixels may be set independently. A subsample rate of 0 is interpreted specially to display all data. (This is typically much quicker than subsampling at a small rate, e.g., 0.1.) The length of an arrow represents the magnitude of the vector eld. All arrows are drawn with a length between zero and full-scale. By default, the full-scale arrow length is computed so that it covers the region of the screen that one displayed vector is intended to represent, given the current subsample rate. Following this default, arrows do not signicantly overlap each other, yet all non-zero portions of the vector eld have a representation in the display. Similarly, pixels are drawn with a default size that lls an area equal to the region of the screen one pixel is intended to represent, given the pixel subsample rate. The Size column allows the user to (independently) override the default size of pixels and full-scale arrows. A value of 1 represents the default size. By changing to a larger or smaller Size value, the user may request arrows or pixels larger or smaller than the default size. Below the Arrow and Pixel Controls are several additional controls. The Data Scale entry aects the data value scaling. As described above, all arrows are displayed with length between zero and full-scale. The full-scale arrow length corresponds to some scalar value of the magnitude of the vector eld. The Data Scale entry allows the user to set the value at which the drawn arrow length goes full-scale. Any vectors in the vector eld with magnitude equal to or greater than the data scale value will be represented by arrows drawn at full scale. Other vectors will be represented by shorter arrows with length determined by a linear scale between zero and the data scale value. Similarly, the data scale value controls the range of values spanned by the colormap used to color pixels. The usual use of the Data Scale entry is to reduce the data scale value so that more detail can be seen in those portions of the vector eld which have magnitude less than other parts of the vector eld. If the data scale value is increased, then the length of the arrows in the plot is reduced accordingly. If the data scale value is decreased, then the length of the arrows is increased, until they reach full-scale. An arrow representing a vector with magnitude larger than the data scale 101

value may be thought of as being truncated to the data scale value. The initial (default) data scale value is usually the maximum vector magnitude in the eld, so at this setting no arrows are truncated. Entering 0 into the data scale box will cause the data scale to be reset to the default value. (For OVF les (Sec. 19.1), the default data scale value is set from the ValueRangeMaxMag header line. This is typically set to the maximum vector magnitude, but this is not guaranteed.) The data scale control is intended primarily for use with vector elds of varying magnitude (e.g., H-elds), but may also be used to adjust the pixel display contrast for any eld type. The Zoom entry controls the spatial scaling of the display. The value roughly corresponds to the number of pixels per vector in the fully-sampled vector eld. (This value is not aected by the subsampling rate.) The Margin entry species the margin size, in pixels, to be maintained around the vector eld. The next row of entry boxes control slice display. Slice selection allows display of that subset of the data that is within a specied distance of a plane running perpendicular to the view axis. The location of that plane with respect to the view axis is specied in the X-slice center, Y-slice center or Z-slice center entry, depending on the current view axis. The thickness of the slice may be varied separately for arrow and pixel displays, as specied in the next two entry boxes. The slice span boxes interpret specially the following values: 0 resets the slice thickness to the default value, which is usually the thickness of a single cell. Any negative value sets the slice thickness to be the full thickness of the mesh. Values for all of the slice control entries are specied in the fundamental mesh spatial unit, for example, meters. (Refer to the vector eld le format (Sec. 19) documentation for more on mesh spatial units.) Below the slice contols are controls to specify whether or not a bounding polygon is displayed, and the background color for the display window. No changes made by the user in the Options|Congure. . . dialog box aect the display window until either the Apply or OK button is selected. If the OK button is selected, the dialog box is also dismissed. The Close button dismisses the dialog without changing the display window. The next item under the Options menu is a checkbutton that toggles the display of a control bar. The control bar oers alternative interfaces to some of the operations available from the Options|Congure. . . dialog box and the View menu. On the left end of the control bar is a display of the coordinate axes. These axes rotate along with the vector eld in the display window to identify the coordinate system of the display, and are color coded to agree with the pixel (if active) or arrow coloring. A click of the left mouse button on the coordinate axes causes a counter-clockwise rotation. A click of the right mouse button on the coordinate axes causes a clockwise rotation. To the right of the coordinate axes are two rows of controls. The top row allows the user to control the subsample rate and size of displayed arrows. The subsample rate may be modied either by direct entry of a new rate, or by manipulation of the slider. The second row controls the current data scale value and zoom (spatial magnication). A vertical bar 102

in the slider area marks the default data scale value. Specifying 0 for the data scale value will reset the data scale to the default value. The spatial magnication may be changed either by typing a value in the Zoom box of the control bar, or by using the mouse inside the display window. A click and drag with the left mouse button displays a red rectangle that changes size as the mouse is dragged. When the left mouse button is released, the vector eld is rescaled so that the portion of the display window within the red rectangle expands until it reaches the edges of the display window. Both dimensions are scaled by the same amount so there is no aspect distortion of the vector eld. Small red arrows on the sides of the red rectangle indicate which dimension will expand to meet the display window boundaries upon release of the left mouse button. After the rescaling, the red rectangle remains in the display window briey, surrounding the same region of the vector eld, but at the new scale. A click and drag with the right mouse button displays a blue rectangle that changes size as the mouse is dragged. When the right mouse button is released, the vector eld is rescaled so that all of the vector eld currently visible in the display window ts the size of the blue rectangle. Both dimensions are scaled by the same amount so there is no aspect distortion of the vector eld. Small blue arrows on the sides of the blue rectangle indicate the dimension in which the vector eld will shrink to exactly transform the display window size to the blue rectangle size. After the rescaling, the blue rectangle remains in the display window briey, surrounding the same region of the vector eld, now centered in the display window, and at the new scale. When the zoom value is large enough that a portion of the vector eld lies outside the display window, scrollbars appear that may be used to translate the vector eld so that dierent portions are visible in the display window. On systems that have a middle mouse button, clicking the middle button on a point in the display window translates the vector eld so that the selected point is centered within the display window. mmDisp remembers the previous zoom value and data scale values. To revert to the previous settings, the user may hit the ESC key. This is a limited Undo feature. Below the data scale and zoom controls in the control bar is the slice center selection control. This will be labeled Z-slice, X-slice, or Y-slice, depending on which view axis is selected. The thickness of the slice can be set from the Options|Congure. . . dialog box. The nal item under the Options menu is the Options|Lock size checkbutton. By default, when the display is rotated in-plane, the width and height of the viewport are interchanged so that the same portion of the vector eld remains displayed. Selecting the Options|Lock size checkbutton disables this behavior, and also other viewport changing operations (e.g., display wrap). Several keyboard shortcuts are available as alternatives to menu- or mouse-based operations. (These are in addition to the usual keyboard access to the menu.) The eect of a key combination depends on which subwindow of mmDisp is active. The TAB key may be used to change the active subwindow. The SHIFT-TAB key combination also changes the active subwindow, in reverse order. When the active subwindow is the display window, the following key combinations are 103

active: CTRL-o same as menu selection File|Open. . . CTRL-s same as menu selection File|Save as. . . CTRL-p same as menu selection File|Print. . . CTRL-c same as menu selection Options|Congure. . . CTRL-v launches viewpoint selection menu, View|Viewpoint CTRL-w same as menu selection View|Wrap Display CTRL-f same as menu selection View|Fill Display HOME First ll, then wrap the display. CTRL-space Center view in display. CTRL-r same as menu selection View|Rotate ccw SHIFT-CTRL-r same as menu selection View|Rotate cw INSERT decrease arrow subsample by 1 DEL increase arrow subsample by 1 SHIFT-INSERT decrease arrow subsample by factor of 2 SHIFT-DEL increase arrow subsample by factor of 2 PAGEUP increase the zoom value by a factor of 1.149 PAGEDOWN decrease the zoom value by a factor of 1.149 SHIFT-PAGEUP increase the zoom value by factor of 2 SHIFT-PAGEDOWN decrease the zoom value by factor of 2 ESC revert to previous data scale and zoom values When the active subwindow is the control bars coordinate axes display, the following key combinations are active: LEFT same as menu selection View|Rotate ccw RIGHT same as menu selection View|Rotate cw When the active subwindow is any of the control bars value entry windows arrow subsample, size, data scale or zoom, the following key combinations are active: 104

 ESC undo uncommitted value (displayed in red) RETURN commit entered value When the active subwindow is in any of the control bars slidersarrow subsample, data scale or slicethe following key combinations are active: LEFT slide left (decrease value) RIGHT slide right (increase value) ESC undo uncommitted value (displayed in red) RETURN commit current value When any of the separate dialog windows are displayed (e.g., the File|Open. . . or Options|Congure. . . dialogs), the shortcut CTRL-. (control-period) will raise and transfer keyboard focus back to the root mmDisp window.

Details
The selection of vectors for display according to the Subsample diers depending on whether or not the data lie on a regular grid. If so, Subsample takes integer values and determines the ratio of data points to displayed points. For example, a value of 5 means that every fth vector on the grid is displayed. This means that the number of vectors displayed is 25 times fewer than the number of vectors on the grid. For an irregular grid of vectors, an average cell size is computed, and the Subsample takes values in units of 0.1 times the average cell size. A square grid of that size is overlaid on the irregular grid. For each cell in the square grid, the data vector from the irregular grid closest to the center of the square grid cell is selected for display. The vector is displayed at its true location in the irregular grid, not at the center of the square grid cell. As the subsample rate changes, the set of displayed vectors also changes, which can in some circumstances substantially change the appearance of the displayed vector eld.

Using mmDisp as a WWW browser helper application

You may congure your web browser to automatically launch mmDisp when downloading an OVF le. The exact means to do this depends on your browser, but a couple of examples are presented below. In Netscape Navigator 4.X, bring up the Edit|Preferences. . . dialog box, and select the Category Navigator|Applications subwindow. Create a New Type, with the following elds: Description of type: OOMMF Vector Field MIME Type: application/x-oommf-vf 105

Suxes: ovf,omf,ohf,obf Application: tclsh oommfroot/oommf.tcl +fg mmDisp -net 0 arg On Windows platforms, the Suffixes eld is labeled File Extension, and only one le extension may be entered. Files downloaded from a web server are handled according to their MIME Type, rather than their le extension, so that restriction isnt important when web browsing. If you wish to have les on the local disk with all the above le extensions recognized as OOMMF Vector Field les, you must repeat the New Type entry for each le extension. In the Application eld, the values of tclsh, oommfroot, and arg vary with your platform conguration. The value of tclsh is the full path to the tclsh application on your platform (see Section 5). On Unix systems, tclsh may be omitted, assuming that the oommf.tcl script is executable. If tclsh is not omitted on Unix systems, Netscape may issue a security warning each time it opens an OOMMF Vector Field le. The value of oommfroot should be the full path to the root directory of your OOMMF installation. The value of arg should be %1 on Windows and %s on Unix. The MIME type application/x-oommf-vf must be congured on any HTTP server which provides OOMMF Vector Field les as well. For Microsoft Internet Explorer 3.X, bring up the View|Options. . . dialog box, and select the Program tab. Hit the File Types. . . button, followed by the New Type. . . button. Fill the resulting dialog box with Description of type: OOMMF Vector Field Associated extension: ovf Content type (MIME): application/x-oommf-vf You may also disable the Conrm open after download checkbutton if you want. Then hit the New. . . button below the Actions: window, and in the pop-up ll in Action: open Application used to perform action: tclsh oommfroot/oommf.tcl +fg mmDisp -net 0 %1 Hit OK, Close, Close and OK. Replace tclsh and oommfroot with the appropriate paths on your system (cf. Section 5). This will set up an association on les with the .ovf extension. Internet Explorer 3.X apparently ignores the HTML Content Type eld, so you must repeat this process for each le extension (.ovf, .omf, .ohf, .obf and .svf) that you want to recognize. This means, however, that Internet Explorer will make the appropriate association even if the HTML server does not properly set the HTML Content Type eld. Microsoft Internet Explorer 4.X is integrated with the Windows operating system. Internet Explorer 4.X doesnt oer any means to set up associations between particular le types and the applications which should be used to open them. Instead, this association is congured within the Windows operating system. To set up associations for the OOMMF 106

Vector Field le type on Windows 95 or Windows NT, select Settings|Control Panel from the Start menu. The Control Panel window appears. Select View|Options. . . to display a dialog box. A Windows 98 shortcut to the same dialog box is to select Settings|Folder Options. . . from the Start menu. Select the File Types tab and proceed as described above for Internet Explorer 3.X. Depending on the exact release/service patch of your Windows operating system, the exact instructions may vary. Once you have your browser congured, you can test with the following URL: http://math.nist.gov/MDonahue/cubevortex.ovf

Known Bugs
The slice selection feature does not work properly with irregular meshes.

107

14

Data Archive: mmArchive

Overview
The application mmArchive provides automated vector eld and data table storage services. Although mmDisp (Sec. 13) and mmGraph (Sec. 12) are able to save such data under the direction of the user, there are situations where it is more convenient to write data to disk without interactive control. mmArchive does not present a user interface window of its own, but like mmSolve2D (Sec. 10.1) relies on mmLaunch (Sec. 6) to provide an interface on its behalf. Because mmArchive does not require a window, it is possible on Unix systems to bring down the X (window) server and still keep mmArchive running in the background.

Launching
mmArchive may be started either by selecting the mmArchive button on mmLaunch, or from the command line via tclsh oommf.tcl mmArchive [standard options] When the mmArchive button of mmLaunch is invoked, mmArchive is launched with the -tk 0 option. This allows mmArchive to continue running if the X window server is killed. The -tk 1 option is useful only for enabling the -console option for debugging. As noted above, mmArchive depends upon mmLaunch to provide an interface. The entry for an instance of mmArchive in the Threads column of any running copy of mmLaunch has a checkbutton next to it. This button toggles the presence of a user interface window through which the user may control that instance of mmArchive.

Inputs
mmArchive accepts vector eld and data table style input from client applications (typically running solvers) on its network (socket) interface.

Outputs
The client applications that send data to mmArchive control the ow of data. mmArchive copies the data it receives into les specied by the client. There is no interactive control to select the names of these output les. A simple status line shows the most recent vector le save, or data table le open/close event. 108

Controls
The Exit in the mmLaunch-supplied user interface terminates mmArchive. Simply closing the user interface window does not terminate mmArchive, but only hides the control window. To kill mmArchive the Exit button must be pressed.

Known Bugs
mmArchive appends data table output to the le specied by the source client application (e.g., a running solver). If, at the same time, more than one source species the same le, or if the the same source sends data table output to more than one instance of mmArchive, then concurrent writes to the same le may corrupt the data in that le. It is the responsibility of the user to ensure this does not happen; there is at present no le locking mechanism in OOMMF to protect against this situation.

109

15

Documentation Viewer: mmHelp

Overview
The application mmHelp manages the display and navigation of hypertext (HTML) help les. It presents an interface similar to that of World Wide Web browsers. Although mmHelp is patterned after World Wide Web browsers, it does not have all of their capabilities. mmHelp displays only a simplied form of hypertext required to display the OOMMF help pages. It is not able to display many of the advanced hypertext features provided by modern World Wide Web browsers. In the current release, mmHelp is not able to follow http: URLs. It only follows file: URLs, such as le:/path/to/oommf/doc/userguide/userguide/Documentation Viewer mmHelp.html OOMMF software can be customized (See Sec. 2.3.2) to use another program to display the HTML help les.

Launching
mmHelp may be launched from the command line via tclsh oommf.tcl mmHelp [standard options] [URL] The command line argument URL is the URL of the rst page (home page) to be displayed. If no URL is specied, mmHelp displays the Table of Contents of the OOMMF Users Guide by default.

110

Controls
Each page of hypertext is displayed in the main mmHelp window. Words which are underlined and colored blue are hyperlinks which mmHelp knows how to follow. Words which are underlined and colored red are hyperlinks which mmHelp does not know how to follow. Moving the mouse over a hyperlink displays the target URL of the hyperlink in the Link: line above the display window. Clicking on a blue hyperlink will follow the hyperlink and display a new page of hypertext. mmHelp keeps a list of the viewed pages in order of view. Using the Back and Forward buttons, the user may move backward and forward through this list of pages. The Home button causes the rst page to be displayed, allowing the user to start again from the beginning. These three buttons have corresponding entries in the Navigate menu. Use the menu selection File|Open to directly select a le from the le system to be displayed by mmHelp. The menu selection File|Refresh, or the Refresh button causes mmHelp to reload and redisplay the current page. This may be useful if the display becomes corrupted, or for repeatedly loading a hypertext le which is being edited. When mmHelp encounters hypertext elements it does not recognize, it will attempt to work around the problem. However, in some cases it will not be able to make sense of the hypertext, and will display an error message. Documentation authors should take care to use only the hypertext elements supported by mmHelp in their documentation les. Users should never see such an error message. mmHelp displays error messages in one of two ways: within the display window, or in a separate window. Errors reported in the display window replace the display of the page of hypertext. They usually indicate that the hypertext page could not be retrieved, or that its contents are not hypertext. File permission errors are also reported in this way. Errors reported in a separate window are usually due to a formatting error within the page of hypertext. Selecting the Continue button of the error window instructs mmHelp to attempt to resume display of the hypertext page beyond the error. Selecting Abort abandons further display. The menu selection Options|Font scale... brings up a dialog box through which the user may select the scale of the fonts to use in the display window, relative to their initial size. The menu selection File|Exit or the Exit button terminates the mmHelp application. The menu Help provides the usual help facilities.

Known Bugs
mmHelp is pretty slow. You may be happier using local customization (Sec. 2.3.2) methods to replace it with another more powerful HTML browser. Also, we have noticed that the underscore character in the italic font is not displayed (or is displayed as a space) at some font sizes on some platforms.

111

16

Command Line Utilities

This section documents a few utilities distributed with OOMMF that are run from the command line (Unix shell or Windows DOS prompt). They are typically used in pre- or post-processing of data associated with a micromagnetic simulation.

16.1

Bitmap File Format Conversion: any2ppm

The any2ppm program converts bitmap les of various formats into the Portable Pixmap (PPM) P3 (text) format. Supported input formats are PPM, BMP, and GIF. Additional formats may be available if the Tcl/Tk Img 12 package is installed on your system. (Note: OOMMF support for BMP requires Tk 8.0 or later.) Launching The any2ppm launch command is: tclsh oommf.tcl any2ppm [standard options] [-noinfo] \ [-o outfile] [infile ...] where -noinfo Suppress writing of progress information to stderr. -o outle Write output to outname; use - to pipe output to stdout. The default is to create a new le by stripping the extension, if any, o of each input lename, and appending .ppm. If the generated lename already exists, a -000 or -001 . . . sux is appended. If the input is coming from stdin, i.e., there is no input lename, then the default output is to stdout. Note that if outname is specied, then all output will go to this one le; in this case it is unlikely that one wants to specify more than one input le. inle . . . List of input les to process. If none, or if an inle is the empty string, then read from stdin. Tk Requirement: any2ppm uses the Tk image command in its processing. This requires that Tk be properly initialized, which in particular means that a valid display must be available. This is not a problem on Windows, where a desktop is always present, but on Unix this means that an X server must be running. The Xvfb 13 virtual framebuer can be used if desired. (Xvfb is an X server distributed with X11R6 that requires no display hardware or physical input devices.)
12 13

http://purl.oclc.org/net/nijtmans/img.html http://www.itworld.com/AppDev/1461/UIR000330xvfb/

112

16.2

Making Data Tables from Vector Fields: avf2odt

The avf2odt program converts rectangularly meshed vector eld les in any of the recognized formats (OVF, VIO; see Sec. 19) into the ODT 1.0 (Sec. 18) data table format. Launching The avf2odt launch command is: tclsh oommf.tcl avf2odt [standard options] \ [-average <space|plane|line|point>] [-axis <x|y|z>] \ [-region <xmin> <ymin> <zmin> <xmax> <ymax> <zmax>] \ infile >outfile where -average <space|plane|line|point> Specify type of averaging. Space outputs 1 data line consisting of the average vx , vy and vz eld values in the selected region (see -region option below). For example, in magnetization les, vx , vy and vz correspond to Mx , My and Mz . If plane or line is selected, then the output data table consists of multiple lines with 4 or 5 columns respectively. The last 3 columns in both cases are the vx , vy and vz averaged over the specied axes-parallel ane subspace (i.e., plane or line). In the plane case, the rst column species the averaging plane oset along the coordinate axis normal to the plane (see -axis option below). In the line case, the rst 2 columns specify the oset of the averaging line in the coordinate plane perpendicular to the line. If -type is set to point, then no averaging is done, and the output consists of 6 column data lines, one line for each point in the selected region, where the rst 3 columns are the point coordinates, and the last 3 are the vx , vy and vz values at the point. This parameter is optional. The default value is space. -axis <x|y|z> For the -type plane and -type line averaging types, selects which subset of ane subspaces the averaging will be performed over. In the plane case, the -axis represents the normal direction to the planes, while for line it is the direction parallel to the lines. This parameter is ignored if -type is space or point. Optional; default is x. -region <xmin> <ymin> <zmin> <xmax> <ymax> <zmax> Axes-parallel rectangular box denoting region in the vector eld le over which data is to be collected. The locations are in problem units (typically meters). A single hyphen, -, may be specied for any of the box corner coordinates, in which case the corresponding extremal value from the input le is used. Optional; the default, -region - - - - - -, selects the entire input le.

113

inle Name of input le to process. Must be one of the recognized formats, OVF 1.0 or VIO, in a rectangular mesh subformat. Required. >outle Avf2odt writes its output to stdout. Use the redirection operator > to send the output to a le. For output format details, see the ODT le description (Sec. 18). Note: The mx , my and mz average magnetization values reported by mmSolve2D (Sec. 10.1) exclude points with 0 saturation magnetization. Such points are included by avf2odt, so the data table output from this program will probably not agree with that directly output by mmSolve2D if there are any such regions.

16.3

Vector Field File Format Conversion: avf2ovf

The avf2ovf program converts vector eld les from any of the recognized formats (OVF, VIO; see Sec. 19) into the OVF 1.0 format. Launching The avf2ovf launch command is: tclsh oommf.tcl avf2ovf [standard options] \ [-clip xmin ymin zmin xmax ymax zmax] [-flip flipstr] \ [-format <text|b4|b8>] [-grid <reg|irreg>] [-info] \ infile >outfile where -clip xmin ymin zmin xmax ymax zmax The arguments specify the vertices of a bounding clip box. Only mesh points inside the clip box are brought over into the output le. -ip ipstr Provides an axis coordinate transformation. Flipstr has the form A:B:C, where A, B, C is a permutation of x, y, z, with an optional minus sign on each entry. The rst component A denotes the axis to which x is mapped, B where y is mapped, and C where z is mapped. The default is the identity map, x:y:z. To rotate 90 about the z-axis, use -ip y:-x:z, which sends x to the +y axis, y to the -x axis, and leaves z unchanged. -format <text|b4|b8> Specify output data format. The default is ASCII text; b4 selects 4-byte binary, b8 selects 8-byte binary. (The OVF format has an ASCII text header in all cases.) -grid <reg|irreg> Specify output grid structure. The default is reg, which will output a regular (rectangular) grid if the input is recognized as a regular grid. The option -grid irreg forces irregular mesh style output. 114

-info Instead of converting the le, print to stderr information about the le, such as size, range, and descriptive text from the le header. inle Name of input le to process. Must be one of the recognized formats, OVF 0.0, OVF 1.0, or VIO. >outle Avf2ovf writes its output to stdout. Use the redirection operator > to send the output to a le. The -clip option is useful when one needs to do analysis on a small piece of a large simulation. The -info option is helpful here to discover the extents of the original mesh. The -flip option can change be used to align dierent simulations to the same orientation. It can also be used to change a le into its mirror image; for example, -ip -x:y:z reects the mesh through the yz-plane. The -format text and -grid irreg options are handy for preparing les for import into non-OOMMF applications, since all non-data lines are readily identied by a leading #, and each data line is a 6-tuple consisting of the node location and vector value. Pay attention, however, to the scaling of the vector value as specied by # valueunit and # valuemultiplier header lines. For output format details, see the OVF le description (Sec. 19.1).

16.4

Making Bitmaps from Vector Fields: avf2ppm

The avf2ppm utility converts a collection of vector eld les (e.g., .omf, .ovf) into color bitmaps suitable for inclusion into documents or collating into movies. The command line arguments control lename and format selection, while plain-text conguration les, modeled after the mmDisp (Sec. 13) conguration dialog box, specify conversion parameters. Launching The avf2ppm launch command is: tclsh oommf.tcl avf2ppm [standard options] [-config file] [-f] \ [-filter program] [-format <P3|P6|B24>] [-ipat pattern] \ [-opatexp regexp] [-opatsub sub] [-v level] [infile ...] where -cong le User conguration le that species the image conversion parameters. This le is discussed in detail below. -f Force overwriting of existing (output) les. By default, if avf2ppm tries to create a le, say foo.ppm, that already exists, it generates instead a new name of the form foo.ppm-000, or foo.ppm-001, . . . , or foo.ppm-999, that doesnt exist and writes to that instead. The -f ag disallows alternate lename generation, and overwrites foo.ppm instead. 115

-lter program Post-processing application to run on each app2ppm output le. May be a pipeline of many programs. -format <P3|P6|B24> Specify the output image le format. Currently supported formats are the true color Portable Pixmap (PPM) formats P3 (ASCII text) and P6 (binary), and the uncompressed Windows BMP 24 bits-per-pixel format. The default is P6. -ipat pattern Specify input les using a pattern including glob-style wildcards. Mostly useful in DOS. -opatexp regexp Specify the regular expression applied to input lenames to determine portion to be replaced in generation of output lenames. Default: (\.[^.]?[^.]?[^.]?$|$) -opatsub sub The string with which to replace the portion of input lenames matched by the -opatexp regexp during output lename generation. The default is .ppm for type P3 and P6 le output, .bmp for B24 le output. -v level Verbosity (informational message) level, with 0 generating only error messages, and larger numbers generating additional information. The level value is an integer, defaulting to 1. inle . . . List of input les to process. The le specication options require some explanation. Input les may be specied either by an explicit list (infile ...), or by giving a wildcard pattern, e.g., -ipat *.omf, which is expanded in the usual way by avf2ppm (using the Tcl command glob). Unix shells (sh, csh, etc.) automatically expand wildcards before handing control over to the invoked application, so the -ipat option is not needed (although it is useful in case of a command-line too long error). DOS does not do this expansion, so you must use -ipat to get wildcard expansion in Windows. As each input le is processed, a name for the output le is produced from the input lename by rules determined by handing the -opatexp and -opatsub expressions to the Tcl regsub command. Refer to the Tcl regsub documentation for details, but essentially whatever portion of the input lename is matched by the -opatexp expression is removed and replaced by the -opatsub string. The default -opatexp expression matches against any lename extension of up to 3 characters, and the default -opatsub string replaces this with the extension .ppm or .bmp. If you have command line image processing lter programs, e.g., ppmtogif (part of the NetPBM package), then you can use the -filter option to pipe the output of avf2ppm through that lter before it is written to the output le specied by the -opat* expressions. If the processing changes the format of the le, (e.g., ppmtogif converts from PPM to GIF), then you will likely want to specify a -opatsub dierent from the default. 116

Here is an example that processes all les with the .omf extension, sending the output through ppmtogif before saving the results in a les with the extension .gif: tclsh oommf.tcl avf2ppm -ipat *.omf -opatsub .gif -filter ppmtogif (On Unix, either drop the -ipat ag, or use quotes to protect the input le specication string from expansion by the shell, as in -ipat *.omf.) You may also pipe together multiple lters, e.g., -filter "ppmquant 256 | ppmtogif". Conguration les The details of the conversion process are specied by plain-text conguration les, with elds analogous to the entries in the mmDisp (Sec. 13) conguration dialog box. Each of the parameters is an element in an array named plot config. The default values for this array are taken from the default conguration le oommf/app/mmdisp/scripts/avf2ppm.def, which is a Tcl script read during avf2ppm initialization. There are several places in the conguration le where colors are specied. Colors may be represented using the symbolic names in oommf/config/colors.def, in any of the Tk hexadecimal formats, e.g., #RRGGBB, or as a shade of gray using the format grayD (or greyD), where D is a decimal integer from 0-100, inclusive. Examples in the latter two formats are #FFFF00 for yellow, gray0 for black and gray100 or #FFFFFF for white. The sample default conguration script shown in Fig. 4 (page 121) can be used as a starting point for user (per-run) conguration les. Refer to this sample le and the mmDisp documentation (Sec. 13) as we discuss each element of the array plot config. (See the Tcl documentation for details of the array set command.) colormaps A list of valid colormaps known to the program. This entry is not usercongurable, and should not appear in user conguration les. arrow,status Set to 1 to display arrows, 0 to not draw arrows. arrow,colormap Select the colormap to use when drawing arrows. Should be one of the strings specied in the colormaps array element. arrow,colorcount Number of discretization levels to use from the colormap. A value of zero will color all arrows with the rst color in the colormap. arrow,quantity Scalar quantity the arrow color is to represent. Supported values include x, y, z, xy-angle, xz-angle, yz-angle, and slice. The mmDisp conguration dialog box will present the complete list of allowed quantities (which may be image dependent). arrow,colorphase The phase is a real number between -1 and 1 that provides a translation in the selected colormap. For the xy-angle, xz-angle and yz-angle color quantities, this displays as a rotation of the colormap, for example, setting colorphase to 0.333 117

would eectively change the Red-Green-Blue-Red colormap into Green-Blue-Red-Green. For the other color quantities, it simply shifts the display band, saturating at one end. For example, setting colorphase to 0.5 changes the Blue-White-Red colormap into White-Red-Red. arrow,colorinvert The colorinvert value should be 1 or 0, signifying to invert or not invert, respectively. If invert is selected, the the colormap ordering is reversed, changing for example Blue-White-Red into Red-White-Blue. If both inversion and phase adjustment are requested, then inversion is applied rst. arrow,autosample If 1, then ignore the value of arrow,subsample and automatically determine a reasonable subsampling rate for the arrows. Set to 0 to turn o this feature. arrow,subsample If arrow,autosample is 0, then subsample the input vectors at this rate when drawing arrows. A value of 0 for arrow,subsample is interpreted specially to display all data. arrow,size Size of the arrows relative to the default size (represented as 1.0). arrow,antialias If 1, then each pixel along the edge of an arrow is drawn not with the color of the arrow, but with a mixture of the arrow color and the background color. This makes arrow boundaries appear less jagged, but increases computation time. Also, the colors used in the anti-aliased pixels are not drawn from the arrow or pixel colormap discretizations, so color allocation in the output bitmap may increase dramatically. pixel,. . . Most of the pixel conguration elements have analogous arrow conguration elements, and are interpreted in the same manner. The exceptions are the pixel,opaque element which is discussed next, the arrow,antialias element which has no corresponding pixel element, and the qualitative dierence in that the auto subsampling rate for pixels is considerably denser than for arrows. pixel,opaque If the opaque value is 1, then the pixel is drawn in a solid manner, concealing any arrows which are drawn under it. If opaque is 0, then the pixel is drawn only partially lled-in, so objects beneath it can still be discerned. misc,background Specify the background color. misc,drawboundary If 1, then draw the bounding polygon, if any, as specied in the input vector eld le. misc,boundarywidth Width of the bounding polygon, in pixels. A value of 0 is treated the same as 1. To disable drawing of the boundary, use the misc,drawboundary option. misc,boundarycolor Color of the bounding polygon.

118

misc,boundarypos Placement of the bounding polygon, either back or front, i.e., either behind or in front of the rendered arrows and pixel elements. misc,matwidth Species the width, in pixels, of a mat (frame) around the outer edge of the image. The mat is drawn in front of all other objects. To disable, set matwidth to 0. misc,matcolor Color of the mat. misc,margin The size of the border margin, in pixels. misc,width, misc,height Maximum width and height of the output bitmap, in pixels. If misc,crop is enabled, then one or both of these dimensions may be shortened. misc,crop If disabled (0), then any leftover space in the bitmap (of dimensions misc,width by misc,height) after packing the image are lled with the background color. If enabled (1), then the bitmap is cropped to just include the image (with the margin specied by misc,margin). NOTE: Some movie formats require that bitmap dimensions be multiples of 8 or 16. For such purposes, you should disable misc,crop and specify appropriate dimensions directly with misc,width and misc,height. misc,zoom Scaling factor for the display. This is the same value as shown in the zoom box in the mmDisp control bar, and corresponds roughly to the number of pixels per vector in the (original, fully-sampled) vector eld. If set to zero, then avf2ppm will automatically set the scaling so the image (with margins) just ts inside the area specied by misc,width and misc,height. misc,rotation Counterclockwise rotation in degrees; either 0, 90, 180 or 270. misc,datascale Scale for arrow size and colormap range; this element is exactly equivalent to the mmDisp Data Scale control, Sec. 13. In general, this should be a positive real value, but a zero or empty value will set the scaling to its default value. misc,centerpt This element should either be empty, or else be a three item list of real numbers specifying the center of the display, in input le mesh units. The OOMMF command line program avf2ovf (Sec. 16.3) may be invoked with the -info option to determine the range of the le mesh. This information is also contained in the Bounding box message returned when avf2ppm is run, which should in any event be consulted since any portion of the mesh that is shifted outside the bounding box will not be rendered. This element provides the functionality of the scroll bars on the mmDisp main display window. If an empty value is given, then by default the center of the mesh is used. viewaxis Select the view axis, which should be one of +z, -z, +y, -y, +x, or -x. This option is equivalent to the mmDisp View|Viewpoint menu control. 119

viewaxis,center The viewaxis,center element corresponds to the mmDisp slice selection control. It should be a single real number in the range of that portion of the input le mesh bounding box corresponding to the selected view axis. For example, if the view axis is +z or -z, then the view axis center value should lie between the minimum and maximum z-values of the le mesh. If an empty value is given, then the view axis center is set from the corresponding coordinate of the misc,centerpt value. The portion of the mesh that is rendered depends upon the interaction between the bounding box, the center point, the view axis center, and the axis-selected arrow and pixel spans. viewaxis,xarrowspan, viewaxis,yarrowspan, viewaxis,zarrowspan Species the thickness of the arrow display slice, for the corresponding view, e.g., if the view axis is +z or -z, then only viewaxis,zarrowspan is active. These values for each of these elements should be either a single real value in units relating to the corresponding coordinate range of the input le mesh, or else an empty string, which is interpreted to be the entire thickness of the mesh in the selected view direction. viewaxis,xpixelspan, viewaxis,ypixelspan, viewaxis,zpixelspan Identical interpretation and behavior as the corresponding arrow span elements, but with regards to pixel display. User (per-run) conguration les are specied on the command line with the -config option. To create a user conguration le, make a copy of the default avf2ppm.def conguration le, and edit it as desired in a plain text editor. You may omit any entries that you do not want to change from the default. (Each entry consists of a name + value pair, e.g., misc,width 640.) You may layer conguration les by specifying multiple user conguration les on the command line. These are processed from left to right, with the last value set for each entry taking precedence.

16.5

Vector Field File Dierence: avfdi

The avfdi program computes dierences between vector eld les in any of the recognized formats (OVF, VIO; see Sec. 19). The input data must lie on rectangular meshes with identical dimensions. Launching The avfdi launch command is: tclsh oommf.tcl avfdiff [standard options] file-0 file-1 [... file-n] where le-0 Name of input le to subtract from other les. Must be either an OVF 1.0 le in the rectangular mesh subformat, or an VIO le. Required. 120

array set plot_config { colormaps { Red-Black-Blue Blue-White-Red Teal-White-Red Black-Gray-White Black-White-Black White-Black-White White-Green-Black Red-Green-Blue-Red } arrow,status 1 misc,background #FFFFFF arrow,colormap Black-Gray-White misc,drawboundary 1 arrow,colorcount 0 misc,boundarywidth 1 arrow,quantity z misc,boundarycolor #000000 arrow,colorphase 0. misc,boundarypos front arrow,colorinvert 0 misc,matwidth 0 arrow,autosample 1 misc,matcolor #FFFFFF arrow,subsample 10 misc,margin 10 arrow,size 1 misc,width 640 arrow,antialias 1 misc,height 480 misc,crop 1 pixel,status 1 misc,zoom 0 pixel,colormap Teal-White-Red misc,rotation 0 pixel,colorcount 225 misc,datascale 0 pixel,opaque 1 misc,centerpt {} pixel,quantity x pixel,colorphase 0. viewaxis {+z} pixel,colorinvert 0 viewaxis,center {} pixel,autosample 1 viewaxis,xarrowspan {} pixel,subsample 0 viewaxis,xpixelspan {} pixel,size 1 viewaxis,yarrowspan {} viewaxis,ypixelspan {} viewaxis,zarrowspan {} viewaxis,zpixelspan {} } Figure 4: Sample default conguration script avf2ppm.def.

121

le-1 Name of rst input le from which file-0 is to be subtracted. Must also be either an OVF 1.0 le in the rectangular mesh subformat, or an VIO le, and must have the same dimensions as file-0. Required. . . . le-n Optional additional les from which file-0 is to be subtracted, with the same requirements as file-1. For each input le file-1 through file-n, a separate output le is generated, in the OVF 1.0 format. Each output le has a name based on the name of corresponding input le, with a -diff sux. If a le with the same name already exists, it will be overwritten. For output le format details, see the OVF le description (Sec. 19.1).

16.6

Calculating H Fields from Magnetization: mag2held

The mag2held utility takes a MIF 1.1 micromagnetic problem specication le (.mif, see Sec. 17.2) and a magnetization le (.omf, see Sec. 19) and uses the mmSolve2D (Sec. 10.1) computation engine to calculate the resulting component (magnetostatic, exchange, crystalline anisotropy, Zeeman) and total energy and/or H elds. The main use of this utility to study the elds in a simulation using magnetization les generated by an earlier mmSolve2D run. Launching The mag2held launch command is: tclsh oommf.tcl mag2hfield [standard options] [-component [all,][anisotropy,][demag,][exchange,][total,][zeeman] \ [-data [energy,][field]] [-energyfmt fmt] [-fieldstep #] \ mif_file omf_file where -component [all,][anisotropy,][demag,][exchange,][total,][zeeman] Specify all energy/eld components that are desired. Optional; default is total, which is the sum of the crystalline anisotropy, demagnetization (self-magnetostatic), exchange, and Zeeman (applied eld) terms. -data [energy,][eld] Calculate energies, H elds, or both. Energy values are printed to stdout, H elds are written to les as described below. Optional; the default is energy,field. -energyfmt fmt Output C printf-style format string for energy data. Optional. The default format string is "%s". -eldstep # Applied eld step index, following the schedule specied in the input MIF le (0 denotes the initial eld). Optional; default is 0. 122

mif le MIF micromagnetic problem specication le (.mif). Required. omf le Magnetization state le. This can be in any of the formats accepted by the avfFile record of the input MIF le. Required. The H eld output le format is determined by the Total Field Output Format record of the input MIF 1.1 le (Sec. 17.2). The output le names are constructed using the form basename-hanisotropy.ohf, basename-hzeeman.ohf, etc., where basename is the input .omf magnetization le name, stripped of any trailing .omf or .ovf extension.

16.7

MIF Format Conversion: mifconvert

The mifconvert utility converts a MIF 1.1 (Sec. 17.2) micromagnetic problem specication le into the MIF 2.1 (Sec. 17.1) format. Eventually, it should be possible to express any problem in the MIF 1.1 format using the MIF 2.1 format, but currently that is not the case. It is recommended that the user carefully inspect the MIF 2.1 les generated by this application for correctness. As a migration aid, mifconvert will also convert most les from the obsolete MIF 2.0 format used with OOMMF 1.2a2 into the newer MIF 2.1 format. Launching The mifconvert launch command is: tclsh oommf.tcl mifconvert [-f|--force] [-h|--help] [-q|--quiet] \ [--unsafe] [-v|--version] input_file output_file where -f or force Force overwrite of output le. Optional. -h or help Print help information and stop. Optional. -q or quiet Suppress normal informational output messages. Optional. unsafe Runs embedded Tcl scripts, if any, in unsafe interpreter. Optional. -v or version Print version string and stop. Optional. input le Import MIF 1.1 (or MIF 2.0) micromagnetic problem specication le. Required. output le Export MIF 2.1 micromagnetic problem specication le. Required.

16.8

ODT Column Extraction: odtcols

The odtcols utility extracts column subsets from ODT (Sec. 18) data table les. 123

Launching The odtcols launch command is: tclsh oommf.tcl odtcols [standard options] [-s] [-w colwidth] \ [-f format] [col ...] <infile >outfile where -s Produces a le summary instead of column extraction. Output includes table titles, column and row counts, and the header for each specied column. If no columns are specied, then the headers for all the columns are listed. -w colwidth Minimum horizontal spacing to provide for each column on output. Optional. Default value is 15. -f format C printf-style format string for each output item. Optional. The default format string is "%-${colwidth}s". col . . . Output column selections. These may either be integers representing the position of the column in the input data (with the rst column numbered as 0), or else arbitrary strings used for case-insensitive glob-style matching against the column headers. The columns are output in match order, obtained by processing the column selections from left to right. If no columns are specied then by default all columns are selected. <inle Odtcols reads its input from stdin. Use the redirection operator < to read input from a le. >outle Odtcols writes its output to stdout. Use the redirection operator > to send the output to a le. Commonly the -s switch is used in a rst pass, to reveal the column headers; specic column selections may then be made in a second, separate invocation.

16.9

Platform-Independent Make: pimake

The application pimake is similar in operation to the Unix utility program make, but it is written entirely in Tcl so that it will run anywhere Tcl is installed. Like make, pimake controls the building of one le, the target, from other les. Just as make is controlled by rules in les named Makefile or makefile, pimake is controlled by rules in les named makerules.tcl.

124

Launching The pimake launch command is: tclsh oommf.tcl pimake [standard options] \ [-d] [-i] [-k] [-out file] [target] where -d Print verbose information about dependencies. -i Normally an error halts operation. When -i is specied, ignore errors and try to continue updating all dependencies of target. -k Normally an error halts operation. When -k is specied, and an error is encountered, stop processing dependencies which depend on the error, but continue updating other dependencies of target. -out le Write output to named le instead of to the standard output. target The le to build. May also be (and usually is) a symbolic target name. See below for standard symbolic targets. By default, the rst target in makerules.tcl is built. There are several targets which may be used as arguments to pimake to achieve dierent tasks. Each target builds in the current directory and all subdirectories. The standard targets are: upgrade Used immediately after unpacking a distribution, it removes any les which were part of a previous release, but are not part of the unpacked distribution. all Creates all les created by the configure target (see below). Compiles and links all the executables and libraries. Constructs all index les. congure Creates subdirectories with the same name as the platform type. Constructs a ocport.h le which includes C++ header information specic to the platform. objclean Removes the intermediate object les created by the compile and link steps. Leaves working executables in place. Leaves OOMMF in the state of its distribution with pre-compiled executables. clean Removes the les removed by the objclean target. Also removes the executables and libraries created by the all target. Leaves the les generated by the configure target. distclean Removes the les removed by the clean target. Also removes all les and directories generated by configure target. Leaves only the les which are part of the source code distribution.

125

maintainer-clean Remove all les which can possibly be generated from other les. The generation might require specialized developer tools. This target is not recommended for end-users, but may be helpful for developers. help Print a summary of the standard targets.

126

17

Problem Specication File Formats (MIF)

Micromagnetic simulations are specied to the OOMMF solvers using the OOMMF Micromagnetic Input Format (MIF). There are two distinct, incompatible versions of this format. The older, version 1.1, is the format used by the 2D solver (mmSolve2D, Sec. 10.1 and batchsolve, Sec. 10.2.1) and the mmProbEd (Sec. 8) problem editor. The new MIF format, version 2.1, is used by the Oxs 3D solver (Sec. 7). In both cases all values are in SI units. A command line utility mifconvert (Sec. 16.7) is provided to aid in converting MIF 1.1 les to the MIF 2.1 format. For both versions it is recommended that MIF les be given names ending with the .mif le extension.

17.1

MIF 2.1

The MIF 2.x format was introduced with the Oxs 3D solver (Sec. 7). It is not backwards compatible with the MIF 1.1 format, however a conversion utility, mifconvert (Sec. 16.7), is available to aid in converting MIF 1.1 les to the MIF 2.1 format. A sample MIF 2.1 le is presented in Fig. 5 (Sec. 17.1.4, pages 141144). The rst line of a MIF le must be of the form # MIF x.y, where x.y represents the format revision number, here 2.1. Unlike MIF 1.1 les, the structure of MIF 2.1 les are governed by the requirement that they be valid Tcl scripts. During processing MIF 2.1 les are evaluated inside a Tcl interpreter. That interpreter may be a safe interpreter, i.e., disk and other system access is disabled. Refer to documentation of the Tcl interp command for details. The security level is controlled by the MIFinterp option in the options.tcl customization le (Sec. 2.3.2). The default setting is Oc_Option Add Oxs* MIFinterp safety custom which enables all the Tcl interpreter extensions described below, but is otherwise a standard Tcl safe interpreter. The keyword custom above may be replaced with either safe or unsafe. The safe selection is similar to custom, except that the ReadFile extension is not provided, thereby eliminating all disk access. At the other extreme, choosing unsafe provides an unrestricted Tcl interpreter. This option should be used with caution, especially if you are reading MIF les from an unknown or untrusted source. 17.1.1 MIF 2.1 Extension Commands

In addition to the standard Tcl commands (modulo the safe Tcl restrictions outlined above), several additional commands are available in MIF 2.1 les: Specify, ClearSpec, Destination, Ignore, OOMMFRootDir, Parameter, Random, RandomSeed, Report, ReadFile, and Schedule. Specify An Oxs simulation is built as a collection of Oxs Ext (Oxs Extension) objects. In general, Oxs Ext objects are specied and initialized in the input MIF 2.1 le using the Specify command, making Specify blocks the primary component of the problem denition. The Specify command takes two arguments: the name of the Oxs Ext 127

object to create, and an initialization string that is passed to the Oxs Ext object during its construction. The objects are created in the order in which they appear in the MIF le. Order is important in some cases, for example, if one Oxs Ext object refers to another in its initialization string, then the referred to object must precede the referrer in the MIF le. Here is a simple Specify block: Specify Oxs_EulerEvolve:foo { alpha 0.5 start_dm 0.01 } The name of the new Oxs Ext object is Oxs EulerEvolve:foo. The rst part of this name, up to the colon, is the the C++ class name of the object. This must be a child of the Oxs Ext class. Here, Oxs EulerEvolve is a class that integrates the LandauLifshitz ODE using a simple forward Euler method. The second part of the name, i.e., the part following the colon, is the name for this particular instance of the object. In general, it is possible to have multiple instances of an Oxs Ext child class in a simulation, but each instance must have a unique name. These names are used for identication by output routines, and to allow one Specify block to refer to another Specify block appearing earlier in the MIF le. If the second part of the name is not given, then as a default the empty string is appended. For example, if instead of Oxs EulerEvolve:foo above the name was specied as just Oxs EulerEvolve, then the eective full name of the created object would be Oxs EulerEvolve:. The second argument to the Specify command, here everything between the curly braces, is a string that is interpreted by the new Oxs Ext (child) object in its constructor. The format of this string is up to the designer of the child class, but there are a number of conventions that designers are encouraged to follow. These conventions are described in Specify Conventions, Sec. 17.1.2, below. ClearSpec This command is used to disable one or all preceding Specify commands. In particular, one could use ClearSpec to nullify a Specify block from a base MIF le that was imported using the ReadFile command. Sample usage is ClearSpec Oxs_EulerEvolve:foo where the parameter is the full name (here Oxs EulerEvolve:foo) of the Specify block to remove. If no parameter is given, then all preceding Specify blocks are removed. Destination The format for the Destination command is Destination <desttag> <appname> [new]

128

This command associates a symbolic desttag with an application. The tags are used by the Schedule command (see below) to refer to specic application instances. The appname may either be an OOMMF application name, e.g., mmDisp, or else a specic application instance in the form application:nickname, such as mmDisp:Spock. In the rst case, the tag is associated with the running instance of the requested application (here mmDisp) with the lowest OOMMF ID (OID) that has not yet been associated with another tag. If no running application can be found that meets these criteria, then a new instance of the application is launched. If the appname refers to a specic application instance, then the tag is associated with the running instance of the application (say mmDisp) that has been assigned the specied nickname. Name matching is case insensitive. If there is no running copy of the application meeting this condition, then a new instance of the application is launched and it is assigned the specied nickname. The OOMMF account service directory guarantees that there is never more than one instance of an application with a given nickname. However, as with the object name in the Specify command, instances of two dierent applications, e.g., mmDisp and mmGraph, are allowed to share nicknames, because their full instance names, say mmDisp:Spock and mmGraph:Spock, are unique. The Destination commands are processed in the order in which they appear in the the MIF le. No desttag may appear in more than one Destination command, and no two destination tags may refer to the same application instance. To insure the latter, the user is advised to place all Destination commands referring to specic instances (e.g., mmDisp:Spock) before any Destination commands using generic application references (e.g., mmDisp). Otherwise a generic reference might be associated to a running application holding a nickname that is referenced by a later Destination command. The tag association by the Destination command is only known to the solver reading the MIF le. In contrast, assigned instance nicknames are recognized across applications. In particular, multiple solvers may reference the same running application by nickname. For example, several sequential solver runs could send stage output to the same mmGraph widget, to build up overlapping hysteresis loops. The last parameter to the Destination command is the optional new keyword. If present, then a fresh copy of the requested application is always launched for association with the given tag. The new option can be safely used with any generic application reference, but caution must be taken when using this option with specic instance references, because an error is raised if the requested nickname is already in use. Ignore The Ignore command takes an arbitrary number of arguments, which are thrown away without being interpreted. The primary use of Ignore is to temporarily comment out (i.e., disable) Specify blocks. 129

OOMMFRootDir This command takes no arguments, and returns the full directory path of the OOMMF root directory. This is useful in conjunction with the ReadFile command for locating les within the OOMMF hierarchy, and can also be used to place output les. File paths must be created directly since the Tcl file command is not accessible inside safe interpreters. For example set outfile [OOMMFRootDir]/data/myoutput In this context one should always use Tcl path conventions. In particular, use forward slashes, /, to separate directories. Parameter The Oxs batch mode interface (Sec. 7.2) allows specied variables in the MIF le to be set from the command line. This behavior is enabled inside the MIF le via the Parameter command: Parameter varname optional default value Here varname is the name of a variable that may be set from the command line. If it is not set on the command line then the variable is set to the optional default value, if any, or otherwise an error is raised. An error is also raised if a variable set on the command line does not have a corresponding Parameter command in the MIF le. See also the notes on variable substitution (Sec. 17.1.3) below. Random Returns a pseudo-random number in the interval [0, 1], using a C-library random number generator. This random number generator is specied by the OMF RANDOM macro in the ocport.h le found in the system-specic subdirectory of oommf/pkg/oc/. The standard Tcl expr rand() command is also available. RandomSeed Initializes both the Tcl and the C-library random number generators. If no parameter is given, then a seed is drawn from the system clock. Otherwise, one integer parameter may be specied to be used as the seed. Report Intended primarily as a MIF debugging aid, Report takes one string argument that is printed to the solver interface console and the Oxs log le. It is essentially a replacement for the standard Tcl puts command, which is not available in safe interpreters. ReadFile The Tcl read command is absent from safe interpreters. The ReadFile command is introduced as a replacement available in custom and unsafe interpreters. ReadFile takes two arguments, the le to be read and an optional translation specication. The le may either be specied with an absolute path, i.e., one including all its directory components, or with a relative path interpreted with respect to the directory containing the MIF le. The OOMMFRootDir command can be used to advantage to locate les in other parts of the OOMMF directory tree.

130

The translation specication should be one of binary, auto (the default), or image. The rst two translation modes provide the functionality of the -translation option of the Tcl fconfigure command. Refer to the Tcl documentation for details. Specifying image causes the input le to be ltered through the any2ppm program and converted into a PPM P3 text le, minus the leading P3. In particular, after conversion the rst 3 whitespace separated values are image width, height and maxvalue, followed by an array of 3 width height values, where each triplet corresponds to the red, green and blue components of an image pixel, sequenced in normal English reading order. This output contains no comments, and may be treated directly as a Tcl list. The return value from the ReadFile command is a string corresponding to the contents of the (possibly translated) le. For example, eval [ReadFile extra_mif_commands.tcl] can be used to embed a separate Tcl le into a MIF 2.1 le. Heres a more complicated example that uses a color image le to create a vector eld: set set set set image [ReadFile sample.gif image] imagewidth [lindex $image 0] imageheight [lindex $image 1] maxval [expr {double([lindex $image 2])}]

set colorimage {} foreach {r g b} [lrange $image 3 end] { set r [expr {$r/$maxval}] set g [expr {$g/$maxval}] set b [expr {$b/$maxval}] lappend colorimage $r $g $b # colorimage is a list of normalized red, green, # and blue values. } unset image proc ColorField { rel_x rel_y rel_z } { # Returns the normalized (r,g,b) triple corresponding # to position (rel_x,rel_y) in the image; Import rel_z # is not used. global colorimage imagewidth imageheight set i [expr {int(floor(double($rel_x)*$imagewidth))}] if {$i>=$imagewidth} {set i [expr {$imagewidth-1}]} set j [expr {int(floor(double(1-$rel_y)*$imageheight))}] if {$j>=$imageheight} {set j [expr {$imageheight-1}]} set red_index [expr {3*($j*$imagewidth+$i)}] 131

set blue_index [expr {$red_index+2}] return [lrange $colorimage $red_index $blue_index] } Specify Oxs_ScriptVectorField:sample { atlas :atlas norm 1.0 script ColorField } The ReadFile command is not available if the MIFinterp safety option is set to safe in the options.tcl customization le (Sec. 2.3.2). Schedule The Schedule command is used to setup outputs from the MIF le. This functionality is critical for solvers running in batch mode, but is also useful for setting up default connections in interactive mode. The syntax for the Schedule command is Schedule <outname> <desttag> <event> <frequency> The Schedule command mirrors the interactive output scheduling provided by the Oxsii and Boxsi graphical interfaces (Sec. 7). The rst parameter to the Schedule command is the name of the output being scheduled. These names are the same as those appearing in the Outputs list in the Oxs graphical interfaces, for example DataTable or Oxs CubicAnisotropy:Nickel:Field. Aside from the DataTable output which is always present, the outnames are MIF le dependent. The second parameter to the Schedule command is a destination tag. This is a tag associated to a running application by a previous Destination command (see above). The symbolic destination tag replaces the application:OID nomenclature used in the graphical interface, because in general it is not possible to know the OOMMF ID for application instances at the time the MIF le is composed. In fact, some of the applications may be launched by Destination commands, and so dont even have OIDs at the time the Destination command is processed. The event parameter should be one of the keywords Step or Stage, and the frequency parameter should be a positive integer, representing with what frequency of the specied event should output be dispatched. For example, if Step 5 is given, then on every fth step of the solver output of the indicated type will be sent to the selected destination. Set frequency to 1 to send output each time the event occurs. All of the parameters to the Schedule command are required. There are examples of scheduling with the Destination and Schedule commands in the sample MIF 2.1 le presented in Fig. 5 (Sec. 17.1.4, pages 141144). There, three destinations are tagged. The rst refers to a possibly already running instance of 132

mmGraph, having nickname Hysteresis. The associated Schedule command sends DataTable output to this application at the end of each Stage, so hysteresis graphs can be produced. The second destination tag references a dierent copy of mmGraph that will be used for monitoring the run. To make sure that this output is rendered onto a blank slate, the new keyword is used to launch a fresh copy of mmGraph. The Schedule command for the monitor destination delivers output to the monitoring mmGraph every 5 iterations of the solver. The last Destination command tags an arbitrary mmArchive application, which is used for le storage of both DataTable results at the end of each stage, and snapshots of the magnetization at the end of every third stage. 17.1.2 Specify Conventions

The Specify blocks in the input MIF le determine the collection of Oxs Ext objects dening the Oxs simulation. As explained above, the Specify command takes two arguments, the name of the Oxs Ext object to create, and an initialization string. The format of the initialization string can be arbitrary, as determined by the author of the Oxs Ext class. This section presents a number of recommended conventions which Oxs Ext class authors are encouraged to follow. Any Oxs Ext classes that dont follow these conventions should make that fact explicitly clear in their documentation. Details on the standard Oxs Ext classes included with OOMMF can be found in the Oxs documentation (Sec. 7). 17.1.2.1 Initialization string format Consider again the simple Specify block presented above: Specify Oxs_EulerEvolve:foo { alpha 0.5 start_dm 0.01 } The rst convention is that the initialization string be structured as a Tcl list with an even number of elements, with consecutive elements consisting of a label + value pairs. In the above example, the initialization string consists of two label + value pairs, alpha 0.5 and start dm 0.01. The rst species that the damping parameter in the Landau-Lifshitz ODE is 0.5. The second species the initial step size for the integration routine. Interested parties should refer to a Tcl programming reference (e.g., [16]) for details on forming a proper Tcl list, but in this example the list as a whole is set o with curly braces ({ and }), and individual elements are white space delimited. Generally, the ordering of the label + value pairs in the initialization string is irrelevant, i.e., start dm 0.01 could equivalently precede alpha 0.5. Sometimes the value portion of a label + value pair will itself be a list, as in this next example:

133

Specify Oxs BoxAtlas:myatlas { ... } Specify Oxs RectangularMesh:mymesh { cellsize { 5e-9 5e-9 5e-9 } atlas Oxs BoxAtlas:myatlas } Here the value associated with cellsize is a list of 3 elements, which declare the sampling rate along each of the coordinate axes, in meters. (Oxs BoxAtlas is a particular type of Oxs Atlas, and . . . mark the location of the Oxs BoxAtlas initialization string, which is omitted because it is not pertinent to the present discussion.) 17.1.2.2 Oxs Ext referencing The atlas value in the mesh Specify block of the preceding example refers to an earlier Oxs Ext object, Oxs BoxAtlas:myatlas. It frequently occurs that one Oxs Ext object needs access to another Oxs Ext object. In this example the mesh object :mymesh needs to query the atlas object :myatlas in order to know the extent of the space that is to be gridded. The atlas object is dened earlier in the MIF input le by its own, separate, top-level Specify block, and the mesh object refers to it by simply specifying its name. Here the full name is used, but the short form :myatlas would suce, provided no other Oxs Ext object has the same short name. Alternatively, the Oxs RectangularMesh object could dene an Oxs BoxAtlas object inline: Specify Oxs RectangularMesh:mymesh { atlas { Oxs BoxAtlas { ... } } cellsize { 5e-9 5e-9 5e-9 } } In place of the name of an external atlas object, a two item list is provided consisting of the type of object (here Oxs BoxAtlas) and the corresponding initialization string. The initialization string is provided as a sublist, with the same format that would be used if that object were initialized via a separate Specify block. More commonly, embedded Oxs Ext objects are used to initialize spatially varying quantities. For example, Specify Oxs_UniaxialAnisotropy { axis { Oxs_RandomVectorField { min_norm 1 134

max_norm 1 } } K1 } The magneto-crystalline anisotropy class Oxs UniaxialAnisotropy supports cellwise varying K1 and anisotropy axis directions. In this example, the anisotropy axis directions are randomly distributed. To initialize its internal data structure, Oxs UniaxialAnisotropy creates a local Oxs RandomVectorField object. This object is also a child of the Oxs Ext hierarchy, which allows it to be constructed using the same machinery invoked by the Specify command. However, it is known only to the enclosing Oxs UniaxialAnisotropy object, and no references to it are possible, either from other Specify blocks or even elsewhere inside the same initialization string. Because it cannot be referenced, the object does not need an instance name. It does need an initialization string, however, which is given here as the 4-tuple min norm 1 max norm 1. Notice how the curly braces are nested so that this 4-tuple is presented to the Oxs RandomVectorField initializer as a single item, while Oxs RandomVectorField and the associated initialization string are wrapped up in another Tcl list, so that the value associated with axis is parsed at that level as a single item. The value associated with K1 is another embedded Oxs Ext object. In this particular example, K1 is desired uniform (homogeneous) throughout the simulation region, so the trivial Oxs UniformScalarField class is used for initialization (to the value 530103 J/m3 ). In the case of uniform elds, scalar or vector, a shorthand notation is available that implicitly supplies a uniform Oxs Ext eld class: Specify Oxs_UniaxialAnisotropy { axis { 1 0 0 } K1 530e3 } which is equivalent to Specify Oxs_UniaxialAnisotropy { axis { Oxs_UniformVectorField { vector { 1 0 0 } } } K1 { Oxs_UniformScalarField { value 530e3 } } } While embedding Oxs Ext objects inside Specify blocks can be convenient, it is important to remember that such objects are not available to any other Oxs Ext objectonly objects declared via top-level Specify blocks may be referenced from inside other Specify blocks. 135 { Oxs_UniformScalarField { value 530e3 } }

Also, embedded Oxs Ext objects cannot directly provide user output. Furthermore, the only Oxs Energy energy objects included in energy and eld calculations are those declared via top-level Specify blocks. For this reason Oxs Energy terms are invariably created via top-level Specify blocks, and not as embedded objects. 17.1.2.3 Grouped lists As noted earlier, sometimes the value portion of a label + value pair will be a list. Some Oxs objects support grouped lists, which provide a type of run-length encoding for lists. Consider the sample list { 1.1 1.2 1.2 1.2 1.2 1.3 }

In a grouped list the middle run of 1.2s may be represented as a sublist with a repeat count of 4, like so { 1.1 { 1.2 4 } 1.3 :expand: }

Here the :expand: keyword, when appearing as the last element of the top level list, enables the group expansion mechanism. Any preceding element, such as { 1.2 4 }, that 1) is a proper sublist, and 2) has a positive integer as the last element, is treated as a grouped sublist with repeat count given by the last element. No element of the top-level list is ever interpreted as a repeat count. For example, the short form of the list { 1e-9 1e-9 1e-9 1e-9 1e-9 1e-9 } is { { 1e-9 6 } :expand: } Note the additional level of brace grouping. Grouped lists may also be nested, as in this example { 5.0 { 5.1 { 5.2 3 } 5.3 2 } :expand: } which is equivalent to { 5.0 5.1 5.2 5.2 5.2 5.3 5.1 5.2 5.2 5.2 5.3 }

There are some diculties with this mechanism when the list components are strings, such as lenames, that may contain embedded spaces. For example, consider the list { "file 3" "file 3" "5 file" } If we tried to write this as { { "file 3" 2 } "5 file" :expand: } we would nd that, because of the nested grouping rules, this grouped list gets expanded into 136

{ file file file file file file "5 file" } Here the trailing 3 in le 3 is interpreted as a repeat count. Following normal Tcl rules, the double quotes are treated as equivalents to braces for grouping purposes. However, the keyword :noexpand: may be used to disable further expansion, like so { { {"file 3" :noexpand:} 2 } "5 file" :expand: } The :noexpand: keyword placed at the end of a list disables all group expansion in that list. Although it is an unlikely example, if one had a at, i.e., non-grouped list with last element :expand:, then one would have to disable the grouping mechanism that would otherwise be invoked by appending :noexpand: to the list. In at lists generated by program code, it is recommended to append :noexpand: just to be certain that the list is not expanded. As a matter of nomenclature, standard (i.e., at) lists and single values are also considered grouped lists, albeit trivial ones. Any Oxs object that accepts grouped lists in its Specify block should explicitly state so in its documentation. 17.1.2.4 Comments The standard Tcl commenting mechanism treats all text running from an initial # symbol through to the end of a line as a comment. You may note in the above examples that newlines are treated the same as other whitespace inside the curly braces delimiting the Specify initialization string. Because of this and additional reasons, Tcl comments cannot be used inside Specify blocks. Instead, by convention any label + value pair where label is comment is treated as a comment and thrown away. For example: Specify Oxs_UniaxialAnisotropy { axis { 1 0 0 } comment {K1 4500e3} K1 530e3 comment { 530e3 J/m^3 is nominal for Co } } Pay attention to the dierence between comment used here as the label portion of a label + value pair, and the MIF extension command Ignore used outside Specify blocks. In particular, Ignore takes an arbitrary number of arguments, but the value element associated with a comment label must be grouped as a single element, just as any other value element. 17.1.2.5 Attributes Sometimes it is convenient to dene label + value pairs outside a particular Specify block, and then import them using the attributes label. For example: Specify Oxs_LabelValue:probdata { alpha 0.5 start_dm 0.01 } Specify Oxs_EulerEvolve { attributes :probdata } 137

The Oxs LabelValue object is an Oxs Ext class that does nothing except hold label + value pairs. The attributes label acts as an include statement, causing the label + value pairs contained in the specied Oxs LabelValue object to be embedded into the enclosing Specify initialization string. This technique is most useful if the label + value pairs in the Oxs LabelValue object are used in multiple Specify blocks, either inside the same MIF le, or across several MIF les into which the Oxs LabelValue block is imported using the ReadFile MIF extension command. 17.1.2.6 User dened support procedures A number of Oxs Ext classes utilize userdened Tcl procedures (procs) to provide extended runtime functionality. The most common examples are the various eld initialization script classes, which call a user specied Tcl proc for each point in the simulation discretization mesh. The proc returns a value, either scalar or vector, which is interpreted as some property of the simulation at that point in space, such as saturation magnetization, anisotropy properties, or an external applied eld. Here is an example proc that may be used to set the initial magnetization conguration into an approximate vortex state, with a central core in the positive z direction: proc Vortex { x_rel y_rel z_rel } { set xrad [expr {$x_rel-0.5}] set yrad [expr {$y_rel-0.5}] set normsq [expr {$xrad*$xrad+$yrad*$yrad}] if {$normsq <= 0.0125} {return "0 0 1"} return [list [expr {-1*$yrad}] $xrad 0] } The return value in this case is a 3D vector representing the spin direction at the point (x rel,y rel,z rel). Procs that are used to set scalar properties, such as saturation magnetization Ms , return a scalar value instead. But in both cases, the import argument list species a point in the simulation mesh. In the above example, the import point is specied relative to the extents of the simulation mesh. For example, if x rel were 0.1, then the x-coordinate of the point is one tenth of the way between the minimum x value in the simulation and the maximum x value. In all cases x rel will have a value between 0 and 1. In most support proc examples, relative coordinates are the most exible and easiest representation to work with. However, by convention, scripting Oxs Ext classes also support absolute coordinate representations. The representation used is selected in the Oxs Ext object Specify block by the optional script args entry. The Tcl proc itself is specied by the script entry, as seen in this example: Specify ScriptScalarField:Ms { atlas :atlas script_args { rawpt } script SatMag 138

} proc SatMag { x y z } { if {$z < 20e-9} {return 8e5} return 5e5 } The value associated with the label script args should in this case be a subset of {relpt rawpt minpt maxpt span}. Each selection represents a triple of values that are to be included in the proc argument list, in the order specied. The relpt selection provides x rel, y rel, z rel as discussed above. Conversely, rawpt provides the point representation in problem coordinates, i.e., in meters. The minpt and maxpt options list the minimum and maximum values in the simulation mesh in problem coordinates, i.e., minpt rawpt maxpt in each coordinate. The span option provides the 3-vector resulting from (maxpt minpt). All script args arguments except relpt are in meter units. If script args is not specied then the eective default is relpt. Some Oxs Ext objects may support a dierent list of allowed script args values. Check the documentation of the Oxs Ext object in question for details. Please note that the names used in the proc argument lists above are for exposition purposes only. You may use other names as you wish. It is the order of the arguments that is important, not their names. Also, because the MIF le is parsed rst in toto before the Specify blocks are evaluated, the support procs may be placed anywhere in the MIF le, regardless of the location of the referencing Specify blocks. The command call to the Tcl support proc is actually built up by appending to the script value the arguments as specied by the script args value. This allows additional arguments to the Tcl proc to be specied in the script value, in which case they will appear in the argument list in front of the script args values. The following is equivalent to the preceding example: Specify ScriptScalarField:Ms { atlas :atlas script_args { rawpt } script {SatMag 20e-9 8e5 5e5} } proc SatMag { zheight Ms1 Ms2 x y z } { if {$z < $zheight} {return $Ms1} return $Ms2 } Notice in this case that the script value is wrapped in curly braces so that the string SatMag 20e-9 8e5 5e5 will be treated as the single value associated with the label script. As seen in the earlier example using the Vortex Tcl proc, support procedures in MIF 2.1 les will frequently make use of the Tcl expr command. If you are using Tcl version 8.0 or later, then the cpu time required by the potentially large number of calls to such procedures can be greatly reduced by grouping the arguments to expr commands in curly braces, as 139

illustrated in the Vortex example. The braces aid the operation of the Tcl bytecode compiler, although there are a few rare situations involving multiple substitution where such bracing cannot be applied. See the Tcl documentation for the expr command for details. Sometimes externally dened data can be put to good use inside a Tcl support proc, as in this example: # Lay out a 6 x 16 mask, at global scope. set mask { 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 1 1 1 1 1 } proc MyShape { xrel yrel znotused } { global mask ;# Make mask accessible inside proc set Ms 8e5 ;# Saturation magnetization of element set xindex [expr {int(floor($xrel*16))}] set yindex [expr {5 - int(floor($yrel*6))}] set index [expr {$yindex*16+$xindex}] # index references point in mask corresponding # to (xrel,yrel) return [expr {[lindex $mask $index]*$Ms}] } The variable mask holds a Tcl list of 0s and 1s dening a part shape. The mask is brought into the scope of the MyShape proc via the Tcl global command. The relative x and y coordinates are converted into an index into the list, and the proc return value is either 0 or 8e5 depending on whether the corresponding point in the mask is 0 or 1. This is essentially the same technique used in the ColorField proc example presented in the ReadFile MIF extension command documented above (Sec. 17.1.1), except that there the data structure values are built from a separate image le rather than from data embedded inside the MIF le. 17.1.3 Variable Substitution

One powerful consequence of the evaluation of MIF 2.1 input les by Tcl is the ability to dene and use variables. For example, the batch mode interface to Oxs (Sec. 7.2) uses the Parameter command to set variables from the command line for use inside the MIF input le. Variables in Tcl are evaluated (i.e., value substituted) by prexing the variable name with the symbol $. For example, if cellsize is a variable holding the value 5e-9, then $cellsize evaluates to 5e-9. 140

Unfortunately, there are complications in using variables inside Specify blocks. Consider this simple example: Parameter cellsize 5e-9 Specify Oxs_RectangularMesh:BadExample { comment {NOTE: THIS DOESNT WORK!!!} cellsize {$cellsize $cellsize $cellsize} atlas :atlas } This doesnt work, because the curly braces used to set o the Specify initialization string also inhibit variable substitution. There are several ways to work around this, but the easiest is usually to embed the initialization string inside a subst (substitution) command: Parameter cellsize 5e-9 Specify Oxs_RectangularMesh:GoodExample [subst { comment {NOTE: This works.} cellsize {$cellsize $cellsize $cellsize} atlas :atlas }] Here the square brackets, [ and ], cause Tcl to perform command substitution, i.e., execute the string inside the square brackets as a Tcl command, in this case the subst command. See the Tcl documentation for subst for details, but the default usage illustrated above performs variable, command and backslash substitutions on the argument string. One more example, this time involving both variable and command substitution: set pi [expr {4*atan(1.0)}] set mu0 [expr {4*$pi*1e-7}] Specify Oxs_UZeeman [subst { comment {Set units to mT} Hscale [expr {0.001/$mu0}] Hrange { { 0 0 0 10 0 0 2 } { 10 0 0 -10 0 0 2 } } }] Note that the subst command is evaluated at global scope, so that the global variable mu0 is directly accessible. 17.1.4 Sample MIF 2.1 File

# MIF 2.1 # 141

# All units are SI. # # This file must be a valid Tcl script. # # Initialize random number generators with seed=1 RandomSeed 1 # Individual Oxs_Ext objects are loaded and initialized via # Specify command blocks. The following block defines the # extents (in meters) of the volume to be modeled. The # prefix "Oxs_BoxAtlas" specifies the type of Oxs_Ext object # to create, and the suffix ":WorldAtlas" is the name # assigned to this particular instance. Each object created # by a Specify command must have a unique full name (here # "Oxs_BoxAtlas:WorldAtlas"). If the suffix is not # explicitly given, then the default ":" is automatically # assigned. References may be made to either the full name, # or the shorter suffix instance name (here ":WorldAtlas") # if the latter is unique. See the Oxs_TimeDriver block for # some reference examples. Specify Oxs_BoxAtlas:WorldAtlas { xrange {0 500e-9} yrange {0 250e-9} zrange {0 10e-9} } # The Oxs_RectangularMesh object is initialized with the # discretization cell size (in meters). Specify Oxs_RectangularMesh:mesh { cellsize {5e-9 5e-9 5e-9} atlas :WorldAtlas } # Magnetocrystalline anisotropy block. The setting for # K1 (500e3 J/m^3) implicitly creates an embedded # Oxs_UniformScalarField object. Oxs_RandomVectorField # is an explicit embedded Oxs_Ext object. Specify Oxs_UniaxialAnisotropy { K1 530e3 axis { Oxs_RandomVectorField { min_norm 1 142

max_norm 1 } } } # Homogeneous exchange energy. A = 13e-12 J/m. Specify Oxs_UniformExchange:NiFe { A 13e-12 } # Define a couple of constants for later use. set PI [expr {4*atan(1.)}] set MU0 [expr {4*$PI*1e-7}] # The Oxs_UZeeman class is initialized with field ranges # in A/m. The following block uses the multiplier option to # allow ranges to be specified in mT. Use the "subst" # command to enable variable and command substitution. Specify Oxs_UZeeman:AppliedField [subst { multiplier [expr 0.001/$MU0] Hrange { { 0 0 0 10 0 0 2 } { 10 0 0 -10 0 0 2 } { 0 0 0 0 10 0 4 } { 1 1 1 5 5 5 0 } } }] # Enable demagnetization (self-magnetostatic) field # computation. This block takes no parameters. Specify Oxs_Demag {} # First order Euler ODE solver, using default # parameter values. Specify Oxs_EulerEvolve {} # The following procedure is used to set the initial spin # configuration in the Oxs_TimeDriver block. The arguments # x, y, and z are coordinates relative to the min and max # range of each dimension, e.g., 0<=x<=1, where x==0 # corresponds to xmin, x==1 corresponds to xmax. proc UpDownSpin { x y z } { if { $x < 0.45 } { 143

return } elseif return } else { return } }

"0 1 0" { $x > 0.55 } { "0 -1 0" "0 0 1"

Specify Oxs_TimeDriver { evolver Oxs_EulerEvolve stopping_dm_dt 0.01 mesh :mesh Ms 8e5 comment {implicit Oxs_UniformScalarField object} m0 { Oxs_ScriptVectorField { script {UpDownSpin} norm 1 atlas :WorldAtlas } } basename example scalar_output_format "%#.8g" vector_field_output_format {binary 4} } # Default outputs Destination hystgraph mmGraph:Hysteresis Destination monitor mmGraph new Destination archive mmArchive Schedule Schedule Schedule Schedule DataTable hystgraph Stage 1 DataTable monitor Step 5 DataTable archive Stage 1 Oxs_TimeDriver::Magnetization archive Stage 3 Figure 5: Example MIF 2.1 le.

17.2

MIF 1.1

The MIF 1.1 format is an older micromagnetic problem specication format used by the 2D solver. It is completely incompatible with the MIF 2.1 format used by the 3D solver. However, the command line tool mifconvert (Sec. 16.7) may be used as a conversion aid.

144

A sample MIF 1.1 le is presented in Fig. 6. The rst line of a MIF le must be of the form # MIF x.y, where x.y represents the format revision number. (The predecessor MIF 1.0 format was not included in any released version of OOMMF.) After the format identier line, any line ending in a backslash, \, is joined to the succeeding line before any other processing is performed. Lines beginning with a # character are comments and are ignored. Blank lines are also ignored. All other lines must consist of a Record Identier followed by a parameter list. The Record Identier is separated from the parameter list by one or more : and/or = characters. Whitespace and case is ignored in the Record Identier eld. The parameter list must be a proper Tcl list. The parameters are parsed (broken into separate elements) following normal Tcl rules; in short, items are separated by whitespace, except as grouped by double quotes and curly braces. The grouping characters are removed during parsing. Any # character that is found outside of any grouping mechanism is interpreted as a comment start character. The # and all following characters on that line are interpreted as a comment. Order of the records in a MIF 1.1 le is unimportant, except as explicitly stated below. If two or more lines contain the same Record Identier, then the last one takes precedence, with the exception of Field Range records, of which there may be several active. All records are required unless listed as optional. Some of these record types are not supported by mmProbEd, however you may modify a MIF 1.1 le using any plain text editor and supply it to mmSolve2D (Sec. 10.1) using FileSource (Sec. 9). For convenience, the Record Identier tags are organized into several groups; these groups correspond to the top-level buttons presented by mmProbEd. We follow this convention below. 17.2.1 Material parameters

# Material Name: This is a convenience entry for mmProbEd; inside the MIF 1.1 le it is a comment line. It relates a symbolic name (e.g., Iron) to specic values to the next 4 items. Ignored by solvers. Ms: Saturation magnetization in A/m. A: Exchange stiness in J/m. K1: Crystalline anisotropy constant in J/m3 . If K1 > 0, then the anisotropy axis (or axes) is an easy axis; if K1 < 0 then the anisotropy axis is a hard axis. Anisotropy Type: Crystalline anisotropy type; One of <uniaxial|cubic>. Anisotropy Dir1: Directional cosines of rst crystalline anisotropy axis, taken with respect to the coordinate axes (3 numbers). Optional; Default is 1 0 0 (x-axis). Anisotropy Dir2: Directional cosines of second crystalline anisotropy axis, taken with respect to the coordinate axes (3 numbers). Optional; Default is 0 1 0 (y-axis). 145

For uniaxial materials it suces to specify only Anisotropy Dir1. For cubic materials one must also specify Anisotropy Dir2; the third axis direction will be calculated as the cross product of the rst two. The anisotropy directions will be automatically normalized if necessary, so for example 1 1 1 is valid input (it will be modied to .5774 .5774 .5774). For cubic materials, Dir2 will be adjusted to be perpendicular to Dir1 (by subtracting out the component parallel to Dir1). Anisotropy Init: Method to use to set up directions of anisotropy axes, as a function of spatial location; This is a generalization of the Anisotropy Dir1/2 records. The value for this record should be one of <Constant|UniformXY|UniformS2>. Constant uses the values specied for Anisotropy Dir1 and Dir2, with no dispersion. UniformXY ignores the values given for Anisotropy Dir1 and Dir2, and randomly varies the anisotropy directions uniformly in the xy-plane. UniformS2 is similar, but randomly varies the anisotropy directions uniformly on the unit sphere (S 2 ). This record is optional; the default value is Constant. Edge K1: Anisotropy constant similar to crystalline anisotropy constant K1 described above, but applied only along the edge surface of the part. This is a uniaxial anisotropy, directed along the normal to the boundary surface. Units are J/m3 , with positive values making the surface normal an easy axis, and negative values making the surface an easy plane. The default value for Edge K1 is 0, which disables the term. Do Precess: If 1, then enable the precession term in the Landau-Lifshitz ODE. If 0, then do pure damping only. (Optional; default value is 1.) Gyratio: The Landau-Lifshitz gyromagnetic ratio, in m/(A.s). This is optional, with default value of 2.21 105 . See the discussion of the Landau-Lifshitz ODE under the Damp Coef record identier description. Damp Coef: The ODE solver in OOMMF integrates the Landau-Lifshitz equation [7, 9], written as dM | | = | | M He M (M He ) , dt Ms where is the Landau-Lifshitz gyromagnetic ratio (m/(As)), is the damping coecient (dimensionless).

(Compare to (2), page 54.) Here is specied by the Damp Coef entry in the MIF 1.1 le. If not specied, a default value of 0.5 is used, which allows the solver to converge in a reasonable number of iterations. Physical materials will typically have a damping coecient in the range 0.004 to 0.15. The 2D solver engine mmSolve (Sec. 10) requires a non-zero damping coecient.

146

17.2.2

Demag specication

Demag Type: Specify algorithm and demagnetization kernel used to calculate selfmagnetostatic (demagnetization) eld. Must be one of ConstMag: Calculates the average eld in each cell under the assumption that the magnetization is constant in each cell, using formulae from [12]. (The other demag options calculate the eld at the center of each cell.) 3dSlab: Calculate the in-plane eld components using oset blocks of constant (volume) charge. Details are given in [3]. Field components parallel to the z-axis are calculated using squares of constant (surface) charge on the upper and lower surfaces of the sample. 3dCharge: Calculate the in-plane eld component using rectangles of constant (surface) charge on each cell. This is equivalent to assuming constant magnetization in each cell. The z-components of the eld are calculated in the same manner as for the 3dSlab approach. FastPipe: Algorithm suitable for simulations that have innite extent in the z-direction. This is a 2D version of the 3dSlab algorithm. None: No demagnetization. Fastest but least accurate method. :-} All of these algorithms except FastPipe and None require that the Part Thickness (cf. the Part Geometry section) be set. Fast Fourier Transform (FFT) techniques are used to accelerate the calculations. 17.2.3 Part geometry

Part Width: Nominal part width (x-dimension) in meters. Should be an integral multiple of Cell Size. Part Height: Nominal part height (y-dimension) in meters. Should be an integral multiple of Cell Size. Part Thickness: Part thickness (z-dimension) in meters. Required for all demag types except FastPipe and None. Cell Size: In-plane (xy-plane) edge dimension of base calculation cell. This cell is a rectangular brick, with square in-plane cross-section and thickness given by Part Thickness. N.B.: Part Width and Part Height should be integral multiples of Cell Size. Part Width and Part Height will be automatically adjusted slightly (up to 0.01%) to meet this condition (aecting a small change to the problem), but if the required adjustment is too large then the problem specication is considered to be invalid, and the solver will signal an error. Part Shape: Optional. Part shape in the xy-plane; must be one of the following: 147

 Rectangle The sample lls the area specied by Part Width and Part Height. (Default.) Ellipse The sample (or the magnetically active portion thereof) is an ellipse inscribed into the rectangular area specied by Part Width and Part Height. Ellipsoid Similar to the Ellipse shape, but the part thickness is varied to simulate an ellipsoid, with axis lengths of Part Width, Part Height and Part Thickness. Oval r Shape is a rounded rectangle, where each corner is replaced by a quarter circle with radius r, where 0 r 1 is relative to the half-width of the rectangle. Pyramid overhang Shape is a truncated pyramid, with ramp transition base width (overhang) specied in meters. Mask lename Shape and thickness are determined by a bitmap le, the name of which is specied as the second parameter. The overall size of the simulation is still determined by Part Width and Part Height (above); the bitmap is spatially scaled to t those dimensions. Note that this scaling will not be square if the aspect ratio of the part is dierent from the aspect ratio of the bitmap. The given lename must be accessible to the solver application. At present the bitmap le must be in either the PPM (portable pixmap), GIF, or BMP formats. (Formats other than the PPM P3 (text) format may be handled by spawning an any2ppm (Sec. 16.1) subprocess.) White areas of the bitmap are interpreted as being non-magnetic (or having 0 thickness); all other areas are assumed to be composed of the material specied in the Material Parameters section. Thickness is determined by the relative darkness of the pixels in the bitmap. Black pixels are given full nominal thickness (specied by the Part Thickness parameter above), and gray pixels are linearly mapped to a thickness between the nominal thickness and 0. In general, bitmap pixel values are converted to a thickness relative to the nominal thickness by the formula 1-(R+G+B)/(3M), where R, G and B are the magnitudes of the red, green and blue components, respectively, and M is the maximum allowed component magnitude. For example, black has R=G=B=0, so the relative thickness is 1, and white has R=G=B=M, so the relative thickness is 0. The code does not perform a complete 3D evaluation of thickness eects. Instead, the approximation discussed in [13] is implemented. 17.2.4 Initial magnetization

Init Mag: Name of routine to use to initialize the simulation magnetization directions 148

(as a function of position), and routine parameters, if any. Optional, with default Random. The list of routines is long, and it is easy to add new ones. See the le maginit.cc for details. A few of the more useful routines are: Random Random directions on the unit sphere. This is somewhat like a quenched thermal demagnetized state. Uniform Uniform magnetization in the direction indicated by the two additional parameters, and , where the rst is the angle from the z-axis (in degrees), and the second is the angle from the x-axis (in degrees) of the projection onto the xy-plane. Vortex Fits an idealized vortex about the center of the sample. avfFile lename The second parameter species an OVF/VIO (i.e., any vector eld) le to use to initialize the magnetization. The grid in the input le will be scaled as necessary to t the grid in the current simulation. The le must be accessible to the intended solver application. 17.2.5 Experiment parameters

The following records specify the applied eld schedule: Field Range: Species a range of applied elds that are stepped though in a linear manner. The parameter list should be 7 numbers, followed by optional control point (stopping criteria) specications. The 7 required elds are the begin eld Bx By Bz in Tesla, the end eld Bx By Bz in Tesla, and an integer number of steps (intervals) to take between the begin and end elds (inclusive). Use as many Field Range records as necessarythey will be stepped through in order of appearance. If the step count is 0, then the end eld is ignored and only the begin eld is applied. If the step count is larger than 0, and the begin eld is the same as the last eld from the previous range, then the begin eld is not repeated. The optional control point specs determine the conditions that cause the applied eld to be stepped, or more precisely, end the simulation of the magnetization evolution for the current applied eld. The control point specs are specied as type value pairs. There are 3 recognized control point types: torque, time, and iteration. If a torque pair is given, then the simulation at the current applied eld is ended 2 when m h (i.e., M H /Ms ) at all spins in the simulation is smaller than the specied torque value (dimensionless). If a time pair is given, then the simulation at the current eld is ended when the elapsed simulation time for the current eld step reaches the specied time value (in seconds). Similarly, an iteration pair steps the applied eld when the iteration count for the current eld step reaches the iteration 149

value. If multiple control point specs are given, then the applied eld is advanced when any one of the specs is met. If no control point specs are given on a range line, then the Default Control Point Spec is used. For example, consider the following Field Range line: Field Range: 0 0 0 .05 0 0 5 -torque 1e-5 -time 1e-9

This species 6 applied eld values, (0,0,0), (0.01,0,0), (0.02,0,0), . . . , (0.05,0,0) (in Tesla), with the advancement from one to the next occurring whenever m h is smaller than 1e-5 for all spins, or when 1 nanosecond (simulation time) has elapsed at the current eld. (If torque was not specied, then the applied eld would be stepped at 1, 2, 3 4 and 5 ns in simulation time.) This Field Range record is optional, with a default value of 0 0 0 0 0 0 0. Default Control Point Spec: List of control point type value pairs to use as stepping criteria for any eld range with no control point specs. This is a generalization of and replacement for the Converge |mxh| Value record. Optional, with default -torque 1e-5. Field Type: Applied (external) eld routine and parameters, if any. This is optional, with default Uniform. At most one record of this type is allowed, but the Multi type may be used to apply a collection of elds. The nominal applied eld (NAF) is stepped through the Field Ranges described above, and is made available to the applied eld routines which use or ignore it as appropriate. The following Field Type routines are available: Uniform Applied eld is uniform with value specied by the NAF. Ribbon relcharge x0 y0 x1 y1 height Charge Ribbon, lying perpendicular to the xy-plane. Here relcharge is the charge strength relative to Ms, and (x0,y0), (x1,y1) are the endpoints of the ribbon (in meters). The ribbon extends height/2 above and below the calculation plane. This routine ignores the NAF. Tie rfx rfy rfz x0 y0 x1 y1 ribwidth The points (x0,y0) and (x1,y1) dene (in meters) the endpoints of the center spine of a rectangular ribbon of width ribwidth lying in the xy-plane. The cells with sample point inside this rectangle see an applied eld of (rfx,rfy,rfz), in units relative to Ms. (If the eld is large, then the magnetizations in the rectangle will be tied to the direction of that eld.) This routine ignores the NAF.

150

 OneFile lename multiplier Read B eld in from a le. Each value in the le is multiplied by the multiplier value on input. This makes it simple to reverse eld direction (use -1 for the multiplier), or to convert H elds to B elds (use 1.256637e-6). The input le may be any of the vector eld le types recognized by mmDisp. The input dimensions will be scaled as necessary to t the simulation grid, with zeroth order interpolation as necessary. This routine ignores the NAF. FileSeq lename procname multiplier This is a generalization of the OneFile routine that reads in elds from a sequence of les. Here lename is the name of a le containing Tcl code to be sourced during problem initialization, and procname is the name of a Tcl procedure dened in lename, which takes the nominal B eld components and eld step count values as imports (4 values total), and returns the name of the vector eld le that should be used as the applied B eld for that eld step. Multi routinecount \ param1count name1 param1 param2 . . . \ param2count name2 param1 param2 . . . \ ... Allows a conglomeration of several eld type routines. All entries must be on the same logical line, i.e., end physical lines with \ continuation characters as necessary. Here routinecount is the number of routines, and param1count is the number parameters (including name1) needed by the rst routine, etc. Note that all lengths are in meters. The coordinates in the simulation lie in the rst octant, running from (0,0,0) to (Part Width, Part Height, Part Thickness). 17.2.6 Output specication

Base Output Filename: Default base name used to construct output lenames. Magnetization Output Format: Format to use in the OVF (Sec. 19.1) data block for exported magnetization les. Should be one of binary 4 (default), binary 8, or text format-spec, where format-spec is a C printf-style format code, such as %# .17g. Optional. Total Field Output Format: Analogous to the Magnetization Output Format, but for total eld output les. Optional, with default binary 4. Data Table Output Format: Format to use when producing data table style scalar output, such as that sent to mmDataTable (Sec. 11), mmGraph (Sec. 12), and mmArchive (Sec. 14). Should specify a C printf-style format code, such as the default %.16g. Optional.

151

17.2.7

Miscellaneous

Converge |mxh| Value: Nominal value to use as a stopping criterion: When mh 2 (i.e., MH /Ms ) at all spins in the simulation is smaller than this value, it is assumed that a relaxed (equilibrium) state has been reached for the current applied eld. This is a dimensionless value. NOTE: This Record Identier is deprecated. Use Default Control Point Spec instead. Randomizer Seed: Value with which to seed random number generator. Optional. Default value is 0, which uses the system clock to generate a semi-random seed. Max Time Step: Limit the maximum ODE step size to no larger than this amount, in seconds. Optional. Min Time Step: Limit the minimum ODE step size to no less than this amount, in seconds. Optional. User Comment: Free-form comment string that may be used for problem identication. Optional. # MIF 1.1 # # All units are SI. # ################# MATERIAL PARAMETERS ###################### Ms: 800e3 # Saturation magnetization in A/m. A: 13e-12 # Exchange stiffness in J/m. K1: 0.5e3 # Anisotropy constant in J/m^3. Anisotropy Type: uniaxial # One of <uniaxial|cubic>. Anisotropy Dir1: 1 0 0 # Directional cosines wrt to # coordinate axes ################# DEMAG SPECIFICATION ###################### Demag Type: ConstMag # One of <ConstMag|3dSlab|2dSlab # |3dCharge|FastPipe|None>. #################### PART GEOMETRY ######################### Part Width: 0.25e-6 # Nominal part width in m Part Height: 1.0e-6 # Nominal part height in m Part Thickness: 1e-9 # Part thickness in m. Cell Size: 8.1e-9 # Cell size in m. #Part Shape: # One of <Rectangle|Ellipse|Oval|Mask>. # Optional.

152

################ INITIAL MAGNETIZATION ##################### Init Mag: Uniform 90 45 # Initial magnetization routine # and parameters ################ EXPERIMENT PARAMETERS ##################### # Field Range: Start_field Stop_field Steps Field Range: -.05 -.01 0. .05 .01 0. 100 Field Range: .05 .01 0. -.05 -.01 0. 100 Field Type: Multi 4 \ 7 Ribbon 1 0 1.0e-6 0.25e-6 1.0e-6 1e-9 \ 7 Ribbon 1 0 0 0.25e-6 0 1e-9 \ 9 Tie 100 0 0 0.12e-6 0.5e-6 0.13e-6 0.5e-6 8.1e-9 \ 1 Uniform # The above positions ribbons of positive charge along the # upper and lower edges with strength Ms, applies a large # (100 Ms) field to the center cell, and also applies a # uniform field across the sample stepped from # (-.05,-.01,0.) to (.05,.01,0.) (Tesla), and back, in # approximately 0.001 T steps. Default Control Point Spec: -torque 1e-6 # Assume equilibrium has been reached, and step the applied # field, when the reduced torque |mxh| drops below 1e-6. ################ OUTPUT SPECIFICATIONS ##################### Base Output Filename: samplerun Magnetization Output Format: binary 8 # Save magnetization # states in binary format with full (8-byte) precision. #################### MISCELLANEOUS ######################### Randomizer Seed: 1 # Random number generator seed. User Comment: Example MIF 1.1 file, with lots of comments. Figure 6: Example MIF 1.1 le.

18

Data Table File Format (ODT)

Textual output from solver applications that is not of the vector eld variety is output in the OOMMF Data Table (ODT) format. This is an ASCII text le format, with column information in the header and one line of data per record. Any line ending in a \ character 153

is joined to the succeeding line before any other processing is performed. Any leading # characters on the second line are removed. As with the OVF format (Sec. 19.1), all non-data lines begin with a # character, comments with two # characters. (This makes it easier to import the data into external programs, for example, plotting packages.) An example is shown in Fig. 7. The rst line of an ODT le should be the le type descriptor # ODT 1.0 It is also recommended that ODT les be given names ending in the le extension .odt so that ODT les may be easily identied. The remaining lines of the ODT le format should be comments, data, or any of the following 5 recognized descriptor tag lines: # Table Start: Optional, used to segment a le containing multiple data table blocks. Anything after the colon is taken as an optional label for the following data block. # Title: Optional; everything after the colon is interpreted as a title for the table. # Columns: Required. One parameter per column, designating the label for that column. Spaces may be embedded in a column label by using the normal Tcl grouping mechanisms (i.e., double-quotes and braces). # Units: Optional. If given, it should have one parameter for each column, giving a unit label for the corresponding column. # Table End: Optional, no parameters. Should be paired with a corresponding Table Start record. Data may appear anywhere after the Columns descriptor record and before any Table End line, with one record per line. The data should be numeric values separated by whitespace. The command line utility, odtcols (Sec. 16.8), can be a useful tool for examining and partitioning ODT les.

19

Vector Field File Format (OVF)

Vector eld les specify vector quantities (e.g., magnetization or magnetic ux density) as a function of spatial position. The OOMMF Vector Field (OVF) format is the output vector eld le format used by both the 2D (Sec. 10) and 3D (Sec. 7) micromagnetic solvers. It is also the input data type read by mmDisp (Sec. 13). There are two versions of the OVF format supported by OOMMF. The OVF 1.0 format is the preferred format and the only one written by OOMMF software. It supports both rectangular and irregular meshes, in binary and ASCII text. The OVF 0.0 format (formerly SVF) is an older, simpler format that can be useful for importing vector eld data into OOMMF from other programs. (A third 154

# ODT 1.0 # Table Start # Title: This is a small sample ODT file. # ## This is a sample comment. You can put anything you want ## on comment lines. # # Columns: Iteration "Applied Field" {Total Energy} Mx # Units: {} "mT" "J/m^3" "A/m" 103 50 0.00636 787840 1000 32 0.00603 781120 10300 -5000 0.00640 -800e3 # Table End Figure 7: Sample ODT le. format, the VecFil or Vector Input/Output (VIO) format, was used by some precursors to the OOMMF code. Although OOMMF is able to read the VIO format, its use is deprecated.) The recommended le extensions for OVF les are .omf for magnetization les, .ohf for magnetic eld (H) les, .obf for magnetic ux density (B) les, or .ovf for generic les.

19.1

The OVF 1.0 format

A commented sample OVF 1.0 le is provided in Fig. 8. An OVF le has an ASCII header and trailer, and a data block that may be either ASCII or binary. All non-data lines begin with a # character; double ## mark the start of a comment, which continues until the end of the line. There is no line continuation character. Lines starting with a # but containing only whitespace characters are ignored. All non-empty non-comment lines in the le header are structured as label+value pairs. The label tag consists of all characters after the initial # up to the rst colon (:) character. Case is ignored, and all space and tab characters are eliminated. The value consists of all characters after the rst colon, continuing up to a ## comment designator or the end of the line. The rst line of an OVF le should be a le type identication line, having the form # OOMMF: rectangular mesh v1.0 or # OOMMF: irregular mesh v1.0 where the value rectangular mesh v1.0 or irregular mesh v1.0 identies the mesh type and revision. While the OVF 1.0 format was under development in earlier OOMMF releases, 155

the revision strings 0.99 and 0.0a0 were sometimes recorded on the le type identication line. OOMMF treats all of these as synonyms for 1.0 when reading OVF les. The remainder of the le is conceptually broken into Segment blocks, and each Segment block is composed of a (Segment) Header block and a Data block. Each block begins with a # Begin: <block type> line, and ends with a corresponding # End: <block type> line. The number of Segment blocks is specied in the # Segment count: 1 line. Currently only 1 segment is allowed. This may be changed in the future to allow for multiple vector elds per le. This is followed by # Begin: Segment to start the rst segment. 19.1.1 Segment Header block

The Segment Header block start is marked by the line # Begin: Header and the end by # End: Header. Everything between these lines should be either comments or one of the following le descriptor lines. They are order independent. All are required unless otherwise stated. Numeric values are oating point values unless integer is explicitly stated. title: Long le name or title. desc: Description line. Optional. Use as many as desired. Description lines may be displayed by postprocessing programs, unlike comment lines which are ignored by all automated processing. meshunit: Fundamental mesh spatial unit, treated as a label. The comment marker ## is not allowed in this label. Example value: nm. valueunit: Fundamental eld value unit, treated as a label. The comment marker ## is not allowed in this label. Example: kA/m. valuemultiplier: Values in the data block are multiplied by this to get true values in units of valueunit. This simplies the use of normalized values. xmin, ymin, zmin, xmax, ymax, zmax: Six separate lines, specifying the bounding box for the mesh, in units of meshunit. This may be used by display programs to limit the display area, and may be used for drawing a boundary frame if boundary is not specied. boundary: List of (x,y,z) triples specifying the vertices of a boundary frame. Optional.

156

 ValueRangeMaxMag, ValueRangeMinMag: The maximum and minimum eld magnitudes in the data block, in the same units and scale as used in the data block. These are for optional use as hints by postprocessing programs; for example, mmDisp will not display any vector with magnitude smaller than ValueRangeMinMag. meshtype: Grid structure; should be either rectangular or irregular. Irregular grid les should specify pointcount in the header; rectangular grid les should specify instead xbase, ybase, zbase, xstepsize, ystepsize, zstepsize, and xnodes, ynodes, znodes. pointcount: Number of data sample points/locations, i.e., nodes (integer). For irregular grids only. xbase, ybase, zbase: Three separate lines, denoting the position of the rst point in the data section, in units of meshunit. For rectangular grids only. xstepsize, ystepsize, zstepsize: Three separate lines, specifying the distance between adjacent grid points, in units of meshunit. Required for rectangular grids, but may be specied as a display hint for irregular grids. xnodes, ynodes, znodes: Three separate lines, specifying the number of nodes along each axis (integers). For rectangular grids only. 19.1.2 Data block

The data block start is marked by a line of the form # Begin: data <representation> where <representation> is one of text, binary 4, or binary 8. Text mode uses the ASCII specication, with individual data items separated by an arbitrary amount of whitespace (spaces, tabs and newlines). Comments are not allowed inside binary mode data blocks, but are permitted inside text data blocks. The binary representations are IEEE oating point in network byte order (MSB). To insure that the byte order is correct, and to provide a partial check that the le hasnt been sent through a non 8-bit clean channel, the rst datum is a predened value: 1234567.0 (Hex: 49 96 B4 38) for 4-byte mode, and 123456789012345.0 (Hex: 42 DC 12 21 83 77 DE 40) for 8-byte mode. The data immediately follow the check value. The structure of the data depends on whether the meshtype declared in the header is irregular or rectangular. For irregular meshes, each data element is a 6-tuple, consisting of the x, y and z components of the node position, followed by the x, y and z components of the eld at that position. Ordering among the nodes is not relevant. The number of nodes is specied in the pointcount line in the segment header. For rectangular meshes, data input is eld values only, in x, y, z component triples. These are ordered with the x index incremented rst, then the y index, and the z index last. 157

This is nominally Fortran order, and is adopted here because commonly x will be the longest dimension, and z the shortest, so this order is more memory-access ecient than the normal C array indexing of z, y, x. The size of each dimension is specied in the xnodes, ynodes, znodes lines in the segment header. In any case, the rst character after the last data item should be a newline, followed by # End: data <representation> where <representation> must match the value in the Begin: data line. This is followed by a # End: segment line that ends the segment, and hence the le. Note: An OVF 1.0 le with ASCII data and irregular meshtype is also a valid OVF 0.0 (SVF) le, although as a OVF 0.0 le the value scaling as specied by # valueunit and # valuemultiplier header lines is inactive. # OOMMF: rectangular mesh v1.0 # ## This is a comment. ## No comments allowed in the first line. # # Segment count: 1 ## Number of segments. Should be 1 for now. # # Begin: Segment # Begin: Header # # Title: Long file name or title goes here # # Desc: Description tag, which may be used or ignored by postprocessing # Desc: programs. You can put anything you want here, and can have as many # Desc: Desc lines as you want. The ## comment marker is disabled in # Desc: description lines. # ## Fundamental mesh measurement unit. Treated as a label: # meshunit: nm # # meshtype: rectangular # xbase: 0. ## (xbase,ybase,zbase) is the position, in # ybase: 0. ## meshunit, of the first point in the data # zbase: 0. ## section (below). # # xstepsize: 20. ## Distance between adjacent grid pts.: on the x-axis, 158

# ystepsize: 10. ## 20 nm, etc. The sign on this value determines the # zstepsize: 10. ## grid orientation relative to (xbase,ybase,zbase). # # xnodes: 200 ## Number of nodes along the x-axis, etc. (integers) # ynodes: 400 # znodes: 1 # # xmin: 0. ## Corner points defining mesh bounding box in # ymin: 0. ## meshunit. Floating point values. # zmin: -10. # xmax: 4000. # ymax: 4000. # zmax: 10. # ## Fundamental field value unit, treated as a label: # valueunit: kA/m # valuemultiplier: 0.79577472 ## Multiply data block values by this # ## to get true value in valueunits. # # ValueRangeMaxMag: 1005.3096 ## These are in data block value units, # ValueRangeMinMag: 1e-8 ## and are used as hints (or defaults) # ## by postprocessing programs. The mmDisp program ignores any # ## points with magnitude smaller than ValueRangeMinMag, and uses # ## ValueRangeMaxMag to scale inputs for display. # # End: Header # ## Anything between # End: Header and # Begin: data text, ## # Begin: data binary 4 or # Begin: data binary 8 is ignored. ## ## Data input is in x-component y-component z-component triples, ## ordered with x incremented first, then y, and finally z. # # Begin: data text 1000 0 0 724.1 0. 700.023 578.5 500.4 -652.36 <...data omitted for brevity...> 252.34 -696.42 -671.81 # End: data text # End: segment

159

Figure 8: Commented OVF sample le.

19.2

The OVF 0.0 format

The OVF 0.0 format is a simple ASCII text format supporting irregularly sampled data. It is intended as an aid for importing data from non-OOMMF programs, and is backwards compatible with the format used for problem submissions for the rst MAG standard problem14 . Users of early releases of OOMMF may recognize the OVF 0.0 format by its previous name, the Simple Vector Field (SVF) format. It came to the attention of the OOMMF developers that the le extension .svf was already registered in several MIME systems to indicate the Simple Vector Format15 , a vector graphics format. To avoid conict, we have stopped using the name Simple Vector Field format, although OOMMF software still recognizes the .svf extension and you may still nd example les and other references to the SVF format. A sample OVF 0.0 le is shown in Fig. 9. Any line beginning with a # character is a comment, all others are data lines. Each data line is a whitespace separated list of 6 elements: the x, y and z components of a node position, followed by the x, y and z components of the eld at that position. Input continues until the end of the le is reached. It is recommended (but not required) that the rst line of an OVF le be # OOMMF: irregular mesh v0.0 This will aid automatic le type detection. Also, three special (extended) comments in OVF 0.0 les are recognized by mmDisp: ## File: <filename or extended filename> ## Boundary-XY: <boundary vertex pairs> ## Grid step: <cell dimension triple> All these lines are optional. The File provides a preferred (possibly extended) lename to use for display identication. The Boundary-XY line species the ordered vertices of a bounding polygon in the xy-plane. If given, mmDisp will draw a frame using those points to ostensibly indicate the edges of the simulation body. Lastly, the Grid step line provides three values representing the average x, y and z dimensions of the volume corresponding to an individual node (eld sample). It is used by mmDisp to help scale the display. Note that the data section of an OVF 0.0 le takes the simple form of columns of ASCII formatted numbers. Columns of whitespace separated numbers expressed in ASCII are easy to import into other programs that process numerical datasets, and are easy to generate, so the OVF 0.0 le format is useful for exchanging vector eld data between OOMMF and
14 15

http://www.ctcms.nist.gov/rdm/stdprob 1.html http://www.softsource.com/svf/

160

# OOMMF: irregular mesh v0.0 ## File: sample.ovf ## Boundary-XY: 0.0 0.0 1.0 0.0 1.0 2.0 0.0 2.0 0.0 0.0 ## Grid step: .25 .5 0 # x y z m_x m_y m_z 0.01 0.01 0.01 -0.35537 0.93472 -0.00000 0.01 1.00 0.01 -0.18936 0.98191 -0.00000 0.01 1.99 0.01 -0.08112 0.99670 -0.00000 0.50 0.50 0.01 -0.03302 0.99945 -0.00001 0.99 0.05 0.01 -0.08141 0.99668 -0.00001 0.75 1.50 0.01 -0.18981 0.98182 -0.00000 0.99 1.99 0.01 -0.35652 0.93429 -0.00000 Figure 9: Example OVF 0.0 le. non-OOMMF programs. Furthermore, the data section of an OVF 0.0 le is consistent with the data section of an OVF 1.0 le that has been saved as an irregular mesh using text data representation. This means that even though OOMMF software now writes only the OVF 1.0 format for vector eld data, simple interchange of vector eld data with other programs is still supported.

161

20

Troubleshooting

The OOMMF developers rely on reports from OOMMF users to alert them to problems with the software and its documentation, and to guide the selection and implementation of new features. See the Credits (Sec. 22) for instructions on how to contact the OOMMF developers. The more complete your report, the fewer followup messages will be required to determine the cause of your problem. Usually when a problem arises there is an error message produced by the OOMMF software. A stack trace may be oered that reveals more detail about the error. When reporting an error, it will help the developers diagnose the problem if users cut and paste into their problem report the error message and stack trace exactly as reported by OOMMF software. In addition, please include a copy of the output generated by tclsh oommf.tcl +platform so that the OOMMF developers will know the details of your platform conguration. Before making a report to the OOMMF developers, please check the following list of xes for known problems: 1. When compiling (Sec. 2.2.3), there is an error about being unable to open system header les like stdlib.h, time.h, math.h, or system libraries and related program startup code. This usually indicates a bad compiler installation. If you running on Windows and building with the the Microsoft Visual C++ command line compiler, did you remember to run vcvars32.bat to set up the necessary environment variables? If you are using the Borland C++ compiler, are the bcc32.cfg and ilink32.cfg les properly congured? In all cases, check carefully any notes in the chapter Advanced Installation (Sec. 2.3) pertaining to your compiler. 2. When compiling (Sec. 2.2.3), there is an error something like: <30654> pimake 1.x.x.x MakeRule panic: Dont know how to make /usr/include/tcl.h This means the header le tcl.h is missing from your Tcl installation. Other missing header les might be tk.h from the Tk installation, or Xlib.h from an X Window System installation on Unix. In order to compile OOMMF, you need to have the development versions of Tcl, Tk, and (if needed) X installed. The way to achieve that is platform-dependent. On Windows you do not need an X installation, but when you install Tcl/Tk be sure to request a full installation, or one with header and library les. On Linux, be sure to install developer packages (for example, the XFree86-devel RPM) as well as user packages. Other platforms are unlikely to have this problem. In the case of Xlib.h, it is also possible that the tkConfig.sh le has an incorrect entry for TK XINCLUDES. A workaround for this is to add the following line to your oommf/config/cache/platform le: $config SetValue TK_XINCLUDES "-I/usr/X11R6/include" 162

Adjust the include directory as appropriate for your system. 3. When compiling (Sec. 2.2.3), there is an error indicating that exceptions are not supported. Parts of OOMMF are written in C++, and exceptions have been part of the C++ language for many years. If your compiler does not support them, it is time to upgrade to one that does. OOMMF 1.2 requires a compiler capable of compiling source code which uses C++ exceptions. 4. Compiling (Sec. 2.2.3) with gcc/egcs produces syntax errors on lines involving auto ptr templates. This is known to occur on RedHat 5.2 systems. The auto ptr denition in the system STL header le memory (located on RedHat 5.2 systems in the directory /usr/include/g++) is disabled by two #if statements. One solution is to edit this le to turn o the #if checks. If you do this, you will also have to x two small typos in the denition of the release() member function. 5. When compiling (Sec. 2.2.3) there is an error message arising from system include directories being too early in the include search path. Try adding the oending directories to the program compiler c++ system include path property in the platform cache le, e.g., $config SetValue program_compiler_c++_system_include_path \ [list /usr/include /usr/local/include] 6. On Solaris, gcc reports many errors like ANSI C++ forbids declaration XSetTransientForHint with no type On many Solaris systems, the header les for the X Window System are not ANSI compliant, and gcc complains about that. To work around this problem, edit the le oommf/config/cache/solaris.tcl to add the option -fpermissive to the gcc command line. 7. On Windows, when rst starting oommf.tcl, there is an error: Error launching mmLaunch version 1.x.x.x: couldnt execute "...\omfsh.exe": invalid argument This cryptic message most likely means that the pre-compiled OOMMF binaries which were downloaded are for a dierent version of Tcl/Tk than is installed on your system. Download OOMMF again, taking care this time to retrieve the binaries that match the release of Tcl/Tk you have installed. 8. When rst starting oommf.tcl, there is an error: 163

Error in startup script: set in

Neither Omf export nor Omf export list

The le oommf/ext/net/omfExport.tcl may be missing from your OOMMF installation. If necessary, download and install OOMMF again. 9. When launching multiple OOMMF applications on Windows 9X, there is an error: couldnt open socket: no buffer space available

OOMMF uses network sockets for communications between its various components. On Windows 9X, the socket resources are limited, and most OOMMF applications use several sockets. The only workaround is to close unneeded OOMMF applications, and any other applications that may be using network resources. The system command line utility netstat can be used to monitor network communications. This problem does not arise on Windows NT or Unix systems. 10. In the Cygwin environment on Windows there is an warning like: Tcl version mismatch: C:/Cygwin/lib/tclConfig.sh from 8.0p2 Running Tcl 8.0.4 This is caused by broken tclConfig.sh and tkConfig.sh les in the Cygwin distribution. You may ignore the warning, or edit the tclConfig.sh and tkConfig.sh les to change the TCL PATCH LEVEL and TK PATCH LEVEL values from p2 to .4. However, the best option is to upgrade Tcl/Tk. The stock Tcl/Tk 8.4.1 (and presumably later) release works in Cygwin. 11. I ran out of memory! Are you using mmGraph (Sec. 12) to monitor a long-running simulation? All data sent to mmGraph is kept in memory by default. See the mmGraph documentation for information on how to manage this problem.

164

21

References

[1] A. Aharoni, Introduction to the Theory of Ferromagnetism (Oxford, New York, 1996). [2] A. Aharoni, Demagnetizing Factors for Rectangular Ferromagnetic Prisms, J. App. Phys. 83, 34323434 (1999). [3] D. V. Berkov, K. Ramstck, and A. Hubert, Solving Micromagnetic Problems: Towards o an Optimal Numerical Method, Phys. Stat. Sol. (a) 137, 207222 (1993). [4] W. F. Brown, Jr., Micromagnetics (Krieger, New York, 1978). [5] M. J. Donahue and R. D. McMichael, Exchange Energy Representations in Computational Micromagnetics, Physica B 233, 272278 (1997). [6] M. J. Donahue and D. G. Porter, OOMMF Users Guide, Version 1.0, Technical Report No. NISTIR 6376, National Institute of Standards and Technology, Gaithersburg, MD (1999) . [7] T. L. Gilbert, A Lagrangian Formulation of the Gyromagnetic Equation of the Magnetization Field, Phys. Rev. 100, 1243 (1955). [8] P. R. Gillette and K. Oshima, Magnetization Reversal by Rotation, J. Appl. Phys. 29, 529531 (1958). [9] L. Landau and E. Lifshitz, On the Theory of the Dispersion of Magnetic Permeability in Ferromagnetic Bodies, Physik. Z. Sowjetunion 8, 153169 (1935). [10] R. D. McMichael and M. J. Donahue, Head to Head Domain Wall Structures in Thin Magnetic Strips, IEEE Trans. Mag. 33, 41674169 (1997). [11] L. Nel, Some Theoretical Aspects of Rock Magnetism, Adv. Phys. 4, 191242 (1955). e [12] A. J. Newell, W. Williams, and D. J. Dunlop, A Generalization of the Demagnetizing Tensor for Nonuniform Magnetization, J. Geophysical Research - Solid Earth 98, 9551 9555 (1993). [13] D. G. Porter and M. J. Donahue, Generalization of a Two-Dimensional Micromagnetic Model to Non-Uniform Thickness, Journal of Applied Physics 89, 72577259 (2001). [14] M. R. Scheinfein, J. Unguris, J. L. Blue, K. J. Coakley, D. T. Pierce, and R. J. Celotta, Micromagnetics of Domain Walls at Surfaces, Phys. Rev. B 43, 33953422 (1991). [15] E. C. Stoner and E. P. Wohlfarth, A Mechanism of Magnetic Hysteresis in Heterogeneous Alloys, Phil. Trans. Royal Soc. London A240, 599642 (1948). [16] B. B. Welch, Practical Programming in Tcl and Tk, 3rd ed. (Prentice Hall, Upper Saddle River, New Jersey USA, 2000).

165

22

Credits

The main contributors to this document are Michael J. Donahue (michael.donahue@nist.gov) and Donald G. Porter (donald.porter@nist.gov), both of ITL/NIST. Section 3 is based on notes from Dianne P. OLeary. The OOMMF16 code is being developed mainly by Michael Donahue and Donald Porter. Robert D. McMichael (rmcmichael@nist.gov) made contributions to the early development of the 2D micromagnetic solver. Jason Eicke (jeicke@seas.gwu.edu) is responsible for the problem editor, and has worked on the self-magnetostatic module of the 2D micromagnetic solver. Numerous users have contributed to the development of OOMMF by submitting bug reports, small pieces of code, or suggestions for improvements. Many thanks to all these people, including Dieter Buntinx, NgocNga Dao, Olivier Grardin, Ping He, Michael Ho, Mansoor e B. A. Jalil, Jrg Jorzick, Pierre-Olivier Jubert, Pavel Kabos, Michael Kleiber, H. T. Leo ung, David Lewis, Sang Ho Lim, Yi Liu, Van Luu, Andy P. Manners, Damien McGrouther, Wong Lai Mun, Edward Myers, Andrew Newell, Valentine Novosad, Andrew Perrella, Angeline Phoa, Anil Prabhakar, Robert Ravlic, Stephen E. Russek, Renat Sabirianov, Zhupei Shi, Xiaobo Tan, Stephen Thompson, Vassilios Tsiantos, Pieter Visscher, Scott L. Whittenburg, Kong Xiangyang, Tan Swee Yong, Chengtao Yu, Steven A. Zielke, and Pei Zou. If you have bug reports, contributed code, feature requests, or other comments for the OOMMF developers, please send them in an e-mail message to <michael.donahue@nist.gov>. Acknowledgement is appreciated if the software is used. We recommend citing the following NIST technical report: M. J. Donahue and D. G. Porter OOMMF Users Guide, Version 1.0 Interagency Report NISTIR 6376 National Institute of Standards and Technology, Gaithersburg, MD (Sept 1999). and optionally include the URL of the OOMMF home page, http://math.nist.gov/oommf/. To help us keep our bibliography page17 current, please direct publication information to <michael.donahue@nist.gov>.

16 17

http://math.nist.gov/oommf/ http://math.nist.gov/oommf/bibliography.html

166

Index
account service directory, 21, 27, 79, 80 expires, 22 launching of, 22 animations, 115 announcements, 2 antialias, 118 application any2ppm, 28, 72, 80, 112, 148 avf2odt, 113 avf2ovf, 66, 114 avf2ppm, 100, 115 avfdi, 120 batchmaster, 82 batchslave, 80 batchsolve, 79, 81, 127 bootstrap, 2324 Boxsi, 127 boxsi, 32 FileSource, 70, 145 gzip, 99 Internet Explorer, 10, 106 mag2held, 122 make, 124 mifconvert, 123, 127 mmArchive, 16, 1820, 30, 61, 92, 108 mmDataTable, 16, 17, 19, 30, 61, 91, 94, 95 mmDisp, 1, 16, 18, 19, 30, 61, 74, 80, 98, 108, 115, 117, 119 mmGraph, 1620, 30, 61, 78, 92, 94, 108, 164 mmHelp, 110 mmLaunch, 16, 26, 28, 29, 32, 33, 73, 78, 79 mmProbEd, 16, 68, 70, 80, 127, 166 mmSolve, 146 mmSolve2D, 16, 17, 72, 78, 80, 108, 114, 127, 145 Netscape, 10, 105 167 odtcols, 123 OOMMF Batch System, 78 Oxsii, 16, 18, 28, 127 pimake, 8, 124 ppmquant, 117 ppmtogif, 116 rsh, 82, 85, 87 tclsh, 3 web browser, 105, 110 Windows Explorer, 14, 25 wish, 3 Xvfb, 3, 24, 112 architecture, 21 batch processing, see application,OOMMF Batch System bitmap les, see le,bitmap Borland C++, see platform,Windows,Borland C++ boundary, 1, 102, 118 bug reports, see reporting bugs cell size, 147 citation information, 166 client, 21 client-server architecture, 21 color discretization, 117 map, 100, 117 quantity, 100, 117 communication protocol, 84 compilers, 4 contact information, 166 contributors, 166 control points, see simulation,control point crystalline anisotropy, 145 curve break, 95 customize, 10 le format translation, 99 help le browser, 110 host server port, 21

cut-and-paste, 92 Cygwin, see platform,Windows,Cygwin environment data print, 95, 100, 104 save, 17, 19, 95, 97, 99, 104, 108 scale, 101 slice selection, 102, 103 zoom, 102 demagnetization, 147 Destination command (MIF), 128 download, 4 e-mail, 2, 166 edge anisotropy, 146 energy anisotropy, 75, 77 crystalline anisotropy, 145 demag, 75, 77, 166 edge anisotropy, 146 exchange, 75, 77 total, 75, 77, 80 Zeeman, 75, 77 environment variables DISPLAY, 22 inherited from parent process, 22 LD LIBRARY PATH, 7 OOMMF TCL CONFIG, 6 OOMMF TCLSH, 7 OOMMF TK CONFIG, 7 OOMMF WISH, 7 OSTYPE, 13 PATH, 8 TCL LIBRARY, 7, 14 TERM, 13 TK LIBRARY, 7 exchange stiness, 145 FFT, 1, 77, 147 eld applied, 1, 74, 80, 150 demag, 1 168

eective, 77 update count, 74 eld range, 149 le bitmap, 28, 3639, 72, 80, 112, 115, 131, 131132, 148 bmp, 112, 116, 148 conguration, 96, 99, 117 conversion, 112115, 122, 123 data table, 18, 20, 74, 80, 85, 86, 95, 113, 123, 151, 153 dierence, 120 gif, 112, 116, 148 hosts, see platform,Windows,hosts le HTML, 110 log, 75, 79, 81 magnetization, 79, 86, 122, 151 mask, 28, 3639, 72, 80, 140, 148 MIF, 123, 127 MIF 1.1, 68, 70, 76, 7981, 8487 obf, see le,vector eld odt, see le,data table ohf, see le,vector eld omf, see le,magnetization options.tcl, 10 ovf, see le,vector eld ppm, 112, 116, 148 svf, 154, 158, 160 VecFil, 155 vector eld, 18, 19, 74, 80, 99, 102, 106, 113115, 120, 122, 149, 151, 154, 160 vio, 113, 114, 120, 149, 155 grid, 1, 77, 105, 114, 157 grouped lists (MIF), 136 gyromagnetic ratio, 146 host service directory, 21, 26 expires, 22 launching of, 22 installation, 3

options.tcl, 10 output schedule, 17, 18, 20, 74 Oxs Ext child classes, 35 Oxs AtlasScalarField, 63 Landau-Lifshitz, see ODE,Landau-Lifshitz Oxs AtlasVectorField, 65 launch Oxs BoxAtlas, 36 by account service directory, 2122 Oxs CGEvolve, 56 command line arguments, 2324 Oxs CubicAnisotropy, 42 foreground, 23 Oxs Demag, 47 from command line, 23 Oxs EulerEvolve, 54 standard options, 24 Oxs Exchange6Ngbr, 42 version requirement, 23 Oxs ExchangePtwise, 43 with bootstrap application, 23 Oxs FileVectorField, 66 with mmLaunch, 27 Oxs FixedZeeman, 48 license, iv Oxs ImageAtlas, 36 Oxs LabelValue, 67 magnetization, 75, 80 Oxs LinearScalarField, 63 initial, 1 Oxs MinDriver, 62 magnetization initial, 148 Oxs MultiAtlas, 39 margin, 119 Oxs PlaneRandomVectorField, 67 mask le, see le,mask Oxs RandomScalarField, 64 materials, 69, 145 Oxs RandomSiteExchange, 46 max angle, 75 Oxs RandomVectorField, 66 memory use, 96 Oxs RectangularMesh, 41 mesh, see grid Oxs ScriptAtlas, 40 MIF, see le,mif Oxs ScriptScalarField, 64 MIF 2.1 Commands, 127 Oxs ScriptUZeeman, 48 mmLaunch user interface, 26, 27, 29, 33, Oxs ScriptVectorField, 65 73, 78, 108 Oxs SimpleDemag, 47 movies, see animations Oxs StageZeeman, 51 mxh, see simulation,mxh Oxs TimeDriver, 59 NetPBM, 116 Oxs TransformZeeman, 49 network socket, 1, 31, 78, 84 Oxs TwoSurfaceExchange, 44 bug, see platform,Windows,network socket bug Oxs UniaxialAnisotropy, 42 Oxs UniformExchange, 43 OBS, see application,OOMMF Batch SysOxs UniformScalarField, 63 tem Oxs UniformVectorField, 65 ODE Oxs UZeeman, 47 Landau-Lifshitz, 1, 54, 76, 77, 146 Oxs Ext referencing (MIF), 134 predictor-corrector, 77 Runge-Kutta, 77 part geometry, 147 step size, 152 platform, 162 optimization, 10 169

TclTk, 67 Internet, see TCP/IP iteration, 74, 80

conguration, 5 names, 6, 1112 Unix executable Tcl scripts, 25 PostScript to printer, 95, 100 X server, 108 Windows Borland C++, 13 conguration, 78, 1215 Cygwin environment, 6, 13 desktop shorcut, 15 dummy user ID, 27 le extension associations, 14, 25 le path separator, 78 hosts le, 8 Microsoft Visual C++, 13 network socket bug, 31, 35, 78 no Tcl conguration le, 6 setting environment variables, 14 wildcard expansion, 116 platforms, 4 precession, 146 random numbers, 152 record identier, 145 reporting bugs, 162, 166 requirement application version, see launch,version requirement C++ compiler, 4 disk space, 34, 910 display, 28, 72, 80 rsh, 82 Tcl/Tk, 3 TCP/IP, 3 Tk, 28, 72, 80, 112 Tk 8.0+, 112 sampling, 118 saturation magnetization, 145 Schedule command (MIF), 132 segment block, 156 self-magnetostatic, see demagnetization 170

server, 21 services, 21 simulation 2D, 1, 72, 78, 166 control point, 18, 74, 78, 84, 86, 149, 150 equilibrium, 18 interactive control, 17, 18, 75, 80 iteration, 149 mxh, 75, 149, 152 restarting, 73, 79 scheduling, 82, 87 termination, 76, 80 time, 74, 149 simulation 3D, 1 batch, 32 interactive, 28 interactive control, 19, 20 stage, 19 sockets, 164 Specify attributes (MIF), 137 Specify block (MIF), 127 Specify comments (MIF), 137 Specify conventions (MIF), 133 Specify initialization string (MIF), 133 Specify support procs (MIF), 138 step size, 74 task script, 82, 84 Tcl list, 145 TCP/IP, 3, 21 threads, 17, 18, 27, 29, 33, 73, 74 time step, 74 torque, see simulation,mxh total eld, see eld,eective URL, 110 user ID, 21, 27 variable substitution (MIF), 140 vortex, 149 working directory, 5, 8, 22, 23, 27, 80, 87 Xvfb, see application,Xvfb