S2PLOT:Installation

From S2PLOT

Contents 1 Installing S2PLOT 2 Architectures 3 Prerequisites 4 Choosing the Distribution 5 Install from all tarball 6 Install from base and ARCH tarballs 7 Configuration 8 Testing 9 Where to Next? 10 Disclaimers

Installing S2PLOT

Detailed information on how to install S2PLOT on your system may be found in the files INSTALL.TXT and ENVIRONMENT.TXT. The following instructions provide a quick summary of the standard steps required to install and configure S2PLOT, however, users are encouraged to read the full installation documentation - particularly if there are any errors when you try to build your code.

Architectures

The currently supported architectures and operating systems for S2PLOT are:

OS	Compiler	Architecture	S2ARCH
Linux	GNU	i386	linux-gnu-i386
Linux	GNU	x86_64	linux-gnu-x86_64
Linux	GNU	x86_64	linux-gomp-x86_64 - enables OpenMP support
Darwin	GNU	i386	darwin-gnu-i386
Darwin	GNU	Power PC	darwin-gnu-ppc
Darwin	GNU	Universal build (No FORTRAN)	darwin-gnu-univ
Darwin	GNU	i386	darwin-gomp-i386 - enables OpenMP support
Windows	GNU	i386	cygwin-gnu-i386

Prerequisites

1. For C/C++ users, the GCC compiler is required. For FORTRAN users, the G77 compiler is required. S2PLOT has also been tested with Intel FORTRAN compilers. Please refer to INSTALL.TXT for details.
2. An OpenGL-compliant graphics card, or the Mesa3d library. See INSTALL.TXT for details of cards and system configurations that S2PLOT has been tested on.

Choosing the Distribution

As of version 1.80, the S2PLOT distribution comes in either a single file (containing all possible architectures) named:

• s2plot-all-A.BB-YYYY-MM-DD.tar.bz2

or two parts named:

• s2plot-base-A.BB-YYYY-MM-DD.tar.bz2
• s2plot-ARCH-A.BB-YYYY-MM-DD.tar.bz2

where:

• ARCH is replaced by one of the S2ARCH strings above
• A is the major version
• BB is the minor version
• YYYY is the year of the release
• MM is the month of the release
• DD is the day of the release

Before continuing installation, please check that you have the latest version of S2PLOT.

Install from all tarball

Unzip the all distribution file using:

bunzip2 s2plot-all-A.BB-YYYY-MM-DD.tar.bz2 (replacing A, BB, etc.)

Untar the all distribution file using: tar -xvf s2plot-all-A.BB-YYYY-MM-DD.tar (replacing A, BB, etc.)

This will produce a directory named by the pattern s2plot-A.BB. You can now move the s2plot-A.BB directory to any location you prefer, for example to /usr/local. You are now ready to move onto the Configuration step.

Install from base and ARCH tarballs

Unzip the base distribution file using:

bunzip2 s2plot-base-A.BB-YYYY-MM-DD.tar.bz2 (replacing A, BB, etc.)

Untar the base distribution file using: tar -xvf s2plot-base-A.BB-YYYY-MM-DD.tar (replacing A, BB, etc.)

This will produce a directory named by the pattern s2plot-A.BB. Now unzip and untar the specific architecture version you wish to use. For example, to use Darwin Gnu compiler version:

bunzip2 s2plot-darwin-gnu-i386-2.00-2007-12-17.tar.bz2

tar -xvf s2plot-darwin-gnu-i386-2.00-2007-12-17.tar

which will install the relevant version of the S2PLOT library within the s2plot-A.BB directory. You can now move the s2plot-A.BB directory to any location you prefer, for example to /usr/local.

Configuration

Now is a good time for you read the INSTALL.TXT and ENVIRONMENT.TXT files that are in the s2plot-A.BB directory.

Configuration of S2PLOT is achieved by editing s2plot.csh in the distribution directory and adding several environment variables to the .cshrc file in your home directory. As a minimum, the following should be added to your .cshrc file:

