readme.windows

XMDS is a code generator that integrates equations. You write them down in human readable form in a

# $Id: README.Windows,v 1.6 2004/07/19 03:52:54 paultcochrane Exp $

This document is the Readme file for installing Octave
(http://www.octave.org) on Windows using the Cygwin
(http://www.cygwin.com) environment, altered to be specific for
installation of xmds.  

Orinally written by:
John W. Eaton
[e-mail]
University of Wisconsin-Madison
Department of Chemical Engineering
Wed Apr 30 17:15:32 2003

Modified by:
Paul T. Cochrane
[e-mail]
Department of Physics
University of Queensland
Australia
Mon Jul 19 13:44:42 EST 2004

----------------------------------------------------------------------

The following is my current best set of directions for building xmds
from sources on a Windows system using the Cygwin tools.  If you
already have Cygwin installed, you may need to update your
installation of tools to include those mentioned below.

Following these steps should give you a properly working xmds
installation.


 1. Use your favorite browser to view the page http://www.cygwin.com

 2. Click on the "Install or update now" link.

 3. A dialog should appear with the option to run the setup program
    from its current location or save it to disk.  Either will work,
    but I usually choose to save the setup program to disk so that it
    is possible to run it later to update the installation without
    having to go back to the web page using a browser.

 4. Run the setup program.

 5. Choose "Install from Internet".

 6. Select a root install directory.  You may choose any directory, but
    it needs to have about 600MB available to install all the
    necessary Cygwin tools plus build and install xmds from sources.
    That may seem like a large disk space requirement, but remember
    that you are getting more than just xmds, you are installing a
    Unix-like development environment including C, C++, and Fortran
    compilers as well.

    You may choose to install for just you or all users (if you have
    permission to do so).  I would select "Unix" as the default text
    file type (this option should be the default).

 7. Select a local package directory.  This is a directory that the
    setup program will use to temporarily store package files before
    installing them.  It should have plenty of space (probably 70MB
    or more).  You may delete this directory once the installation is
    complete.

 8. Select your Internet Connection.  Probably "Direct Connection" is
    OK unless you are behind a firewall of some kind that limits your
    access to the Internet.

 9. Choose a download site.  One that is "near" you on the net is
    probably best.

10. Select packages.  The defaults are not enough to build all of
    Octave from sources.  In addition to the default set of packages,
    you should select the following packages from the following
    categories:

      Archive: unzip
      Devel:   autoconf, binutils, bison, cvs, dejagnu, flex, gcc,
               gperf, make
      Text:    less, tetex, tetex-base
      Utils:   diff, patch

    Once you have made these selections, click the Next button to
    download and install all the selected packages.  The download and
    install may take a while depending on the speed of your computer
    and your connection to the net.

11. Once the download and file installation is done, click Finish.  I
    usually choose to create an icon on the desktop and put an icon in
    the start menu.  After you click finish, a series of scripts will
    run, displaying some output in a terminal window.  It will take a
    few minutes.

12. Now grab and install fftw; this is necessary for the installation
    of xmds.  Make sure you get fftw version 2.1.5 (and NOT version 3
    or above) from http://www.fftw.org.  

    a. Put the tar.gz file into somewhere like /var/tmp (within
       Cygwin)

    b. Unpack the source files using the command (assuming that you
       downloaded fftw version 2.1.5):

         tar -xvzf fftw-2.1.5.tar.gz

    c. Change into the fftw directory and run the configure script

       cd fftw-2.1.5
       ./configure

    d. Then run make and install the package by going:
    
       make
       make install

    This should have put the fftw libraries and header files under the
    /usr/local are within your Cygwin environment.  Have a check by
    using the command:

       ls /usr/local/lib/libfftw* /usr/local/include/fftw*

13. Get the xmds sources, either from a current
    distribution or from CVS:

    Distribution:

      a. Download a copy of the current version of xmds from
         http://www.xmds.org.  You are looking for the most recent
         version under the Downloads link from the main page.  At the
         time of this writing, it was xmds-1.3-5.tar.gz.  Save this
         file to your Cygwin home directory.  This directory will
         usually be called something like c:\cygwin\home\cochrane from
         Windows (the precise location depends on where you chose to
         install Cygwin).

      b. Unpack the source files using the command:

           tar zxf xmds-1.3-5.tar.gz

         in the Cygwin shell.  This command will create a subdirectory
         called xmds-1.3-5 in your home directory.

      c. Change your current working directory to the top-level xmds
         source directory:

           cd xmds-1.3-5

         then continue with step 14 below.

    CVS:

      a. Check out a copy of the current sources from the public CVS
         archive by running the following commands
	 
	   cvs -d:pserver:[e-mail]:/cvsroot/xmds login
	   cvs -z3 -d:pserver:[e-mail]:/cvsroot/xmds co xmds-devel

         in the Cygwin shell.  The first command will prompt you for a
         password, just hit return/enter.  The checkout command will
         create a subdirectory called xmds-devel containing the current
         CVS version of the xmds development sources.

      b. Change your current working directory to the top-level xmds
         source directory:

           cd xmds-devel

      c. Build the configure scripts by running the commands

           aclocal
	   automake
	   autoconf
	   autoheader

         then continue with step 14 below.


14. Configure xmds by running the command

      ./configure --with-fftw-path=/usr/local

    This command will take several minutes to run as the configure
    script determines what features are available on your system.
    You will possibly need to add the flag --with-fftw-path=/usr/local
    to the configure command (if your fftw libraries and headers are
    based from /usr/local that is) as the configure script doesn't
    always check in /usr/local (it does on some systems, but not on
    all) and consequently it won't find fftw.h, libfftw.a and
    friends.  Have a look at the README file for xmds and/or go
    ./configure --help for a more complete list of options.

15. Build the xmds binary by running the command

      make

16. Complete the installation by running the command

      make install

17. Try running xmds by changing into the examples directory
    
      cd examples

    And then running the nlse.xmds script:

      xmds nlse.xmds

    This will run xmds and hopefully compile the output simulation.
    Run the simulation by merely going:
    
      nlse

    This will produce an output file called nlse.xsil which can be
    converted to something usable by either scilab or matlab using the
    xsil2graphics command (also built and installed along with xmds).
    This command is used as follows:
    
      xsil2graphics nlse.xsil

    This will produce an output file called nlse.m and a data file
    called nlse1.dat.  Start matlab and execute the command nlse at
    the matlab prompt to load the variables into matlab, and then you
    can use your favourite set of plotting commands to view the
    output.

    If you have scilab you need to type instead:

      xsil2graphics --scilab nlse.xsil

    This will produce a file called nlse.sci, which can be used inside
    scilab with the command

      exec('nlse.sci')

18. If that's all worked, then congratulations!  You've got a working
    xmds installation.