Changelog of versions 2.x

New in version 2.3.1 (2025-10-14)

Bug fix

  • Fix major bug of version 2.3 where the resolution of problem with both mesh symmetries and a lid for irregular frequencies removal returned wrong values. (GH 761)

  • Fix issue where in-place transformation of a FloatingBody (such as body.keep_immersed_part() or body.translate(...)) were sometimes not taken into account. In-place transformation are not recommended and might be removed in a future version, use the versions returning new objects as seen in the documentation (e.g. body.immersed_part() and body.translated(...)).

  • If loading the tabulation from the file fails, then the tabulation is recomputed (Issue 739)

Internals

  • The source code moved from capytaine to src/capytaine in the main repository to avoid importing the local folder instead of the installed version (GH 395 and PR 749).

  • Replace development dependencies in editable_install_requirements.txt and [project.optional-dependencies] with [dependency-groups] (PR 750).

New in version 2.3 (2025-07-17)

Major change

  • The implementations of the Green function from HAMS are now included in Capytaine:

    • The infinite depth version from [Liang, Wu, Noblesse, 2018] is LiangWuNoblesseGF (PR 617),

    • The finite depth version from [Liu et al., 2018] is FinGreen3D (PR 647),

    • The class HAMS_GF is a thin wrapper using one or the other method above depending of the water depth (PR 658).

    They can be passed to Capytaine’s solver as follows:

    solver = cpt.BEMSolver(green_function=cpt.HAMS_GF())

    Please cite the corresponding papers if you use them in a scientific publication (see the Citing page).

  • Revamp of default finite depth Green function implementation.

    • The new implementation should better handle panels on or near the free surface and have the right asymptotic consistency with the infinite depth method when depth goes to infinity. The legacy behavior of previous versions is still available by setting the parameter finite_depth_method added to Delhommeau to finite_depth_method="legacy", while the better behavior is used by default. (PR 654 and PR 656)

    • The Prony decomposition is now done in Python and its failure (typically for \(kh < 0.1\)) raises an error instead of returning wrong values. This behavior is controlled by the finite_depth_prony_decomposition_method parameter of Delhommeau, which is now "python" by default. (PR 675)

    • Infinite frequency is now supported in finite depth (zero frequency is still not and returns the same error as other finite depth low-frequency cases). (PR 703)

  • Do not interrupt a batch of resolutions when one of them fails. Instead the exception is displayed in the log and the results are replaced by a FailedDiffractionResult or FailedRadiationResult. The output dataset is filled with a NaN value for these parameters. (PR 678) Diffraction problems with zero or infinite frequencies used to have a special treatment to be run with a batch resolution despite raising an error when run alone, they have been reworked to use the same design as other failing resolutions. (PR 719)

  • The Boundary Integral Equation (method keyword argument) used to solve the problem can now be specified when initializing a solver and will then be use for all resolution with this solver. This general setting can be over overridden by using the method argument when solving:

    solver = cpt.BEMSolver(method="direct")  # That is new and recommended
solver.solve(problem, method="direct")  # That is still possible and override the above setting.

The method is also saved in the metadata of the results with the other parameters of the solver (whether it was defined when initializing the solver or later). (PR 686)

Minor change

  • Add optional freq argument (frequency in Hz) for problem set up and output.

  • Add assemble_dataframe() which collect results into a Pandas DataFrame (this was already done internally in assemble_dataset()) (PR 677). Also add assemble_matrices() function which is a simplified version of assemble_dataset() without metadata, meant to be used mostly for teaching. (PR 643)

  • The environment variable CAPYTAINE_PROGRESS_BAR can be used to disable globally the display of a progress bar when solving problems. This is meant mostly for testing environments and CI. (PR 646)

  • Add timer attribute to BEMSolver storing the time spent in each steps of the resolution. Summary can be accessed by timer_summary(). (PR 674)

  • Add export_to_wamit() as a unified interface to export hydrodynamic results to WAMIT-compatible files. (PR 714)

