S2PLOT:Installation

From S2PLOT

Jump to: navigation, search

Contents

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.

PLEASE NOTE THAT THE INSTALLATION NOTES BELOW REFER TO OLDER VERSIONS OF S2PLOT RELEASED PRIOR TO VERSION 3.2.1. We will update this information in the very near future.

Architectures

The currently supported architectures and operating systems for S2PLOT are:

OSCompiler Architecture S2ARCHNotes
LinuxGNUi386linux-gnu-i386
LinuxGNUx86_64linux-gnu-x86_6464-bit, OpenMP required
DarwinGNUi386darwin-gnu-i386
DarwinGNUx86_64darwin-gnu-x86_6464-bit, OpenMP required
DarwinGNUPower PCdarwin-gnu-ppc
DarwinGNUUniversal builddarwin-gnu-univno FORTRAN


Prerequisites

  1. For C/C++ users, the gcc compiler is required. For FORTRAN users, the gfortran or g77 compiler is required.
  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

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.

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
  • FORTRAN programmers: you will need to examine the architecture definition file ($S2ARCH.in) file for your architecture to see whether gfortran or g77 is being used, and whether your source file extension should be .f or .f90. Build your code with ${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.


Personal tools