Chapter 1 Getting Started

1.0 Assumptions and notational conventions

In what follows, an introductory knowledge of UNIX, X11 graphical clients, and discrete dynamical systems is assumed. Should you need assistance in these areas, please see the references listed in Appendix A. I will attempt to denote references to UNIX commands, filenames, X11 graphical clients and servers by displaying these in bold type. For example, the UNIX command cp can be used to copy the endo binary to the /usr/bin/X11 directory if so desired. References to dynamical systems terminology will be italicized. Optional command line arguments will be enclosed in braces as in "-w val1 [val2]".

1.1 Requirements

Endo is an X11 graphical client. It is written in the C programming language and is highly portable across a wide variety of computer architectures. In order to run endo , your computer system must be running an X server. The X server is available from the X Consortium and through a wide variety of commercial vendors. You will also need access to an X development system and compiler in order to build endo from source. Finally, your system will need sufficient memory and disk space. On most systems, 8 Mb of memory is sufficient. The endo binary, objects, source and scripts consume under 2 Mb of disk space. However, you may want to reserve additional disk space for saved images as endo allows you to dump the contents of any of its windows to a file.

1.2 Obtaining the source

Assuming you have an X server and development system, your first step will be to acquire the software. Endo has been submitted to the Usenet Newsgroup comp.sources.x and the latest version is archived at ftp.uu.net. It has also been accepted as contributed software for the X11 R6 distribution available from the X Constortium. You can retrieve the source via anonymous ftp to ftp.uu.net, ftp.x.org or any other site that archives comp.sources.x. In addition, a copy of the software on a 3.5" MS-DOS format diskette should accompany this document. Additional copies or alternate formats can be obtained from the author by e-mailing a request to rr@ronrecord.com .

1.3 Building

After acquiring and extracting the source onto your system, the next step will be building the endo binary. First, cd into the endo source directory. Execute the command Build in the current directory. This Bourne Shell script will attempt to execute the xmkmf program. If it is not found, it will attempt to execute the imake command. If neither the xmkmf or imake programs are found, the X development system may not be installed on your system. Install the X development system and re-execute the Build script. If you are unable to install an X development system or if imake is unavailable, a standard Makefile called Makefile.std is provided for use with the make program. If xmkmf or imake are found, the Build script then executes the make program and proceeds to compile the endo source modules. After compiling these successfully, the endo binary will be linked.

1.4 Installing

You are now ready to install the endo software package. Execute the Install script in the current directory. This script checks to see if you are the root user. If so, it copies the endo distribution to /usr/local/bin and /usr/local/lib/endo. If you do not have root permissions, the endo binary is copied to $HOME/bin and the endo scripts are copied to $HOME/lib/endo.

To summarize, in order to build and install endo it is only necessary to execute the Build and Install scripts in the endo source directory.

1.5 Basic Definitions

The following brief definitions of a few of the terms used in this document should suffice to get you started. As the terms become more familiar and especially when used in conjunction with the software, these definitions should become more clear.

basin of attraction - For an attractor, those points whose trajectories eventually lead to the attractor. One of the five main endo windows displays the basins of attraction. In most of the provided color palettes, colors indicate with which attractor the basin is associated, and shades of that color indicate the rate at which that point's trajectory is approaching its attractor.

bifurcation diagram - For maps in one dimension, the bifurcation diagram was usually a figure in two dimensions with the horizontal axis representing a parameter interval and the vertical axis representing an interval in the domain. Points were plotted on this diagram by iterating the map for each of a discrete number of parameter values in the selected interval. In the two dimensional case, bifurcation diagrams are presented in a variety of ways. All of these involve one axis representing a parameter interval and two axes representing a rectangle in the domain. The system is run without recording for a specified number of iterations to allow for the passing of "transients".

command line switch (also referred to as an argument, switch, or option) - A string or strings, usually beginning with a '-' and optionally followed by numeric values. These strings are parsed by the UNIX shell and processed as arguments to the command.

