================
Surface dynamics
================

The surface_dynamics package for SageMath adds functionality related to interval exchange
transformations, translation surfaces, mapping classes and more. It is
distributed as an external Python package. It installs on top of an existing
Sage installation (tested on versions 8.0, 8.1 and 8.2).

This package is based on `SageMath <http://www.sagemath.org>`_ and relies heavily on:

* gmp or mpir for arbitrary precision arithmetic
* PARI/GP for number field computations
* GAP for finite groups representation and permutation groups
* PPL (Parma Polyhedra Library) and LattE (Lattice point Enumeration) for polytope computations

Prerequisites
-------------

Installing surface_dynamics requires a working Sage installation (with Cython and gcc). It is
also recommanded to install the optional SageMath packages ``gap_packages``, ``database_gap``
and ``latte_int``.

Installation
------------

The module is distributed on PyPI and is easily installed through the Python package manager
pip. If you downloaded a binary from the Sagemath website (including the Cygwin version
running on Windows) or compiled from source, run the following command::

    $ sage -pip install surface_dynamics [--user]

The --user option is optional and allows to install the module in your user space
(and does not require administrator rights).

If you use Debian, Ubuntu and you installed Sage through the operating system
(that is the package sagemath) run these two commands::

    $ source /usr/share/sagemath/bin/sage-env
    $ pip install surface_dynamics --user

If you use Archlinux, you need to install from source (see next section).

Install and use source version
------------------------------

In this section, we provide detailed instruction on how to download, modify
and install the development version of `surface_dynamics`. In all command
lines

* `PIP` has to be replaced by either `pip`, `pip2` or `sage -pip`
* `PYTHON` has to be replaced by either `python`, `python2` or `sage -python`

If you are an Archlinux user with the sagemath package install, use
`PIP=pip2` and `PYTHON=python2`. If you downloaded SageMath as a tarball
or installed it from source use `PIP=sage -pip` and `PYTHON=sage -python`.

You can install the latest development version in one line with::

    $ PIP install git+https://gitlab.com/videlec/surface_dynamics [--user]

As before, the --user option is optional and when specified will
install the module in your user space. 

You can also perform a two stage installation that will allow you to
modify the source code. The first step is to clone the repository

    $ git clone https://gitlab.com/videlec/surface_dynamics

The above command creates a repository surface_dynamics with the source code,
documentation and miscellaneous files. If you cd into the created directory
you can install the surface dynamics module with::

    $ PIP install . [--user]

Do not forget the `.` that refers to the current directory.

When you don't want to install the package or you are testing some
modifications to the source code, a more convenient way of using
surface dynamics is to do everything locally. To do so, you need
to compile the module in place via

    $ PYTHON setup.py build_ext --inplace

Once done, you can import the `surface_dynamics` module. To check that you
are actually using the right module (i.e. the local one) you can do in a
SageMath session

    sage: import surface_dynamics
    sage: surface_dynamics.__path__
    ['/home/robert/surface_dynamics/surface_dynamics/']

The result of the command must correspond to the path of the repository
created by the command `git clone` given above. The compilation step
`PYTHON setup.py build_ext` has to be redone each time you modify
a C or Cython source file (i.e. with `.c`, .h`, `.pxd` or `.pyx`
extension). In other words, it is not needed if you only
modify or create Python files (ie `.py` files).

If you wish to install your custom version of surface dynamics
just use `PIP` as indicated before.

Documentation
-------------

* short tutorial: http://www.labri.fr/perso/vdelecro/flatsurf.html
* complete module documentation: http://www.labri.fr/perso/vdelecro/surface-dynamics/

Check
-----

After installing surface_dynamics, check that it works by launching Sage
and typing the following commands. You should get the same
output as below.::

    sage: from surface_dynamics.all import *
    sage: o = Origami('(1,2)','(1,3)')
    sage: o
    (1,2)(3)
    (1,3)(2)
    sage: o.sum_of_lyapunov_exponents()
    4/3
    sage: o.lyapunov_exponents_approx()    # abs tol 0.05
    [0.33441823619678734]
    sage: o.veech_group()
    Arithmetic subgroup with permutations of right cosets
     S2=(2,3)
     S3=(1,2,3)
     L=(1,2)
     R=(1,3)
    sage: q = QuadraticStratum(1,1,1,1)
    sage: q.orientation_cover()
    H_5(2^4)
    sage: q.components()
    [Q_2(1^4)^hyp]
    sage: c = q.components()[0]
    sage: c
    Q_2(1^4)^hyp
    sage: c.orientation_cover_component()
    H_5(2^4)^odd

    sage: AbelianStrata(genus=3).list()
    [H_3(4), H_3(3, 1), H_3(2^2), H_3(2, 1^2), H_3(1^4)]

    sage: O = OrigamiDatabase()
    sage: q = O.query(("stratum","=",AbelianStratum(2)), ("nb_squares","=",5))
    sage: q.number_of()
    2
    sage: for o in q:
    ....:     print("%s\n- - - - - - - -" % o)
    (1)(2)(3)(4,5)
    (1,2,3,4)(5)
    - - - - - - - -
    (1)(2)(3,4,5)
    (1,2,3)(4)(5)
    - - - - - - - -
    sage: Q12_reg = QuadraticStratum(12).regular_component()
    sage: Q12_reg.lyapunov_exponents_H_plus(nb_iterations=2**20)   # abs tol 0.05
    [0.6634, 0.4496, 0.2305, 0.0871]
    sage: Q12_reg.lyapunov_exponents_H_minus(nb_iterations=2**20)  # abs tol 0.05
    [1.0000, 0.3087, 0.1192]

Installing development version - source code
--------------------------------------------

The development webpage is https://gitlab.com/videlec/surface_dynamics

Assuming you have the program git on your computer, you can install the
development version with the command::

    $ sage -pip install git+https://gitlab.com/videlec/surface_dynamics [--user]

Contact
-------

Your comments and help are welcome: vincent.delecroix@labri.fr
For problems with Mac OS X: samuel.lelievre@gmail.com

Authors
-------

* Vincent Delecroix: maintainer
* Samuel Lelièvre: contribution for origamis and permutation representative 
  of quadratic strata
* Charles Fougeron: Lyapunov exponents for strata coverings

Versions
--------

* flatsurf 0.4.0 was released on 2018-05-14 (as a Python package on PyPI)
* flatsurf 0.3 was released on 2017-08-11 (as a Python package on PyPI)
* flatsurf 0.2 was released on 2015-11-15 (as a Sage spkg).
* flatsurf 0.1 was released on 2015-07-30 (as a Sage spkg).
