Raschii Python API¶

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

Main functions ¶

raschii.get_wave_model(model_name: Literal['Airy', 'Fenton', 'Stokes'], air_model_name: Literal['FentonAir', 'ConstantAir']) → tuple[type[WaveModel], type[AirPhaseModel]]¶

raschii.get_wave_model(model_name: Literal['Airy', 'Fenton', 'Stokes'], air_model_name: None) → tuple[type[WaveModel], None]

Get a Raschii wave model by name (returns the class, not an instance)

If you want to use an air-phase model, you can specify it with the air_model_name argument and the air-model class will be returned as the second element of the tuple, otherwise the second returned element will be None.

Returns a tuple of (wave_model_class, air_model_class | None)

raschii.check_breaking_criteria(height: float, depth: float, length: float | None = None, period: float | None = None) → tuple[str, str]¶

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!

Example of use:

err, warn = check_breaking_criteria(wave_height, water_depth, wave_length)
if err:
    print(err)
if warn:
    print(warn)
if err:
    raise RaschiiError("Breaking criteria exceeded, see above for details")

Wave model API summary ¶

All three wave model classes (AiryWave, StokesWave, and FentonWave) share the following attributes and methods.

Attributes and methods available on all wave models¶
Attribute / Method	Description
`height`, `depth`, `length`, `period`, `g`	Constructor input parameters, stored as instance attributes.
`omega`	Angular frequency [rad/s] (attribute).
`k`	Wave number [1/m] (attribute).
`c`	Phase speed [m/s] (attribute).
`warnings`	String with any warnings raised during construction (empty if none, attribute).
`surface_elevation(x, t=0, include_depth=True)`	Free-surface elevation. Returns a scalar when both x and t are scalar, an ndarray otherwise (NumPy scalar-in / scalar-out convention).
`velocity(x, z, t=0, all_points_wet=False)`	Fluid velocity at each (x, z) point. Shape `(2,)` for scalar inputs, `(N, 2)` or `(T, N, 2)` for array inputs.
`velocity_potential(x, z, t=0)`	Earth-frame velocity potential φ (mean flow excluded). Same scalar/array convention as `surface_elevation`.
`write_swd(path, dt, tmax=None, nperiods=None, amp=1)`	Write the wave field to a file in the SWD format.
`cpp`	C++ code generator (experimental — see C++ code generators).

The following methods are only available on specific wave model classes.

Methods available on specific wave models only¶
Method	Description	Available on
`stream_function(x, z, t=0, frame=Frame.EARTH)`	Stream function ψ. Use `Frame` to choose the reference frame (`Frame.EARTH` or `Frame.WAVE`).	`FentonWave`
`surface_slope(x, t=0)`	Horizontal derivative dη/dx of the free-surface elevation.	`FentonWave`
`acceleration(x, z, t=0, all_points_wet=False)`	Fluid acceleration. Water-phase only; returns zero above the free surface (air blending is not yet implemented for accelerations).	`FentonWave`

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: AirPhaseModel | None = 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: AirPhaseModel | None¶: The optional air-phase model

c: float¶: Wave celerity (phase speed) in [m/s]

cpp: AiryCppGenerator | FentonCppGenerator | StokesCppGenerator | None¶: The C++ code generator for this wave model, to be defined in subclasses

depth: float¶: The water depth

g: float¶: The acceleration of gravity

height: float¶: The wave height

k: float¶: Wave number (2 * pi / wavelength) in [1/m]

length: float¶: The wave length

omega: float¶: Wave angular frequency in [rad/s]

period: float¶: Wave period in [s]

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

Returns a scalar when both x and t are scalar, an ndarray otherwise. Output shape follows the NumPy convention (scalar in → scalar out):

scalar x, scalar t → scalar
array x (N), scalar t → (N,)
scalar x, array t (T) → (T,)
array x (N), array t (T) → (T, N)

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.

Output shape:

(2,) if x, z, and t are scalar
(N, 2) if x/z are arrays and t is scalar
(T, 2) if x/z are scalar and t is an array
(T, N, 2) if x/z are arrays and t is an array

Compute the earth-frame velocity potential φ at time t for position(s) (x, z).

z is measured from the sea floor (z=0 at bottom, z≈depth at calm surface). The gradient of φ equals the oscillatory fluid velocity as returned by velocity(); the mean-flow current term is excluded.

Returns a scalar when both x/z and t are scalar, an ndarray otherwise. Output shape:

