# Good ViBrations

2009-2014
Pietro Battiston
Pietro Battiston (me@pietrobattiston.it)

This document is made available under the Creative Commons ShareAlike 3.0 License (CC-BY-SA).

This documentation is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE AS DESCRIBED IN THE DISCLAIMER.

A copy of the licence is available here.

Pietro
Battiston
GVB developer
me@pietrobattiston.it
Gvb manual 1.1
January 2014

Pietro Battiston me@pietrobattiston.it

Pietro Battiston

This manual describes version 1.3 of Good ViBrations (GVB).

## Feedback

To report a bug or make a suggestion regarding the Good ViBrations application or this manual, please use the project's Launchpad page.

User manual for Good ViBrations.

## Introduction

Good ViBrations is an application that can simulate 1 and 2-dimensional vibrations.

### Good ViBrations main window

The vast majority of Good ViBrations functionalities can be accessed directly from the main screen:

#### GVB main window

Shows the GVB main window.

On the left, the main action area can be seen, where the simulation is visualized.

On the right are the various controls and indicators: press Start to see them in action.

- Speed: sets the speed at which the simulation evolves.

- Step: in those calculation methods which operate in discrete time (see for more info), this sets the time between an iteration and the following. Notice that the lower the value, the higher will be the precision of the simulation but also the computational effort required.

- Below Step, is the counter, showing how many frames were calculated from the beginning of the simulation.

- calculation ms. shows the milliseconds which were spent, on average, in calculations for each frame (in the last 2 seconds).

- drawing ms. shows the milliseconds which were spent, on average, in graphically rendering each frame (in the last 2 seconds).

- Rope and Membrane allow to switch between (respectively) 1 dimension and 2 dimensions simulations. Changing this will stop and reset the animation.

- Below, the button Start now shows Stop: push it in order to stop the animation.

- Calculation: sets the calculation method used. See for a list of methods and their descriptions.

- Frames/second: sets the number of frames shown per second. Under 20, the animation can appear choppy, but over 25, almost no improvement should be noticed (and the computational effort will increase for calculation methods operating in continuous time).

- Graphics: sets the drawing method used. See for a list of methods and their descriptions.

#### Beware excessive precision!

Speed, Step and Frames/second are key parameters (together with the number of points used - see ) to determine the number of mathematical operations the computer must perform for each second of simulation: if excessive values are chosen, the animation may become choppy, or Good ViBrations may even freeze, becoming unresponsive. In this case, click Stop (only once): in most cases, the interface will be responsive again in few seconds.

### The File menu

The File menu lists some general operations:

- File Open: open a disposition (the definition of points positions and speeds) from a file.

- File Save: save the disposition and speed of points to a file.

