Export outputs

The Dataset output format is a standard object from Xarray and all methods from Xarray’s manual can be used to manipulate and export it. On top of that, Capytaine provides some wrappers functions to simplify the export into a NetCDF file, as well as into other formats more specific to hydrodynamics.

NetCDF format

The xarray dataset produced by assemble_dataset (or fill_dataset) has a structure close to the NetCDF file format and can easily be saved to this format by export_dataset():

cpt.export_dataset("path/to/dataset.nc", dataset, format="netcdf")

Note

The netCDF standard does not handle complex numbers.

Capytaine is using a non-standard representation of complex numbers by transforming all complex-valued arrays of shape (...) into real-valued arrays of shape (..., 2)` using the functions separate_complex_values() and merge_complex_values() (done automatically by export_dataset()).

See also https://github.com/PlasmaFAIR/nc-complex for more context and alternatives.

Note

Exporting more outputs such as pressure field on the hull in a NetCDF file is considered in the future. See https://github.com/capytaine/capytaine/issues/520 for examples of such outputs.

Wamit format

The hydrodynamic results from a Capytaine xarray.Dataset can be exported into WAMIT-compatible text files (.1, .3, .3fk, .3sc, .hst) using:

cpt.export_dataset("problem_name", dataset, format="wamit", exports=("1", "3", "3fk", "3sc", "hst"))

This will produce the following files (depending on the fields present in the dataset and the flags passed to the optional exports argument):

  • problem_name.1 for added mass and radiation damping coefficients,

  • problem_name.3 for total excitation forces (Froude-Krylov + diffraction),

  • problem_name.3fk for Froude-Krylov forces only,

  • problem_name.3sc for diffraction forces only.

  • problem_name.hst for hydrostatics results (if supported)

Invalid or unavailable exports are skipped with a warning.

The length scale used for normalization in WAMIT data is taken by default as \(1\) meter.

Note

These exports require that the forward_speed in the dataset is zero. If not, a ValueError is raised to avoid exporting inconsistent results.

Nemoh format

The results from a Capytaine xarray.Dataset can be exported into Nemoh-computible text files (Hydrostatics.dat, KH.dat, RadiationCoefficients.tec and ExcitationForce.tec) using:

cpt.export_dataset("path/to/result_dir/", dataset, format="nemoh")

This feature is still experimental. Please report issues encountered with this.

Alternatively, Hydrostatics.dat and KH.dat can be exported with the following syntax:

from capytaine.io.legacy import export_hydrostatics
body.hydrostatic_stiffness = body.immersed_part().compute_hydrostatic_stiffness()
export_hydrostatics("directory_to_save_hydrostatics_data", body)

for a single rigid body or, e.g.,:

from capytaine.io.legacy import export_hydrostatics
body_1.hydrostatic_stiffness = body_1.immersed_part().compute_hydrostatic_stiffness()
body_2.hydrostatic_stiffness = body_2.immersed_part().compute_hydrostatic_stiffness()
body_3.hydrostatic_stiffness = body_3.immersed_part().compute_hydrostatic_stiffness()
export_hydrostatics("directory_to_save_hydrostatics_data", body_1 + body_2 + body_3)

for several rigid bodies.

Excel format

Export to Excel format is not currently built in export_dataset(). This section is meant to show an example of exporting to a format that is not explicitly implemented in Capytaine. We use here the openpyxl library (that can be installed with pip install openpyxl) to export a dataset to Excel format:

dataset[["added_mass", "radiation_damping"]].to_dataframe().to_excel("radiation_data.xlsx")

from capytaine.io.xarray import separate_complex_values
separate_complex_values(dataset[["Froude_Krylov_force", "diffraction_force"]]).to_dataframe().to_excel("diffraction_data.xlsx")

For convenience, the radiation and diffraction data have been stored in separate files. Since this export method poorly supports complex number, the separate_complex_values has been used to transform them to a pair of real numbers, as discussed for NetCDF export above.