====================================================
Instructions for installing Plex (Version 2.5)
====================================================

Plex is written by Patrick Perry and Vin de Silva, with the support of
various grants held by Gunnar Carlsson at Stanford University. The
original version (and the interface) was written by Vin de Silva in
MATLAB. The present version is based on a C++ library by Patrick Perry,
called 'scomplex' and included with this distribution; the front end looks
the same as before. Most of the heavy coding is by Patrick, and most of
the scripts are by Vin.

Included with Plex is the excellent and important persistent homology code
by Afra Zomorodian and Lutz Kettner. This is available as part of
CGAL. From some points of view, Plex can be viewed and used simply as a
MATLAB front-end to that library. We thank both of those authors, and
especially Afra Zomorodian for cooperating well beyond the call of duty in
helping to bolt together the two libraries.

In making this code available, we nonetheless reserve all legal rights, on
our behalf and on behalf of the other authors and interested parties.

As well as the core library, whose purpose is to enable a MATLAB user to
build and manipulate simplicial complexes, there is a "metric data"
toolbox, which includes various bits of code for converting point-cloud
data sets into simplicial complexes and filtered simplicial complexes.

Comments and bug reports are welcome. We have found Plex to be very useful
in practice, but we've spent a lot of time figuring out how to take
advantage of MATLAB to use it well. It is definitely true that it's not
quite as user-obvious as we'd like it to be. Perhaps we should include
some sample scripts; suggestions on what those should be are welcome.

Installation instructions follow. These may not be quite correct, so
please let me know and I'll make changes.

To get documentation for using Plex, begin with the lines:

>> help Plex

and

>> help Plex/metric

There is extensive help text for each function. At this point there is no
separate manual for Plex.

[VdS: 2006-Jul-14]

---------------------------------------------------------------------------
Installation (for Linux or Mac OS X):

(64-bit machines should also work with some modification, but I don't know
exactly what that is; will as Patrick.)

(1) Download the archive file plex-beta.tar.gz
(2) Expand the archive:

      > tar xzvf plex-2.5.tar.gz

    This creates a directory called plex.

(3) Create a new directory for the installation. For example:

      > mkdir $HOME/matlab/PlexHome

    Determine the full pathname of this chosen directory. For instance

      > echo $HOME/matlab/PlexHome
      /Users/vin/matlab/PlexHome

    will return the full path, if you are not sure where your home
    directory is located. We will write (PLEXHOME) to denote this full
    pathname.

(4) Identify the root directory (MATLABROOT) of the MATLAB installation on
    your machine. You can get this by typing

      >> matlabroot

    within MATLAB. It's often something like:

      /usr/local/matlab or /usr/local/matlab14

    in Linux, or

     /Applications/MATLAB72

    in Mac OS X.

(5) Within the directory plex (created from the tar file), type the
    following line, making the appropriate substitutions for (PLEXHOME)
    and (MATLABROOT):

      > ./configure --prefix=(PLEXHOME) --with-matlab=(MATLABROOT)

    This creates the Makefiles needed to compile Plex.

(6) Having run 'configure', compile the code (within the plex directory tree)
    by typing

      > make

    and then copy over the relevant files into the install directory by
    typing

      > make install

(7) If you wish, you can now delete the directory plex.

(8) To run Plex, add the following directories to your MATLAB search path:

      (PLEXHOME)/share/matlab/Plex
      (PLEXHOME)/share/matlab/Plex/metric

    If you're unfamiliar with manipulating the MATLAB search path, type
    'help addpath' at the MATLAB prompt. For my own convenience I keep a
    script called "plexstart.m" which I can use to add Plex to my search
    path whenever I need it.

(9) Let me know if you have any difficulties or any bugs to report.

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