Tips for writing MIF 2.x files

MIF 2.x files are Tcl scripts, and so composing a MIF file is a programming exercise, with all the pitfalls that entails. In this section we detail some tips for authoring MIF files.

Generally a good place to start is to take an existing MIF file, either one you've written earlier or one from the oommf/app/oxs/examples/ directory, that has some similarity to the one you want to write. Make a copy of that and start to edit. If you need any complex functionality then an elementary understanding of Tcl is essential. In particular, you should be familiar with Tcl lists, arrays, and some of the basic Tcl commands such as set, expr, for, foreach, if/else, lrange, and subst. You can find a list of Tcl tutorials on the Tcler's Wiki Online Tcl and Tk Tutorials page. The Tcl Tutorial by Chris verBurg and Learn Tcl in Y Minutes linked on that page are good places to start. The Tcl Dodekalogue is also a handy reference for figuring out confusing error messages. Many more resources, including online manuals, can be found at the Tcl Developer Xchange.

Although MIF files are Tcl scripts, they also rely on a number of MIF extension commands. The most prominent of these is the Specify command, used to initialize Oxs_Ext (Oxs extension) objects, such as region definitions (atlases), mesh discretization, energy terms (exchange, anisotropy, dipole-dipole, applied fields), and solution method (energy minimization or LLG integration). The contents of each Specify block, which depend upon the particular Oxs_Ext being initialized, are documented in the Standard Oxs_Ext Child Classes section.

Other commonly used MIF extension commands are Parameter, Destination, and Schedule. Parameter operates similar to the Tcl set command, but allows the user to change the default value at runtime, through either the Params box in the Oxsii Load Problem dialog, or via the -parameters command line option to Boxsi. The Destination and Schedule commands are used primarily for non-interactive set up of simulation output for Boxsi.

As in any programming activity, bugs happen. Here are a few tips to aid in debugging your MIF code:

1. Check to see if your favorite programming editor (FPE) has support for Tcl syntax highlighting and indenting. This can help spot a lot of errors, particularly brace nesting issues, before you hand the file over to the Tcl interpreter inside OOMMF.

2. For development purposes, set the problem dimensions and cell sizes so the total number of cells is relatively small. This will allow problems to load and run faster, making it easier to detect and correct errors. Use the Oxsii|Help|About menu to see the number of cells in the simulation. For larger simulations you may want to temporarily disable the Oxs_Demag module, because that module can take some time to initialize and is usually the slowest module to run. If the cellsize magnetization is set correctly, then Oxs_Demag will usually be okay; you might want to take a little extra care when working with periodic boundary conditions, however, because demagnetization effects across PBC's can be nonintuitive.

3. When the MIF file is ready, launch Oxsii and bring up the File|Load dialog box. Select the Browse check box, as otherwise the Load dialog box is automatically closed when you select OK to load the file. The Browse option allows you to correct syntax errors in your MIF file without having to repeatedly open the File|Load dialog box and reselect your MIF file and parameters.

4. If the load fails, open the MIF file in your FPE and use the error message to help locate the point of failure in the file. Correct, save to disk, and try loading again.

5. If you can't figure out an error message, or to just double-check that your file is being interpreted as you intend, use the MIF Report command to print the contents of variables or other state information to the Oxsii console. (The Oxsii console is launched via the File|Show Console menu item on the main Oxsii window. If you are running Boxsi, Report output goes to the Boxsi log file, oommf/boxsi.errors.)

6. Once the file loads without errors, send Magnetization output from Oxsii to mmDisp for a visual check of the simulation structure. Use Ctrl- or Shift-Ctrl-<left mouse click> in mmDisp to view magnetization component values at various locations. Bring up the mmDisp Options|Configure dialog box to adjust the coloring, pixel and arrow selection, etc. The # of Colors and Data Scale settings in particular can make it easier to see small differences in the selected Color Quantity. The Arrow span setting can be used to control the number of levels of arrows that get displayed in the slice view. For example, if the cell dimension in the out-of-view-plane direction is 4 nm, then setting Arrow span to 4e-9 will cause a single slice of the magnetization to be displayed as you adjust the slice control slider in the main mmDisp window. If you set Arrow span to 8e-9 you'll see two layers of overlapping arrows, which can be helpful for checking interface conditions.

7. By default mmDisp opens with a top-down view along the z-axis. For multilayer structures it is helpful to see cross-sectional views along other axes too; these are available from the View|Viewpoint submenu in the main mmDisp window. Also, the mmDisp rendering of high aspect ratio cells can be rather poor. In this situation you may want to enable pixel display in the mmDisp configuration dialog with pixel size set smaller than 1, and adjust the background color to make the individual cells visible.

8. The Magnetization output viewed in mmDisp allows you to check that you have set Ms and m0 properly in the driver Specify block. You can send other fields, such as anisotropy and exchange, to mmDisp to check parameter settings for those energy terms as well. In this context it can be helpful to adjust m0 to align in specific directions for testing. You may want to open two instances of mmDisp, with Magnetization displayed in one and an energy field in the other, to help correspond energy field values with magnetization structure.

9. If you are having problems implementing some functionality, do a search through the MIF files in oommf/app/oxs/examples for something similar. For example, a text search for ``pulse'' will turn up matches in pillar.mif, pingpillar.mif, and pulse.mif, each illustrating how to implement an applied field pulse of various shapes.

OOMMF Documentation Team
September 27, 2023