Keywords: userguide

Next: Advanced Installation Up: Installation Previous: Requirements
Subsections

- Download
- Effects of the Installed Tcl/Tk
- Check Your Platform Configuration
  - Additional Configuration Issues on Windows
- Compiling and Linking
- Installing
- Using OOMMF Software
- Reporting Problems

## Basic Installation

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

###
Download

The latest release of the OOMMF software may be retrieved from the OOMMF download page. Each release is available in two formats. The first format is a gzipped tar file 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 Windows. 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.6.x is compatible with Tcl/Tk 8.6.0, 8.6.1, ....

For the first format, unpack the distribution archive using gunzip and tar:

    gunzip -c oommf20a0.tar.gz | tar xvf -

For the other format(s), you will need a utility program to unpack the `.zip` archive. One utility program which is known to be suitable is UnZip.

Using your utility, unpack the `.zip` archive, e.g.

    unzip oommf20a0_86.zip

For either distribution format, the unpacking sequence creates a subdirectory `oommf` which contains all the files and directories of the OOMMF distribution. If a subdirectory named `oommf` already existed (say, from an earlier OOMMF release), then files 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 files from an old and a new OOMMF distribution combine to create a working set of files.

### Effects of the Installed Tcl/Tk

OOMMF interacts with your Tcl/Tk installation in several ways. One important restriction is that the major+minor release number of Tcl/Tk must match the major+minor release number of the Tcl/Tk that OOMMF was built against. For example, if OOMMF was built using Tcl/Tk 8.5.18, then the resulting executables can run with any past or future releases of Tcl/Tk from the 8.5.* series, but they won't run (for example) with Tcl/Tk 8.4.20 or 8.6.4.

Another restriction is that the width of memory addresses in Tcl/Tk and OOMMF must match. Most general-purpose operating systems today use primarily 64-bit memory addresses, but for backwards compatibility can also run programs using 32-bit memory addresses. However, a 64-bit executable cannot link against a 32-bit library, or vice versa. Therefore, if you have a 64-bit Tcl/Tk installed, then you will need a 64-bit OOMMF, and likewise a 32-bit Tcl/Tk needs a 32-bit OOMMF.

Another restriction is that while OOMMF can be built to run in parallel across multiple cpu cores on a shared memory machine using threads, to do this requires that the installed Tcl/Tk be thread-enabled. Typical Tcl/Tk installs on Windows and Mac OS X are thread-enabled. Tcl/Tk installs on recent releases of Unix also tend to be thread-enabled, but some older versions have non-threaded Tcl/Tk installs. If your system Tcl/Tk install is non-threaded, then you can either build a non-threaded version of OOMMF, or else you can make an additional, threaded Tcl/Tk install, for example under your home directory or `/usr/local`. Be aware that if you have multiple Tcl/Tk installations on your system then you need to be careful to use the proper `tclsh` whenever you build or launch OOMMF.

If you download OOMMF with pre-built binaries, then it is imperative that you select the download that matches the major+minor release number and memory address width of the Tcl/Tk you want to run OOMMF with. On the other hand, if you build OOMMF from source, then the `tclsh` you use to run the build process is inspected to determine relevant information about the local Tcl/Tk environment. Some adjustment of the platform configuration file, as described in the next section, may be necessary. Also, in many cases the compilers used to build 32-bit and 64-bit executables are different--if you encounter build problems, double-check that the proper compiler is being used.

All of the OOMMF downloads containing pre-built binaries are built for use with thread-enabled Tcl/Tk. You will need to build from source if you want a non-threaded OOMMF. The build scripts will detect if the `tclsh` running the build procedure is non-threaded and will build OOMMF appropriately.

In all cases, use the platform configuration check described in the next section to verify the compatibility of your Tcl/Tk and OOMMF installs.

