capytaine.io.wamit module

capytaine.io.wamit.check_dataset_ready_for_export(ds: Dataset) → None

Sanity checks to validate that the dataset is exportable to BEMIO/WAMIT-like formats.

Parameters:

ds (xarray.Dataset) – The dataset to be validated.

Raises:

ValueError – If any unsupported coordinate has multiple values or if non-rigid-body DOFs are present.

capytaine.io.wamit.export_to_wamit(dataset: Dataset, problem_name: str, exports: Iterable[str] = ('1', '3', '3fk', '3sc', 'hst')) → None

Master function to export a Capytaine dataset to WAMIT-format files.

Parameters:

• dataset (xarray.Dataset) – Dataset containing the desired complex-valued force field.

• problem_name (str) – Base filename for WAMIT files (e.g. “output” → output.1, output.3fk, etc.).

• exports (iterable of str) – Which files to export: any combination of “1”, “3”, “3fk”, “3sc”, “hst”.

capytaine.io.wamit.export_wamit_1(dataset: Dataset, filename: str, length_scale: float = 1.0) → None

Export added mass and radiation damping coefficients to a WAMIT .1 file.

Coefficients are normalized as:

Aij = Aij / (rho * length_scale^k) Bij = Bij / (omega * rho * length_scale^k)

Format:

PER I J Aij [Bij]

Special handling:

• For PER = -1 (omega = inf), only Aij is written.

• For PER = 0 (omega = 0), only Aij is written.

Parameters:

• dataset (xarray.Dataset) – Must contain ‘added_mass’, ‘radiation_damping’, and either ‘omega’ or ‘period’.

• filename (str) – Output .1 file.

• length_scale (float) – Reference length scale (L) used for normalization.

Raises:

ValueError – If required fields are missing or forward speed is not zero.

capytaine.io.wamit.export_wamit_3(dataset: Dataset, filename: str) → None

Export total excitation to WAMIT .3 file.

Parameters:

• dataset (xarray.Dataset) – Dataset containing the desired complex-valued force field.

• filename (str) – Output path for the .3 file.

capytaine.io.wamit.export_wamit_3fk(dataset: Dataset, filename: str) → None

Export Froude-Krylov contribution to WAMIT .3fk file.

Parameters:

• dataset (xarray.Dataset) – Dataset containing the desired complex-valued force field.

• filename (str) – Output path for the .3fk file.

capytaine.io.wamit.export_wamit_3sc(dataset: Dataset, filename: str) → None

Export scattered (diffraction) contribution to WAMIT .3sc file.

Parameters:

• dataset (xarray.Dataset) – Dataset containing the desired complex-valued force field.

• filename (str) – Output path for the .3sc file.

capytaine.io.wamit.export_wamit_hst(dataset: Dataset, filename: str, length_scale: float = 1.0) → None

Export the nondimensional hydrostatic stiffness matrix to a WAMIT .hst file.

Format:

I J C(I,J)

Parameters:

• dataset (xarray.Dataset) – Must contain ‘hydrostatics’ field with ‘hydrostatic_stiffness’ (named-dict or labeled 6x6 array). Must also contain ‘rho’ and ‘g’ (either in dataset or within hydrostatics).

• filename (str) – Output path for the .hst file.

• length_scale (float) – Reference length scale L for nondimensionalization.

capytaine.io.wamit.get_dof_index_and_k(dof_i: str, dof_j: str) → Tuple[int, int, int]

Get the degree of freedom indices and the corresponding stiffness matrix index.

Parameters:

• dof_i (str) – The name of the first degree of freedom.

• dof_j (str) – The name of the second degree of freedom.

Returns:

A tuple containing the indices (i, j) and the stiffness matrix index k.

Return type:

tuple

capytaine.io.wamit.identify_frequency_axis(dataset: Dataset | DataArray) → Tuple[str, ndarray, ndarray]

Identify the frequency axis in the dataset and return its values along with the periods.

Parameters:

dataset (xarray.Dataset or xarray.DataArray) – Dataset that must include ‘period’ coordinate and at least one of: ‘omega’, ‘freq’, ‘period’, ‘wavenumber’, or ‘wavelength’ as dimension.

Returns:

• freq_key (str) – The name of the main frequency-like coordinate.

• freq_vals (np.ndarray) – The values from the frequency coordinate (as present in the dataset).

• period_vals (np.ndarray) – The values of the ‘period’ coordinate in seconds.

Raises:

ValueError – If ‘period’ is not a coordinate or if no frequency-like dimension is found.