**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.

Back to Dr. Record's Resume or proceed to Chapter 2 of Dr. Record's Ph.D. Thesis