###
Check Your Platform Configuration

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 a console on 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 file named `oommf.tcl`. It is the bootstrap application which is used to launch all OOMMF software. With the command line argument `+platform`, it will print a summary of your platform configuration 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 Mac OS X 10.9 system:

    $ tclsh oommf.tcl +platform
    <5426> oommf.tcl 1.2.0.6  info:
    OOMMF release 1.2.0.6, snapshot 2015.03.25
    Platform Name:		darwin
    Tcl name for OS:	Darwin 13.4.0
    C++ compiler:   	/usr/bin/g++
     Version string:	 Apple LLVM version 6.0 (clang-600.0.57) (based on LLVM 3.5svn) / Target: x86_64-apple-darwin13.4.0 / Thread model: posix
    Shell details ---
     tclsh (running): 	/usr/bin/tclsh
                      	(links to /usr/bin/tclsh8.5)
                      	(links to /System/Library/Frameworks/Tcl.framework/Versions/8.5/tclsh8.5)
                      	 --> Version 8.5.9, 64 bit, threaded
     tclsh (OOMMF): 	/usr/bin/tclsh8.5
                      	 --> Version 8.5.9, 64 bit, threaded
     filtersh:           	/Users/dgp/oommf/app/omfsh/darwin/filtersh
                      	 --> Version 8.5.9, 64 bit, threaded
     tclConfig.sh:        	/System/Library/Frameworks/Tcl.framework/Versions/8.5/tclConfig.sh
                          	 --> Version 8.5.9
     wish (OOMMF):        	/usr/bin/wish8.5
                      	 --> Version 8.5.9, Tk 8.5.9, 64 bit, threaded
     tkConfig.sh:         	/System/Library/Frameworks/Tk.framework/Versions/8.5/tkConfig.sh
                          	 --> Tk Version 8.5.9
    OOMMF threads:         	Yes: Default thread count = 2
    OOMMF API index:       	20150129
    Temp file directory: 	/var/folders/dy/srfj33512f51kc5knp_lph_r0000gp/T/

If `oommf.tcl +platform` doesn't print a summary similar to the above, it should instead print an error message describing why it can't. Follow any instructions provided and repeat until `oommf.tcl +platform` successfully prints a summary of the platform configuration information.

The first line of the example summary reports that OOMMF recognizes the platform by the name `darwin`. 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 configuration files 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 configuration files 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 for further instructions.

The second line reports the operating system version, which is mainly useful to OOMMF developers when fielding bug reports. The third 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 configuration file for your platform. Continuing the example above, one would edit the file `config/platforms/darwin.tcl`. Editing instructions are contained within the file. On other platforms the name `darwin` in `config/platforms/darwin.tcl` should be replaced with the platform name OOMMF reports for your platform. For example, on a 32-bit Windows machine using an x86 processor, the corresponding configuration file is `config/platforms/wintel.tcl`.

The next group of lines describe the Tcl configuration OOMMF finds on your platform. The first couple of lines, ``tclsh (running)'', describe the Tcl shell running the oommf.tcl script. After that, the ``tclsh (OOMMF)'' subgroup describes the Tcl shell that OOMMF will launch when it needs to run Tcl scripts. If the OOMMF binaries have been built, then there will also be a `filtersh` subgroup, which describes the augmented Tcl shell used to run many of the OOMMF support scripts. All of these shells should report the same version, bitness, and threading information. If OOMMF can't find `tclsh`, or if it finds the wrong one, you can correct this by setting the environment variable OOMMF_TCLSH to the absolute location of `tclsh`. (For information about setting environment variables, see your operating system documentation.)

Following the Tcl shell information, the `tclConfig.sh` lines report the name of the configuration file installed as part of Tcl, if any. Conventional Tcl installations on Unix systems and within the Cygwin environment on Windows have such a file, usually named `tclConfig.sh`. The Tcl configuration file 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 configuration file is present on your system, you can tell OOMMF where to find the file by setting the environment variable OOMMF_TCL_CONFIG to its absolute filename. In unusual circumstances, OOMMF may find a Tcl configuration file which doesn't correctly describe your Tcl installation. In that case, use the environment variable OOMMF_TCL_CONFIG to instruct OOMMF to use a different file that you specify, and, if necessary, edit that file to include a correct description of your Tcl installation.

Next, the `oommf.tcl +platform` reports similar information about the `wish` and Tk configuration. The environment variables `OOMMF_TK_CONFIG` and `OOMMF_WISH` may be used to tell OOMMF where to find the Tk configuration file and the `wish` program, respectively.

