magma_kernel/README.md

# Magma Jupyter Kernel

A simple Jupyter kernel for the Magma computer algebra system.

## Requirements

-   Magma must be installed and runnable using the standard path, i.e., typing the command `magma`
    will run Magma.

-   Jupyter running on Python 3.

## Installation

If `pip` and `python` point to their Python 3 versions, you can install the kernel as a user with
the commands:

```sh
pip install git+https://git.phc.dm.unipi.it/phc/magma_kernel
python -m magma_kernel.install
```

On some systems, you may need to use `pip3` and `python3` instead.

### Using a remote magma installation

If the magma instance is on a remote machine, you can add an ssh key to the remote machine and
create a script like the following (e.g., in `~/.local/bin/magma`, ensuring that the directory is in
your `PATH`):

```sh
#!/bin/sh
exec ssh -qt user@remote "magma $*"
```

Then run `chmod +x ~/.local/bin/magma` to make it executable. Now, if you install the kernel as
above you can use it "locally" by running `magma` as if it were installed on your machine.

## Usage

You need the local `magma` executable to be in your `PATH` to use the kernel, you can also use the
remote magma installation as described above. Now to use the kernel, run one of the following
commands

```sh
# Select "New" -> "Notebook" and then in the new tab select "Magma" as the kernel
jupyter notebook

# Or run the console with the Magma kernel (still better than pure magma)
jupyter console --kernel magma
```

## Development

To install the kernel in development mode, clone the repository and run

```sh
# Create a virtual environment
python -m venv venv
source venv/bin/activate

# Locally install the kernel
pip install -r requirements.txt
python -m magma_kernel.install
```

## Credits

This code is based on a Magma kernel for IPython written by [@nbruin](https://github.com/nbruin),
which was in turn based on [@cgranade/magma_kernel](https://github.com/cgranade/magma_kernel) which
in turn was based on the Bash example kernel by Thomas Kluyver. Improvements made in the current
version include:

-   Removed some deprecated function usages

-   Added a `requirements.txt` file