readme

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

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

This is XMDS: eXtensible Multi Dimensional Simulator; an open source
numerical simulation package that integrates equations. You write them
down in human readable form in an XML file, and it goes away and
writes and compiles a C++ program that integrates those equations as
fast as it can possibly be done in your architecture.

INSTALLATION
------------

See the file `INSTALL' in the current directory.  Supplimentary to
that information (which is the generic GNU stuff at this stage) one
can use the following switches to customise the installation at the
configuration step (i.e. when you run ./configure):

--with-user 	
        This option installs xmds, xsil2graphics and xmdscomplex.h
        into $HOME/bin (by default the configure script installs into
        /usr/local (or /usr depending upon your system)

--with-fftw-path=<base path to fftw>
        This option tells the configure script to look elsewhere than
        /usr/include and /usr/lib or for the relevant fftw files.
        e.g. --with-fftw-path=/usr/local

--enable-mpi
        This option has no arguments and must be set if you wish to
        use mpi.

--with-mpi-path=<base path to mpi installation>
        This option tells configure to look elsewhere other than
        /usr/include and /usr/lib for the relevant mpi files.

--with-mpi-libs=<mpi libraries>
        This option tells the configure script the extra libraries
        that may be needed to properly check for MPI on your system.
        e.g. --with-mpi-libs=-llam (if you have the LAM implementation
        of MPI)

--with-mpi-compiler=<mpi compiler name>
        This option sets the mpi compiler to whatever you have on your
        system.  For example, on some systems the mpi compiler isn't
        mpicc it is cxx, so in this case you would use
        --with-mpi-compiler=cxx to tell configure the correct compiler
        to use.

This information (and more) is also supplied when one asks the
configure script for help; i.e. when you run the command:

bash$ ./configure --help

Other ways to alter the configuration (place these options on the
command line BEFORE ./configure, e.g. CC=gcc ./configure):

CC=<C compiler>  
	Defines the C compiler to use for compilation of xmds itself.
	Examples: CC=gcc or CC=icc (Intel C/C++ compiler)

CXX=<C++ compiler> 
	Defines the C++ compiler to use for compilation of xmds.
	Examples: CXX=g++ or CXX=icc (Intel C/C++ compiler)

XMDS_CC=<C/C++ compiler> 
	Defines the C/C++ compiler to use for compilation of xmds
	simulations.  It is better to use a C++ compiler here than a C
	compiler with C++ extensions.
	Examples: XMDS_CC=g++ or XMDS_CC=cxx

XMDS_CFLAGS=<C/C++ compiler flags>
	Defines the C/C++ compiler flags to use for the compilation of xmds
	simulations.
	Examples: XMDS_CFLAGS="-O2" or XMDS_CFLAGS="-O3 -funroll-all-loops"

MAN PAGES
---------

The manual (man pages) for xmds, xsil2graphics and loadxsil.m are
installed with xmds during the 'make install' process.  If you have
installed xmds in a non-standard location, or in your home directory,
and you want to view the man pages with the 'man' command, you will
need to append the relevant path to your MANPATH environment
variable.  For example, if you have installed xmds in your home
directory, the man pages will be located in $HOME/man/.  You
therefore need to run the following command (assuming your shell is
bash): 

bash$ export MANPATH=${MANPATH}:${HOME}/man

You will now be able to use the command:

bash$ man xmds

to view the xmds manual page.

TRY IT OUT!
-----------

Try out the nlse.xmds example in the examples/ directory. Type:

.../xmds-1.3-5> cd examples
.../xmds-1.3-5/examples> xmds nlse.xmds

This makes an executable file called nlse, which includes all the
high-level simulation data in nlse.xmds, in the form of an executable,
compiled C++ program. All you have to do is run the code to get the
results of your simulation:

.../xmds-1.3-5/examples> nlse

The output is in the file nlse.xsil, in scientific interchange xml
format. There is a utilitly installed to convert this into other
formats for plotting:

.../xmds-1.3-5/examples> xsil2graphics nlse.xsil

once in matlab, type:

>>nlse
>>mesh(t_1,z_1,pow_dens_1')

 OR

.../xmds-1.3-5/examples> xsil2graphics --scilab nlse.xsil

and once in scilab, type:

>>exec('nlse.sci')
>>plot3d(t_1,z_1,pow_dens_1)