scalar x/z, scalar t → scalar
array x/z (N), scalar t → (N,)
scalar x/z, array t (T) → (T,)
array x/z (N), array t (T) → (T, N)

warnings: str¶: Warnings raised when generating this wave

write_swd(path, dt, tmax=None, nperiods=None, amp: int = 1)¶

Write a SWD-file of the wave field.

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
amp: SWD amp flag (1, 2, or 3). Default is 1.
- 1: store potential coefficients at z=0 (calm surface)
- 2: store potential coefficients on the actual wavy free surface
- 3: store elevation only (no potential data)

Implemented via a Stokes N=1 wave (analytically identical to Airy theory).

See the SWD documentation for the details:

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: AirPhaseModel | None = 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: AirPhaseModel | None¶: The optional air-phase model

c: float¶: The wave celerity [m/s], to be defined in subclasses

cpp: AiryCppGenerator | FentonCppGenerator | StokesCppGenerator | None¶: The C++ code generator for this wave model, to be defined in subclasses

depth: float¶: The water depth

g: float¶: The acceleration of gravity

height: float¶: The wave height

k: float¶: The wave number

length: float¶: The wave length

omega: float¶: The wave angular frequency [rad/s], to be defined in subclasses

order: int¶: The approximation order

period: float¶: The wave period [s], to be defined in subclasses

set_data(data)¶: Update the coefficients defining this Stokes wave

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

Returns a scalar when both x and t are scalar, an ndarray otherwise. Output shape follows the NumPy convention (scalar in → scalar out):

scalar x, scalar t → scalar
array x (N), scalar t → (N,)
scalar x, array t (T) → (T,)
array x (N), array t (T) → (T, N)

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.

Output shape:

(2,) if x, z, and t are scalar
(N, 2) if x/z are arrays and t is scalar
(T, 2) if x/z are scalar and t is an array
(T, N, 2) if x/z are arrays and t is an array

Compute the earth-frame velocity potential φ at time t for position(s) (x, z).

z is measured from the sea floor (z=0 at bottom, z≈depth at calm surface). The gradient of φ equals the oscillatory fluid velocity as returned by velocity(); the mean-flow current term is excluded.

Returns a scalar when both x/z and t are scalar, an ndarray otherwise. Output shape:

scalar x/z, scalar t → scalar
array x/z (N), scalar t → (N,)
scalar x/z, array t (T) → (T,)
array x/z (N), array t (T) → (T, N)

warnings: str¶: Warnings raised when generating this wave

write_swd(path, dt, tmax=None, nperiods=None, amp: int = 1)¶

Write a SWD-file of the wave field.

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
amp: SWD amp flag (1, 2, or 3). Default is 1.
- 1: store potential coefficients at z=0 (calm surface)
- 2: store potential coefficients on the actual wavy free surface
- 3: store elevation only (no potential data)

See the SWD documentation for the details:

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: AirPhaseModel | None = None, g: float = 9.81, relax: float = 0.5, maxiter: int = 500, num_steps: int | None = None)¶

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)

acceleration(x: float | NDArray, z: float | NDArray, t: float | NDArray = 0.0, all_points_wet: bool = False)¶

Compute the horizontal and vertical fluid acceleration at each position (x, z) at each time t.

Note

This method is water-phase only. Acceleration above the free surface is set to zero when all_points_wet=False (the default). Air-phase blending for accelerations is not yet implemented. If an air model is attached and you query points above the free surface with all_points_wet=False, a RaschiiError is raised.

Parameters¶

xfloat | array: Horizontal position(s).
zfloat | array: Vertical position(s) where z = 0 at the sea floor and z = depth at the free surface.
tfloat | array, optional: Time(s) at which to compute the acceleration (default 0).
all_points_wetbool, optional: If True, evaluate the wave formula at all points regardless of whether they are above the free surface. Useful for testing.

Returns¶

ndarray: Shape (2,) for scalar inputs, (N, 2) for array points and scalar time, (T, 2) for scalar point and array time, (T, N, 2) for array points and array time.

air: AirPhaseModel | None¶: The optional air-phase model

c: float¶: The wave celerity [m/s], to be defined in subclasses

cpp: AiryCppGenerator | FentonCppGenerator | StokesCppGenerator | None¶: The C++ code generator for this wave model, to be defined in subclasses

depth: float¶: The water depth

g: float¶: The acceleration of gravity

height: float¶: The wave height

k: float¶: The wave number [1/m], to be defined in subclasses

length: float¶: The wave length