critical curve - The 2-D analog of critical points in 1-D maps. That is, those points for which the determinant of the Jacobian of the map is zero. One of the five main endo windows displays the critical curves and their iterates.

determinant of the Jacobian - The calculation of the critical curves and Lyapunov exponents utilizes the determinant of the Jacobian matrix of the map at a point. This is simply the determinant of the matrix of partial derivatives, , where the map is defined by

(x, y)(f(x, y), g(x, y)).

See one of the references in Appendix A for more information.

domain of iteration - Although the map may be defined on the entire plane, endo uses a finite grid for its domain of iteration. The grid size and location is determined by the window width and height and by the user specified minimum and maximum x and y values.

dwell - The number of iterations which will be plotted.

endomorphism - A mapping of a set into itself, usually noninvertible. That is, the pre-image of a point is not always unique. Typically, a planar endomorphism will "fold", "stretch", and "rotate" the plane.

Mandelbrot set - This familiar term is used in a more general sense in this document. It refers to those parameter values for which the point trajectory is not attracted to infinity.

initial conditions - The x and y values used to begin the iteration process.

iteration - Repeatedly using the output of a map as its input. If the map is defined as :

(x, y)E(x,y) (F(x, y), G(x, y))

then the second (forward) iterate would be :

E(E(x,y)) = (F(F(x, y), G(x, y)), G(F(x, y), G(x, y)))

Lyapunov exponent - A measure of the rate at which the trajectories of nearby points diverge. Two negative Lyapunov exponents are indicative of point or periodic attractors. A positive Lyapunov exponent is one characteristic of chaotic dynamics. One of the five main endo windows graphically displays the Lyapunov exponents.

parameters - A map of the plane is sometimes specified with constants and parameters as well as variables. Endo uses x and y as its two spatial variables. Each of our included maps has two or more parameters that can be varied. Varying a parameter can produce changes in the dynamics (e.g. a bifurcation from a fixed point attractor to a period two attractor).

precritical curves - Those points whose trajectory eventually lies on the critical curve. One of the five main endo windows displays precritical curves.

settle - The number of iterates to calculate prior to plotting a trajectory.

trajectory - The trajectory of a point is the set of all its iterates. That is, the trajectory of the point (x,y) is the set :

(x,y), (F(x,y),G(x,y)), (F(F(x,y),G(x,y)),G(F(x,y),G(x,y))) ... or, letting E(x,y)=(F(x,y),G(x,y)), the set { (x,y), E(x,y), E(E(x,y)), ...}.

One of the five main endo windows displays trajectories.

view - The five main endo windows each represent a dynamical view. These views are the basins of attraction, Lyapunov exponents, point trajectories, critical curves, and precritical curves. The point trajectories view becomes a bifurcation diagram when the Lyapunov exponents view is selected and a view of the attractor(s) when the basins of attraction view is selected.

1.6 Adding a new map

To alter an existing map's definition or add a new map to endo 's menu of maps, the endo source files must be modified and the endo binary recompiled. To do so, follow these steps :

Edit endo.h and add the pair, double, PFP, PFD, and Mapnames declarations. Follow the example set by the "standard" map or any of the existing maps.

Edit maps.c and add the map and derivative function definitions. Again, follow the example set by mimicking the standard() and dstandard() functions.

Edit params.h adding the numerical values to use in the amins, aranges, bmins, branges, pmins, pmaxs, and defparms arrays. In each case, when adding the map, you will be adding the value in the array (which may itself be an array).

Edit defines.h, incrementing NUMMAPS and increasing NUMDEFS by 2.

Edit info.c, adding a string representation of the map definition to the Mapdefs[] array and an entry in the numparams[] array indicating how many parameters the map has.

Execute the command "make clean; make tags; make" and copy the resulting endo binary to the installation directory.

An alternative to adding a new map is replacing an existing map. This process is somewhat easier and quicker. To do so, only maps.c, params.h, and info.c in the above process need to be edited. Choose a map to replace and modify these three files, altering the map and map derivative definitions in maps.c, default numerical values in params.h, string representation and number of parameters in info.c. Then recompile using the command above.