[Don Hills]

The following is a "work in progress" of information collected from various sources which may be useful to people using the simulator for QRD modelling etc. I have more work to do on useful cell dimensions corresponding to the available frequencies. (Knowing how many cells correspond to a wavelength at a given frequency makes it possible to do scale models.)

Ripple simulation import/export format.
----------------------------------------
The following information was gathered from reverse engineering and examination of the source code for Version 1.7e of the ripple tank simulation program.

The following example is a 60x60 window with a single wall cell in the middle. It can be pasted into the import/export window of the simulator.

$ 0 60 1 0 false false 50 15 600 1
s 50 20
c 4950 0
w 1 0
l 99
c 4950 0


The first record contains the settings for the checkboxes, menus and sliders.
-------------------------------------
$ 0 # Settings record header
60 # Resolution slider (32x32 to 395x395)
1 # Predefined Setup number
0 # Colour Scheme number - 1
false # Fixed Edges
false # 3-D View
50 # Simulation speed slider (1 to 99)
15 # Frequency slider (1 to 29)
600 # Brightness slider (1 to 1199)
1 # Aux slider (2nd source freq, phase difference etc)


----------------------------------------
Frequency setting:
-------------------
Setting the slider all the way to the left sets the lowest frequency. All subsequent steps are multiples of the original frequency. For example, move the slider all the way to the left (position 1), then two steps to the right (position 3). The frequency will now be 3 times what it was at position 1. The slider position steps correspond to the frequency number in the first record of the import/export data.


Slider position 1 (frequency 1) = lowest frequency
Slider position 2 (frequency 2) = 2x the lowest frequency
Slider position 3 (frequency 3) = 3x the lowest frequency
Slider position 4 (frequency 4) = 4x the lowest frequency
etc...


----------------------------------------
The cell matrix is square. The X and Y sizes are the visible resolution plus 20 or more cells offscreen on all sides.
Resolution (visible) = 32 to 395 cells high and wide
Total cell matrix = 72 to 481 cells high and wide

The width of the offscreen border is determined as follows:

Border width = Resolution / 9, discard remainder.
If the result is less than 20, then Border width = 20.

For example:
Resolution 90: 90 / 9 = 10 (Border = 20)
Resolution 188: 188 / 9 = 20.89 (Border = 20)
Resolution 189: 189 / 9 = 21 (Border = 21)


----------------------------------------
The "s" record type specifies a source location.
Sources are located using x and y coordinates, 0 based from top left.
For example:

s 80 20

s # Source x-y coordinate record
80 # x
20 # y (20 = first onscreen row)


----------------------------------------
The cell matrix is defined in raster format, starting top left at cell 0 and ending bottom right at cell number ((resolution + 40) ^2) - 1
For a 60x60 resolution (100x100 matrix), the cells number from 0 to 9999.
Cells are written in sequence starting from cell 0.


----------------------------------------
The "c" record type specifies empty space.
The medium number represents the wave speed in that cell.
The refractive index of the medium is calculated as sqrt(1-(.5/191)*medium_number).
The following example says, "write 4950 empty cells of medium 0".

c 4950 0

c # Empty space cells record
4950 # Repeat Count
0 # Medium (0 to 191)


----------------------------------------
The "w" record type specifies walls.
The following example says, "write 1 wall cell."

w 1 0

w # Wall cells record
1 # Repeat Count
0


----------------------------------------
The "l" record type specifies a "copy cells above" count.
The following example says, "copy the cell from the row above to this cell, repeat 99 times."

l 99

l # Copy cell(s) from cell(s) above record
99 # Repeat Count


----------------------------------------
Using the example from earlier, which plots a single dot in the middle of the screen:

Matrix is 100 x 100 (visible 60 x 60) = 10000 cells.

c 4950 0 # Write 4950 empty cells (49.5 rows)

w 1 0 # write a single wall cell

l 99 # copy the next 99 cells from the ones above.

c 4950 0 # Write the remainder of the empty cells to the matrix.


The "l" record in the above example appears to be unnecessary, it could be written:

c 4950 0 # Write 4950 empty cells (49.5 rows)

w 1 0 # write a single wall cell

c 5049 0 # Write the remainder of the empty cells to the matrix.

In fact, the import routine will accept this format.


----------------------------------------
Horizontal lines are drawn using multiple wall cells:

w 5 0 # Draw a wall 5 cells wide starting at the current location.


----------------------------------------
Vertical lines are most easily drawn using the copy record. The following example is for a 5 cell high wall, 100 x 100 matrix:

w 1 0 # Draw the top cell of the wall
l 400 # copy the row 4 times

This is much more compact than the following:

w 1 0 # Draw the top cell of the wall
c 99 0 # write empty cells until below the first wall cell
w 1 0 # write the next cell of the wall below the first cell
c 99 0 # write empty cells until below the previous wall cell
w 1 0 # write the next cell of the wall below the previous cell
c 99 0 # write empty cells until below the previous wall cell
w 1 0 # write the next cell of the wall below the previous cell
c 99 0 # write empty cells until below the previous wall cell
w 1 0 # write the last cell of the wall below the previous cell


----------------------------------------
If a wall cell is located on any of the visible screen edges, the wall should be extended from there to the edge of the matrix to prevent "leakage" around it. The program does this automatically when you draw on the screen with the mouse, and you should replicate it if you are generating data for import. You can see how the program handles it by drawing some walls or clicking the "Add Border" button and exporting the result.

For example: 60 x 60 screen (100 x 100 matrix), draw a line from one side of the screen to the other.

This is incorrect:
c 20 0 # offscreen border
w 60 0 # Wall across visible part of the screen
c 20 0 # offscreen border

This is correct:
w 100 0 # Wall across the whole matrix

If you don't do this, the routine that plots the walls from the import data will sometimes draw the walls incorrectly. If none of the walls touch the edge of the visible screen, the problem should not occur.


-----------------------------------------
Resonance:
At frequency = 1,
170 cells between walls = 5/4 cycles.
1/4 cycle = 34 cells