Following the Tk information are some lines reporting ``thread'' build and run status. Threads are used by OOMMF to implement parallelism in the Oxs (`oxsii` and `boxsi`) 3D solvers on multi-processor/multi-core shared memory machines. In order to build or run a parallel version of OOMMF, you must have a thread-enabled version of Tcl. The Tcl thread status is indicated on the first thread status line. If Tcl is thread enabled, then the default OOMMF build process will create a threaded version of OOMMF. You can override this behavior if you wish to build a non-parallel version of OOMMF by editing the `oommf_threads` value in the `config/platforms/` file for your platform.

If Tcl and OOMMF threads are enabled, then the default number of threads run by the Oxs solvers is also reported. (This value may vary between machines, depending on the number of processors in the machine.) You can change this by setting (in order of increasing precedence) the `oommf_thread_count` value in the installation-wide `config/options` file, the `thread_count` value in the `config/platforms/` file for your platform, via the environment variable `OOMMF_THREADS`, or by the `oxsii`/`boxsi` command line option `-threads`.

By default, OOMMF sets no upper limit on the number of threads you may run in `oxsii` or `boxsi`. However, performance is degraded if you run more threads than available cpu cores. To protect against this, or to limit resource use on a shared machine, you may wish to set a hard limit on the maximum number of threads per `oxsii` or `boxsi` instance. This can be done by setting (in order of increasing precedence) the environment variable `OOMMF_THREADLIMIT`, the `thread_limit` value in the `config/platforms/` file for your platform, or the `oommf_thread_limit` value in the `config/options` file. (Note the precedence order is reversed compared to that for the default thread count.) If a limit is set then that value is displayed in the threads line of the `oommf.tcl +platform` output.

If NUMA support is provided on your platform (see below), then the following `oommf.tcl +platform` output line will indicate whether or not the build process will create NUMA-aware Oxs solvers.

After the thread and NUMA information, `oommf.tcl +platform` reports the directory that OOMMF will use to write temporary files. This directory is used, for example, to transfer magnetization data from the micromagnetic solvers to the mmDisp display module. You must have write access to this directory. It needs to have enough space to manage the dataflows of your simulations. It is also beneficial if this directory is local to the processors performing the calculations. If you don't like the OOMMF default, you may change it via the `path_directory_temporary` setting in the `config/platforms/` file for your platform. Or you can set the environment variable `OOMMF_TEMP`, which will override all other settings.

If any environment variables relevant to OOMMF are set, then `oommf.tcl +platform` will report these next, followed finally by any warnings about possible problems with your Tcl/Tk installation, such as if you are missing important header files.

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` find 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 on Unix or PATH on Windows). 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.

#### Additional Configuration Issues on Windows

A few other configurations should be checked on Windows platforms. First, note that absolute filenames 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 filename. 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 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 file which records that `localhost` is a synonym for the loopback interface (127.0.0.1). If a file 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` file exists, but a `hosts.sam` file exists, make a copy of `hosts.sam` with the name `hosts`, and edit the copy to have the `localhost` entry.

The directory that holds the `tclsh` and `wish` programs also holds several `*.dll` files that OOMMF software needs to find to run properly. Normally when the OOMMF bootstrap application or mmLaunch is used to launch OOMMF programs, they take care of making sure the necessary `*.dll` files 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` files needed when starting an executable.

###
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 configured. In particular, if you are running on a Windows system, please read carefully the notes in the Advanced Installation section pertaining to your compiler.

The compiling and linking of the C++ portions of OOMMF software are guided by the application pimake (``Platform Independent Make'') which is distributed as part of the OOMMF release. To begin building OOMMF software with `pimake`, first 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 files 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 files 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 configuration for your platform, `pimake` should be able to compile and link all the OOMMF software without error. If `pimake` reports errors, please first consult Troubleshooting to see if a fix 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.

### 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.

### Using OOMMF Software

To start using OOMMF software, run the OOMMF bootstrap application. 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 in a new window.

If you publish material created with the aid of OOMMF, please refer to Credits for citation information.

### Reporting Problems

If you encounter problems when installing or using OOMMF, please report them to the OOMMF developers. The `oommf.tcl +platform` command has been designed in large part to help OOMMF developers debug installation problems, so PLEASE be sure to include the complete output from `oommf.tcl +platform` in your report. See also the section on troubleshooting for additional instructions.

OOMMF Documentation Team
September 29, 2018