1. setenv S2PATH [location] where [location] is the path to the s2plot-A.BB directory.
2. setenv S2ARCH [architecture] where [architecture] is a valid archictecture description - see the table above, or ENVIRONMENT.TXT for details.
3. Configure the dynamic linker on your system to find the S2PLOT library.
   • Linux: Add ${S2PATH}/${S2ARCH} to the colon-separated environment variable LD_LIBRARY_PATH.
   • Darwin: Add ${S2PATH}/${S2ARCH} to the colon-separated environment variable DYLD_LIBRARY_PATH.
4. You way wish to add $S2PATH to your executable path: eg. set path = ($path $S2PATH). This will simplify the process of building with the fbuild.csh and cbuild.csh scripts. Alternatively, make copies of the scripts and modify them as required.
5. If you are planning to use textures, set the environment variable S2PLOT_TEXPATH. The recommended default value is: setenv S2PLOT_TEXPATH ${S2PATH}/textures.
6. If you are planning to use the LaTeX commands, set the environment variable S2PLOT_LATEXBIN to the location of your local LaTeX installation. eg. setenv S2PLOT_LATEXBIN /usr/local/latex (Linux) or setenv S2PLOT_LATEXBIN /sw/bin/latex (OSX). You will also need to set variables S2PLOT_DVIPNGBIN and S2PLOT_IMPATH. See ENVIRONMENT.TXT for details.
7. For other environment variables, see here.

To use S2PLOT on Windows, you must have a working installation of cygwin. Please make sure you read the INSTALL.TXT and ENVIRONMENT.TXT files that are in the s2plot-A.BB directory for information on which packages need to be installed. Configuration is similiar to Linux version. Please note that Cgywin S2PLOT can be slow.

Testing

Once S2PLOT is installed, and the configuration tasks have been completed, you are now ready to test the installation using the precompiled binaries.

1. Test that you can run the programs from a terminal (do not use the Apple Finder or other file managers). Change to directory ${S2PATH}/${S2ARCH} and run any of the demonstration programs.
2. Copy s2opend.c from the directory ${S2PATH}/functions to your own directory. Compile with cbuild.csh s2opend and check that you can run execute the binary.
3. If either of these steps results in errors, please refer to INSTALL.TXT for recommended actions.

Where to Next?

You should now have a fully-functional installation of S2PLOT.

To learn more about using S2PLOT, you can try the various function examples available as source code (in the ${S2PATH}/functions directory) or as pre-compiled binaries (in the${S2PATH}/${S2ARCH} directory). Note that you cannot compile the source code samples within the ${S2PATH}/functions directory. The Function List on this web-site also contains sample code for every single S2PLOT function. We are developing a series of How Tos to aid programmers new to S2PLOT.

• C/C++ programmers: use the files named filename.c and build with ${S2PATH}/cbuild.csh filename/code>
• FORTRAN-77 programmers: there is currently no sample code, but you should build your code with <code>${S2PATH}/fbuild.csh

You are now ready to write your own S2PLOT code, and compile it in your own workspace. More details on using S2PLOT may be found by exploring this website. A complete function list is available here.

Disclaimers

S2PLOT is freely available for non-commercial and educational use, however, it is not public-domain software. The programming libraries and documentation may not be redistributed or sub-licensed in any form without permission from Swinburne University of Technology. The programming library and sample codes are provided without warranty.

We would appreciate it if research outcomes using S2PLOT would provide the following acknowledgement:

Three-dimensional visualisation was conducted with the S2PLOT progamming library

and a reference to

D.G.Barnes, C.J.Fluke, P.D.Bourke & O.T.Parry, 2006, Publications of the Astronomical Society of Australia, 23(2), 82-93.

S2PLOT development was funded through the Researcher Developer Grant Scheme at Swinburne University of Technology.

Back to S2PLOT home page.