Download and Installation Guide

This is the installation manual for the current version of GIPSY (primarily upgraded on Rocky Linux 9 with Anaconda3/2023.03 and last modified in July 2023).
It supports 64 bits so called 'coordinate words' to handle large data sets. It uses Python3, Qt5 and modules from a recent Anaconda distribution (NumPy, SciPy, Matplotlib, ...).
With the GIPSY installation, a version of the Kapteyn Package (https://www.astro.rug.nl/software/kapteyn) will be downloaded and installed.

Contents:

Common install notes

Currently (Sep, 2023) we managed to upgrade the installation of GIPSY for Linux based systems with some limitations.

Quick install

A note about Python packages provided by Anaconda: Anaconda does not install Cython by default. If you install it with conda, you could get version 3.0 which has bugs that prevent the GIPSY Python module to be compiled. For now, you can install it with:
pip install "cython<3"
If you fulfilled all requirements (see also next section for a specific OS), then the installation can be done with a script. You need the TC-shell to execute the script.

BASH:

  1. Download installation script: gipsy_install.py
  2. You can make the script executable: chmod +x gipsy_install.py
  3. Run the script which prompts for a directory where to install GIPSY and start the installation: python gipsy_install.py of if you made it executable: ./gipsy_install.py

TCSH

  1. Download installation script: If your shell is the TC-shell: Download gipsy_install.csh
  2. Make script executable:chmod +x gipsy_install.csh
  3. Run the script which first prompts for a directory where to install GIPSY: ./gipsy_install.csh
In the installation directory the script creates a file install.log which can be consulted in case of problems. You can follow the installation results in detail in a separate terminal with:

tail -f install.log

When done, the install script will print
+++ FINISHED +++

Setting the environment and starting GIPSY

When your installation was succesful you need to modify your environment by adding the appropriate lines in your .cshrc or .bashrc:

.cshrc
        setenv gip_root <PATH_TO_GIPSY_ROOT_DIRECTORY>
        source $gip_root/sys/gipenv.csh
.bashrc:
        export gip_root="<PATH_TO_GIPSY_ROOT_DIRECTORY>"
        source $gip_root/sys/gipenv.sh
and after sourcing the relevant file (or after opening a new terminal) you can start the system with:

gipsy

The GIPSY environment defines a number of commands to start tasks on the command line:

Requirements

This document describes how to install GIPSY64. We assume you have an existing Python installation with packages like NumPy, SciPy, Astropy, Matplotlib and some others. Preferably installed with an Anaconda distribution for Python 3.

Below is a list of requirements to install GIPSY's core system. Please note that depending on the operating system distribution, some software may already be provided and other software can be installed from repositories belonging to that distribution. Separate pages with preparation instructions are available for

Below a description of common requirements.

Manually installing on the command line, step by step

Below we give instructions how to install GIPSY manually which provides more control over the installation when the install script failed.
You need a terminal with the TC-shell to execute the commands.

Installation step 0: Download the source

First create a directory gipsy in the tree where you want to keep the GIPSY source files. It is advisable to create a user gipsy, but this is not really necessary. When you have a user gipsy on your system, the GIPSY root directory should be the HOME directory of user gipsy. Do not install GIPSY as root to avoid problems with ownership of downloaded files.

You will end up with a GIPSY directory tree with the following subdirectories:

Installation step 1: Clients file

Go to the GIPSY system directory with:
        cd $gip_root/sys
You are now in the directory which contains all the GIPSY system files. Make the current host a GIPSY client with:
        ./mkclient.csh  <number>
<number> denotes the GIPSY client mode and should be one of the following:
<number>            What GIPSY client may/can do
              RUN COMPILE INSTALL SUID GLOCK NOOLD REMOTE GFTP LINK
    65         +1                                     +64           =  65
    71         +1     +2      +4                      +64           =  71
   103         +1     +2      +4               +32    +64           = 103
   199         +1     +2      +4                      +64 +128      = 199
   231         +1     +2      +4               +32    +64 +128      = 231
   487         +1     +2      +4               +32    +64 +128 +256 = 487
It should be 71 or 103 If your machine does not allow set owner and set group ID on the disk where the GIPSY sources are stored, you may have to add 8 to the GIPSY client code.

The mkclient.csh script creates an entry in the clients file, which resides in $gip_root/loc. The modified file is in the current directory and is called clients.new. You should check this file and if necessary, modify it. Usually the fields which are modified are the paths to the GIPSY exe, lib and tmp directories.

A description of the clients file and the mkclient.csh script can be found in $gip_root/doc/clients.doc and $gip_root/doc/mkclient.doc resp. After inspecting and/or modifying the file clients.new type:

        mv clients.new $gip_root/loc/clients
Next type:
        source cshrc.csh

This should define the necessary environment variables. A description can be found in $gip_root/doc/cshrc.doc.

Installation step 2: Compiler setup

The next step is to create the setup file for the compilers in the $gip_loc directory ($gip_loc is defined as $gip_root/loc by the gipenv.csh script). You can check the $gip_sys/setup.mgr file for entries which match your local situation. Now copy the file with:
        cd $gip_loc
        cp $gip_sys/setup.mgr setup 
For standard installations, usually no editing is necessary. Otherwise, delete all the lines that are not relevant and do NOT delete the last (comment) line! (see also $gip_doc/setup.doc).

Mac with X11 installed with MacPorts
If you installed the X11 libraries using MacPorts, then you need the change the following lines in the apple_i64 section
-I/usr/X11R6/include -I/usr/X11R6/include/X11:\
-L/usr/X11R6/lib/ -lX11:\
-L/usr/X11R6/lib -lXaw3d -lXmu -lXt -lXext -lSM -lICE -lX11
into:
-I/opt/local/include -I/usr/X11R6/include/X11:\
-L/opt/local/lib/ -lX11:\
-L/opt/local/lib -lXaw3d -lXmu -lXt -lXext -lSM -lICE -lX11

Next we have to compile the compile program, the file extractor, the Fortran to C interface program, the GIPSY lock server, the Sheltran compiler, the GIPSY file transporter and install the fonts for PGPLOT. This can be done with the install script. This script will check whether the necessary directories are present and create them if possible and necessary. In principle only the system dependent directories will be created. In order to run install type

        cd $gip_sys
        ./install.csh
If it complains, then probably some variables are not yet set, and running install again might provide the solution. See $gip_doc/install.doc for a description. Note that the install script tries to send a mail with registration information to the GIPSY server. If you don't want that, then comment out the calls to 'register.sh' in the scripts 'install.csh' and 'gipsy.csh' (both in $gip_sys).

Installation step 3: Building the sources

Now you have to build the GIPSY library and the GIPSY applications. Type:
        cd $gip_sys
        ./mkbookkeeper.csh
        mv bookkeeper.new bookkeeper
If you have the ftp bit on in $gip_loc/clients (bit 8), turn it off by subtracting 128 from field 3 in $gip_loc/clients. Next type:
        p -update > & install.log & 

This will generate the GIPSY library and the GIPSY applications. It is the most time consuming part of the installation. Use command: tail -f install.log   in a separate terminal to check the compilation.

Note that when you kill 'p' there might be some lock files which will not allow 'p' to be restarted. You will have to remove the lock files by typing:

        rm -f $gip_sys/.*lock $gip_sys/*.lock $gip_tmp/update.lock
You should inspect the log file install.log for any errors. If there are any, try to find out what caused them. If you can't solve the problem by adjusting setup parameters or installing missing software components, such as libraries or header files, you can contact the GIPSY manager at Groningen (gipsy@astro.rug.nl).

Installation step 4: Local system setup

You can skip this section if you don't have legacy hardware like text printers and magnetic tape readers.

In order to get the system running properly, you may have to edit the following setup files in the $gip_loc directory:

        File                Purpose                              Documentation

        grdevices           Contains info about graphics devices $gip_doc/grdevices.doc
        lpdevices           Contains info about text printers    $gip_doc/lpdevices.doc
        mtdevices           Contains info about tape units       $gip_doc/mtdevices.doc
        tvdevices           Contains info about X11 servers      $gip_doc/tvdevices.doc

Installation step 5: Set the environment

See section Setting the environment and starting GIPSY

Post installation: Regular updates

Updates for this distribution cannot yet be done in the way it could with the original version of GIPSY. The architecure of the GIPSY distribution was not meant to support multiple versions. The plan is to create two separate systems that cannot interfere with each other.

Post Installation: Troubleshooting

You may run into problems installing, running or compiling GIPSY. Here are some things to check first before contacting the GIPSY maintainer.
  1. Check whether you have the correct version of the operating system and the compilers mentioned above. You may have to make small modifications to $gip_loc/setup to enable correct compiling.
  2. Check whether you have initialized the gipsy environment See section Setting the environment and starting GIPSY
  3. Then check whether you have made the necessary modifications to the setup files.
  4. If you still have problems, you can contact the GIPSY manager at Groningen: gipsy@astro.rug.nl.

Post Installation: Creating a dummy set

Test to create a dummy set with task CREATE
Start GIPSY with command

gipsy

The Hermes interface for task management will be started. Documentation about Hermes can be read in Hermes, GIPSY's user interface.
On the Hermes command line enter

!create and press <esc> e

A command line editor will be started (see remark about this editor below if you want to change the default). Paste the list with keywords below. Save the file and exit. Task CREATE will start with these keywords and a dummy set 'test' will be created which can be viewed with task VISIONS.

BUNIT=
CDELT1= -0.01
CDELT2= 0.01
CDELT3= 1000000
CROTA2=
CRPIX1= 150
CRPIX2= 100
CRPIX3= 1
CRVAL1= 45
CRVAL2= 30
CRVAL3= 1401000000
CTYPE1= RA---NCP
CTYPE2= DEC--NCP
CTYPE3= FREQ-OHEL
CTYPE4=
CUNIT1=
CUNIT2=
CUNIT3=
DRVAL3= 400
DUNIT3=
FREQ0= 1400000000
FUNCTION= RA*DEC*FREQ
INSTRUME= WSRT
NAXIS1= 300
NAXIS2= 200
NAXIS3= 60
OUTSET= test

Post Installation: A template .cshrc file

To run GIPSY you need TCSH. A template contents of its resource file .cshrc is given below.
#============== TCSH template .cshrc ===============
set filec                                       # enable file completion
#
# History
#
set history = 2000                              # length of history
set histfile=$HOME/.tcshHistory/history.$HOST
set savehist=(2000 merge)
history -L

if ($shell:t == tcsh) then                      # we are running tcsh
         bindkey -k up history-search-backward
         bindkey -k down history-search-forward
endif

if ($?autologout) then                          # if autologout is enable
        unset autologout                        # do not logout automatically
endif                                           # done
#set prompt = "$HOST>"                          # prompt is machine name
set prompt="%U$HOST%u\:%/ >"

setenv gip_root /home/kapteyn/gipsy64   # !! Replace this with your GIPSY home !!
source $gip_root/sys/gipenv.csh

# This  can be useful if you want to override the default editor 'vi'
set     EDITOR = nano
setenv  EDITOR   nano
#===================================================

GIPSY documentation (.doc) files

Additional documentation is stored in the GIPSY documents (doc) directory.

GIPSY references


COPYRIGHT © 1999-2023
Kapteyn Institute, University of Groningen, The Netherlands
All Rights Reserved.


GIPSY