2.2.3 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 macOS 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/xerxes/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.