================
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.

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).

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

The module is distributed on PyPI. You just need to 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).

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: print o
    (1,2)(3)
    (1,3)(2)
    sage: o.sum_of_lyapunov_exponents()
    4/3
    sage: o.lyapunov_exponents_approx()
    [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: QuadraticStratum(1,1,1,1).orientation_cover()
    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 o, "\n"
    (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()
    [0.6671, 0.4506, 0.2372, 0.08841]
    sage: Q12_reg.lyapunov_exponents_H_minus()
    [1.001, 0.6669, 0.45018, 0.3139, 0.23218, 0.12143, 0.08594]


Installing development version. Source code
-------------------------------------------

The development webpage is https://github.com/videlec/flatsurf-package

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

    $ sage -pip install git+https://github.com/videlec/flatsurf-package [--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.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).