Source code for capytaine.post_pro.impedance

#!/usr/bin/env python
# coding: utf-8
"""Computation of the impendance matrix."""
# Copyright (C) 2017-2019 Matthieu Ancellin
# See LICENSE file at <https://github.com/mancellin/capytaine>

import logging

import numpy as np
import xarray as xr

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 a :code:`inertia_matrix` matrix to be defined in the hydrodynamical dataset')

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

    # ASSEMBLE MATRICES
    omega = dataset.coords['omega']  # Range of frequencies in the dataset

    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.
    """
    return 1/(-1j * dataset.coords["omega"]) * rao_transfer_function(dataset, dissipation, stiffness)