Wave Equation Demo (animation)
Programmed by: Bill Rockenbach
Readme file for:
WaveEqn.exe (Source = WaveEqn.7j in MS QuickBASIC 4.5)
Compiled for IBM PC in an English MS-DOS environment.
This text written: May 3, 1999
(modified: May 30,1999)
---------------------------------------------------------------------
This file:
A. Purpose and disclaimer
B. Files
C. Executing the program
D. Editing and display control functions
E. Active keys and their functions
F. Wave data file generation utility
G. Known problems/limitations
H. Planned future modifications
I. Sample screen shots of WaveEqn display output
J. Download the software and related files
---------------------------------------------------------------------
A. Purpose and disclaimer
This program (WaveEqn) is a toy application based on the Wave
Equation for an ideal one-dimensional string vibrating in a plane.
It uses a simple finite-difference method to compute successive wave
contours, and allows the user to tinker with various initial
waveforms. Error checking is minimal. The program and sample
datafiles referenced here can be found on my website:
http://www2.osk.3web.ne.jp/~brockenb/DosProgs/WaveEqn/WaveEqn_download.shtml
I am making this program available here to anyone who might be
interested in using it "as is." Hence this disclaimer: Use of
this program implies agreement on the part of the user that there are
no guarantees whatsoever, express or implied, regarding the fitness
or applicability of this program under any given circumstances and
that the author of the program will accept no responsibility for any
possible consequences of its use, including, but not limited to,
accidental overwriting or other loss of data.
I do ask, however, that no modifications be made either to the
executable file or to the accompanying documentation and sample
files.
If you find this program useful or have other constructive comments,
I would be happy to hear from you, although I cannot offer "support"
per se for the program. That having been said, however, I will add
that, if you should find a clearly-defined use for the program
and are having trouble with a data set (or sets) that "should work
but don't," I would welcome:
(1) a clear description of the intended use of the program
(2) a clear description of the problem
(3) a complete copy of the problematic data set and how it was
created, so that I can verify it easily
and I will try, if possible, to look into the problem.
---------------------------------------------------------------------
B. Files (executable, readme, utility, sample data, sample images)
81,856 05-28-99 10:43p WaveEqn.exe binary (DOS executable)
28,344 05-31-99 8:34a WaveEqn.htm text (readme)
1,643 05-04-99 12:00a MakeWave.bas text (BASIC utility source)
1,255 05-04-99 12:00a wavedat/sine.txt text (sample data)
1,321 05-04-99 12:00a wavedat/3sines.txt text (sample data)
1,288 05-04-99 12:00a wavedat/2nddeg.txt text (sample data)
1,392 05-04-99 12:00a wavedat/4thdeg.txt text (sample data)
665 05-04-99 12:00a wavedat/blip.txt text (sample data)
557 05-04-99 12:00a gif/sine_1.gif binary (sample image)
17,932 05-04-99 12:00a gif/sine_2.gif binary (sample image)
1,071 05-04-99 12:00a gif/3sines_1.gif binary (sample image)
13,681 05-04-99 12:00a gif/3sines_2.gif binary (sample image)
719 05-04-99 12:00a gif/2nddeg_1.gif binary (sample image)
18,111 05-04-99 12:00a gif/2nddeg_2.gif binary (sample image)
1,024 05-04-99 12:00a gif/4thdeg_1.gif binary (sample image)
12,541 05-04-99 12:00a gif/4thdeg_2.gif binary (sample image)
813 05-04-99 12:00a gif/blip_1.gif binary (sample image)
19,941 05-04-99 12:00a gif/blip_2.gif binary (sample image)
---------------------------------------------------------------------
C. Executing the program
1. Type "waveeqn" from the directory in which the executable
WaveEqn.exe resides, then press a key to clear the opening message
screen.
2. The program is now in Edit mode, showing a flat wave across the
center of the screen. To get a feeling for what the program is
intended to do, press "L" to load one of the sample wavedata files
(sine.txt, 3sines.txt, 2nddeg.txt, 4thdeg.txt, blip.txt) included in
this package. If they are in the current directory, type (say)
"3sines.txt", followed by Enter, to load the data for the wave
defined by
f(x) = sin(x) + sin(2x) + sin(3x)
on the interval (0,pi). (If the sample files are in the subdirectory
"wavedat", then type "wavedat\3sines.txt".)
Alternatively, press "D" from Edit mode to immediately launch
a preset wave motion demo. In this case, you will already be in
Motion mode, so do not press Enter (Change Mode) as described at
the beginning of step 3 below.
3. Now, press Enter (Change Mode) to switch to Motion mode, which
will be signaled visually by a change in the plotted wave's color.
The simulated string will now vibrate in the plane as it would after
being released from rest in the given conformation. Press "T" (Trace
Toggle) to toggle off/on a trace of the wave motion and see what the
wave envelope looks like. Press "V" (Velocity Display) to toggle a
display of the velocity contour of the string, showing which points
along the string are in motion and which are momentarily at rest.
Pressing "T" repeatedly now will add/remove a trace of the velocity
plot. Finally, press Enter again to return to the Edit screen.
Press Escape, followed by any other key, to exit the program.
4. Basically, the above is the kind of dynamic display of wave and
velocity contours that will be generated for any waveform that is
loaded or created within the Edit screen. Please go ahead and try
the other sample wave data files, and then read through the following
explanation of key functions to see how to create/modify your own
simple waveforms, as well as save them to disk. Good luck!
---------------------------------------------------------------------
D. Editing and display control functions
This list of editing and display control functions supported by
WaveEquation is hyperlinked to the following section on individual
active keys and their functions.
1. Switch between Edit and Motion modes
2. Pause/Resume the wave motion in Motion mode
3. Move the cursor horizontally in Edit mode:
to the left end, right end, or center
one edit position to the left or right
to a specified horizontal coordinate location
4. Adjust the wave contour vertically in Edit mode:
one unit (pixel) up or down
to a specified vertical coordinate location
5. Expand/Shrink the display vertically
6. Shift (scroll) the displayed region vertically
7. Display/Hide the velocity profile in Motion mode
8. Display/Hide wave and velocity traces in Motion mode
9. Speed up/Slow down the wave motion in Motion mode
10. Add/Remove damping (friction effect)
11. Display/Hide the wave parameters and status display in Motion mode
12. Display/Hide the potential/kinetic/total energy estimates in Motion mode
13. Load waveform data files from disk
14. Save waveform data files to disk
15. Display a summary of key functions in Edit and Motion modes
16. Launch a wave motion demo from Edit mode
17. Exit the program
---------------------------------------------------------------------
E. Active keys and their functions
1. Enter (Switch between Edit and Motion modes)
Hitting Enter toggles between Edit and Motion modes.
Switching from Edit to Motion mode causes the wave animation to
start anew, as though a string had just been released from the
resting configuration specified at the point of exit from the
Edit screen. Upon first entry into Motion mode after startup of
the program, the Motion display parameters have their original
(default) values; upon second and subsequent entries, they
retain the values they had upon exit from the previous Motion
session, with the exception of the Velocity Display toggle,
which can be changed from within Edit as well as Motion mode.
Switching from Motion to Edit mode clears the screen and resumes
the editing of the waveform from the point at which the previous
Edit session was exited, with the same Edit display parameter
values that were in effect then.
Hitting Enter twice in succession from Motion mode is a
convenient way of clearing the screen and restarting the
animation with the same parameter values.
2. Space bar (Pause display)
Hitting the Space bar pauses the wave animation. From the
paused state, hitting any other key (including the Space bar)
resumes the animation. In the present version of WaveEqn, no
changes in display parameters can be made while in the paused
state.
3a. Home / "C" / End (Move Edit cursor to left end/center/right end)
The Home, "C" and End keys move the Edit cursor to preset Edit
screen locations:
Home: leftmost edit location
C: center edit location
End: rightmost edit location
The Edit cursor is initially situated at the center location.
3b. Left arrow / Right arrow (Move Edit cursor left/right)
The Left and Right arrow keys move the Edit cursor one edit
location to the left or right, respectively. In the present
version of WaveEqn, for editing and motion calculation purposes
the total length of the wave is divided into 120 segments, which
means that the number and locations of string loci whose initial
y-coordinates can be adjusted is fixed. Of these, the left and
right endpoints are assumed to be fixed, leaving 119 editable
locations along the length of the wave. Which edit location is
being accessed by the Edit cursor, as well as its corresponding
x-coordinate, is shown in the Edit parameter display.
3c. "X" (Manually enter x-coord)
Hitting the "X" key results in a request for a manually entered
x-coordinate on the interval (0,pi). After the user has typed
in a coordinate value and pressed Enter, the Edit cursor will be
relocated to the nearest editable location along the length of
the wave contour. If Enter is pressed without any location
request, the current Edit cursor location will remain unchanged.
4a. Up arrow / Down arrow (Change y-coord)
The Up and Down arrow keys move the Edit cursor one screen
location (= one pixel in 640 x 480 monitor display mode) up or
down, respectively. The actual change in y-coordinate depends
upon the vertical Edit display magnification in effect: a higher
magnification allows a finer adjustment of position, while a
lower magnification allows more rapid, coarse adjustment. Note
that since this is a screen (pixel) based method of adjustment,
returning the Edit cursor to its original position may leave the
wave edit location with a y-coordinate different from the
original one, and, in this version of WaveEqn, manual editing of
the y-coordinate will be necessary in order to return the
y-coordinate to its original value.
If this movement of the Edit cursor would result in it "falling
off" the top of bottom of the Edit screen, the display will
automatically scroll so as to keep the Edit cursor visible.
4b. "Y" (Manually enter y-coord)
Hitting the "Y" key results in a request for a manually entered
y-coordinate for the Edit cursor. After the user has typed
in a coordinate value and pressed Enter, the Edit cursor will be
relocated to the Edit screen location closest to the actual
location specified; note that although the displayed Edit cursor
location may only approximate the manually entered value,
the value actually entered (unrounded) will be the one used in
WaveEqn calculations. If necessary, the Edit display will be
scrolled up or down to keep the Edit cursor visible. If Enter
is pressed without any y-coordinate request, the current Edit
cursor location will remain unchanged.
5. "1" / "2" (Shrink/Expand display vertically)
Hitting the "1" or "2" keys results in a vertical rescaling of
the Edit or Motion display: "1" shrinks the display, making more
of a waveform visible, whereas "2" expands it, thereby allowing
more detailed observation of the waveform. Changing the
vertical magnification also results in a change in the
"granularity" of the cursor movement in Edit mode, which can
also be useful. In Edit mode, the Edit screen will be scrolled
automatically if necessary to keep the Edit cursor in view.
6. Page Up / Page Down (Shift display vertically)
Hitting Page Up or Page Down results in shifting (scrolling) the
visible portion of the Edit or Motion display. In Edit mode the
Edit cursor must always remain visible, so the display may not
be shifted so far up or down that the shift would result in
"losing sight of" the cursor. In Motion mode, shifting is
unrestricted (within reasonable limits). The parameter display
indicates the current vertical screen offset, expressed in
pixels (in 640 x 480 monitor display mode).
7. "V" (Velocity display: toggle)
The "V" key toggles the display of the wave's velocity profile
(and trace, if that is also activated) in Motion mode. Toggling
the display on starts the display, whereas toggling it off
clears the current display and blocks subsequent display of the
velocity profile.
The velocity profile display parameter can also be toggled from
within Edit mode. A badly behaved waveform can give rise to an
erratic velocity profile, whose display must be suppressed in
order to permit display of the waveform itself. Of course, the
physical assumptions underlying the validity of the Wave
Equation itself will probably be violated in the case of such a
wave, however.
8. "T" ("trace": toggle)
The "T" key is a toggle for the display of traces for either or
both of: (1) the wave itself, and (2) the associated velocity
contour. If the velocity contour is being displayed, "T"
toggles the display of a velocity contour trace; if not, then
the toggle applies to the waveform trace. Hence, in order to
toggle the waveform trace when a velocity contour is being
displayed, one must first turn off the velocity display with
"V", toggle the waveform trace with "T", then reactivate the
velocity contour display (if desired) with another "V" press.
9. "F" / "S" (Speed up/Slow down display)
A certain default delay is built into the Motion display loop
upon startup of the program. Pressing "F" (="faster")
repeatedly will decrease this delay and thus speed up the
animation somewhat, whereas "S" (="slower") will lengthen the
delay and decrease the speed.
10. "D" / "U" (Damp/Undamp wave motion)
In Motion mode, pressing "D" will add a damping factor
(proportional to the string velocity) by a fixed increment,
while "U" will decrease the damping factor. In Edit mode,
"U" will cancel whatever damping may currently be in effect.
Note: In Edit mode, "D" has the unrelated function of launching
a non-editable wave motion demo.)
11. "P" (Parameter display: toggle)
Pressing the "P" key toggles the display of wave display and
status parameters in Motion mode. The parameters shown are the
following:
File:
Name of the file (if any) containing the wave data currently
loaded into WaveEqn. If this data has been modified
but not saved during the current WaveEqn session, the name
will be followed by an asterisk (*). The display assumes
that DOS 8.3 name conventions have been followed.
Keys: D/S
Time:
Time elapsed in (pseudo-)seconds since entry into Motion
mode. The time is always reset to 0 upon reentry.
Delay:
One increment up (down) corresponds to a rough doubling
(halving) of the length of the built-in delay loop, and
thereby a slowing down (speeding up) of the animation.
Keys: F/S
PixOffset:
Vertical screen display offset. Initially this is 0, with
the wave display in both Edit and Motion modes centered
vertically on the screen. This can be varied independently
(in quarter-screen increments) in each Mode.
Keys: PageUp/PageDown
Y.Scale:
Vertical magnification/compression of the waveform display.
Keys: 1/2 when Velocity display not enabled
V.Scale:
Vertical magnification/compression of the velocity contour
display. Shown only when Velocity display enabled.
Keys: 1/2 when Velocity display enabled
Damping:
Damping (friction) factor. Shown only when damping is
in effect.
Keys: D/U in Motion mode; U only in Edit mode.
Energy estimates:
Shown when Energy display enabled. See "E" below.
Key: E
12. "E" (Energy display: toggle)
Pressing the "E" key toggles the display of the energy display
in Motion mode. The parameters shown are the following:
KE:
Kinetic energy as a percentage of the total and in
pseudounits.
PE:
Potential energy as a percentage of the total and in
pseudounits.
TotE:
Total energy in pseudounits.
These are computed with a simple quadrature formula (Simpson's
rule) based on the wave position at the edit points (= 120 in
this version of WaveEqn). The total energy should, of course,
remain constant in the absence of friction, but the displayed
values fluctuate because of accumulated discretization error in
the wave motion and energy integral calculations.
13. "L" (Load wave data from file)
Pressing "L" in Edit mode initiates a request for the name of a
textfile containing waveform data. Since this program is a
QuickBASIC MS-DOS PC application, the filename given should be
in the 8.3 DOS format. The format of the file is as follows:
[1st line]
Program version header; see sample files
[Subsequent lines]
[Comment lines]
Any line that is empty or whose first character is a pound
sign (#) is treated as a comment line (= ignored).
[Data lines]
Y-coordinates (one per line) of equally spaced points along
the initial waveform. Left and right endpoint values are
assumed to be zero, so these lines are interpreted as being
for interior points on the interval (0,pi). Thus for best
results with this version of WaveEqn, there should be 119
lines of data, corresponding to the 119 interior points of
a 120-segment partition of [0,pi] and describing a
"wave-like" function which is 0 at the endpoints of
[0,pi]. The number of interior points specified is
inferred from the number of lines of data, however, and
values will be interpolated (linearly) to 119 values if
the number of non-empty data lines in the file differs
from this. A simple QuickBASIC program source file for
creating such a file is included in this distribution (see
below) but, of course, requires QuickBASIC (or a
compatible system) for running it. Data files created
from within WaveEqn will automatically be saved in this
format.
14. "S" (Save wave data to file)
Pressing "S" in Edit mode initiates a request for the name of a
textfile to which the current wave data is to be saved. Since
this program is a QuickBASIC MS-DOS PC application, the filename
given should be in the 8.3 DOS format. (The sample files have
been given a .txt extension, but this is not required; any
extension will do.) In the event that the filename given refers
to an already-existing file, the program will offer to overwrite it
after confirmation; however, for safety reasons, this overwrite
request will be refused if the file referred to is not already a
wavedata file in the proper format. See "L" (Load) above for
details.
15. "H" (Help display)
Pressing the "H" key will clear the current Edit or Motion
display and show a help screen consisting of a concise summary
of the key functions applicable to the current mode. Pressing
another key will resume the Edit or Motion session. In
the case of Motion mode, any previous trace displays will have
been erased but the animation will continue uninterrupted.
16. "D" (Launch wave motion demo)
Pressing "D" in Edit mode will launch a preset wave motion
demo. All keys normally active in Motion mode will still be
active. Upon return to Edit mode, the previous waveform
will be reloaded; however, any changes made to display
parameter settings will be retained.
(Note: Pressing "D" in Motion mode has the unrelated function
of adding damping to the wave motion.)
17. Escape (Exit the program)
Pressing Escape will exit the program.
Caution: This version of WaveEqn does not prompt for
confirmation to exit or to save currently loaded wave data.
---------------------------------------------------------------------
F. Wave data file generation utility
For what it is worth, I'm providing the sourcefile for (very simple!)
QuickBASIC program used to create the sample data files included
here. Of course, in order to actually run this program, you'll need
the MS QuickBASIC system, or a compatible one.
---------------------------------------------------------------------
G. Known problems/limitations
* Although it is quite easy to hand-edit a wave in Edit mode and
watch it propagate in Motion mode, the "velocity contour" will
generally be erratic, partially because of the inherent granularity
of the screen editing and partially simply because of the fact
that the computed velocity is very sensitive to sharp bends/kinks
in the waveform.
* In order to avoid run-time errors as much as possible, the program
has been made very quick to issue "wild velocity" messages when
the velocity contour is being displayed, especially with hand-edited
waveforms. Sometimes making the waveform uniformly shallower (e.g.,
by halving all y-coordinates at edit points) will lead to an
"acceptable" velocity plot.
---------------------------------------------------------------------
H. Planned future modifications
* addition of a reset of all parameters to their original defaults
* confirmation of whether or not to save the currently loaded
wave data before exiting the program
* menu-assisted loading/saving of wave data files
* adjustment of Motion display parameters from the paused state
* more control over vertical scaling
* control over the number of points used in editing and calculation
---------------------------------------------------------------------
I. Sample screen shots of WaveEqn display output
---------------------------------------------------------------------
H. Download the software and related files
---------------------------------------------------------------------
[end of readme file]
