Advanced Installation
Keywords: userguide

Next: Platform Specific Installation Issues Up: Installation Previous: Basic Installation
Subsections

- Reducing Disk Space Usage
- Local Customizations
- Optimization
- Parallelization
- Managing OOMMF Platform Names
  - Changing the name OOMMF assigns to your platform
  - Adding a new platform type
  - Resolving platform name conflicts

##
Advanced Installation

The following sections provide instructions for some additional installation options.

###
Reducing Disk Space Usage

To delete the intermediate files created when building the OOMMF software from source code, use pimake to build the target `objclean` in the root directory of the OOMMF distribution.

    tclsh oommf.tcl pimake objclean

Running your platform `strip` utility on the OOMMF executable files should also reduce their size somewhat.

###
Local Customizations

OOMMF software supports local customization of some of its features. All OOMMF programs load the file `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 file `config/local/options.tcl`, if it exists. Because future OOMMF releases may overwrite the file `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 file `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 uses, and the choice of what program is used for the display of help documentation. By default, OOMMF software uses the application mmHelp, which is included in the OOMMF release, but the help documentation files are standard HTML, so any web browser may be used instead. Complete instructions are in the file `config/options.tcl`.

###
Optimization

In the interest of successful compilation of a usable software package ``out of the box,'' the default configuration for OOMMF does not attempt to achieve much in terms of optimization. However, in each platform's configuration file (for example, `config/platforms/wintel.tcl`), there are alternative values for the configuration's optimization flags, available as comments. If you are familiar with your compiler's command line options, you may experiment with other choices as well. You can edit the platform configuration file to replace the default selection with another choice that provides better computing performance. For example, in `config/platforms/wintel.tcl`, alternative optimization flags for the MSVC++ compiler may be invoked by editing how the configuration variable `opts` is defined, following instructions in the comments.

The extensible solver, Oxs, can be compiled with debugging support for extensive run-time code checks. This will significantly 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 file `config/options.tcl`:

    Oc_Option Add * Platform cflags {-def NDEBUG}

To enable these checks, either comment/remove this line, or else add to the `config/local/options.tcl` file a ``cflags'' option line without ``-def NDEBUG'', such as

    Oc_Option Add * Platform cflags {-warn 1}

The `config/local/options.tcl` file may be created if it does not already exist.

###
Parallelization

The OOMMF Oxs 3D solvers (`oxsii` and `boxsi`) can be built thread-enabled to allow parallel processing on multi-processor/multi-core machines. In order to build and run a parallel version of OOMMF, you must have a thread-enabled version of Tcl. Most standard binary releases of Tcl today are thread-enabled, so OOMMF releases that include pre-built executables are built thread-enabled. If you build OOMMF from source, then by default OOMMF will be built thread-enabled if your Tcl is thread-enabled. As explained earlier, you can check thread build status with the `tclsh oommf.tcl +platform` command. If you want to force a non-threaded build of OOMMF, then edit the `config/platforms/` file for your platform. In the section labeled `LOCAL CONFIGURATION`, you will find a line that looks like

    # $config SetValue oommf_threads 0

Uncomment this line (i.e., remove the leading ``#`' character) to force a non-threaded build. Then run

    tclsh oommf.tcl pimake distclean
    tclsh oommf.tcl pimake

from the OOMMF root directory to create a fresh build.

You can use the `tclsh oommf.tcl +platform` command to see the default number of compute threads that will be run by the Oxs 3D solver programs `oxsii` and `boxsi`. You can modify the default as explained in the Check You Platform Configuration section, or you can override the default at run time via the command line option `-threads` to `oxsii` and `boxsi`.

Some multi-processor machines have a non-uniform memory architecture (NUMA), which means that although each processor can access all of system memory, some parts of memory can be accessed faster than others. Typically this is accomplished by dividing the system memory and processors into ``nodes.'' Memory accesses within a node are faster than accesses between nodes, and depending on the architecture access latency and bandwidth may be different between different node pairs. Examples of machines with NUMA include some multi-processor AMD Opteron and Intel Xeon boxes.

Computer programs such as OOMMF can run on NUMA machines without making any special allowances for the memory architecture. However, a program that is written to take advantage of the faster local (intra-node) memory accesses can sometimes run significantly faster. OOMMF contains NUMA-aware code, but this code is highly operating system specific. At present, OOMMF can be built with NUMA support only on Linux (32- and 64-bit) systems. To do this, you must install the operating system NUMA support packages ``numactl'' and ``numactl-devel''. The names may vary somewhat between Linux distributions, but the first typically includes the executable `numactl` and the second includes the header file `numa.h`. Once the numactl package is installed, you can run the command

    numactl --hardware

to get an overview of the memory architecture on your machine. If this shows you have only one node, then there is no advantage to making a NUMA-aware build of OOMMF.

The next step is to edit the `config/platforms` for your platform. For example, on a 64-bit Linux box this file is `config/platforms/linux-x86_64.tcl`. In the section labeled `LOCAL CONFIGURATION`, find the line

    # $config SetValue use_numa 1

Edit this to remove the leading ``#`' character. Alternatively (and, actually, preferably), create a `local` subdirectory and make a local configuration file with the same platform name; e.g., `config/platforms/local/linux-x86_64.tcl` on a 64-bit Linux machine. Add the line

    $config SetValue use_numa 1

to this file. (The advantage of using a `config/platforms/local` file is that you can make changes without modifying the original OOMMF source code, which makes it easier to port your local changes to future releases of OOMMF.) If this is done correctly, then the command ``tclsh oommf.tcl +platform`' will show that NUMA support is enabled. Then simply run ``tclsh oommf.tcl pimake distclean`' and ``tclsh oommf.tcl pimake`' from the OOMMF root directory to build a NUMA-aware version of OOMMF.

To activate the NUMA-aware code, you must specify the `-numanodes` option on the `oxsii`/`boxsi` command line, or set the the environment variable `OOMMF_NUMANODES`. Check the Oxs documention for details.

###
Managing OOMMF Platform Names

OOMMF software classifies computing platforms into different 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 configuration files so that a single OOMMF installation may contain platform-dependent sections for many different 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 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 file

> `config/names/foo.tcl` to `config/names/bar.tcl`

and

> `config/platforms/foo.tcl` to `config/platforms/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 OOMMF's vocabulary of platform names, create the file `config/names/foo.tcl`. The simplest way to proceed is to copy an existing file in the directory `config/names` and edit it to recognize your platform.

The files in `config/names` include Tcl code like this:

      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 file `config/names/foo.tcl`, you also need to create a new platform file `config/platforms/foo.tcl`. A reasonable starting point is to copy the file `config/platforms/unknown.tcl` for editing. Contact the OOMMF developers for assistance.

Please consider contributing your new platform recognition and configuration files to the OOMMF developers for inclusion in future releases of OOMMF software.

#### Resolving platform name conflicts

If the script `oommf.tcl +platform` reports ``Multiple platform names are compatible with your computer'', then there are multiple files in the directory `config/names/` that return 1 when run on your computer. For each compatible platform name reported, edit the corresponding file 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 machine's 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.

OOMMF Documentation Team
September 29, 2018