## vibration vibration — Add a support to animate the node positions with a phonon frequency. |

## Synopsis

    gboolean            visu_vibration_init                 (VisuData *data,
                                                             guint n,
                                                             guint nNodes);
    gboolean            visu_vibration_getNPhonons          (VisuData *data,
                                                             guint *n);
    gboolean            visu_vibration_setCurrentMode       (VisuData *data,
                                                             guint iph,
                                                             GError **error);
    gboolean            visu_vibration_setDisplacements     (VisuData *data,
                                                             guint iph,
                                                             float *vibes,
                                                             gboolean complex);
    gboolean            visu_vibration_setCharacteristic    (VisuData *data,
                                                             guint n,
                                                             float q[3],
                                                             float en,
                                                             float omega);
    gboolean            visu_vibration_getCharacteristic    (VisuData *data,
                                                             guint n,
                                                             float q[3],
                                                             float *en,
                                                             float *omega);
    void                visu_vibration_setUserFrequency     (VisuData *data,
                                                             float freq);
    guint               visu_vibration_getCurrentMode       (VisuData *data);
    guint               visu_vibration_play                 (VisuData *data);
    gboolean            visu_vibration_stop                 (guint timeoutID);
    void                visu_vibration_resetPosition        (VisuData *data);
    void                visu_vibration_setZeroTime          (VisuData *data);
    gboolean            visu_vibration_setAmplitude         (VisuData *data,
                                                             float ampl);
    void                visu_vibration_buildListSpin        (VisuData *data);
    gboolean            visu_vibration_setUseSpin           (gboolean value);
    gboolean            visu_vibration_isSet                (VisuData *data);

## Description

Define a way to store vibration or phonons to a VisuData object. One can store several phonons in one object, each phonon is them represented by its id. The phonons can be animated on screen, using a user defined frequency (visu_vibration_setUserFrequency) and amplitue (visu_vibration_setAmplitude), by calling `visu_vibration_play()`.

Phonons are set with `visu_vibration_setCharacteristic()` and VisuNode displacements are set with `visu_vibration_setDisplacements()`.

## Details

### visu_vibration_init ()

    gboolean            visu_vibration_init                 (VisuData *data,
                                                             guint n,
                                                             guint nNodes);

Allocate (or reallocate) storage of phonons for `data`. The allocated memory will be automatically freed when `data` is destroyed.

`data` : | a VisuData object.
`n` : | number of phonons to set.
`nNodes` : | number of vibrating nodes.
Returns : | TRUE if `data` has no phonons before.

Since 3.5

### visu_vibration_getNPhonons ()

    gboolean            visu_vibration_getNPhonons          (VisuData *data,
                                                             guint *n);

Retrieves if `data` contains phonons or not. Number of stored phonons is set in `n`.

`data` : | a VisuData object.
`n` : | a location.
Returns : | TRUE if `data` has phonons.

Since 3.5

### visu_vibration_setCurrentMode ()

    gboolean            visu_vibration_setCurrentMode       (VisuData *data,
                                                             guint iph,
                                                             GError **error);

Set all node displacements to zero and setup the displacement vector (u+iv) for each VisuNode. After this call, `visu_vibration_play()` will move the nodes according to their vibration.

`data` : | a VisuData object.
`iph` : | a phonon id.
`error` : | a location for a possible error.
Returns : | TRUE if its the first time VisuNodes are displaced.

Since 3.5

### visu_vibration_setDisplacements ()

    gboolean            visu_vibration_setDisplacements     (VisuData *data,
                                                             guint iph,
                                                             float *vibes,
                                                             gboolean complex);

`visu_vibration_init()` must have been call before. This routine is used to define a set of displacement vectors, corresponding to one phonon. The displacement vectors can be `complex`, in that case `vibes` contains 6 values for each VisuNode.

`data` : | a VisuData object.
`iph` : | a phonon id.
`vibes` : | a set of displacement vectors.
`complex` : | a flag.
Returns : | TRUE on success.

Since 3.5

### visu_vibration_setCharacteristic ()

    gboolean            visu_vibration_setCharacteristic    (VisuData *data,
                                                             guint n,
                                                             float q[3],
                                                             float en,
                                                             float omega);

This routine is used to define the characteristics of a given phonon.

`data` : | a VisuData object.
`n` : | a phonon id.
`q` : | a reciprocal vector.
`en` : | the phonon energy.
`omega` : | the phonon frequency.
Returns : | TRUE on success.

Since 3.5

### visu_vibration_getCharacteristic ()

    gboolean            visu_vibration_getCharacteristic    (VisuData *data,
                                                             guint n,
                                                             float q[3],
                                                             float *en,
                                                             float *omega);

This routine is used to get the characteristics of a given phonon, see `visu_vibration_setCharacteristic()` to set them.

`data` : | a VisuData object.
`n` : | a phonon id.
`q` : | a location for the reciprocal vector.
`en` : | a locattion for the phonon energy.
`omega` : | a location for the phonon frequency.
Returns : | TRUE on success.

Since 3.5

### visu_vibration_setUserFrequency ()

    void                visu_vibration_setUserFrequency     (VisuData *data,
                                                             float freq);

Change the frequency at which phonons are played with `visu_vibration_play()`.

`data` : | a VisuData object.
`freq` : | a frequency.

Since 3.5

### visu_vibration_getCurrentMode ()

    guint               visu_vibration_getCurrentMode       (VisuData *data);

Retrieves the phonon that is currently applied to `data`.

`data` : | a VisuData object.
Returns : | a phonon id.

Since 3.5

### visu_vibration_play ()

    guint               visu_vibration_play                 (VisuData *data);

Make the phonon displace the VisuNode of `data` according to their definitions (see `visu_vibration_setDisplacements()` and `visu_vibration_setCurrentMode()`).

`data` : | a VisuData object.
Returns : | the timer's ID

Since 3.5

### visu_vibration_stop ()

    gboolean            visu_vibration_stop                 (guint timeoutID);

Stop the timer with the given `timeoutID`.

`timeoutID` : | an id.
Returns : | if the timer is indeed removed.

Since 3.5

### visu_vibration_resetPosition ()

    void                visu_vibration_resetPosition        (VisuData *data);

Reset the node position of the given VisuData.

`data` : | a VisuData object.
Returns : | a boolean

Since 3.5

### visu_vibration_setZeroTime ()

    void                visu_vibration_setZeroTime          (VisuData *data);

Reset the position of phonons to use position at time equals zero (so applying just the q vector displacement).

`data` : | a VisuData object.

Since 3.5

### visu_vibration_setAmplitude ()

    gboolean            visu_vibration_setAmplitude         (VisuData *data,
                                                             float ampl);

Change the amplitude at which phonon are displayed on screen when using `visu_vibration_play()`.

`data` : | a VisuData object.
`ampl` : | an amplitude.
Returns : | TRUE if amplitude is actually changed.

Since 3.5

### visu_vibration_buildListSpin ()

    void                visu_vibration_buildListSpin        (VisuData *data);

Make a new list to make OpenGl know that he draw spins or not.

`data` : | a VisuData object.

Since 3.5

### visu_vibration_setUseSpin ()

    gboolean            visu_vibration_setUseSpin           (gboolean value);

Tells openGl if he has to draw the spin/phonons list

`value` : | the value of the checkbox that allow to draw spin or not;
Returns : | TRUE if status changed.

Since 3.5

### visu_vibration_isSet ()

    gboolean            visu_vibration_isSet                (VisuData *data);

Retrieve if `data` has some phonon attached to.

`data` : | a VisuData object.
Returns : | TRUE if `visu_vibration_init()` has been called already.

Since 3.5