Raschii Python API

Documentation of the Raschii Python API, automatically generated from the source code comments.

Main functions

raschii.get_wave_model(model_name: str, air_model_name: str | None = None) → Tuple[AiryWave | StokesWave | FentonWave, FentonAirPhase | ConstantAirPhase]

Get a Raschii wave model by name

raschii.check_breaking_criteria(height: float, depth: float, length: float | None = None, period: float | None = None)

Return two empty strings if everything is OK, else a string with warnings about breaking criteria and a string with warnings about being close to a breaking criterion

  • height: wave height above still water level

  • depth: still water distance from the flat sea bottom to the free surface

    in meters, but you can give -1.0 for infinite depth

  • length: the periodic length of the wave (optional, if not given then period is used)

  • period: the wave period (optional, if not given then length is used) Since we need the wave length we assume Airy to convert period to length!

Wave model classes

Airy waves

Raschii linear waves, see the Airy wave model.

class raschii.AiryWave(height: float, depth: float, length: float | None = None, period: float | None = None, air=None, g: float = 9.81)

Linear Airy waves

  • height: wave height above still water level

  • depth: still water distance from the flat sea bottom to the surface in meters, but you can give -1.0 for infinite depth

  • length: the periodic length of the wave (optional, if not given then period is used)

  • period: the wave period (optional, if not given then length is used)

air

The optional air-phase model

depth: float

The water depth

elevation_cpp()

Return C++ code for evaluating the elevation of this specific wave. The positive traveling direction is x[0]

g: float

The acceleration of gravity

height: float

The wave height

length: float

The wave length

surface_elevation(x: float | list[float], t: float = 0.0, include_depth: bool = True)

Compute the surface elavation at time t for position(s) x

velocity(x: float | list[float], z: float | list[float], t: float = 0, all_points_wet: bool = False)

Compute the fluid velocity at time t for position(s) (x, z) where z is 0 at the bottom and equal to depth at the free surface

velocity_cpp(all_points_wet=False)

Return C++ code for evaluating the particle velocities of this specific wave. Returns the x and z components only with z positive upwards. The positive traveling direction is x[0] and the vertical coordinate is x[2] which is zero at the bottom and equal to +depth at the mean water level.

warnings: str

Warnings raised when generating this wave

write_swd(path, dt, tmax=None, nperiods=None)

NOT IMPLEMENTED FOR AIRY!

Write a SWD-file of the wave field according to the file specification in the Github repository spectral-wave-data ….

  • path: Full path of the new SWD file

  • dt: The temporal sampling spacing in the SWD file

  • tmax: The temporal sampling range in the SWD file is [0, tmax]

  • nperiods: Alternative specification: tmax = nperiods * wave_period

Stokes waves

Raschii implements the Stokes 1st through 5th order wave models, see the Stokes wave model.

class raschii.StokesWave(height: float, depth: float, length: float | None = None, N: int = 5, period: float | None = None, air=None, g: float = 9.81)

Implement Stokes waves based on the paper by J. D. Fenton (1985), “A Fifth-Order Stokes Theory for Steady Waves”.

  • height: wave height above still water level

  • depth: still water distance from the flat sea bottom to the surface in meters, but you can give -1.0 for infinite depth

  • length: the periodic length of the wave (optional, if not given then period is used)

  • N: the number of coefficients in the truncated Fourier series

  • period: the wave period (optional, if not given then length is used)

air

The optional air-phase model

depth: float

The water depth

g: float

The acceleration of gravity

height: float

The wave height

length: float

The wave length

order: int

The approximation order

set_data(data)

Update the coefficients defining this Stokes wave

surface_elevation(x: float | list[float], t: float = 0.0, include_depth: bool = True)

Compute the surface elavation at time t for position(s) x

velocity(x: float | list[float], z: float | list[float], t: float = 0, all_points_wet: bool = False)

Compute the fluid velocity at time t for position(s) (x, z) where z is 0 at the bottom and equal to depth at the free surface

warnings: str

Warnings raised when generating this wave

write_swd(path, dt, tmax=None, nperiods=None)

Write a SWD-file of the wave field according to the file specification in the Github repository spectral-wave-data ….

  • path: Full path of the new SWD file

  • dt: The temporal sampling spacing in the SWD file

  • tmax: The temporal sampling range in the SWD file is [0, tmax]

  • nperiods: Alternative specification: tmax = nperiods * wave_period

Fenton stream-function waves

Raschii implements the Fenton stream-function wave model as described in the Fenton wave model.

class raschii.FentonWave(height: float, depth: float, length: float | None = None, N: int = 5, period: float | None = None, air=None, g: float = 9.81, relax: float = 0.5)

