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 three formats. The first format is a gzipped tar file
containing an archive of all the OOMMF source code. The second and
third formats
are .zip compressed archives containing source code and
pre-compiled executables for Windows. They contain 64-bit and
32-bit executables repectively. 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 oommf12b0.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 oommf12b0_86_x64.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.

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.19, 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.6.

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 CentOS 7 Linux system:

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 linux-x86_64. 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/linux-x86_64.tcl.
Editing instructions are contained within the file. On other platforms
the name linux-x86_64 in config/platforms/linux-x86_64.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 via other means, 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.

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.

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