Bug fixes

  • Properly use progress_bar argument in fill_dataset() to disable progress bar.

  • Always remove degenerate faces after clipping (GH 620 and PR 624).

  • Fix missing geometric center in legacy predefined body ReflectionSymmetricMesh. It was causing inconsistent definition of dofs with respect to earlier versions. (PR 625)

  • Fix Python implementation of the Prony decomposition for the finite depth Green function, which is now the default. (PR 621). Move some code of its code to the prony_decomposition module. (PR 649)

  • After joining several bodies, editing the mesh of one of the components does not affect the joined body anymore (GH 660 and PR 662:).

  • Check the consistency of the dofs with the mesh and raises ValueError when an inconsistency is detected (PR 663).

  • Fix error when removing all the faces from a symmetric mesh (PR 668)

  • Add safeguard if a custom linear solver returns a result vector of wrong shape (e.g. column instead of row) (PR 670)

  • Fix loading BEMIO datasets from Nemoh (PR 681)

  • Fix computing zero and infinite frequency radiation problems with a lid for irregular frequencies removal (GH 704 and PR 708)

  • Fix solving LinearPotentialFlowProblem directly.

  • Fix missing variable attributes for main frequency variable (GH 702 and PR 717)

  • Trying to generate a lid over a purely vertical mesh does not raise an error anymore (GH 625).

  • When the hull mesh and the lid mesh are both symmetric with the same reflection plane, the symmetry is not lost anymore when solving the BEM problem. Also generate_lid and extract_lid should now work with reflection symmetric meshes without losing the symmetry. (GH 527, PR 667, PR 720).

Internals

  • Major refactoring of the Fortran core, including its interface in Python:

    • Add interface.f90 Fortran file to group some routines used only for wrapping the Fortran core. (PR 612)

    • Add all_tabulation_parameters() to make it easier to test Fortran core from Python (PR 648)

    • Refactor implementation of Delhommeau’s finite depth Green function to compute all the frequency-independant Rankine terms at the same time (for future caching) (PR 652)

    • The main interface to the Fortran core build_matrices does not take coeffs and same_body inputs anymore. The role of the former is played by gf_singularities and wavenumber. The diagonal term added by the latter is now added independently. (PR 701)

  • NaN values are not striped out of output data (PR 676)

  • Define a MeshLike protocol that classes implementing a mesh should follow. Also ensure that Mesh and CollectionOfMeshes follow it. (PR 667)

New in version 2.2.1 (2024-11-18)

Minor change

  • More efficient implementation of the mesh connected-component clustering algorithm (PR 603).

Bug fixes

  • Lid meshes on the free surface do not cause errors when clipped. Also empty lid meshes are properly handled when initializing or clipping a mesh (GH 573 and PR 575).

  • GDF meshes are accepted in the alternate format now. Meshes files can list points in either 3×4 × nb_faces or a 12 × nb_faces format. (GH 540 and PR 585).

  • When filling a test matrix with both diffraction problems and radiation problems, zero and infinite frequencies can now be provided. (Previously, the computation was failing because these frequencies are not defined for diffraction problems.) (PR 587)

  • Radiation damping at infinite frequency is now zero instead of infinity. When forward speed is non-zero, added mass and radiation dampings at zero encounter frequency are NaN. (PR 588)

  • User does not need to import pyplot themself before running show_matplotlib() (PR 592)

  • Fixes usage of ReflectionSymmetricMesh with direct solver (GH 593 and PR 594).

  • Do not recompute the same first_irregular_frequency_estimate() for the same body several times. Also better expose the _check_wavelength option to skip wavelength check, including irregular frequency estimation. (GH 601 and PR 602).

  • Fix bug in the \(r\)-range of the tabulation of the Green function (GH 538 and PR 611).

New in version 2.2 (2024-07-08)

