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