# WaveTools

source: `proteus.WaveTools`

## Usage

This module offers a framework for calculating the free-surface elevation and wave velocities based on various wave theories. Wave theories are organised in classes within the module. The module is written in Python / Cython and C++ for optimising calculation speed.

### Import in command line

Once installed Proteus, you can open a python or ipython command line and type

```
from proteus import WaveTools as wt
```

You can see information on the module (including available classes) by typing:

```
help(wt)
```

and you can see a list of classes and functions by typing

```
wt.__all__
```

Each function or class has documentation info which is accessible by typing

```
help(wt.function)
help(wt.class)
help(wt.class.function)
```

### List of wave theories

Available classes that correspond to wave theories are

`SteadyCurrent`

- Introduce steady currents with ramp time

`SolitaryWave`

- Generate 1st order solitary waves

`MonochromaticWaves`

- Generate linear and nonlinear monochromatic waves. Nonlinear wave theory according to Fenton’s Fourier transform

`NewWave`

- Generate waves according to NewWave theory Tromans et al 1991

`RandomWaves`

- Generate plane random waves from JONSWAP or Pierson Moskovitch

`MultiSpectraRandomWaves`

- Generate random waves by overlaying multiple frequency spectra. Wave spectra can meet in different angles

`DirectionalWaves`

- Generate random waves using JOSNWAP / PM spectra for frequencies and cos-2s/Mitsuyashu spectra for directions

`TimeSeries`

- Generate waves from a given free-surface time series. Time series can be reconstructed using direct or windowed methods

`RandomWavesFast`

- Same as `RandomWaves`

only much more computationally efficient, see Dimakopoulos et al 2019

`RandomNLWaves`

- Generate plane random waves from JONSWAP or RM, using 2nd order theory, following Dalzell’s formulae

`RandomNLWavesFast`

- Same as `RandomNLWaves`

only much more computationally efficient, by using the approach of Dimakopoulos et al 2019

`CombineWaves`

- Generate waves by combining any of the wave theories above

### How to use in Proteus

The wave tools module is loaded at the preample as in the case of the command line:

```
from proteus import WaveTools as wt
```

Then the target wave theory is set, by initializing the relevant class as follows

```
wave = wt.MonochromaticWaves(period=1.,
waveHeight=0.1,
mwl=0.5,
depth=0.5,
g=np.array([0,-9.81,0]),
waveDir=np.array([1,0,0]),
waveType="Fenton",
autoFenton=True,
Nf=8)
```

The wave theory is passed through the `setUnsteadyTwoPhaseVelocityInlet`

boundary condition as follows:

```
tank.BC['x-'].setUnsteadyTwoPhaseVelocityInlet(wave, smoothing=smoothing, vert_axis=1)
```

If the relaxation zone method is used, then the class should be passed through the relevant `setGenerationZones`

function

```
tank.setGenerationZones(x_n=True, waves=wave, dragAlpha=dragAlpha, smoothing = smoothing)
```

Guidance for using the `setUnsteadyTwoPhaseVelocityInlet`

and `setGenerationZones`

functions are given in the BoundaryConditions and Spatial Tools sections of the documentation

Simple examples of usage within the context of a 2D numerical tank can be found in air-water-vv

### How to use as stand-alone tool

After importing the tool in a python interface (command line, editor) following the examples above, you can load a class that corresponds to a wave theory, as follows:

```
wave = wt.RandomWavesFast(Tstart=0.,
Tend=5000.,
x0=np.array([0.,0.,0.])
Tp=2.5,
Hs=0.1,
mwl=0.5,
depth=0.5,
waveDir=np.array([1,0,0]),
g=np.array([0,-9.81,0]),
N=2000,
bandFactor=2.,
spectName="JONSWAP",
Lgen=1.,
Nwaves=16,
Nfreq=32,
checkAcc=True,
fast=True)
```

Then the free surface and velocity for a point in space and time can be calculated as follows:

```
x0 = [1.,0.,0.]
t0 = 0.
U = wave.u(x0,t0)
```

Full time series can be calculated and plotted by appropriately manipulating the calculations and storing in arrays, e.g.:

```
x0 = [1.,0.,0.]
time_array = np.linspace(0,10,1000)
eta = np.zeros(len(time_array),)
for i,t in enumerate(time_array):
eta[i] = wave.eta(x0,t)
import matplotlib.pyplot as plt
plt.plot(time_array,eta)
plt.xlabel("Time (s)")
plt.ylabel("Free-surface elevation (m)")
plt.savefig("Free-surface.pdf")
plt.show()
```