README

// -*- text -*-

Congratulations!  You are reading the README file for a software
package you downloaded!  You are now officially an *advanced* software
installer.

This is the README file for OOF3D, describing how to build and install
it with the Python distutils utility.

This README file is for OOF3D version 3.2.0 or later.

Disclaimer:
----------

This software provided is provided by NIST as a public service. You
may use, copy and distribute copies of the software in any medium,
provided that you keep intact this entire notice. You may improve,
modify and create derivative works of the software or any portion of
the software, and you may copy and distribute such modifications or
works. Modified works should carry a notice stating that you changed
the software and should note the date and nature of any such
change. Please explicitly acknowledge the National Institute of
Standards and Technology as the source of the software.  To facilitate
maintenance we ask that before distributing modified versions of this
software, you first contact the authors at oof_manager@nist.gov.

The software is expressly provided "AS IS". NIST MAKES NO WARRANTY OF
ANY KIND, EXPRESS, IMPLIED, IN FACT OR ARISING BY OPERATION OF LAW,
INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTY OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT
AND DATA ACCURACY. NIST NEITHER REPRESENTS NOR WARRANTS THAT THE
OPERATION OF THE SOFTWARE WILL BE UNINTERRUPTED OR ERROR-FREE, OR THAT
ANY DEFECTS WILL BE CORRECTED. NIST DOES NOT WARRANT OR MAKE ANY
REPRESENTATIONS REGARDING THE USE OF THE SOFTWARE OR THE RESULTS
THEREOF, INCLUDING BUT NOT LIMITED TO THE CORRECTNESS, ACCURACY,
RELIABILITY, OR USEFULNESS OF THE SOFTWARE.

You are solely responsible for determining the appropriateness of
using and distributing the software and you assume all risks
associated with its use, including but not limited to the risks and
costs of program errors, compliance with applicable laws, damage to or
loss of data, programs or equipment, and the unavailability or
interruption of operation. This software is not intended to be used in
any situation where a failure could cause risk of injury or damage to
property. The software was developed by NIST employees. NIST employee
contributions are not subject to copyright protection within the
United States.

Installation:
------------

Installation is similar to other Python libraries.  If your system is
well-set-up, and has the required libraries, there should be no
difficulties.

The executive summary of steps is:

> tar -xzf oof3d-<version>.tar.gz
> cd oof3d-<version>
> python setup.py build --3D
> python setup.py install --3D

but please read the rest of this file before proceeding.

If something goes wrong, your system adminstrator may be able to help
you, or you can contact the oof developers at oof_manager@nist.gov.
It's diagnostically useful to include all the output from setup.py.

OOF3D has been built and tested on Linux and Macintosh OS X.  OOF3D
does *not* work on Microsoft Windows, but should work within a Linux
virtual machine on Windows.

Details:
-------

0. What You Should Already Have:

   A computer running a variant of the Unix operating system,
   including Linux and macOS (Macintosh OS X).

   A C++ compiler.
   
   The following external programs and libraries and the header files
   ("includes") associated with these programs and libraries.  These
   are usually available as part of a "development" version of the
   library software.

    Python (2.6 or 2.7)      http://www.python.org 
    gtk+-2.0 (2.6 or later)  http://www.gtk.org/download/   
    pygtk2 (2.6 or later)    http://www.pygtk.org
    vtk	(8.1.1 or later)     http://www.vtk.org

   Please note that the words "or later" do not include later major
   versions.  OOF3D will not work with Python 3.x or gtk+ 3.x. 

   Linux users should already have an X11 server.  Macintosh users can
   build OOF3D either to use X11 or native Mac graphics.
   
   You should also have the ability to run lapack and the blas basic
   linear algebra subroutines.  On Macintosh OS X, they are built in
   to the Accelerate framework in the OS, and no special libraries are
   required.  On Linux and commercial Unix systems, they may have to
   be installed, and you may require headers (sometimes provided as
   part of a "-dev" package).

   Detailed instructions for installing the OOF3D prerequisites on a
   number of different operating systems can be found at
   http://www.ctcms.nist.gov/oof/oof3d/prerequisites.html.

1. What You Got From Us:
   
   The file "oof3d-<version>.tar.gz".


Procedure:
---------

   (Macintosh OS X users can install OOF2 from either a Terminal or
   xterm window, or the equivalent.)

0. Unpack

   Unpack the .tar.gz file.  The usual way is to run "tar -xf" on the
   file you want to unpack.  This will create a subdirectory named
   "oof2-<version>" in the directory where you run tar.

