The Topology of Chaos: part.txt
------------------------------------------------------------------------
HOW TO USE THE PART PROGRAM TO COMPUTE GENERATING PARTITIONS
------------------------------------------------------------------------
As shown by Plumecoq and Lefranc (Physica D 144, 231-258 and 259-278),
the topological invariants of an unstable periodic orbit contain a lot
of information about its symbolic dynamics. These topological
invariants how this orbit can be projected on a template. Once an
orbit has been projected on the template, a symbolic name can be
assigned to it using the natural coding on the template (one symbol
per branch). What is fascinating about topological analysis is that
this symbolic name coincides with that obtained in the limit of
infinite dissipation (maps of the interval into itself) and in the
hyperbolic limit (Smale's horseshoe).
------------------------------------------------------------------------
The "part" program makes use of the information obtained from running
"orbcomb" and "findnames" to construct a generating partition. Its
output consists of a picture of the partition aw well as of a
parametric representation of it (through a list of reference points
with corresponding symbol).
------------------------------------------------------------------------
The part program is used in the following way:
part [-w] [-d] [-o orbits] [-p polygon][-i invariants][-t template]...
...[-s partinit] [-n names] [-a attractor]...
...[-f output_name_prefix(=part_out)]
where:
-w : tell part to display partition in a X window
-d : tells part to draw the partition in a postscript file
For the following mandatory options, replace "orbits", "polygon",
"invariants",..., by the actual file names:
-o orbits : specifies the file containing the coordinates of the
periodic points
-p polygon : specifies a file containing a polygon enclosing the
support of the attractor [see papers]
-i invariants : specifies the file containing the invariants of the
periodic orbits contained in "orbits"
-t template : specifies the file describing the template structure,
as output by orbcomb
-s partinit : describes the initial partition.
The following options are not required
-a attractor : specifies a file containing random points in the
attractor if you want to superimpose a picture of the
attractor on the partition.
-f output_name_prefix : specifies a prefix for the various files
output by the programs
------------------------------------------------------------------------
------------------------------------------------------------------------
INPUT
------------------------------------------------------------------------
------------------------------------------------------------------------
------------------------------------------------------------------------
PERIODIC POINTS: FILE FORMAT (-o option)
------------------------------------------------------------------------
Here is an example of file of periodic points. It contains the
intersections of the periodic orbits with the Poincaré section where
the partition will be computed.
1 1
0.830725 -0.0607841
2 2
0.854432 -0.334459
0.909298 0.0981086
3 4
0.826233 -0.167762
0.862034 0.0625477
0.872388 -0.395946
0.922558 0.0818454
[...]
The format is
"orbit number" "period"
x1 y1
x2 y2
... ...
xp yp
Orbit numbers should be 1, 2, 3, ... In the example above, we find the
coordinates for one orbit of period 1, one orbit of period 2 and one
orbit of period 4, whose numbers are (surprise...) 1, 2, and 3.
------------------------------------------------------------------------
ENCLOSING POLYGON: FILE FORMAT (-p option)
------------------------------------------------------------------------
The polygon file contains a list of points which specify a closed
curve. The intersection of the attractor with the Poincaré section
should be entirely enclosed inside the polygon.
0.9006153920 -0.4936898600
0.9018392848 -0.4936898600
0.9030631776 -0.4936898600
0.9030631776 -0.4876137328
0.9042870704 -0.4876137328
[...]
------------------------------------------------------------------------
INVARIANTS: FILE FORMAT (-i option)
------------------------------------------------------------------------
See libtop.txt for a detailed description of the file format. Here is
an example of a file containing 24 orbits with the lowest-period
orbits being the period-1, period-2, and period-4 orbits whose
intersections are given above.
24
0 5 1 0
5 11 2 0 5
31 21 4 0 10 11 10
[...]
------------------------------------------------------------------------
TEMPLATE: FILE FORMAT (-t option)
------------------------------------------------------------------------
See libtop.txt for a detailed description of the file format. Here is
the template file for the example above. It is a reverse horseshoe
with a global torsion of 2.
Examining 2-branch templates
Done
| 5 6 |
| 6 6 |
( 0 -1 )
------------------------------------------------------------------------
INITIAL PARTITION: FILE FORMAT (-s option)
------------------------------------------------------------------------
Here is a simple example for a two-branch template. You are
responsible for choosing the initial partition from which the
algorithm will grow a refined partition. Basically you assign
explicitly a symbol to a number of low-period periodic points. Beware
that the program will never take the freedom to change them so that
your choice is important. If things do not go well, experiment with a
few different initial partitions.
Here is a simple example:
1 1
0
2 1
0
2 2
1
The format is:
"orbit number" "point number"
"symbol"
So the example above specifies that point 1 of orbit 1 should have
symbol 0, point 1 of orbit 2 should have symbol 0, and point 2 of
orbit 2 should have symbol 1. Orbit numbers are the same as in the
orbits file and point numbers correspond to the order in which points
are listed in this file.
The orbits used in this file should have only one possible symbolic
name, so that the ambiguity is only in the cyclic permutation chosen.
Each different symbol should be assigned to at least one point (thus
if the template has n branches, you need at least n reference points
in the initial partitions). Once you have assigned symbols to points
of a periodic orbit, it is more natural to label all the points of the
orbits since you have anyway fixed the cyclic permutation.
------------------------------------------------------------------------
ATTRACTOR: FILE FORMAT (-a option)
------------------------------------------------------------------------
Just a list of points specified by (x,y) coordinates:
0.826233 -0.167762
0.862034 0.0625477
0.872388 -0.395946
0.922558 0.0818454
[...]
You can put as many points as you like (taking into account machine
resources, of course).
------------------------------------------------------------------------
------------------------------------------------------------------------
OUTPUT
------------------------------------------------------------------------
------------------------------------------------------------------------
Assume that you ran part as "part -f example "to have all your output
files prefixed by "example".
Then you should be left with the following files:
$ ls -l example*
-rw-rw-r-- 1 lefranc lefranc 4675 Oct 28 16:55 example_clean.ps
-rw-rw-r-- 1 lefranc lefranc 758 Oct 28 16:55 example_clean.ptn
-rw-rw-r-- 1 lefranc lefranc 7080 Oct 28 16:55 example_end.ps
-rw-rw-r-- 1 lefranc lefranc 3172 Oct 28 16:55 example_init.ps
-rw-rw-r-- 1 lefranc lefranc 6768 Oct 28 16:55 example_mid.ps
-rw-rw-r-- 1 lefranc lefranc 205 Oct 28 16:55 example.pnm
-rw-rw-r-- 1 lefranc lefranc 3676 Oct 28 16:55 example.ptn
-rw-rw-r-- 1 lefranc lefranc 508 Oct 28 16:55 example.tnm
-rw-rw-r-- 1 lefranc lefranc 89 Oct 28 16:55 example.trg
The .ps files (only if you asked for the -d option) are Postscript
files containing pictures of the partition at different stages of the
construction (init, mid, end). The _clean one is the one obtained by
removing all unnecessary reference points.
The .ptn (partition), .pnm (partition names), .tnm (topological
names), .trg (triangles) contain detailed information about the
partition.
An important think to keep in mind while reading what follows is that
the part program works internally with coordinates between 0 and 1 in
all directions so that all coordinates are handled equally.
------------------------------------------------------------------------
PARTITION REFERENCE POINTS (.PTN FILE FORMAT)
------------------------------------------------------------------------
Here is an example:
2
0.821062 -0.49369
0.943452 0.113923
0.0789501 0.71247 0
0.272652 0.26206 0
0.720943 0.973973 1
[...]
The format is :
"number of different symbols"
xmin ymin
xmax ymax
xref1 yref1 sym1 (with coordinates between 0 and 1)
xref2 yref2 sym2
In the example above, the partition has two regions (two symbols), all
points in the original attractor fall inside the square specified by
the points (0.821062, -0.49369) and (0.943452 0.113923). Then the
coordinates (between 0 and 1) and symbols of all the reference points
are given. For example, the first reference points has normalized
coordinates (0.0789501, 0.71247) (use {x,y}{min,max} information to
convert back to natural coordinates) and has been assigned symbol 0.
Note that the _clean.ptn contains only the necessary reference points
(which cannot be removes without changing the symbol of one points in
the attractor)
------------------------------------------------------------------------
PARTITION NAMES (.PNM FILE FORMAT)
------------------------------------------------------------------------
Lists the symbolic names assigned by the final partition to the orbits
in the orbit file.
Here is an example:
0
01
0001
00001
[...]
Orbit 1 has name "0", orbit 2 has name "01", orbit 3 has name "0001",
etc...
------------------------------------------------------------------------
TOPOLOGICAL NAMES (.TNM FILE FORMAT)
------------------------------------------------------------------------
Lists the possible topological names of the orbits.
Here is an example:
orbite 1 : 0
orbite 2 : 01
orbite 3 : 0001
[...]
oops, still in french...
------------------------------------------------------------------------
PARTITION TRIANGLES (.TRG FILE FORMAT)
------------------------------------------------------------------------
Gives the coordinates of the triangles enclosing the border of the
partition.
Here is an example
0.821062 -0.49369
0.943452 0.113923
0.475725 0.959625 0.332894 0.222186 0.54221 0.971802
The first two lines give xmin, ymin, xmax, ymax in the same way as in
the .ptn file.
Each of the following line gives (x,y) coordinates normalized between
0 and 1 of the three vertices of a triangle.
Marc Lefranc