.. highlight:: rst

SageMath and GAP
++++++++++++++++

"SageMath is a free open-source mathematics software system licensed under the GPL. It builds on top of many existing open-source packages: NumPy, SciPy, matplotlib, Sympy, Maxima, GAP, FLINT, R and many more. Access their combined power through a common, Python-based language or directly via interfaces or wrappers." - https://www.sagemath.org/

For the official SageMath documentation, please see: https://doc.sagemath.org/html/en/index.html

Using SageMath on the cluster
*****************************

The best way to use SageMath on the rcfcluster is to create a new python virtual environment.

Creating the SageMath virtual environment
*****************************************

To create a new virtual enviroment for running SageMath scripts, type the following terminal commands, line-by-line, on the rcfcluster head node: ::

        # Load the miniconda module:
        module load miniconda

        # READ THIS: If this is your first time creating ANY python virtual environment on rcfcluster, include this line. Otherwise you should omit it:
        conda init bash

        # set up your bash environment to use conda:
        source ~/.bashrc

        # Create the new environment, called 'sage' that will include all the sage packages:
        # Note: you may choose to change the python version if desired
        conda create -n sage -c conda-forge sage python=3.9

        # (type 'y' when prompted if you want to install all the suggested packages. This step will take awhile as everything is downloaded and installed)


Installing additional packages
******************************

Installing new packages into the sage virtual enviroment is the same as for any other python virtual environment. Please see the :ref:`Python section <activating-using-the-python-environment>` of this guide for more details.

**NOTE:** If conda can't locate the package you want, you may need to specify the conda-forge repo. For example, to install the ``anytree`` package:: ::

        conda activate sage
        conda install -c conda-forge anytree


Submitting a sage script to slurm
*********************************

Below is an example of a sbatch script for running a sage script, ``example.sage``: ::

        #!/bin/bash

        #SBATCH --job-name=sage-example
        #SBATCH --time=5:00
        #SBATCH --mem-per-cpu=1G
        #SBATCH -n 1
        #SBATCH -N 1

        # Activate sage conda environment:
        module load miniconda
        eval "$(conda shell.bash hook)"
        conda activate sage

        # Run the script:
        sage example.sage



Using GAP on the cluster
***********

SageMath also includes an interface to `GAP <https://www.gap-system.org/>`_, a system for computation discrete algebra.

For official documentation on using GAP packages in sage, see: https://doc.sagemath.org/html/en/reference/interfaces/sage/interfaces/gap.html