Implement stream function waves based on the paper by Rienecker and Fenton (1981)

  • height: wave height above still water level

  • depth: still water distance from the flat sea bottom to the free surface in meters, but you can give -1.0 for infinite depth

  • length: the periodic length of the wave (optional, if not given then period is used)

  • N: the number of coefficients in the truncated Fourier series

  • period: the wave period (optional, if not given then length is used)

air

The optional air-phase model

depth: float

The water depth

elevation_cpp()

Return C++ code for evaluating the elevation of this specific wave. The positive traveling direction is x[0]

g: float

The acceleration of gravity

height: float

The wave height

length: float

The wave length

order: int

The approximation order

relax: float

The numerical relaxation in the optimization loop

set_data(data)

Update the coefficients defining this stream-function wave

slope_cpp()

Return C++ code for evaluating the surface slope of this specific wave. The positive traveling direction is x[0]

stream_function(x, z, t=0, frame='b')

Compute the stream function at time t for position(s) x

stream_function_cpp(frame='b')

Return C++ code for evaluating the stream function of this specific wave. The positive traveling direction is x[0] and the vertical coordinate is x[2] which is zero at the bottom and equal to +depth at the mean water level.

surface_elevation(x: float | list[float], t: float = 0.0, include_depth: bool = True)

Compute the surface elevation at time t for position(s) x

surface_slope(x, t=0)

Compute the x derivative of the surface elevation at time t

velocity(x: float | list[float], z: float | list[float], t: float = 0, all_points_wet: bool = False)

Compute the fluid velocity at time t for position(s) (x, z) where z is 0 at the bottom and equal to depth at the free surface

velocity_cpp(all_points_wet=False)

Return C++ code for evaluating the particle velocities of this specific wave. Returns the x and z components only with z positive upwards. The positive traveling direction is x[0] and the vertical coordinate is x[2] which is zero at the bottom and equal to +depth at the mean water level.

warnings: str

Warnings raised when generating this wave

write_swd(path, dt, tmax=None, nperiods=None)

Write a SWD-file of the wave field according to the file specification in the Github repository spectral-wave-data ….

  • path: Full path of the new SWD file

  • dt: The temporal sampling spacing in the SWD file

  • tmax: The temporal sampling range in the SWD file is [0, tmax]

  • nperiods: Alternative specification: tmax = nperiods * wave_period

Air model classes

Raschii implements special support for kinematics above the free surface, see Air phase models for details. You can use these to construct a fully divergence-free velocity field for a computational domain with both water and air phases. This is normally not done in lower-order methods such as the typical finite-volume solvers (OpenFOAM etc.), but has been used in a higher-order fully divergence-free DG-FEM solver to construct consistent initial and boundary conditions.

class raschii.FentonAirPhase(height, blending_height=None)

Given a set of colocation points with precomputed surface elevations obtained from a wave model in the water phase, produce a stream function approximation of the velocities in the air phase.

set_wave(wave)

Connect this air phase with the wave in the water phase

stream_function(x, z, t=0, frame='b')

Compute the stream function at time t for position(s) x

stream_function_cpp(frame='b')

Return C++ code for evaluating the stream function of this specific wave. The positive traveling direction is x[0] and the vertical coordinate is x[2] which is zero at the bottom and equal to +depth at the mean water level.

velocity(x, z, t=0)

Compute the air phase particle velocity at time t for position(s) (x, z) where z is 0 at the bottom and equal to depth_water at the free surface and equal to depth_water + depth air at the top free slip lid above the air phase

velocity_cpp()

Return C++ code for evaluating the particle velocities of this specific wave. Returns the x and z components only with z positive upwards. The positive traveling direction is x[0] and the vertical coordinate is x[2] which is zero at the bottom and equal to +depth at the mean water level.

class raschii.ConstantAirPhase(height, blending_height=None)

Constant horizontal velocity equal to the phase speed

set_wave(wave)

Connect this air phase with the wave in the water phase

stream_function(x, z, t=0, frame='b')

Compute the stream function at time t for position(s) x

stream_function_cpp(frame='b')

Return C++ code for evaluating the stream function of this specific wave. The positive traveling direction is x[0] and the vertical coordinate is x[2] which is zero at the bottom and equal to +depth at the mean water level.

velocity(x, z, t=0)

Compute the air phase particle velocity at time t for position(s) (x, z) where z is 0 at the bottom and equal to depth_water at the free surface and equal to depth_water + depth air at the top free slip lid above the air phase

velocity_cpp()

Return C++ code for evaluating the particle velocities of this specific wave. Returns the x and z components only with z positive upwards. The positive traveling direction is x[0] and the vertical coordinate is x[2] which is zero at the bottom and equal to +depth at the mean water level.

Exceptions

exception raschii.RasciiError
exception raschii.NonConvergenceError