High Level API

DynamicalBilliards was created with ease-of-use as its main cornerstone. With 3 simple steps, the user can get the output of the propagation of a particle in a billiard.

In general, the workflow of DynamicalBilliards follows these simple steps:

Create a billiard.
Create particles inside that billiard.
Get the output you want by using one of the high level functions.

Adding more complexity in your billiard does not add complexity in your code. For example, to implement a ray-splitting billiard you only need to define one additional variable, a RaySplitter and pass it to the high level functions.

After reading through this page, you will be able to use almost all aspects of DynamicalBilliards with minimal effort.

Visualizations

Visualizing the billiards, particles, and their motion is one of the most important parts of the DynamicalBilliards. It is not discussed in this page however, but rather in the Visualizing & Animating page.

Billiard

A Billiard is simply a collection of Obstacle subtypes. Particles are propagating inside a Billiard, bouncing from obstacle to obstacle while having constant velocity in-between.

There is a tutorial on how to create your own billiard. In addition, there are many pre-defined billiards that can be found in the Standard Billiards Library section. That is why knowing how to construct a Billiard is not important at this point.

In this page we will be using the Bunimovich billiard as an example:

using DynamicalBilliards
bd = billiard_bunimovich()

Billiard{Float64} with 4 obstacles:
  Bottom wall
  Right semicircle
  Top wall
  Left semicircle

Particles

A "particle" is that thingy that moves around in the billiard. It always moves with velocity of measure 1, by convention.

Currently there are two types of particles:

Particle, which propagates as a straight line.
MagneticParticle, which propagates as a circle instead of a line (similar to electrons in a perpendicular magnetic field).

To make a particle, provide the constructor with some initial conditions:

x0 = rand(); y0 = rand();
φ0 = 2π*rand()
p = Particle(x0, y0, φ0)

Particle{Float64}
position: [0.8351881435134845, 0.8192446867530516]
velocity: [0.39923985891529484, 0.916846516628217]

To create a MagneticParticle simply provide the constructor with one more number, the angular velocity:

ω = 0.5
mp = MagneticParticle(x0, y0, φ0, ω)

MagneticParticle{Float64}
position: [0.8351881435134845, 0.8192446867530516]
velocity: [0.39923985891529484, 0.916846516628217]
ang. velocity: 0.5

When creating a billiard or a particle, the object is printed with {Float64} at the end. This shows what type of numbers are used for all numerical operations. If you are curious you can learn more about it in the Numerical Precision.

You can initialize several particles with the same direction but slightly different position is the following function:

DynamicalBilliards.particlebeam — Function

particlebeam(x0, y0, φ, N, dx, ω = nothing, T = eltype(x0)) → ps

Make N particles, all with direction φ, starting at x0, y0. The particles don't all have the same position, but are instead spread by up to dx in the direction normal to φ.

The particle element type is T.