Source code for capytaine.post_pro.impedance

# Copyright 2026 Capytaine developers
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""Computation of the impendance matrix."""

import logging

LOG = logging.getLogger(__name__)




def rao_transfer_function(dataset, dissipation=None, stiffness=None):
    """Complex-valued matrix used for the computation of the RAO.

    Parameters
    ----------
    dataset: xarray Dataset
        The hydrodynamical dataset.
        This function supposes that variables named 'inertia_matrix' and 'hydrostatic_stiffness' are in the dataset.
        Other variables can be computed by Capytaine, by those two should be manually added to the dataset.
    dissipation: array, optional
        An optional dissipation matrix (e.g. Power Take Off) to be included in the transfer function.
        Default: none.
    stiffness: array, optional
        An optional stiffness matrix (e.g. mooring stiffness) to be included in the transfer function.
        Default: none.

    Returns
    -------
    xarray DataArray
        The matrix as an array depending of omega and the degrees of freedom.
    """

    if not hasattr(dataset, 'inertia_matrix'):
        raise AttributeError('Computing the impedance matrix requires an `inertia_matrix` matrix to be defined in the hydrodynamical dataset')

    if not hasattr(dataset, 'hydrostatic_stiffness'):
        raise AttributeError('Computing the impedance matrix requires an `hydrostatic_stiffness` matrix to be defined in the hydrodynamical dataset')

    if 'encounter_omega' in dataset.coords:
        omega = dataset.coords['encounter_omega']
    else:
        omega = dataset.coords['omega']

    # ASSEMBLE MATRICES
    H = (-omega**2*(dataset['inertia_matrix'] + dataset['added_mass'])
         - 1j*omega*dataset['radiation_damping']
         + dataset['hydrostatic_stiffness'])

    if dissipation is not None:
        H = H - 1j*omega*dissipation

    if stiffness is not None:
        H = H + stiffness

    return H





def impedance(dataset, dissipation=None, stiffness=None):
    """Complex-valued mechanical impedance matrix.
    See Falnes for more theoretical details::

        @book{falnes2002ocean,
              title={Ocean Waves and Oscillating Systems: Linear Interactions Including Wave-Energy Extraction},
              author={Falnes, J.},
              isbn={9781139431934},
              url={https://books.google.com/books?id=bl1FyQjCklgC},
              year={2002},
              publisher={Cambridge University Press}
        }

    Parameters
    ----------
    dataset: xarray Dataset
        The hydrodynamical dataset.
        This function supposes that variables named 'inertia_matrix' and 'hydrostatic_stiffness' are in the dataset.
        Other variables can be computed by Capytaine, by those two should be manually added to the dataset.
    dissipation: array, optional
        An optional dissipation matrix (e.g. Power Take Off) to be included in the impedance.
        Default: none.
    stiffness: array, optional
        An optional stiffness matrix (e.g. mooring stiffness) to be included in the impedance.
        Default: none.

    Returns
    -------
    xarray DataArray
        The impedance as an array depending of omega and the degrees of freedom.
    """
    if 'encounter_omega' in dataset.coords:
        omega = dataset.coords['encounter_omega']
    else:
        omega = dataset.coords['omega']
    return 1/(-1j * omega) * rao_transfer_function(dataset, dissipation, stiffness)