1. Build the OOF2 libraries and Python extension modules

   Switch to the newly-created directory, and run

     % python setup.py build --3D

   Macintosh users who prefer not to use X11 should add "--cocoa" to
   the command line ("cocoa" being the name of the Apple GUI API).
   Because we've been having trouble getting VTK to work properly with
   X11 on recent Mac operating systems, using cocoa is recommended:

     % python setup.py build --3D --cocoa

   The build command will create a "build" subdirectory in the top
   OOF2 directory.  Within "build" it will create subdirectories with
   system-dependent names.

   There are three options to the build command that are special to
   OOF3D and aren't discussed with the generic build options below.

   (a) --3D must be provided.

   (b) If your vtk installation isn't in a standard location, you will
   need to add --vtkdir=<vtkprefix> to the command line, replacing
   <vtkprefix> with the base of the directory tree containing vtk.
   For example, if the vtk files are located in
   /usr/unusual/include/vtk-8.1.1 and /usr/unusual/lib, then
   you'd build OOF3D this way:

     % python setup.py build --3D --vtkdir=/usr/unusual

   (c) As mentioned above, --cocoa must be provided to build a macOS
   version that uses native Mac graphics instead of X11.

1.1 Getting more control over the build

   You can ignore this section unless something went wrong when
   building OOF2 in step 1.  setup.py tries to be intelligent about
   choosing options, but it's not perfect.

   The distutils "build" command actually runs a bunch of separate
   subcommands, each of which has its own options.  The relevant
   subcommands are "build_shlib", "build_ext", "build_scripts", and
   "build_py".  "build_shlib" builds the shared libraries,
   liboof3dcommon.so, etc, that contain most of the low-level OOF3D
   machinery. "build_ext" builds the OOF3D Python extension modules
   that provide the interface betweeen C++ and Python.  "build_py"
   copies the Python files from the source directory to the build
   directory, and "build_scripts" copies the start-up script into the
   build directory and makes it executable.  OOF2 installers will
   probably only have to worry about "build_shlib" and "build_ext".

   The four commands must be run in order: build_shlib must precede
   build_ext, and build_ext must precede build_py.

   Each command can be run separately, for example

     % python setup.py build_ext --3D

   or in combination

     % python setup.py build_shlib build_ext --3D

   and options can be provided to each one
  
    % python setup.py build_shlib --debug build_ext --include_dirs=/sw/include

   You can see the full set of options by running

     % python setup.py --help <command name>

   (except that this *doesn't* include the all-important --3D option!).
   Here are the options most likely to be useful:

   For "build_shlib" or "build":

   --library-dirs    Specify a non-standard location for libraries.
                     Multiple directories should be separated by
                     colons, like this:
                       --library-dirs=/strange/spot:/out/of/theway

   --libraries       Specify libraries to load. Due to a bug in
                     distutils, it's only possible to specify a single
                     library. For example
                        --libraries=abc
		     will load libabc.so.  If you need to load more
                     than one library in this way, please contact us.
      
   --blas-libraries  Specify libraries to use for blas and lapack.
                     Multiple library names should be separated by
                     spaces, like this:
                        --blas-libraries="myblas mylapack"

   --blas-link-args  Specify additional link arguments required by
                     blas and lapack, for example:
		        --blas-link-args="-faltivec -framework vecLib"

   For "build_ext" or "build":

   --with-swig       Specify the name of the swig executable.  Swig is
                     a tool that generates the code that allows
                     communication between python and C++.  OOF3D 
                     ships with a modified copy of swig, because we
                     rely on an old version (swig 1.1 build 883, to be
                     precise).  If you have another version of swig
                     that you'd like to use, you can name it here,
                     like this:
                        pyton setup.py build --with-swig=myswig
                     Be advised that it probably won't work with the OOF3D
                     source code. 

   --swig, --swig-cpp, --swig-opts
                     Do NOT use these options.  They will be ignored.
                     They're leftover from the raw distutils swigging
                     mechanism, which we don't use.

   The following arguments can appear anywhere after "setup.py" in the
   command line, and apply to both the build and install steps.  Tf
   you run the build and install steps separately, you must provide
   these arguments in *both* steps if you provide them in one.

   --disable-gui     Don't include any components of the graphical user
                     interface.  When this option is used, it's not
                     necessary to have the gtk, pygtk, or
                     libgnomecanvas libraries installed.

2. Install

   To install OOF3D, run

   % python setup.py install --3D

   This will install OOF3D in the standard location for Python
   extensions on your system.  This is good, because then you won't
   have to do anything special to get OOF3D to run.  It's also bad,
   because unless you are the system administrator, you probably don't
   have permission to install anything in that directory.  You have
   two options:

    a) Get a system administrator to run the installation step.

    b) Tell distutils to install oof3D in a different place, like this:

          % python setup.py install --3D --prefix=<prefix>

    where <prefix> is a directory that you can write to, such as your
    home directory.  

    The installation procedure will create an executable script called
    "oof3d" in <prefix>/bin, a bunch of shared libraries called
    "liboof3d*.so" or "liboof3d*.dylib" in <prefix>/lib, a directory
    called "oof3d" in <prefix>/lib/python2.x/site-packages (where 2.x
    is your python version number), and some example files in
    <prefix>/share/oof3d/examples.  The default value of <prefix>, if
    you haven't used --prefix, is usually /usr/local.  On OS X it may
    be something like /Library/Frameworks/Python.framework/Versions/2.7
    if you're using the system Python, or something in /sw or
    /opt/local if you're using fink or macports.

    (It's possible to use --home=<home> instead of --prefix when
    installing oof3d.  The only difference is that --home will put the
    python libraries in <home>/lib/python instead of
    <prefix>/lib/python2.x/site-packages.)