Major changes

  • New feature: lid-based irregular frequencies removal. Add lid_mesh argument to FloatingBody for irregular frequencies removal (PR 521). Add generate_lid() method to generate lids (PR 477) and extract_lid() method to extract lids from exernally defined meshes (PR 559). Add a warning to the user if irregular frequencies can be expected (PR 564).

  • The compiled Fortran extension is not split into a Delhommeau and a XieDelhommeau version anymore. The same effect is now achieved by the run-time parameter gf_singularities of the class Delhommeau (PR 475). (The class XieDelhommeau is kept for backward compatibility.). The new default method in infinite depth is gf_singularities="low_freq" (formerly XieDelhommeau) instead of gf_singularities="high_freq". The new one is expected to be more accurate near the surface and at low frequency (PR 566) The finite depth Green function is always computed using the low_freq variant, so the gf_singularities parameter has no effect in finite depth. (PR 507). The tabulation stores the data of both variants and is thus slightly longer to initialize and slightly larger to store in memory (PR 543).

  • Experimental support for panels on the free surface, when using gf_singularities="low_freq". (PR 419)

Minor changes

  • Remove mesh resolution warning when the frequency is infinite (or the wavelength is zero) (PR 511).

  • When computing without a tabulation (tabulation_nr=0 or tabulation_nz=0), the value of tabulation_nb_integration_points is actually used to compute Guével-Delhommeau exact formulation of the Green function. Previously, it was only used when precomputing a tabulation (PR 514).

  • Add a new variant of the Green function integration gf_singularities="low_freq_with_rankine_part" as an experimental more accurate version of the low_freq variant (PR 510).

  • Add a tabulation_cache_dir parameter to Delhommeau to choose the directory in which the tabulation is saved on disk. If None is provided instead, the tabulation is not saved on disk and is recomputed at each initialization of the class. Also, if this parameter is not set, look for the CAPYTAINE_CACHE_DIR environment variable and use it to save the tabulation if it exists. (PR 516).

  • Meshio objects can be directly passed to load_mesh() to get a Capytaine mesh (PR 555).

  • Load gmsh v4 format .msh file using load_mesh() (when meshio is installed) (PR 556)

Bug fixes

  • Always use an odd number of points for integration with Simpson rule (PR 515). This bug was partly responsible for some high-frequency inaccuracy (GH 298).

  • mesh_vertical_cylinder() used to return only half of the mesh when called with reflection_symmetry=True (GH 529 and PR 530).

  • Providing the frequency as a scalar coordinate in the test matrix does not result in the value being ignored anymore (GH 547 and PR 548).

  • Improve exception message when giving an unknown radiating_dof to a RadiationProblem (PR 549).

  • Fix issue due to breaking change in linear solver broadcasting in Numpy 2.0 (GH 550).

  • Remove warning mentioning missing divergence for rigid body dofs when computing hydrostatics (PR 487 and PR 570)

Internals

  • Update test environments used in noxfile and add editable_install_requirements.txt. (PR 498)

  • Rename tabulation_method parameter of Delhommeau as the more descriptive tabulation_grid_shape, and similarly for internal variables. (PR 503)

  • Add connected_components() and connected_components_of_waterline() to split a mesh into connected components. (PR 554)

New in version 2.1 (2024-04-08)

Major changes

  • New feature: Approximate forward speed for single rigid body. A forward_speed parameter can now be provided to LinearPotentialFlowProblem (or to the test matrix when using fill_dataset()) to compute the excitation force, added mass and radiation damping with forward speed of the body in the \(x\) direction. Note that the RadiationProblem now accept a wave_direction parameter, which is only used when forward_speed is non zero to compute the encounter frequency. See the theory manual for references. (PR 376)

  • Add rich as a dependency and improve formatting of the console output. Add set_logging() function to quickly set up logging with rich. solve_all() and fill_dataset() now display a progress bar (unless turn off by the progress_bar argument). (PR 382)

  • Reimplement computation of added mass and radiation damping in infinite depth with zero or infinite frequency. (PR 385 and PR 485) When using forward speed, the added mass and radiation damping are undefined, but the forces can still be computed. (PR 483)

  • Implement direct method (source-and-dipole formulation) in obtaining velocity potential solutions. The direct method can be used instead of the default indirect method by setting the method argument of solve(), solve_all() or fill_dataset() (PR 420)

  • Add new shape for the grid used for the tabulation, based on the one used in Nemoh version 3. User can choose to use the Nemoh 3 grid shape (by default) or the former one by setting the tabulation_method parameter of Delhommeau. The new grid shape allows to set both the number of points (with tabulation_nr and tabulation_nz) and the extent of the tabulation (with tabulation_rmax and tabulation_zmin). The new default tabulation might lead to slightly different results, which are likely more accurate in the new version. (PR 439)

