Writing system files

On the Try page, “System file (write your own)” lets you write your own system as a short text and ask about it. The quickest start is to load one of the examples' system files with “Template” and edit it.

The simplest example

# a Lyness-type map
name: Lyness type
vars: x, y
params: a = 3, b = 2
map:
  x' = y
  y' = (a + b*y)/x

Line	Meaning
`#` to the end of the line	a comment
`name:`	the system's name (optional)
`vars:`	the variables of a state; states are written in this order (`2, 5` as s means x = 2, y = 5)
`params:`	parameters (rational numbers); “Override parameters” on the Try page (e.g. `a = 5, b = 3`) changes their values
`map:`	the step's formulas, one `x' = …` per variable; `x'` is x one step later

Writing formulas

Allowed: numbers (fractions written with /), the variables, the parameters, + - * /, powers ^ (or **, with a whole-number exponent from 0 to 64), and parentheses.
Formulas are evaluated exactly as written. Where a denominator vanishes the formula is undefined, and an orbit that gets there breaks off (that state is not regular).
sqrt(c) gives the square root of a constant c (no variables inside). It is taken in each finite field; at a prime with no square root, the system cannot be used.
Write formulas in cancelled form. A formula expanded with large common factors left in is still checked correctly, but in minutes rather than seconds.

Ways to give the step

Use exactly one of these:

Written as	The step
`map:` (with an optional `inverse:`)	a rational map given by formulas. The backward formulas `inverse:` may be left out, in which case Structure Computer finds and records them; if given, Q1 says whether they really are the inverse
`field:` and `kahan: h = …`	a quadratic vector field (written `dx/dt = …` or `x' = …`), discretised by Kahan's method with step size h
`use: NAME`	a known system by name, with its parameters in `params:`; the names are in the table below
several `generator NAME:` blocks	a system of several maps (generators); to ask about one of them, enter its name under “Generator” on the Try page
`potential:` and `alpha:`	a discretisation of the geodesics determined by a potential; the state is the pair (x, x') of the previous and the current point, and the potential may contain `log`
`lagrangian: L = …`	the step determined by a discrete Lagrangian written in the variables and their next values (`x'`); the state is (x, x')

A vector field discretised by Kahan's method (the Euler top)

name: Euler top
vars: x1, x2, x3
params: a1 = 1, a2 = 2, a3 = -3
field:
  dx1/dt = a1*x2*x3
  dx2/dt = a2*x3*x1
  dx3/dt = a3*x1*x2
kahan: h = 1/2

A known system by name

name: Lyness by name
use: lyness
params: a = 3

The names use: takes:

Name	System
`lyness`	Lyness map
`kahan-euler`	Euler top (Kahan's method)
`oscillator`	Oscillator
`e2`	Discrete geodesic on a hyperboloid (E2)
`lyness-type`	Lyness-type map
`lyness-rev`	Reverse Lyness-type map
`linear`	Linear map with determinant 1
`parabolic`	Parabolic translation
`translation`	Translation

Two generators

name: two generators
vars: x, y
generator r:
  x' = -y
  y' = x
generator s:
  x' = x + y^2
  y' = y

Examples of potential: and lagrangian: are the example system files “E2 geodesic”, “discrete oscillator” and “quartic midpoint” (also under “Template” on the Try page).

Declaring a symmetry (needed for Q6)

Q6 (holonomy) is answered only when the system file declares a symmetry.

name: rational rotation
vars: x, y
map:
  x' = (3*x - 4*y)/5
  y' = (4*x + 3*y)/5
symmetry:
  so: x^2 + y^2

A quadratic form after so: declares the group of rotations preserving it as a symmetry. The group acts on each block of 2 to 4 coordinates of the state.
A linear symmetry can also be declared by a matrix, as in linear: [[0, -1], [1, 0]]. Q6 uses the so: one.

Systems recognised as known families

Systems of these forms are recognised as known families and answered from theorems, without following the orbit, even for large q:

(x, y) ↦ (y, (a + b y)/x): the Lyness map (b = 1) and Lyness-type maps
(x, y) ↦ ((a + b x)/y, x): their reverse
(x, y) ↦ (p x + q y, r x + s y) with ps − qr = 1: linear maps with determinant 1 (the oscillator among them)
the Kahan discretisation of the vector field (c1 x2 x3, c2 x3 x1, c3 x1 x2): the Euler top

The Lyness map, affine maps with determinant 1 that have a fixed point, and the Euler top are recognised even when written after an affine change of coordinates (x ↦ Mx + c). In every case the formulas must be undefined exactly where the family's are: a system that divides by an extra factor is treated as a different system.

A system that is not recognised is answered by following its orbit up to the walk limit. To keep a system from being treated as a known family, choose “Do not recognise a known family” on the Try page.

Steps on the Try page

Choose “System file (write your own)”.
Pick a close example under “Template”, or start from a blank one.
Enter “Override parameters” and “Generator” if needed.
Enter the states s and t and the field, and press “Compute everything”.

A mistake in the file shows up on the cards as an error with the reason.