An easy-to-use, modular and extendable Julia package for Dynamical Billiard systems in two dimensions.


DynamicalBilliards Logo: The Julia billiard

A Julia package for dynamical billiard systems in two dimensions. The goals of the package is to provide a flexible and intuitive framework for fast implementation of billiard systems of arbitrary construction.

Documentation Citation Travis AppVeyor Gitter
, status Build Status Build status Gitter

If you have used this package for research that resulted in a publication, please be kind enough to cite the paper associated with DynamicalBilliards.jl. The DOI is https://doi.org/10.21105/joss.00458 and you can cite as:

G. Datseris, The Journal of Open Source Software 2, 458 (2017).

or if you use BibTeX:

  doi = {10.21105/joss.00458},
  url = {https://doi.org/10.21105/joss.00458},
  year  = {2017},
  month = {nov},
  publisher = {The Open Journal},
  volume = {2},
  number = {19},
  pages = {458},
  author = {George Datseris},
  title = {{DynamicalBilliards}.jl: An easy-to-use,  modular and extendable Julia package for Dynamical Billiard systems in two dimensions.},
  journal = {The Journal of Open Source Software}


The core of DynamicalBilliards.jl is separated in simple and cohesive modular structures:

  • Straight propagation : The standard billiard dynamical system. A particle is propagating in a straight line, until a specular reflection is performed at a boundary.
  • Magnetic propagation : Instead of a straight line, the orbit of the particle is a circle, like electrons in a perpendicular magnetic field. The particle still undergoes specular reflections at the boundaries of the billiard.
  • Ray-splitting billiards : A semiclassical implementation of the dynamical billiard. After a collision of a particle with a boundary, the particle may propagate through the boundary given some arbitrary probability and transmission law.
  • Standard billiards : A library of pre-constructed billiard systems that have already been used in Physics/Mathematics (e.g. Sinai, periodic Sinai, Buminovich etc.)
  • Visualization : Functions for plotting and visualizing aspects of a billiard system, such as obstacles, orbits and more. Also includes animation related content.
  • Lyapunov Spectrum : Calculate the lyapunov spectrum of the trajectory of a particle in an arbitrary billiard table. Currently this is only available for Particles.

NOTICE: This package does not support collision between particles (currently), since all particles are considered point-particles.


This package is registered, simply use Pkg.add("DynamicalBilliards") to install it.

The master branch of DynamicalBilliards is used for development purposes. It is not advised to use Pkg.checkout("DynamicalBilliards"), unless you want to contribute to the development of the package.


Plotting in DynamicalBilliards is done through the PyPlot package. However, all plotting-related functions are not available by default but only "on-demand". Use DynamicalBilliards.enableplotting() to bring them into scope.

WARNING: You must be able to using PyPlot if you want to use the plotting capabilities of DynamicalBilliards! If you are having trouble installing PyPlot you can always use the minimal Python installation through miniconda by running these lines in your Julia terminal:

ENV["PYTHON"]=""; Pkg.add("PyCall"); Pkg.build("PyCall");
Pkg.add("PyPlot"); using PyPlot;


This package is mainly developed by George Datseris. However, this development would not have been possible without significant help from other people:

  1. Lukas Hupe(@lhupe) Contributed the lyapunov spectrum calculation for magnetic propagation, implemented the boundary map function and did other contributions in bringing this package to version 2.0 (see here).
  2. Diego Tapias (@dapias) Contributed the lyapunov spectrum calculation method for straight propagation.
  3. David. P. Sanders (@dpsanders) and Ragnar Fleischmann contributed in fruitful discussions about the programming and physics of Billiard systems all-around.
  4. Christopher Rackauckas (@ChrisRackauckas) helped set-up the continuous integration, testing, documentation publishing and all around package development-related concepts.
  5. Tony Kelman (@tkelman) helped significantly in the package publication process, especially in making it work correctly without destroying METADATA.jl.

First Commit


Last Touched

4 days ago


535 commits