next up previous
Next: Program appearance and Controls Previous: Models distributed with xrk

Tutorial

 

Introduction

This section provides a tutorial introduction to using the xrk\ program. Most of the basic features of the program are covered in this section, but you should read the sections on the menus and control panel to learn more, including features not covered in this tutorial.

Starting xrk

To use the xrk program you should be on one of the CCC Alpha machines. To start the program, issue the following command.

xrk &
After a few moments, the xrk windows should show up on your display.

Main windows

When xrk is first started, two windows appear. One is the control window and the other is a plot display window used for displaying the solution. The control window is the interface to the xrk program. It contains the control panel and the menu bar. The menu bar is at the top with entries File, Change, and Task. The items on the three menus allow the user to access the program features other than the ones directly accessible from the control panel.

At the bottom of the control panel, there are push buttons for starting and stopping integration, clearing the display window, resetting the elapsed time, and a window for displaying the elapsed time. To activate any of these push buttons, or any of the other push buttons in the control panel window, simply click MB1 on it. Note that if an average is being computed, clicking on the Reset time button restarts the computation of the average.

The middle pane of the control panel contains label-text field pairs for setting initial conditions and the values of model parameters. To change the values in one of the text fields, simply click MB1 in the field and edit the entry. Note that changes to the values in the text fields do not take effect until either the Set Variables (for initial conditions) or Set Parameters push button (to set parameter values) is pressed. At the top of the control panel, a non-editable label-text field pair identifies the current model.

Start-up appearance

The following table shows the values that should appear in the text fields in the control panel when you first start the program.

tabular169

If any of the values in the xpde window do not match those in the table, you should change them, as described in the sections on the menus and the control panel. Then continue the tutorial by going to the next section.

Quitting the program

To quit the program, select the Quit item from the File menu. If you are following the tutorial, you should not quit now!

Basic program operations with the linear model

This part of the tutorial introduces some of the basic program operations, using the linear model as an example. Several of the menu item selection operations described below will produce dialog boxes that allow the user to select files, models, or the values of various program parameters. If you are presented with a dialog and are not certain how to proceed, you should look in Section 4 for descriptions of the various types of dialogs and complete information on the menus.

Starting integration

To start integration, click on the Start button in the control panel. The solution should start at the point (1,-2) and spiral in a clockwise direction toward the origin, which is at the center of the plot window. Next, stop the integration, by clicking MB1 on the Stop button.

Setting the plot window scale

If the scale in the plot window is too large or too small, you can change it as in the following example.

  1. Select the Plot ranges item in the Change menu.
  2. Edit the values in the Plot ranges_popup of Minimum x, Maximum x, Minimum y, and Maximum y to be -2.0, 2.0, -1.0, and 1.0, respectively.
  3. Click on the OK button in the Plot ranges_popup window to make your changes take effect. (If you want to keep the Plot ranges_popup window around for further experimentation, you can click on the Apply button instead. If the Plot ranges_popup window obscures part of the display window, you might want to move it out of the way.)

    Then, start the integration by clicking on the Start button. You should see the same spiraling motion, but now you have decreased the scale of the plot window.

About Stopping and re-starting integration

The integration can be stopped at any time by clicking on the Stop button in the control panel. Clicking on the Start button will resume the integration, which will continue until the Stop button is clicked.

It is usually not necessary to stop integration before making changes in model or program parameter values or, for that matter, selecting almost any of the menu items. Any exceptions to that rule will be noted below. On the other hand, it will always be safe to first stop integration, then select a menu item or control panel function, and then re-start integration.

Setting inital conditions

You can restart the integration at the initial point (1,-2) by clicking on the Set Variables button in the control panel. If you have stopped integration, you should click on the Start button to start it again. If you didn't stop the integration, then the program will begin integration at the point (1,-2) as soon as you click on the Set Variables button.

To choose a different initial condition, you can edit the values in the x and y text fields. Try changing the initial condition for x to -1.5 and for y to 0 by editing these text fields. Make sure you click on the Set Variables button to make your changes take effect and then click on the Start button (if necessary) to start integration.

A simpler way to set initial conditions is to just click MB1 at the desired point in the plot window. The coordinates of the point you clicked on will appear in the x and y text fields. As before, your initial conditions don't take effect until you click on the Set Variables button.

Changing parameters

Changing parameters will affect the solution. Try changing the value of a to 0.1 by editing the value in the a text field and clicking on the Set Parameters button. Try a few initial conditions with these parameter values. Instead of spiralling, the solutions should now form closed curves. You might need to erase previous trajectories if they are cluttering up the screen too much. To do this, simply click on the Clear button in the control panel.

Increasing the value of the parameter a further will also cause the solution to start spiralling outward. Try increasing a to the value 0.15. Remember to click on the Set Parameters button to make your change take effect.

Changing the time stepsize

You can slow down or speed up the integration by changing the size of the time step xrk uses. To do this, select the Step information item from the Change menu. This will bring up a dialog box with the title Step information_popup. Edit the value in the Stepsize text field to change the time stepsize. Then click on the Apply button. Integration should either speed up or slow down, depending on whether you increased or decreased the step size. You should be aware that increasing the step size too much can make the integration inaccurate.