omega: float¶: The wave angular frequency [rad/s], to be defined in subclasses

order: int¶: The approximation order

period: float¶: The wave period [s], to be defined in subclasses

relax: float¶: The numerical relaxation in the optimization loop

set_data(data)¶: Update the coefficients defining this stream-function wave

stream_function(x, z, t=0, frame=Frame.EARTH)¶

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

frame: Frame – Frame.EARTH (default) includes the constant base-flow term; Frame.WAVE returns only the oscillatory part.

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

Returns a scalar when both x and t are scalar, an ndarray otherwise. Output shape follows the NumPy convention (scalar in → scalar out):

scalar x, scalar t → scalar
array x (N), scalar t → (N,)
scalar x, array t (T) → (T,)
array x (N), array t (T) → (T, N)

surface_slope(x, t=0)¶: Compute the x derivative of the surface elevation at time t

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.

Output shape:

(2,) if x, z, and t are scalar
(N, 2) if x/z are arrays and t is scalar
(T, 2) if x/z are scalar and t is an array
(T, N, 2) if x/z are arrays and t is an array

Compute the earth-frame velocity potential φ at time t for position(s) (x, z).

z is measured from the sea floor (z=0 at bottom, z≈depth at calm surface). The gradient of φ equals the oscillatory fluid velocity as returned by velocity(); the mean-flow current term is excluded.

Returns a scalar when both x/z and t are scalar, an ndarray otherwise. Output shape:

scalar x/z, scalar t → scalar
array x/z (N), scalar t → (N,)
scalar x/z, array t (T) → (T,)
array x/z (N), array t (T) → (T, N)

warnings: str¶: Warnings raised when generating this wave

write_swd(path, dt, tmax=None, nperiods=None, amp: int = 1)¶

Write a SWD-file of the wave field.

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
amp: SWD amp flag (1, 2, or 3). Default is 1.
- 1: store potential coefficients at z=0 (calm surface)
- 2: store potential coefficients on the actual wavy free surface
- 3: store elevation only (no potential data)

See the SWD documentation for the details:

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=Frame.EARTH)¶

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

frame: Frame – Frame.EARTH (default) includes the constant base-flow term; Frame.WAVE returns only the oscillatory part.

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

class raschii.ConstantAirPhase(height, blending_height=None)¶

Air phase model with zero velocity in the earth frame (still air).

The wave-frame stream function contains a backward drift at the wave phase speed, which allows divergence-free blending with the water-phase velocity field across the free surface.

set_wave(wave)¶: Connect this air phase with the wave in the water phase

stream_function(x, z, t=0, frame=Frame.EARTH)¶

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

frame: Frame – Frame.EARTH (default) returns zero (still air in the earth frame); Frame.WAVE returns -c*z (air appears to move backward at the wave phase speed in the co-moving frame).

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

Exceptions ¶

exception raschii.RaschiiError¶

exception raschii.NonConvergenceError¶

Enumerations ¶

class raschii.Frame(*values)¶

Reference frame

Currently only used for stream-function evaluations.

EARTH = 'EARTH'¶: EARTH: earth/lab frame (stationary observer). This includes the constant base-flow term.

WAVE = 'WAVE'¶: WAVE: wave/co-moving frame (observer travelling with the wave crest). The constant base-flow term is excluded.

Other ¶

C++ code generators ¶

Each wave model exposes a wave.cpp attribute that can generate C++ code strings for use in e.g. FEniCS boundary conditions. The available methods are

wave.cpp.elevation()
wave.cpp.velocity(all_points_wet=False)
wave.cpp.stream_function(frame=Frame.EARTH)
wave.cpp.slope()

(the last two are implemented only for FentonWave).

The air-phase model classes expose a air.cpp attribute that can generate C++ code strings for the air-phase velocity field. The available methods are

air.cpp.velocity()
air.cpp.stream_function(frame=Frame.EARTH)

which are available in both air-phase models.

Warning

The C++ code generation interfaces (wave.cpp.* and air.cpp.*) are experimental. The code-generation API may change or be removed in a future release without following the normal deprecation cycle. They are currently not used as far as the author of Raschii is aware.

Raschii Python API¶

Main functions ¶

Wave model API summary ¶

Wave model classes ¶

Airy waves ¶

Stokes waves ¶

Fenton stream-function waves ¶

Parameters¶

Returns¶

Air model classes ¶

Exceptions ¶

Enumerations ¶

Other ¶

C++ code generators ¶

raschii

Navigation

Related Topics