Installing sage-flatsurf

Currently, sage-flatsurf is not widely available in package managers. We therefore recommend to use mamba to install sage-flatsurf. This should work nicely, if you are on Linux or macOS. If you are using Windows, you could try to install sage-flatsurf with mamba in Windows Subsystem for Linux (WSL). If you are having trouble with this or are on another operating system, please contact us. We’re thrilled about any new user of sage-flatsurf and we’re very happy to help and in the process improve these installation instructions.

Install with Mamba

Please first install mambaforge.

Here is some vocabulary, in case you are interested. Feel free to skip this paragraph. mambaforge, is a program that installs both conda and mamba on your system. conda is essentially a package manager for Windows, macOS, and Linux that installs software without requiring superuser permissions. mamba is a fast version of conda. mambaforge installs conda and mamba preconfigured to use packages from conda-forge. conda-forge is a community effort to package lots of software and make it easily installable with conda and mamba. The entire flatsurf stack, in particular sage-flatsurf, is available from conda-forge. conda and mamba install packages in conda environments, independent sets of software. You could for example have different environments for different versions of sage-flatsurf and SageMath. To use software from an environment, it needs to be activated. You can only activate a single environment at a time.

Once you installed mambaforge, open a new command line terminal. The mamba command should now be available. The base environment is already active, it contains the mamba package manager. (If your terminal always prints (base) and you find that annoying, run conda config --set auto_activate_base false to get rid of that prompt.)

You can now create a flatsurf environment (feel free to pick any other name) with the entire flatsurf stack (SageMath, sage-flatsurf, libflatsurf, ipyvue-flatsurf widgets, …) installed:

mamba env create -n flatsurf -f https://github.com/flatsurf/sage-flatsurf/raw/master/flatsurf.yml

Immediately after a new version of sage-flatsurf is released, this command might fail because not all packages have been built for your platform yet. When this is the case, you can also install a previous version of sage-flatsurf; replace the 0.5.0 below with any recent version of sage-flatsurf:

mamba env create -n flatsurf -f https://raw.githubusercontent.com/flatsurf/sage-flatsurf/0.5.0/flatsurf.yml

You can now activate the flatsurf environment and start SageMath:

mamba activate flatsurf
sage

If you prefer to work in a graphical environment, you can also launch Jupyter:

mamba activate flatsurf
jupyter notebook

Upgrade with Mamba

If you followed the above guide, it should be easy to upgrade to the latest release of sage-flatsurf. Before you do that, it’s usually a good idea to make sure that you are using the latest conda and mamba:

mamba upgrade -n base --all

To update sage-flatsurf and all the other packages in the flatsurf environment itself:

mamba upgrade -n flatsurf --all

If after an upgrade something does not work correctly, please let us know; we probably missed to declare some dependency.

You can also reinstall the flatsurf environment when this happens. First, uninstall the flatsurf environment:

mamba uninstall -n flatsurf --all

Then reinstall as above:

mamba env create -n flatsurf -f https://github.com/flatsurf/sage-flatsurf/raw/master/flatsurf.yml

This does not delete or otherwise modify any of your notebooks or SageMath archives.

Install into SageMath

If you are using a source build of SageMath or if you downloaded a SageMath binary, you can install sage-flatsurf into SageMath. Note that this does not install all the optional dependencies of sage-flatsurf so some computations might fail in this setup:

sage -pip install sage-flatsurf

To uninstall sage-flatsurf again later:

sage -pip uninstall sage-flatsurf

Install from PyPI

You can install sage-flatsurf from PyPI if you installed sagelib as a Python package. Again, this does not come with the optional dependencies of sage-flatsurf, so some computations might fail in this setup:

pip install --user sage-flatsurf

To uninstall sage-flatsurf again later:

pip uninstall --user sage-flatsurf