Minor changes

  • Support passing FloatingBody or FreeSurface objects to post-processing methods such as compute_potential() and compute_free_surface_elevation(). (PR 379)

  • Add top_light_intensity optional arguments to run() and save() to illuminate the scene from top. (PR 380)

  • Clean up __str__ and __repr__ representation of many objects. Also rich.print now return even nicer representations. (PR 384)

  • Always automatically compute and store the excitation_force next to the Froude_Krylov_force and diffraction_force in the dataset (PR 406).

  • Computing the RAO with rao() is not restricted to a single wave direction (or a single value of any other extra parameter) at the time anymore. (GH 405 and PR 406)

  • New computation of quadrature schemes without relying on Quadpy. (PR 416)

  • Add a new function run_cal_file() to solve the problems defined by a Nemoh.cal file, exactly as the command-line interface is doing (PR 422).

  • Rephrase mesh resolution warnings and group several of them together in a single warning. (PR 423)

  • Add block-Jacobi/coarse-correction preconditioner for large arrays of bodies. (PR 436)

  • The tabulation is saved on disk in a cache directory instead of being recomputed at each initialization of the solver. (PR 454)

  • Add a faces_max_radius argument to the predefined geometries from predefined to set up the resolution by giving a length scale for the panels (PR 459).

  • Automatically clip the mesh (and display a warning) when a problem is initialized with a mesh above the free surface or below the sea bottom (PR 486).

Bug fixes

  • When initializing a body with a mesh having degenerate panels, the initialization of the dofs used to happen before the degenerate panels were removed, leading to an inconsistency between the number of panels in the mesh and in the dof definition. (GH 367 and PR 375)

  • Fix the single precision Green function (cpt.Delhommeau(floating_point_precision="float32")) that was broken in v2.0. (GH 377 and PR 378)

  • Update the BEMIO import feature to work with Pandas 2.0 and output periods as now done in Capytaine 2.0. A version of BEMIO that works in recent version of Python and Numpy can be found at https://github.com/mancellin/bemio. (PR 381)

  • Fix compute_pressure() that was broken. (PR 394)

  • Fix error message when computing hydrostatic stiffness of non-neutrally-buoyant body that is not a single rigid body. (GH 413 and PR 414)

  • Fix bug causing the quadrature method of a mesh to be forgotten when the mesh was put in a body. quadrature_method can now be passed as argument when initializing a new mesh. (PR 417)

  • The function load_mesh() more robustly detects filetype using file extension even when the file extension is not lowercase. (PR 441)

  • Fix bug with bodies translation or rotation when the rotation center or the center of mass had been defined as list or tuples instead of array (PR 472).

Internals

  • Add tentative build file for the Guix package manager (PR 339).

  • Fix badly named variables VSP2_SYM and VSP2_ANTISYM in libDelhommeau (PR 391)

  • Remove dependency to hypothesis for testing (PR 391).

  • Change how forces are stored in result objects. Added mass and radiation damping can now be queried with added_mass and radiation_damping and not only the plural forms that were used nowhere else in the code. (PR 393)

  • Use nox to test the code in isolated virtual environments. (PR 401)

  • Fortran source files are not included in wheel anymore (PR 360).

  • The delete_first_lru_cache decorator has been renamed lru_cache_with_strict_maxsize() and now supports keyword arguments in the memoized function (PR 442).

  • Fix Xarray future warning about Dataset.dims (GH 450 and PR 451).

  • Improve some warnings and error messages.

New in version 2.0 (2023-06-21)