2.1. Set environment variables

    If <prefix>/bin is not in your Unix command path, you'll need to
    add it to the PATH environment variable, or create a symbolic link
    from a directory that is in your path (or start OOF2 the hard way
    by by typing <prefix>/bin/oof3d).  (Typing "echo $PATH" will print
    the current value of your path.  The method for setting
    environment variables depends on which Unix shell you're using.)

    If <prefix>/lib is not in the list of directories that the dynamic
    linker searches for libraries, you'll have to add it by setting
    the LD_LIBRARY_PATH environment variable.  Setting LD_LIBRARY_PATH
    is not necessary on Macintosh OS X.

    If <prefix>/lib/python2.x/site-packages is not in your Python
    path, you'll have to add it to the PYTHONPATH environment
    variable.   (Running the command
       % python -c "import sys; print sys.path"
    will print your Python path.)

    If you're using the common "bash" shell, you can set environment
    variables by putting the following lines in a file called .profile
    in your home directory:

     export PATH=<prefix>/bin:$PATH
     export PYTHONPATH=<prefix>/lib/python2.<x>/site-packages:$PYTHONPATH 
     export LD_LIBRARY_PATH=<prefix>/lib:$LD_LIBRARY_PATH

    replacing <prefix> and python2.<x> with the appropriate values.
    To find out if you're using the bash shell, type "echo $SHELL" in
    a terminal window.  If it replies "/bin/bash", you're using bash.

    Setting environment variables in .profile doesn't actually change
    their values in your current terminal session.  To start using the
    new values, you will need to open a new terminal window.


Running OOF3D:
------------

At this point, you should have an executable file named "oof3d" in a
bin directory in your execution path.  You can now simply type "oof3d"
at your shell prompt, and OOF3D will start up.

OOF3D also has many options, and you can get a summary of them by typing
"oof3d --help".

Most of the OOF2 manual also applies to OOF3D.  The manual can be found at

  http://www.ctcms.nist.gov/~langer/oof2man/

The OOF3D web page includes a summary of differences between OOF2 and
OOF3D.  Be sure to go through the tutorials provided in the OOF3D help
menu.


Bugs:
----------

If you encounter bugs in the program, please use the OOF error
reporting tool, which can be accessed via the "Report" button on the
OOF3D error dialog, or the "Report Error" item in the "Help" menu.
This will create a file which you can e-mail to oof_bugs@nist.gov.  If
the file is too large for e-mail, send a message to oof_bugs@nist.gov
and we can arrange another way to transfer the file.

If for some reason you can't use the error reporting tool, please send
e-mail to oof_bugs@nist.gov including what version of OOF3D you're
using, what operating system you're using, and *exactly* what you did
to encounter the error.  It is helpful to include an OOF3D script
(which you can save with the "File/Save/Python Log" menu item) and a
copy of any input files (images, oof data files, etc) required to run
the script.  It is extremely difficult for us to fix a bug if we can't
reproduce it ourselves.

Contact Us: 
---------

Other communications, including requests for help and suggestions for
new features, can be sent to oof_manager@nist.gov.