As described in Section 4, some dialogs have both OK and Apply buttons. Clicking on the OK button will make the specified changes and dismiss the dialog. Clicking on the Apply button makes the specifed changes but keeps the dialog on-screen. Keeping the dialog around is convenient if a series of changes are desired or if you want to be able to refer to the values.

Saving a complete set

The xrk program allows you to save initial conditions and values of parameters in files, which can be read into xrk later. To do so, select the Save set item from the File menu. This will pop up the Save set file selection dialog box. If necessary, move to the Linear subdirectory by clicking on the appropriate entry in the Directories subwindow and then clicking the Filter button. The Files subwindow should list the file saddle.set.

Next, type the name spiral.set at the end of the string in the Selection subwindow in the Save set dialog and click the OK button. The current values of the solution and parameters have been saved in a file called spiral.set in the Linear subdirectory. We will use this file later in the tutorial.

Note that the xrk program expects the name of a file containing initial conditions and parameter values to end with the extension .set. Since xrk can save other kinds of data files, using this extension is very helpful in organizing your files. Another tip is to organize your saved data by model. For example, all your data for the Linear model should be in directory called Linear.

Reading in a complete set

To load the solution and parameter values from the file saddle.set, select the Read set item from the File menu. The Read set file selection dialog window should appear. Select the saddle.set item in the Files subwindow and then click the OK button.

Since a complete set of initial conditions and parameter values are in saddlel.set, reading this file back in sets the values in the variable and parameter text fields and updates their values in the program. It is not necessary to click on the Set Variables or Set Parameters push buttons after reading in a complete set. These buttons are used only to apply changes made by manually editing the text field values.

Click on the Start button. The solution should move from right to left and leave the plot window. You can tell that the program is still integrating because the elapsed time display window is still being updated. Depending on the value of Stepsize you may see another curve that moves rapidly across the plot window. This is not a a real solution, but a phantom solution caused by numerical instability. The problem is that the solution becomes vary large, and the integration method breaks down. Even if you don't see this phantom solution, you should click on the Stop button to stop integration.

One way to deal with this problem is to stop integration manually when the solution leaves the display window. However, xrk can be set up to do this automatically. Just select the Halt on window exit item from the Task menu. Then click on the Set Variables button to reset the initial conditions and click on the Start button to start integration. The program will now check the solution values and stop integration as soon as they lie outside the display window.

The following table contains some other intial conditions to try with the parameter values in the file saddle.set. You should enter the ones labeled with a * by editing the x and y text fields manually and not by just clicking close to them, because they are very sensitive to small changes.

tabular274

More on Stopping integration on window exit

Having xrk stop integration on window exit is convenient, but you don't always want this. Suppose a solution starting at some initial condition is bounded, but has interesting behavior near some point on the trajectory. You may want to restrict the plot range to a small region containing the interesting behavior, but not stop integration when the trajectory goes out of the window. This can be done by selecting the Don't halt on window exit item from the Task menu.

The start-up behavior of xrk is to not stop integration when the trajectory leaves the display window. Thus the first item in the Task menu reads Halt on window exit when you start the program up. If you select this item, xrk will subsequently stop integration on window exit and the menu item will read Don't halt on window exit. That is, the menu entry toggles and doesn't display the current behavior, but the behavior that can be selected.

Reading and saving parameter sets

To provide more flexibility, the xrk program allows the user to read and save files containing only parameter values. The procedures for reading and saving these files are analogous to those described above for complete sets, you just use the Read Parameters and Save Parameters commands from the File menu and the file extension .par.

Approximating periods

The closed curve solutions we got above with a=0.1 are periodic solutions. Unfortunately, xrk has no provision at present for accurately computing the exact value of the period. However, the following method can be used to approximate the period. With some patience, a fairly accurate value can be obtained.

The idea is to use the Start and Stop buttons and the time display in the control panel as a stopwatch. To increase accuracy, decrease the value of the time stepsize. Also, the Time update parameter in the Step Information_popup can be used to decrease the time interval between updates of the time display.

As an example, we approximate the period of one of the closed curve solutions we got above with a=0.1. To load the solution you saved before in the file spiral.set, select the Read set item from the File menu. The Read set file selection dialog window should appear. Select the spiral.set item in the Files subwindow and then click the OK button. Restart integration, if necessary, and integration should continue in the plot window from the initial condition you saved. First, change the value of a to be 0.1. Then set an initial condition of x = 0 and y=1. Remember that you have to click on the buttons to make your changes take effect. Then select the Step information item from the Change menu. When the dialog box comes up, set the values of Stepsize to be 0.0001 and Time update to be 0.001. Don't forget to click on the Apply button to make your values take effect.

Then, click on the Reset Time button to make sure the time has been reset to zero. Then click on the Start button to start integration. When the trajectory returns to the initial condition, click on the Stop button. An approximation of the period appears in the Time field. When I tried this, I got about 6.39.

