\section{The Orbits Window}\label{orbits window}\index{window, Orbits}\index{Orbits window}
%
%
%
\begin{figure}[H]
%\vspace{1.5in}
\centerline{\psfig{figure=ps/orbits.ps,height=185pt}}
\caption{\label{orbits}
The Orbits window.
}
\end{figure}

%
%
%
\begin{description}

\item[Window title:] DsTool:  Orbits
\item[Function:]  The Orbits window allows the user to set conditions for orbit propagation.
\item[Description:] The Orbits window is opened by selecting the Orbits
	option from the Panels menu button located in the Command window.
	The options on this window are used to control the numerical  algorithms used to compute
        trajectories.
%	If unpinned, the panel vanishes when any button is selected.
	
%\item[Window type:] pop-up
%\item[Window attributes:] pinnable(out), resizable, fixed/variable template
\item[Panel items:]\mbox{}
	\begin{itemize}
        \item Start numeric field:
		Displays the number of points to compute before beginning to plot and store data.	
        	Setting this text field to a positive 
		integer means that initial transient behavior will not be displayed. 
        	The default value is $0$.
        \item Stop numeric field:
%\index{stopping conditions}  
		Displays the maximum number of steps that will be taken in computing a trajectory. 
		Depending upon the value of Stopping condition, this field can have different meanings.  
		If Stopping condition is set to Fixed steps, then Stop
        	is used to compute the total number of time steps taken by the propagation
        	routine (see Plot factor field).  If Stopping condition is set to Event stopping or Fixed time, 
		then Stop is used to compute the {\em maximum} number of time steps which the propagation 
		routine may take.  If Stopping condition is set to Poincar\'e section, then Stop is used to 
		compute the maximum number of iterates of the Poincar\'e map.  We assume that
        	the trajectory being computed does not propagate to infinity, and  also that the propagator
        	does not fail in any way. A failure may occur, for example, when trying to implicitly iterate a 
		map backwards.
		The default value is $5000$.
        \item Plot factor numeric field: 
		Displays the number of points to skip between points stored and plotted.  That is,
		the $i$th point calculated will be stored to memory and plotted only if 
        	$i$ is greater than $start$ and $i - start$ is evenly divisible by $plot$.  The exception
        	to this rule is that the initial and final conditions are always stored and plotted.
        	This field is replaced by the Max steps between sections field when Stopping condition is 
		set to Poincar\'e section.   The default value is $1$.
 
        Example:  If the previous three text fields read Start=500, Stop=1000, and Plot=3,
        	then DsTool will calculate 1000 points along a trajectory but will
        	only store the points indexed by 500, 503, 506,..., 998, and 1000 (the final condition is {\em always}
        	kept).   Setting Plot~$= k > 1$ for mappings may be thought of as studying the $k$th iterate of the map.
        	For vector fields, setting Plot~$ > 1$ is useful when it is necessary to choose a small 
		integration step, but we do not want to see every plotted point.

        \item Max steps between sections numeric field:  
		Displays the maximum number of integration steps which the propagation routine may take between
		hitting Poincar\'e sections.
		This field takes the place of the Plot factor field when Stopping condition is set to Poincar\'e 
		section.  If a section is not crossed before taking this many
        	steps, then the propagation routine stops and returns the last plotted point.  
		The default value is $1$.
        \item Step size read-write text field: 
		Displays the initial step size with which to begin vector field integration.
        	This field is only visible if the dynamical system is a vector field.  The default value is $0.01$.  
		Like the Stop field, the interpretation of the value in the Step size field depends upon the value of 
		the stack setting entitled Stopping condition and upon the current choice of the integrator.  
        
        	If the current integrator is a {\em fixed step}\index{integrator, fixed step} algorithm
        	(\eg, the Euler method or a standard fourth order Runge-Kutta method): 
        	\begin{itemize}
        		\item If the Stopping condition is Fixed steps, the size of each integration step is constant 
				and has the value shown in the Step size field.
        		\item If the Stopping condition is Event stopping, the integration step is initially set to the 
				the value shown in the Step size field, and no step size will ever be larger that this 
				value.  The given step size is used by the integration algorithm until an event is 
				detected.  The final step (which may be smaller than the value of Step size)
        			used by the integrator is chosen so that the last point
        			of the trajectory satisfies the given condition even up to some tolerance.
        		\item If the Stopping condition is Fixed time, a new time step is computed for use by the 
        			integration routine.  The new step is less than or equal to the value shown in the Step 
				Size field, but is the largest step which divides that flight time by an integral value.
        		\end{itemize}
 
        	If the current integrator is a {\em variable step}\index{integrator, variable step} algorithm
        	(\eg, quality-control algorithms and the Bulirsch-Stoer method), then 
        	the value shown in the Step size field is used as an initial step size.
        \item Stopping condition stack setting: \index{stopping condition}
		Allows the user to choose the type of event which will terminate
		a trajectory calculation.  There are several options. The exact number depends on whether the
        	current dynamical system is a mapping or a vector field and, if it is a vector field, on the
        	currently installed integrator.  
        	\begin{description}
        		\item[Fixed steps:] 
        			The propagation algorithm will attempt to propagate the trajectory for the number
        			of time steps specified by the Stop read-write field.   This is the default setting.
        		\item[Event stopping:] 
        			The propagation algorithm will halt propagation as soon as {\em any} of the 
        			specified events are satisfied.  An event is specified by typing in a value for an event
				field, and checking the non-exclusive field to the right of that field.
				Any variable or auxiliary function may be used to determine an event.
        			For example, if we wish to propagate a trajectory until the scalar 
				auxiliary function $g$ is zero,
        			then we would type $0.0$ into the event field next to the label for $g$ and check the 
				non-exclusive field to the right of $g$.  If we want to
				propagate until the variable $x$ reaches the value 0.5 {\em or} until the 
				auxiliary function $g$ is 1.0, then we would type both of these values into the 
				event fields labeled by $x$ and $g$ and check both corresponding non-exclusive fields.
				The propagator will stop the first time that {\em any} of the specified events are true.
				The parameters controlling the Newton iterations and tolerance for the event are set in 
				the Propagation window.
        		\item[Fixed time:] The propagation algorithm will attempt to propagate a trajectory until a 
				final value of the independent variable is satisfied.  
				This field only exists when the current dynamical system is a vector field.  
        			The label for this condition is always 
				Fixed {\em indep\_varb} where {\em indep\_varb} is the name of the independent variable 
        			for the current vector field (often ``time'' is used). This is currently implemented by 
        			using Newton's method\index{Newton's method} to solve for a final time step 
        			so that the last point satisfies the condition to within some error tolerance.  The 
				parameters for controlling Newton's method are set in the Propagation window.
		        \item[Poincar\'e section:]\index{Poincar\'e section} The propagation algorithm will 
				set up a section or union of sections as stopping events in the same
                                fashion as Event stopping.  
                                This field exists only when the current dynamical system is a vector field.
                                The trajectory is flowed from
                                the initial condition until the number of
                                events specified by the Stop field have occurred.  Each event starting with the one
                                indicated by the Start field is plotted and saved.  Intermediate points are neither
                                plotted nor saved.  The Max steps between sections field specifies the
                                maximum number of propagation steps which the propagation routine is allowed to take
                                between events before stopping.
        		\end{description}
        \item {\em Name} Event read-write text fields:  
		Displays the values used to define events for stopping conditions.
		If the Stopping condition choice is Fixed steps, then none of these       
        	fields are relevant and trajectories will propagate as described above under the 
		description of Start, Stop, and Plot factor.  If the choice is Event stopping or Poincar\'e section
         	then all dependent variables and auxiliary functions whose Event enable setting is on will be 
		relevant in determining the stopping condition, as described above.  
        	If the choice is Fixed time then only the independent variable is relevant, and only then if 
		its Event enable setting in on. 
	\item {\em Name} Event enable non-exclusive settings:
		Allows the user to choose which events will be relevant to determining stopping conditions.
		Checking any of these settings causes the corresponding variable or auxiliary function to 
		possibly become relevant in determining the stopping condition for the trajectory calculation.
		The relevance of the variable or auxiliary function is determined by the stopping condition
		field, as described above.  
        \item Clear last command button: 
		Deletes the last computed trajectory segment
	        from memory and updates the number of trajectory data points. 
        \item Clear all command button: 
		Deletes all stored trajectory data points, including those generated by the Multiple Orbits
		window.\index{data, deleting}  
	\item Propagation window button:\index{Propagation window}\index{window, Propagation}
		Opens and brings to the foreground the Propagation window.
	\item Forwards command button:
		Begins propagation (\ie, integrating a vector field or iterating a map)  forward
        	in time using the initial condition given in the Initial column of the Selected Point window
		and the settings specified by the above fields.
        \item Continue command button:
                Begins propagation in the current direction, using the
                final point of the last computed trajectory as the initial condition and the settings
                specified by the above fields.  If there is no last trajectory, selecting Continue is equivalent to
                selecting Forwards.  The current direction is ``forward'' if the user selected the
                Forwards button or the SELECT mouse button more recently than the user selected the
                Backwards button or the MENU mouse button. (See Section~\ref{oneDwin} or \ref{twoDwin} for more
                information on the effects of mouse buttons.)
        \item Backwards command button:  
		Begins propagation backwards   
        	in time using the initial condition given in the Initial column of the Selected Point window
		and the settings specified by the above fields.
        	If the installed dynamical system is a map, finding inverse images takes on two meanings.
        	If the map has an explicit inverse, the inverse image is computed explicitly.  If a map does
        	not have an explicit inverse,\index{implicit inverse iteration} 
        	Newton's method\index{Newton's method} is used to determine approximate inverse
        	images.  The Jacobian of the map, the convergence criteria for Newton's method, and other relevant
        	parameters for this numerical procedure may be set by using the Propagation window.
	\item Dismiss command button:
		Closes the Orbits window. 
%  The fields will not revert back to their default values.	
	\end{itemize}
\end{description}	
