====== GipsyX ======

<WRAP round box important>
**Important License Information**

The license for using this software is restrictive. As part of the terms of the license it is **only** available to select HPC projects on Comet. If you need to use this software and you are //not// a member of a project which already has access, then please [[:contact:index|contact us]] first.
</WRAP>

> GipsyX is developed by the Jet Propulsion Laboratory (JPL), and maintained by the Near Earth Tracking Applications and Systems groups. It replaces the GIPSY-OASIS (GNSS-Inferred Positioning System and Orbit Analysis Simulation Software) software.

**Features:**
   * Analysis of data from Global Navigation and Satellite Systems (GNSS):
      * Global Positioning System (GPS)
      * Russian GLONASS
      * French DORIS
      * Satellite Laser Ranging (SLR) system
   * Precise centimeter-level GNSS-based positioning and timing:
      * Space platforms, including low-Earth orbiters and GNSS constellations
      * Airplanes
      * Terrestrial (ground) stations, static or moving
      * Time transfer
   * Single high-level user interface supports majority of precise positioning applications
   * Single-receiver ambiguity resolution using JPL's GPS orbit and clock products

**Applications:**
   * Terrestrial positioning for geophysical research:
      * Earth deformation, plate tectonics
      * GNSS Networks (e.g. PBO and SCIGN)
      * Ice flow
      * Studying troposphere and ionosphere
      * Reference frame (geocenter and scale) and Earth rotation parameters
   * Airplane positioning
   * Precise orbit determination
      * Low-Earth orbiters: Topex/Poseidon, Jason-1, Jason-2/OSTM, Jason-3, Sentinel-6, NISAR, GRACE, GRACE-FO, Champ, SAC-C, COSMIC, COSMIC-2, DSAC, Space Shuttle (e.g. SRTM), Commercial Satellites
      * GNSS constellations including GPS, GLONASS, Galileo, Beidou, QZSS, and IRNSS

For further information: https://gipsyx.jpl.nasa.gov/

----

===== Running GipsyX on Comet =====

**GipsyX** has been installed on Comet as an **application container**. This allows the software to be fully restricted to the HPC project group(s) who are allowed access as part of the terms of the license. It also allows the staff in those groups to update the container to new software versions as-and-when required //without// any superuser intervention.

<WRAP todo round box>
To be written
</WRAP>

==== Sample GipsyX Slurm Job ====

<WRAP todo round box>
To be written
</WRAP>

----

===== Running GipsyX graphical tools on Comet =====

<WRAP todo round box>
To be written
</WRAP>

----

===== Building GipsyX on Comet =====

<WRAP important round box>
**Important!**

This section is only relevant to RSE HPC support staff or users who want to understand how GipsyX has been installed. If you only want to //use// the software, stop reading now.
</WRAP>

<WRAP todo round box>
This section is still in development!!!
</WRAP>

You will need:

   * GipsyX container definition file (named ''gipsyx.def''), listed below - //only needed to build the container, not to run it//
   * GipsyX runtime helper (named ''gipsyx.sh''), listed below - your users ''source'' this file to run GipsyX
   * GipsyX build script (named ''gipsyx.build.sh''), listed below - //only needed to build the container, not to run it//
   * GipsyX installation tarball (named ''gipsyx.tar.gz'') - this __must__ be provided by a user //licensed to download the software//

The output will be a single file named ''gipsyx.sif'', containing the GipsyX software and all runtime dependencies. This should be copied to a location only accessible to members of the allowed HPC project group. We therefore suggest the use of your ''/nobackup/proj/PROJECT_NAME'' folder.

**Container Definition:**

This file should be named ''gipsyx.def''.

<code lang=bash title=gipsyx.def>
Bootstrap: docker
From: ubuntu:jammy

####################################################################
# GipsyX Container
# ==================
# This is a runtime environment for GipsyX
# Please see: 
#	https://hpc.researchcomputing.ncl.ac.uk/dokuwiki/dokuwiki/doku.php?id=advanced:software:gipsyx
#
####################################################################
%post
    # Prevent interactive prompts
    export DEBIAN_FRONTEND=noninteractive

####################################################################
# Basic system packages
####################################################################

	# Update & install only necessary packages
	apt-get update
	apt-get install -y wget unzip
	
	# Clean up APT cache to save space
	apt-get clean 

	# Remove all src packages
	cd /
	rm -rf /src

####################################################################
# Additional environment variables
####################################################################
%environment

%runscript
</code>

**Runtime Helper:**

This file should be named ''gipsyx.sh'', and should be set executable with ''chmod 750 gipsyx.sh''.

<code lang=bash title=gipsyx.sh>
#!/bin/bash

module load apptainer

IMAGE_NAME=/nobackup/proj/YOUR_PROJECT_DIRECTORY/gipsyx.sif

container.run() {
	# Run a command inside the container...
	# automatically bind the /scratch and /nobackup dirs
	# pass through any additional parameters given on the command line
	apptainer exec --bind /nobackup/proj/YOUR_PROJECT_DIRECTORY/gipsyx_config:/opt/gipsyx/etc --bind /scratch:/scratch --bind /nobackup:/nobackup ${IMAGE_NAME} $@
}
</code>

==== Steps to building a new container ====

Put the files ''gipsyx.def'' and ''gipsyx.tar.gz'' in the same directory, save the following script as ''gipsyx.build.sh'' in the same directory and then run it:

<code lang=bash title=gipsyx.build.sh>
#!/bin/bash
module load apptainer

# Build the container image
apptainer build gipsyx.sif gipsyx.def

# Set the container to be readable by self and group only
chmod 440 gipsyx.sif
</code>

----

[[:advanced:software|Back to software]]