- File Save As: save the disposition and speed of points to a new file (if you still didn't save any disposition, this is equivalent to File Save).

- File Quit: exit Good ViBrations.

### The Disposition menu

The Disposition menu allows to set the shape of the string or of the membrane at the start of the simulation. This can be done in two ways:

- by choosing one of the precooked dispositions: a collection of them is available, in both 1 and 2 dimensions,

- by opening the advanced editor, also available for both 1 and 2 dimensions (see ).

### The Options menu

The Options menu allows to configure some aspects of the simulation.

- Options Number of points: change the number of points used in the simulation (see ).

- Options Save frames as png: if this checkbox is toggled, the animation will be saved to disk instead of being rendered to screen: see for more information.

### The Help menu

The Help menu can be used to access informations about the program.

- Help Contents: open this help.

- Help About: show some informations about Good ViBrations.

## Changing the number of points

In Good ViBrations, the string and the membrane are approximated as some points connected by straight lines. The higher the number of points, the higher the quality of the simulation, but also number of computational operations required to perform it. To change the number of points, click Options Number of points.

When this dialog is opened, the animation, if running, will automatically pause and, if the number of points is then indeed changed, will reset to its initial disposition, since Good ViBrations is not able to change the number of points of a running simulation.

While in 1 dimension any number is equally acceptable, in 2 dimensions the points must be placed on a rectangular (and almost square) grid. If the number chosen does not fit, less points will be used. For instance, if the number of points chosen is 11, only 9 will be used (3×3), if it is 14, only 12 will be used (3×4).

### When points are too many

The number of points used is a key factor in determining the computational requirements to perform the simulation: performance may deteriorate very fast with their increase in number, and while some number between 100 and 150 should be acceptable on any computer, a number above those values may cause the interface to be unresponsive (depending also on the calculation method chosen - see - and on the value of the others parameters explained in ).

If you want to observe harmonics, some optimal number can be found in the following way:

- take a number with many small factors, for instance 2×2×3=12,

- substract 1: 11.

- if you want to perform a bidimensional simulation, take its square: 11×11=121.

This example will allow you to observe optimally the second, fourth and third harmonics.

## Drawing methods

Good ViBrations has three different ways of rendering a simulation, both in 1 and 2 dimensions, accessible through the drop-down box:

- wave/3D the points are drawn at different heights (in perspective, if working in 2 dimensions), resulting in something indeed similar to a string or to a membrane;

- speeds is similar to the former, but it also shows the current speed of each point, in the form of a red segment oriented in the direction of movement;

- geo shows the heights as a geographical maps would show altitudes: points are represented by squares, with colours varying from dark blue (lowest points) to light blue, green, brown, dark brown and finally white (highest points).

## The advanced dispositions editor

By clicking Dispositions 1 dimension: advanced or Dispositions 2 dimensions: advanced, the advanced dispositions editor opens. This is a window that allows to configure the starting position of the string or of the membrane interactively, with much more freedom than by just taking one of the precooked dispositions.

### The advanced editor in 2 dimensions

Shows the GVB advanced editor.

On the top, the Graphics drop-down box makes it possible to change the visualization of the disposition in the editor, similarly to what could be done in the main window. Notice that in this case there is no particular difference between wave/3D and speeds, since there is no speed involved.

The advanced editor works by tuning the parameters of given wave shapes and combining them. On the left, a preview of the disposition makes it possible to see changes as they are applied. On the right are the various controls that can be used to tune the shape until it is as desired.

### Dimension-speficic controls

- Waveform: determines the form of the wave to use: can be sinusoidal, triangular, square or just a peak.

- Total lenght: determines the fraction of the available space on which the new shape be applied. It defaults to all of it, but if for instance the cursor is halfway, the resulting shape will occupy only half of space of the simulation.

- Shift: determines if the wave shape must start from the first point (default) or from some other point in the middle. Notice that if the wave shape is shifted, any part that overflows from the right/front border will by placed to the left/back, in a sort of rotation.

- Wavelenght: determines the wavelenght of the wave, which is the space over which its shape repeats, or in other terms the distance between two subsequent peaks of it. It defaults to exactly the whole space, but its value can be tuned down to 4 times less and up to 4 times more.

- Phase: determines the phase of the wave, which is the offset by which the waveform shifted. If Total lenght is set to the maximum, this has exactly the same effect of Shift; if however this is not the case, it can be used to shift/rotate the wave shape inside the range in which it is applied.

- Amplitude: determines the amplitude of the wave, which is the vertical distance between its peaks and the rest line: defaults to the maximum, but can be reduced to scale down vertically the wave shape.

- Centering: determines at which point the waveform must reach its peak: it defaults to the middle - resulting in a symmetric waveform - but can be moved left or right to increase the slope of the shape on the left of the peak and decrease it on the right, or vice versa.

- Reflect: toggling this check substitutes the wave shape with its symmetric with respect to an horizontal axis in the middle.

Those listed so far are properties that are bound to a single dimension: hence, when working in 2 dimensions, two instances of each are available, one in the Horizontal column and one in the Vertical one, applying respectively to the left-right and to the back-front domain.

### General controls

The other options that follow are instead general, applying to 1 or 2 dimensions.

- Invert: toggling or untoggling this check inverts the wave shape, hence changing the height of every point through a reflection on the horizontal plane: what is above will go below, and vice versa.

- Composition rule (only enabled when working in 2 dimensions): since the dimension-specific controls only result in the definition of two particular 1-dimensional wave shapes, which will be oriented one from left to right and one from back to front, here it is possible to establish how those two shapes must then be combined:

  - product: each point's height will be the product of the heights given by the two shapes;
  - sum: each point's height will be the sum of the heights given by the two shapes;
  - maximum: each point's height will be the maximum value it takes among the two shapes;
  - minimum: each point's height will be the minimum value it takes among the two shapes.

- Add to current disposition: if the number of dimensions we are working in is the same as the one currently used in the main window's simulation, it is possible, by toggling this check, to sum the wave form just created to the current state of the simulation. This is a very powerful tool to get arbitrarily complex dispositions, by just adding one wave shape at a time, possibly each restricted to a particular section of the available space.

On the bottom of the window, three buttons are available.

- Revert resets all the regulations to their default values.

- Cancel closes the window, discarding any change made.

- Apply closes the window, applying all changes made.

## Calculation methods

Several calculation methods are available in Good ViBrations, and are accessible from the Calculation drop-down box in the main window.

### Warning, technical details!

This page contains a technically detailed list of the algorythms available in Good ViBrations, and as such it is probably not understandable to readers not practical with the mathematical concepts used. Since it's not necessary to be graduated in math to use Good ViBrations, here's a smaller and simpler summary:

- naif: quite unprecise and slow, no real reason to ever use it;

- matrix: faster than naif, and much less precise;

- quad: more precise, but requires more computational power;

- eig: less precise than quad for very short animations, but the most precise on the long run, since it will not introduce and amplify errors as time passes by: however, it must do some initial calculations, which may take a lot of time and make the program interface become unresponsive before the animation starts, if a high numbers of points is used.

The more detailed list follows.

- naif operates in discrete time: for each time period, it calculates the acceleration of each point, which is equal to the difference between its previous position and the average previous positions of the surrounding point; then it calculates the speed of each point, which is equal to the previous speed plus the acceleration multiplied by the time elapsed (which is given by the Step parameter), and finally the new position of each point, which is equal to the previous position plus the speed again multiplied by time.

- matrix is similar to naif except it doesn't calculate the points singularly, but considers them as a vector, which is updated iteration after iteration through the multiplication by a proper matrix. However such vector contains both positions and speeds: the consequence of this is that positions are updated according to the previous speeds. This makes the method much less stable over time (in particular for large values of Step). This said, computationally wise it can be considered as a benchmark: comparing calculation times with naif's ones gives an idea of how much the underying scipy libraries for matrix computations are able to perform better than native Python code.

- quad is similar to naif, except it doesn't linearize the calculation of speed, which is no more calculated as the simple difference in height with respect to the surrounding points, but instead takes in consideration the "real" distance, including the horizontal component.

- eig operates in continuous time: it takes the linearized problem (as naif), but considers the associated system of differential equations, and computes the exponential of the matrix which determine it: for this step to be accomplished, it must calculate the eigenvalues and eigenvectors of it (through the scipy library). Once this calculation is done, it simply multiplies together the resulting matrix and the diagonal matrix given by the exponentials of the eigenvalues.

## Saving frames as images

When Options Save frames as png is clicked, a dialog will open asking to choose a directory, and the frames will be saved in that directory as png images instead than being rendered to screen. This is useful when they are needed to create a video, or when the complexity of calculation involved is simply to high for them to be seen in real time.

Clicking it again will untoggle the checkbox, and the animation will start to be drawn again to screen.

An easy way to transform the produced images into a video is the following:

- ensure the program `avconv` (part of the library libav) is installed on your system,

- open a terminal and move to the directory containing the images prepared with Good ViBrations,

- give the command `avconv -i %08d.png video.mp4`.