Follow the instructions in the following sections, in order, to prepare OOMMF software for use on your computer.
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 Microsoft Windows 95/98/NT running on an x86-based microprocessor system. Each Windows binary distribution is compatible with only a particular sequence of releases of Tcl/Tk. We release one Windows binary distribution compatible with Tcl/Tk 8.0.x, one Windows binary distribution compatible with Tcl/Tk 8.2.x, and one Windows binary distribution compatible with Tcl/Tk 8.3.x. Other release formats, e.g., pre-compiled executables for Microsoft Windows NT running on a Digital Alpha Systems RISC-based microprocessor system, and/or compatible with Tcl/Tk version 7.6/4.2 or Tcl/Tk 8.1.x. may be made available on request.
For the first format, unpack the distribution archive using gunzip and tar:
gunzip -c oommf10b3_20000224.tar.gz | tar xvf -
For the other format(s), you will need a utility program to unpack the .zip archive. This program must preserve the directory structure of the files in the archive, and it must be able to generate files with names not limited to the traditional MSDOS 8.3 format. Some very old versions of the pkzip utility do not have these properties. One utility program which is known to work is UnZip. Using your utility, unpack the .zip archive, e.g.
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.
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 the MS-DOS Prompt on Microsoft 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 platform.tcl. 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 from platform.tcl on a Linux/Alpha system:
$ tclsh platform.tcl <24537> platform info: OOMMF release 188.8.131.52 Platform Name: linalp C++ compiler: /usr/bin/gcc Tcl configuration file: /usr/local/lib/tclConfig.sh tclsh: /usr/local/bin/tclsh8.3 Tcl release: 8.3.0 (config) 8.3.0 (running) Tk configuration file: /usr/local/lib/tkConfig.sh wish: /usr/local/bin/wish8.3 Tk release: 8.3.0 (config) 8.3.0 (running)
If platform.tcl doesn't print a summary like that, it should instead print an error message describing why it can't. For example, if your Tcl installation is older than release 7.5, the error message will report that fact. Follow whatever instructions are provided to get platform.tcl to print a summary of platform configuration information.
The first line of the example summary reports that OOMMF recognizes the platform by the name linalp. OOMMF software recognizes many of the most 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 platform.tcl 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 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. The compiler selection for the example above is recorded in the file config/cache/linalp.tcl. To change the compiler selection, that file must be edited. Editing instructions are contained within the file. Of course, on other platforms the name linalp in linalp.tcl should be replaced with the platform name OOMMF reports for your platform. For example, on a Windows machine using an x86 processor, the corresponding configuration file is wintel.tcl.
The next three lines describe the Tcl configuration OOMMF finds on your platform. The first line reports 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 platform.tcl report ``none found''. If platform.tcl 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 location. (For information about setting environment variables, see your operating system documentation.) 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 edit that file to include a correct description of your Tcl installation.
The second line describing your Tcl installation reports the absolute pathname of the tclsh program. If this differs from the tclsh you used to evaluate platform.tcl, there may be something wrong with your Tcl configuration file. Note that the same tclsh program might be known by several absolute pathnames if there are symbolic links in your Tcl installation. If platform.tcl reports that it cannot find a tclsh program, yet you know where an appropriate one is installed on your system, you can tell OOMMF where to find the tclsh program by setting the environment variable OOMMF_TCLSH to its absolute location.
The third line describing your Tcl installation reports its release number according to two sources. First is the release number recorded in the Tcl configuration file. Second is the release number of the tclsh program used to evaluate platform.tcl. If these numbers do not match, it may indicate something is wrong with your Tcl configuration file. If you have multiple releases of Tcl installed under a common root directory on your computer, there can be only one Tcl configuration file. It is important that you use the Tcl release that corresponds to the Tcl configuration file.
The next three lines describe the Tk configuration OOMMF finds on your platform. They are analogous to the three lines describing the Tcl 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.
If platform.tcl 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). 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.
If you plan to compile and link OOMMF software from source code, be sure the C++ compiler reported by platform.tcl is properly configured. In particular, the Microsoft Visual C++ command line compiler, cl.exe, may require the running of vcvars32.bat to set up the path and some environment variables. This file is distributed as part of Visual C++. See your compiler documentation for details.
A few other configurations should be checked on Windows platforms.
First, 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:
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.
Second, in recent releases of Tcl/Tk (version 8.0.3 and later) the directory which 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.
If you downloaded a distribution with pre-compiled executables, you may skip this section.
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 (in the directory app/pimake/). pimake is similar in operation to the Unix utility program make, but it is written entirely in Tcl so that it will run anywhere Tcl is installed. Just as make is controlled by rules in files named Makefile or makefile, pimake is controlled by rules in files named makerules.tcl. pimake takes an optional argument on its command line which names the target to build.
If a previous OOMMF distribution has been compiled and linked from the same root directory, build the target distclean with pimake to clear away any executables and object files left behind from the compilation of the previous distribution:
tclsh app/pimake/pimake.tcl distcleanIn particular, this is required when installing a new version of OOMMF on top of an existing OOMMF distribution.
To build all the OOMMF software, run pimake in the root directory of the OOMMF distribution.
tclsh app/pimake/pimake.tclNote that 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 send both the complete output from pimake and the output from platform.tcl to the OOMMF developers.
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.
To start using OOMMF software, run the OOMMF bootstrap application. This may be launched from the command line interface:
If you prefer, you may launch the OOMMF bootstrap application app/oommf/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.
The OOMMF developers rely on reports from OOMMF users to alert them to problems with the software and its documentation, and to guide the selection and implementation of new features. To contact the OOMMF developers, send e-mail to <firstname.lastname@example.org>.
The more complete your report, the fewer followup messages will be required to determine the cause of your problem. Usually when a problem arises there is an error message produced by the OOMMF software. A stack trace may be offered that reveals more detail about the error. When reporting an error, it will help the developers diagnose the problem if users cut and paste into their problem report the error message and stack trace exactly as reported by OOMMF software. In addition, please include a copy of the output generated by platform.tcl so that the OOMMF developers will know the details of your platform configuration.