Defining the Equations of Motion

We shall use as an example a two-dimensional mapping $f=f_{\alpha,\gamma}$ defined by
\begin{displaymath}
\begin{array}{rcl}
\phi_{j+1} &=& \phi_j + v_j, \\
v_{j+1} &=& \alpha v_j - \gamma \cos(\phi_j + v_j).
\end{array}\end{displaymath} (4.1)

These equations are a model for the dynamics of a ball bouncing on a sinusoidally vibrating table. The variable $\phi$ is proportional to the time, but because of the sinusoidal motion of the table, we may think of $\phi$ as belonging to the circle parametrized by $[0,2 \pi)$. The variable $v$ is proportional to the ball's velocity immediately after contact with the table. The parameter $\alpha$, $0 < \alpha \leq 1$ is the coefficient of restitution for the ball; the parameter $\gamma > 0$ is the amplitude of the table oscillations. Essentially, the equations say that given the time of the $j$th impact ($\phi_j$) and the ball's velocity at that time ($v_j$), we know the time that the ball will next strike the table ($\phi_{j+1}$), as well as the ball's velocity immediately after its next bounce ($v_{j+1}$). See [1] for information about the dynamics of this system.

Suppose that a user wishes to study Equation 4.1 numerically using DsTool. The first task is to define the equations. First, copy the file GENERIC.c to the file that you want to edit. For this example, call the target file bball_def.c. You can use any text editor to edit bball_def.c. The beginning of the file looks like:

#include <model_headers.h>

/* ------------------------------------------------------------------------
   function used to define the vector field or map
   ------------------------------------------------------------------------ */
int user_ds_func(f,x,p)
double *f,*x,*p;
{
}

First change the name of this function from user_ds_func() to bball(). Then edit the function so that it properly defines the mapping. When you are finished, the function should look like:

#include <model_headers.h>

/* ------------------------------------------------------------------------
   function used to define the map
   ------------------------------------------------------------------------ */
int bball(f,x,p)
double *f,*x,*p;
{        
   f[0] = x[0] + x[1];
   f[1] = p[0] * x[1] - p[1] * cos(x[0] + x[1]);
}

The mapping is now defined. We remind novice C-programmers that arrays in C are indexed from 0. When bball() is called, the calling routine is expected to pass in arrays f, x, and p. The input variables are the current state of variables (x) and the current parameters (p):

\begin{eqnarray*}
{\tt x} &=& \{{\tt x[0]}, {\tt x[1]}\} = \{\phi_j, v_j\},\\
{\tt p} &=& \{{\tt p[0]}, {\tt p[1]}\} = \{\alpha, \gamma\}.
\end{eqnarray*}



The function bball() places the new state in the array f:

\begin{eqnarray*}{\tt f} &=& \{ {\tt f[0]}, {\tt f[1]} \} = \{\phi_{j+1}, v_{j+1}\}.
\end{eqnarray*}



This function must be defined in order to begin exploration of dynamics. If the user does not wish to input information about the system's derivative or inverse, and if no auxiliary functions are desired, the user could proceed to Section 4.2.5. For the purpose of illustration, however, we encourage the reader to continue reading.

We remark at this point that although this system is a two-dimensional mapping, the value $x[2]$ contains the current ``time.'' In general, if there are $k$ dependent variables, then x[0], $\ldots$, x[k-1] contain these variables and x[k] contains the independent variable. This is true both for maps and for vector fields.

Adrian Bunk 2001-08-22