Major changes

  • User can specify a period, a wavelength or a wavenumber instead of an angular frequency omega when setting up a problem or a test matrix. If several types of frequency data are provided, an error is raised (PR 283).

  • Breaking The normalization of radiation problems has been changed to use the same normalization as diffraction problems. Added mass and radiation dampings are unchanged, but other outputs of radiation problem (free surface elevation, kochin functions, etc.) may differ from previous version by a factor \(-j \omega\). (GH 173 and PR 348)

  • Breaking The above two points interfered with the handling of \(\omega = 0\) and \(\omega = \infty\) cases. They have been temporarily disabled and will return in a future release.

  • Add methods compute_potential(), compute_velocity() and compute_free_surface_elevation() and compute_pressure() to compute the value of some fields in the domain in post-processing. Their signature has been uniformized with the airy_waves_potential() and airy_waves_velocity() functions (PR 288, PR 326). New functions airy_waves_free_surface_elevation() and airy_waves_pressure() have also been added (PR 293).

  • Breaking The problems can now be initialized by setting a water_depth instead of the sea_bottom (which is still available for user-facing functions). This change is meant to uniformize notations in the code and use water_depth wherever possible (PR 340). Besides the sea_bottom argument of many internal routines has been completely replaced by water_depth. Migrating then requires changing the sign of the float (PR 347).

  • Add Github Actions workflow to build wheels. Precompiled packages will now be available with pip and not only with conda.

Minor changes

  • Support the new format of Nemoh.cal file from Nemoh v3 (GH 278 and PR 280).

  • Breaking Remove the convention parameter to compute excitation force with WAMIT conventions (GH 133 and PR 281). Changing the convention to compare the outputs of different codes is better done by a dedicated software such as BEMRosetta or BEMIO.

  • Add nicer display for Capytaine objects in IPython shell (GH 227 and PR 287).

  • Support exporting hydrostatics data in original Nemoh-format files - Hydrostatics.dat and KH.dat (PR 285).

  • Add nicer display for Capytaine objects in IPython shell (GH 227 and PR 287)

  • Add functions load_PNL() and write_PNL() to load and write meshes in HAMS .pnl format (PR 289).

  • Breaking Remove cpt.Nemoh() class that was replaced by BEMSolver in version 1.1 (PR 291)

  • Breaking Remove full_body attribute from FloatingBody that used to keep a copy of the body before clipping in-place (PR 302).

  • Breaking Remove dimensionless_wavenumber and dimensionless_omega attributes from LinearPotentialFlowProblem as they are not used in the code and can be easily recomputed by users if necessary (PR 306).

  • Add minimal_computable_wavelength() to estimate the wavelengths computable with the mesh resolution (PR 341).

  • Slightly increase default tabulation size to avoid some high-frequency issues such as GH 157 (PR 353).

Bug fixes

  • Fix immersed_part() (PR 307).

  • compute_hydrostatics() used to fail for non-rigid bodies because it could not compute the rigid-body inertia. The rigid-body inertia is now just skipped for bodies with no rigid-body dofs (PR 308).

  • Reduce the default tolerance of the mesh clipper for points just above the free surface (GH 320 and PR 322).

  • Convert center_of_mass and rotation_center to arrays in FloatingBody constructor to avoid a few issues (GH 319 and PR 325).

  • Fix bug (leading to either RuntimeError or wrong output) when clipping with plane that does not contain the origin. (PR 344)

  • Instances of BEMSolver initialized with default parameters do not share the same engine, hence they do not share the same cache. This minor issue was causing minor interferences in some benchmarks (GH 295 and PR 350).

Internals

  • Major update of the compilation toolchain because of the upcoming deprecation of numpy.distutils. Capytaine is now built with meson-python.

  • The method evaluate() (and its counterparts for other Green functions) now accepts a list of points as first argument instead of a mesh. It has now an optional boolean argument early_dot_product to return the integrals of the gradient of the Green function and not only the normal derivative (PR 288).

  • Remove warnings due to 0/0 divisions in compute_faces_properties() (PR 310)

  • Breaking Remove unused and undocumented code about meshes, including mesh.min_edge_length, mesh.mean_edge_length, mesh.max_edge_length, mesh.get_surface_integrals, mesh.volume, mesh.vv, mesh.vf, mesh.ff, mesh.boundaries, mesh.nb_boundaries, compute_faces_integrals, SingleFace. (PR 334)

  • Add analytics to the documentation using Plausible.io (PR 290).