This value is probably not very accurate. To improve the accuracy, you need to slow the integration down by decreasing the value of Stepsize. You should try the process again with the Stepsize set to 0.00001. Don't forget to set the initial condition, clear the plot window, and reset the time before starting integration again. With a little paractice and some patience, good approximations of periods can be obtained this way.

Saving a snapshot file

The terminology ``snapshot file'' refers to a file containing a sequence of solutions at regulary spaced time intervals. The user can set the number of solutions in the sequence and the time interval between solutions in the sequence. The default extension for a snapshot file is .snap.

Such a file is intended to be used as input to another program for producing two-dimensional plots. A Maple program called dataplot is available at WPI to do this. Other programs could be used to plot the data in a snapshot file; see the section on file formats for details of how the data is saved in a snapshot file.

The procedure for saving snapshots is a little involved, so some planning is needed beforehand. For example, the solution you wish to save should be loaded into xrk before you start the procedure. You should also know over what time interval you want to take snapshots. It may also be convenient to set the value of Stepsize to be this time interval divided by a suitable power of ten. For example, to capture one period of the solution in the previous example, a suitable time step would be 0.0064 or 0.00064.

Once you have decided on the time interval for collecting snapshots, you need to decide how many snapshots to collect. A rough guideline is to select the fewest that will resolve the solution behavior.

The actual procedure for saving a snapshot file is as follows. An example of the procedure follows the list.

  1. Stop integration. Set initial conditions and parameter values, if necessary.
  2. Set the value of Stepsize to be the total time interval desired divided by a suitable power of ten.
  3. Select the Snapshot parameters item in the Change menu.
  4. Set the value for Number of snapshots. Suppose that you want to divide the total time interval for snapshot collection into tex2html_wrap_inline1319 equal subintervals. Since xrk saves its first snapshot before integration actually starts, you should set Number of snapshots to be tex2html_wrap_inline1321 to get a snapshot exactly at the end of the time interval.
  5. Set the value of Snapshot steps to be the number of time steps of size Stepsize between snapshots. For example, suppose that about 100 snapshots were desired and total time over which snapshots are to be collected is 6.4. If the value of Stepsize is set to be 0.00064, then there are 10,000 time steps in the entire interval. Then appropriate values to use are 101 for the Number of snapshots and 100 for the Snapshot steps. For a value of 0.0064 for the stepsize, appropriate values would be 101 for the Number of snapshots and 10 for the Snapshot steps.
  6. Click on the OK or Apply button in the Snapshot_popup dialog.
  7. Select the Snapshot file item in the File menu. This will pop up the Snapshot file dialog. Type a name for your file in the Selection subwindow and click on the OK button. This step must be carried out before each attempt to save snapshots, even if the snapshot parameters are unchanged.
  8. Click on the Start button. Snapshots will automatically be saved. A message dialog will pop up with the message
    Snapshot file complete
    when all of the snapshots have been saved.

For example, suppose you wanted to save a snapshot file over one period of the solution from the previous example. Set your initial conditions and parameter values, if necessary, and then follow the steps listed below.

  1. Click on the stop button, if necessary, to stop integration.
  2. Set the value of Stepsize to be 0.0064, which divides the total interval of 6.4 into 1000 subintervals.
  3. Select the Snapshot parameters item in the Change menu.
  4. Set the value of Number of snapshots to be 101.
  5. Set the value of Snapshot steps to be 10, which is 1000/100.
  6. Click the Apply button in the Snapshot_popup dialog.
  7. Set the snapshot file to be test.snap in the Linear subdirectory, using the Snapshot file item in the File menu as described above.
  8. Click on the Start button in the control panel.

Further examples - the nonlinear pendulum model

As described in 2, the nonlinear pendulum is described by the following system of differential equations.

eqnarray73

In this section we will learn how to change models and get some more practice using xrk.

Changing models

To switch to the nonlinear pendulum model, select the Model item in the Change menu. When the model list selection dialog appears, select Pendulum from the list and click on the OK button. The display window should blank out and the control panel should go blank briefly and then the label-text field pairs for the model's two parameters should appear.

Undamped nonlinear pendulum

By default, the nonlinear pendulum model comes up with parameter values a=0 (no damping) and b=3. The model equations are periodic in x with a period of tex2html_wrap_inline1357 , so good values for the minimum and maximum x in the plot window are -6.5 and 6.5. Appropriate values for the y limits are -6 and 6.

The best way to get a good idea of the behavior of this model is to try lots of initial conditions. The fastest way to do this with xrk\ is to first set it up so integration is not stopped on window exit. Then set an initial condition and start integration. While xrk\ is integrating, select the next initial condition by clicking in the plot window. When you are ready to start integration from there, click on the Set Variables button. It is not necessary to stop integration and start it again. You should try enough initial conditions to give you a clear picture of how this model behaves.

Damped pendulum

To add a little damping, change the value of a to be 0.1. Then use the same procedure as in the previous section to investigate the behavior of this model.


next up previous
Next: Program appearance and Controls Previous: Models distributed with xrk

William W. Farr
Fri Oct 25 13:53:45 EDT 1996