wawi 0.0.16__py3-none-any.whl → 0.0.18__py3-none-any.whl

wawi/general.py

@@ -4,6 +4,27 @@ import numpy as np
 from inspect import isfunction
 
 def block_truncate(M, p, n_dofs=6):
+    """
+    Truncate a block matrix to a specified size.
+
+    Parameters
+    ----------
+    M : ndarray
+        Input matrix (2D or 3D).
+    p : int
+        Number of blocks to keep.
+    n_dofs : int, optional
+        Number of degrees of freedom per block (default is 6).
+
+    Returns
+    -------
+    Mtr : ndarray
+        Truncated matrix.
+
+    Notes
+    -----
+    Docstring generated using GitHub Copilot.
+    """
     Mtr = M*1
     if np.ndim(M)==2:
         is_2d = True
@@ -28,6 +49,31 @@ def block_truncate(M, p, n_dofs=6):
     return Mtr
 
 def eval_fun_or_scalar(par, x, y, x0=0, y0=0):
+    """
+    Evaluate a function or return a scalar.
+
+    Parameters
+    ----------
+    par : callable or scalar
+        Function or scalar to evaluate.
+    x : float
+        x value.
+    y : float
+        y value.
+    x0 : float, optional
+        x offset (default is 0).
+    y0 : float, optional
+        y offset (default is 0).
+
+    Returns
+    -------
+    result : float
+        Evaluated result.
+
+    Notes
+    -----
+    Docstring generated using GitHub Copilot.
+    """
     if isfunction(par):
         if 'x' in par.__code__.co_varnames and 'y' in par.__code__.co_varnames:
             return par(x - x0, y - y0)
@@ -38,9 +84,24 @@ def eval_fun_or_scalar(par, x, y, x0=0, y0=0):
     else:
         return par
 
-
-#%% 
 def zero_pad_upsample(B, omega, omega_max):
+    """
+    Zero-pad and upsample a vector to a new maximum frequency.
+
+    Parameters
+    ----------
+    B : ndarray
+        Input vector.
+    omega : ndarray
+        Frequency vector.
+    omega_max : float
+        Maximum frequency after upsampling.
+
+    Returns
+    -------
+    Bi : ndarray
+        Zero-padded and upsampled vector.
+    """
     dw = omega[1]-omega[0]
     omega_max0 = np.max(omega)
     n_add = int(np.floor((omega_max-omega_max0)/dw))
@@ -48,14 +109,51 @@ def zero_pad_upsample(B, omega, omega_max):
     return Bi
 
 def get_omega_upsampled(omega, omega_max):
+    """
+    Get upsampled frequency vector.
+
+    Parameters
+    ----------
+    omega : ndarray
+        Original frequency vector.
+    omega_max : float
+        Maximum frequency after upsampling.
+
+    Returns
+    -------
+    omegai : ndarray
+        Upsampled frequency vector.
+    """
     dw = omega[1]-omega[0]
     omega_max0 = np.max(omega)
     omega_add = np.arange(omega_max0+dw, omega_max, dw)
     omegai = np.hstack([omega, omega_add])
     return omegai
 
-#%% Misc
 def equal_energy_omega(S, omega_min, omega_max, n, dmax=np.inf, domega_ref=1e-4):  
+    """
+    Generate frequency vector with equal energy intervals.
+
+    Parameters
+    ----------
+    S : callable
+        Spectral density function.
+    omega_min : float
+        Minimum frequency.
+    omega_max : float
+        Maximum frequency.
+    n : int
+        Number of intervals.
+    dmax : float, optional
+        Maximum interval width (default is np.inf).
+    domega_ref : float, optional
+        Reference frequency step (default is 1e-4).
+
+    Returns
+    -------
+    omegas : ndarray
+        Frequency vector with equal energy intervals.
+    """
     from scipy.integrate import cumtrapz
 
     omega_ref = np.arange(omega_min, omega_max, domega_ref)
@@ -81,29 +179,100 @@ def equal_energy_omega(S, omega_min, omega_max, n, dmax=np.inf, domega_ref=1e-4)
 
     return omegas
 
-
-#%% Matrix manipulation / generation
 def blkdiag(mat, n):
+    """
+    Create a block diagonal matrix.
+
+    Parameters
+    ----------
+    mat : ndarray
+        Matrix to repeat along the diagonal.
+    n : int
+        Number of blocks.
+
+    Returns
+    -------
+    blk : ndarray
+        Block diagonal matrix.
+    """
     return np.kron(np.eye(n), mat)
 
 def fun_sum(*functions):
+    """
+    Sum multiple functions.
+
+    Parameters
+    ----------
+    *functions : callable
+        Functions to sum.
+
+    Returns
+    -------
+    fun : callable
+        Function representing the sum.
+    """
     def fun(x):
         return sum([f(x) for f in functions])
     
     return fun
 
 def fun_scale(function, scaling):
+    """
+    Scale a function by a constant.
+
+    Parameters
+    ----------
+    function : callable
+        Function to scale.
+    scaling : float
+        Scaling factor.
+
+    Returns
+    -------
+    fun : callable
+        Scaled function.
+    """
     def fun(x):
         return function(x)*scaling
     
     return fun
 
 def fun_const_sum(function, constant):
+    """
+    Add a constant to a function.
+
+    Parameters
+    ----------
+    function : callable
+        Function to add to.
+    constant : float
+        Constant to add.
+
+    Returns
+    -------
+    fun : callable
+        Function plus constant.
+    """
     def fun(x):
         return function(x) + constant
     return fun
 
 def eval_3d_fun(fun, z):
+    """
+    Evaluate a function over a 1D array and stack results into a 3D array.
+
+    Parameters
+    ----------
+    fun : callable
+        Function to evaluate.
+    z : ndarray
+        1D array of input values.
+
+    Returns
+    -------
+    result : ndarray
+        Stacked results.
+    """
     return np.stack([fun(z_k) for z_k in z], axis=2)
 
 def correct_matrix_size(mat, n_freqs, n_dofs):
@@ -111,20 +280,19 @@ def correct_matrix_size(mat, n_freqs, n_dofs):
     Extend matrix to specified dimensions (frequencies and DOFs).
 
     Parameters
-    ---------------------------
-    mat : double
-        matrix to be checked and possibly modified
+    ----------
+    mat : ndarray
+        Matrix to be checked and possibly modified.
     n_freqs : int
-        number of frequencies (depth of final matrix)
+        Number of frequencies (depth of final matrix).
     n_dofs : int
-        number of degrees of freedom (height and width of final matrix)
+        Number of degrees of freedom (height and width of final matrix).
 
     Returns
-    ---------------------------
-    mat_extended : double
-        corrected/verified matrix
+    -------
+    mat_extended : ndarray
+        Corrected/verified matrix.
     """
-
     mat_shape = np.array(np.shape(mat))
 
     for ix in range(0, 3-len(mat_shape)):
@@ -142,9 +310,37 @@ def correct_matrix_size(mat, n_freqs, n_dofs):
     return mat_extended
 
 def wrap_to_pi(angle):
+    """
+    Wrap angle to [-pi, pi].
+
+    Parameters
+    ----------
+    angle : float or ndarray
+        Input angle(s).
+
+    Returns
+    -------
+    wrapped : float or ndarray
+        Wrapped angle(s).
+    """
     return (angle + np.pi) % (2*np.pi) - np.pi
 
 def wrap_to_circular(x, rng=[-np.pi, np.pi]):
+    """
+    Wrap values to a circular range.
+
+    Parameters
+    ----------
+    x : float or ndarray
+        Input value(s).
+    rng : list or ndarray, optional
+        Range to wrap to (default is [-pi, pi]).
+
+    Returns
+    -------
+    wrapped : float or ndarray
+        Wrapped value(s).
+    """
     x0 = np.mean(rng)
     dx_sym = (np.max(rng) - np.min(rng))/2
     x_centered = (x + dx_sym) % (2*dx_sym) - dx_sym
@@ -155,15 +351,20 @@ def merge_tr_phi(phi_trans, phi_rot, thread_stack=True):
     """
     Merge matrices of phi for translational and rotational DOFs.
 
-    Args:
-        phi_trans: phi matrix with only translational DOFs
-        phi_rot: phi matrix with only rotational DOFs
-    Optional keywords:
-        thread_stack: specify if the matrices should be thread in or not (if True, 3 translational DOFs and 3 rotational DOFs ...) (default = True)
-    Returns:
-        phi_combined: phi matrix with all DOFs
-    """
+    Parameters
+    ----------
+    phi_trans : ndarray
+        Phi matrix with only translational DOFs.
+    phi_rot : ndarray
+        Phi matrix with only rotational DOFs.
+    thread_stack : bool, optional
+        If True, stack DOFs in thread order (default is True).
 
+    Returns
+    -------
+    phi_combined : ndarray
+        Phi matrix with all DOFs.
+    """
     Ndofs = phi_trans.shape[0]*2
 
     if thread_stack is True:
@@ -179,9 +380,22 @@ def merge_tr_phi(phi_trans, phi_rot, thread_stack=True):
 
     return phi_combined
 
-
 def mat3d_sel(mat, k):
+    """
+    Select a 2D slice from a 3D matrix.
+
+    Parameters
+    ----------
+    mat : ndarray
+        3D matrix.
+    k : int
+        Index of the slice.
 
+    Returns
+    -------
+    matsel : ndarray
+        Selected 2D matrix.
+    """
     if len(np.shape(mat)) is 3:
         matsel = mat[:, :, k]
     else:
@@ -189,40 +403,47 @@ def mat3d_sel(mat, k):
 
     return matsel
 
-
-
 def interp1z(z,mat,znew):
     """
-    Interpolate 3D matrix along z-component. !! Deprecated - use numpy functions directly instead !!
+    Interpolate 3D matrix along z-component.
 
-    Args:
-        z: z axis (Numpy array)
-        mat: 3D matrix (Numpy array)
-        znew: new z axis (Numpy array)
-    Returns:
-        matnew: interpolated 3D matrix (Numpy array)
+    Parameters
+    ----------
+    z : ndarray
+        z axis.
+    mat : ndarray
+        3D matrix.
+    znew : ndarray
+        New z axis.
 
-    """   
-        
+    Returns
+    -------
+    matnew : ndarray
+        Interpolated 3D matrix.
+    """
     matnew = np.zeros([1,len(mat[0]),len(mat[0][0])])
     for dof1 in range(0,len(mat[0])):
         for dof2 in range(0,len(mat[0][0])):
             matnew[:,dof1,dof2]=np.interp(znew,z,mat[:,dof1,dof2])
     return matnew
 
-
 def interpolate_3d(z, mat, zi):
     """
     Interpolates 3D NumPy array.
 
-    Args:
-        mats: list of 3D NumPy matrices (n_x-by-n_y-by-n_z)
-        z: original z axis
-        zi: interpolated z axis
-
-    Returns:
-        mati: interpolated matrix
+    Parameters
+    ----------
+    z : ndarray
+        Original z axis.
+    mat : ndarray
+        3D matrix (n_x-by-n_y-by-n_z).
+    zi : ndarray
+        Interpolated z axis.
 
+    Returns
+    -------
+    mati : ndarray
+        Interpolated matrix.
     """
     mat_shape = np.shape(mat)
     mati = np.zeros([mat_shape[0], mat_shape[1], len(zi)])
@@ -233,8 +454,24 @@ def interpolate_3d(z, mat, zi):
 
     return mati
 
-
 def fast_interpolation(x, y, new_x):
+    """
+    Fast cubic spline interpolation for multidimensional arrays.
+
+    Parameters
+    ----------
+    x : ndarray
+        Original x values.
+    y : ndarray
+        Original y values.
+    new_x : ndarray
+        New x values for interpolation.
+
+    Returns
+    -------
+    result : ndarray
+        Interpolated values.
+    """
     from scipy.interpolate import interp1d
     from scipy.interpolate._fitpack import _bspleval
     f = interp1d(x, y, axis=-1, kind=3)
@@ -244,10 +481,22 @@ def fast_interpolation(x, y, new_x):
         result[i, j] = _bspleval(value, x, cvals[:, i, j], k, 0)
     return result
 
+def transformation_matrix(angles, axis):
+    """
+    Generate transformation matrices for a set of angles and a given axis.
 
+    Parameters
+    ----------
+    angles : ndarray
+        Array of angles.
+    axis : int
+        Axis of rotation (0, 1, or 2).
 
-#%% Transformation matrix generation / manipulation
-def transformation_matrix(angles, axis):
+    Returns
+    -------
+    T : ndarray
+        Transformation matrices (len(angles), 6, 6).
+    """
     T = np.empty([len(angles),6,6])
     for idx,angle in enumerate(angles):
         c = np.cos(angle)
@@ -263,21 +512,24 @@ def transformation_matrix(angles, axis):
 
     return T
 
-
 def rodrot(theta, rotaxis=[0, 0, 1], style='row'):
     """
     Establishes 3D rotation matrix based on Euler-Rodrigues formula.
-    See https://en.wikipedia.org/wiki/Euler-Rodrigues_formula.
-
-    Args:
-        theta: the rotation angle (in radians)
-        [rotaxis]: vector defining rotation axis (default [0, 0, 1])
 
-    Returns:
-        T: transformation matrix in NumPy format
+    Parameters
+    ----------
+    theta : float
+        Rotation angle (in radians).
+    rotaxis : array_like, optional
+        Vector defining rotation axis (default [0, 0, 1]).
+    style : str, optional
+        Output style ('row' or other, default 'row').
 
+    Returns
+    -------
+    T : ndarray
+        Transformation matrix.
     """
-
     axis = np.asarray(rotaxis)
     axis = rotaxis/np.sqrt(np.dot(rotaxis, rotaxis))    # Normalize
     a = np.cos(theta/2.0)
@@ -293,16 +545,44 @@ def rodrot(theta, rotaxis=[0, 0, 1], style='row'):
     
     return T
 
-
 def multi_rodrot(angles, rotaxis=[0,0,1], style='row'):
+    """
+    Generate multiple 6x6 rotation matrices for a set of angles.
+
+    Parameters
+    ----------
+    angles : ndarray
+        Array of angles.
+    rotaxis : array_like, optional
+        Rotation axis (default [0, 0, 1]).
+    style : str, optional
+        Output style (default 'row').
+
+    Returns
+    -------
+    T : list of ndarray
+        List of 6x6 rotation matrices.
+    """
     T = [None]*len(angles)
     for ix, angle in enumerate(angles):
         T[ix] = blkdiag(rodrot(angle, rotaxis=rotaxis, style=style), 2)
 
     return T
 
-
 def stack_T(T_multi):
+    """
+    Stack multiple transformation matrices into a block diagonal matrix.
+
+    Parameters
+    ----------
+    T_multi : list of ndarray
+        List of transformation matrices.
+
+    Returns
+    -------
+    T : ndarray
+        Block diagonal transformation matrix.
+    """
     n_dofs = np.shape(T_multi[0])[0]
     N = len(T_multi)
 
@@ -313,8 +593,22 @@ def stack_T(T_multi):
 
     return T
 
-
 def transform_unit(e1, e2p):
+    """
+    Generate a transformation matrix from two unit vectors.
+
+    Parameters
+    ----------
+    e1 : array_like
+        First unit vector.
+    e2p : array_like
+        Second vector (not necessarily unit).
+
+    Returns
+    -------
+    T : ndarray
+        Transformation matrix (3x3).
+    """
     e1 = np.array(e1).flatten()
     e2p = np.array(e2p).flatten()
 
@@ -329,8 +623,22 @@ def transform_unit(e1, e2p):
 
     return T
 
-
 def transform_3dmat(mat, T):
+    """
+    Transform a 3D matrix using a transformation matrix.
+
+    Parameters
+    ----------
+    mat : ndarray
+        3D matrix (n_dofs, n_dofs, n_freqs).
+    T : ndarray
+        Transformation matrix.
+
+    Returns
+    -------
+    mat_transformed : ndarray
+        Transformed 3D matrix.
+    """
     M, N = np.shape(T)[0:2]
     [n_dofs, __, n_freqs] = np.shape(mat)
 
@@ -347,9 +655,20 @@ def transform_3dmat(mat, T):
 
     return mat_transformed
 
-#%% Other
 def assess_diagonality_fro(M):
-    # Diagonality Measures of Hermitian Positive-Definite Matrices with Application to the Approximate Joint Diagonalization Problem
+    """
+    Assess diagonality of a Hermitian positive-definite matrix using Frobenius norm.
+
+    Parameters
+    ----------
+    M : ndarray
+        Input matrix (2D, square).
+
+    Returns
+    -------
+    diagonality : float
+        Diagonality measure.
+    """
     if M.ndim != 2:
         raise ValueError('Input must be 2d array.')
     if np.shape(M)[0] != np.shape(M)[1]:
@@ -364,9 +683,20 @@ def assess_diagonality_fro(M):
 
     return diagonality
 
-
 def assess_diagonality(M):
-    # Diagonality Measures of Hermitian Positive-Definite Matrices with Application to the Approximate Joint Diagonalization Problem
+    """
+    Assess diagonality of a Hermitian positive-definite matrix.
+
+    Parameters
+    ----------
+    M : ndarray
+        Input matrix (2D, square).
+
+    Returns
+    -------
+    diagonality : float
+        Diagonality measure.
+    """
     if M.ndim != 2:
         raise ValueError('Input must be 2d array.')
     if np.shape(M)[0] != np.shape(M)[1]:
@@ -380,16 +710,52 @@ def assess_diagonality(M):
 
     return diagonality
 
-
 def modify_stiffness(stiffness, submerged_vol, water_dens, g, z_cog, z_cog_mod):
+    """
+    Modify stiffness matrix for change in center of gravity.
+
+    Parameters
+    ----------
+    stiffness : ndarray
+        Original stiffness matrix.
+    submerged_vol : float
+        Submerged volume.
+    water_dens : float
+        Water density.
+    g : float
+        Gravitational acceleration.
+    z_cog : float
+        Original center of gravity (z).
+    z_cog_mod : float
+        Modified center of gravity (z).
+
+    Returns
+    -------
+    stiffness_mod : ndarray
+        Modified stiffness matrix.
+    """
     stiffness_mod = stiffness
     stiffness_mod[3, 3] = stiffness[3, 3]  + submerged_vol * water_dens * g * (z_cog - z_cog_mod)
     stiffness_mod[4, 4] = stiffness[4, 4]+ submerged_vol * water_dens * g * (z_cog - z_cog_mod)
 
     return stiffness_mod
 
-
 def maxreal(phi, preserve_conjugates=False):
+    """
+    Rotate complex mode shapes to maximize real part.
+
+    Parameters
+    ----------
+    phi : ndarray
+        Mode shape matrix.
+    preserve_conjugates : bool, optional
+        If True, preserve conjugate pairs (default False).
+
+    Returns
+    -------
+    phi_max_real : ndarray
+        Rotated mode shapes with maximized real part.
+    """
     angles = np.expand_dims(np.arange(0,np.pi/2, 0.01), axis=0)
     
     if phi.ndim==1:
@@ -405,8 +771,26 @@ def maxreal(phi, preserve_conjugates=False):
   
     return phi_max_real
 
-
 def create_circular_x(x, tol=1e-5, rng=np.array([-np.pi, np.pi])):
+    """
+    Create a circularly wrapped and sorted version of x.
+
+    Parameters
+    ----------
+    x : ndarray
+        Input array.
+    tol : float, optional
+        Tolerance for uniqueness (default 1e-5).
+    rng : ndarray, optional
+        Range for wrapping (default [-pi, pi]).
+
+    Returns
+    -------
+    x_ang : ndarray
+        Wrapped and sorted array.
+    sort_ix : ndarray
+        Indices of unique values.
+    """
     xrng = np.max(x)-np.min(x)
 
     wrapped_x = np.sort(wrap_to_circular(x, rng))
@@ -421,24 +805,93 @@ def create_circular_x(x, tol=1e-5, rng=np.array([-np.pi, np.pi])):
     
     return x_ang, sort_ix
 
-
 def interp1d_angular(x, mat, rng=[-np.pi, np.pi], axis=-1, **kwargs):
+    """
+    Interpolate data defined on a circular domain.
+
+    Parameters
+    ----------
+    x : ndarray
+        Input angular values.
+    mat : ndarray
+        Data to interpolate.
+    rng : list or ndarray, optional
+        Range for wrapping (default [-pi, pi]).
+    axis : int, optional
+        Axis along which to interpolate (default -1).
+    **kwargs
+        Additional arguments to scipy.interpolate.interp1d.
+
+    Returns
+    -------
+    interp_fun : callable
+        Interpolation function.
+    """
     from scipy.interpolate import interp1d
     x_ang, sort_ix = create_circular_x(x, rng=rng)
     mat = np.take(mat, sort_ix, axis=axis)
     return lambda x: interp1d(x_ang, mat, axis=axis, **kwargs)(wrap_to_circular(x, rng=rng))
 
-
 def interp_hydro_transfer(omega, theta, Q, rng=[-np.pi, np.pi], theta_axis=1, omega_axis=2, interpolation_kind='linear', theta_settings=dict(), omega_settings=dict()):
+    """
+    Interpolate hydrodynamic transfer function in both frequency and angle.
+
+    Parameters
+    ----------
+    omega : ndarray
+        Frequency vector.
+    theta : ndarray
+        Angle vector.
+    Q : ndarray
+        Transfer function data.
+    rng : list or ndarray, optional
+        Range for wrapping (default [-pi, pi]).
+    theta_axis : int, optional
+        Axis for theta (default 1).
+    omega_axis : int, optional
+        Axis for omega (default 2).
+    interpolation_kind : str, optional
+        Interpolation kind (default 'linear').
+    theta_settings : dict, optional
+        Additional settings for theta interpolation.
+    omega_settings : dict, optional
+        Additional settings for omega interpolation.
+
+    Returns
+    -------
+    Qi : callable
+        Interpolated transfer function.
+    """
     from scipy.interpolate import interp1d
     Qi = lambda om, th: interp1d(omega, interp1d(theta, Q, axis=theta_axis, fill_value='extrapolate', **theta_settings)(wrap_to_circular(th, rng=rng)), 
                                    fill_value='extrapolate', kind=interpolation_kind, axis=omega_axis, **omega_settings)(om)
     
     return Qi
-    
-    
 
 def interp2d_angular(x, theta, mat, rng=[-np.pi, np.pi], method='linear', **kwargs):
+    """
+    2D interpolation on a circular domain.
+
+    Parameters
+    ----------
+    x : ndarray
+        First coordinate array.
+    theta : ndarray
+        Angular coordinate array.
+    mat : ndarray
+        Data to interpolate.
+    rng : list or ndarray, optional
+        Range for wrapping (default [-pi, pi]).
+    method : str, optional
+        Interpolation method (default 'linear').
+    **kwargs
+        Additional arguments to scipy.interpolate.griddata.
+
+    Returns
+    -------
+    funi : callable
+        Interpolation function.
+    """
     from scipy.interpolate import griddata
 
     def funi(xi, thetai):
@@ -456,9 +909,24 @@ def interp2d_angular(x, theta, mat, rng=[-np.pi, np.pi], method='linear', **kwar
         
     return funi
 
+def uniquetol(a, tol):
+    """
+    Return unique values of an array within a tolerance.
 
+    Parameters
+    ----------
+    a : ndarray
+        Input array.
+    tol : float
+        Tolerance for uniqueness.
 
-def uniquetol(a, tol):
+    Returns
+    -------
+    result : ndarray
+        Unique values.
+    i : ndarray
+        Indices of unique values.
+    """
     import numpy as np
     i = np.argsort(a.flat)
     d = np.append(True, np.diff(a.flat[i]))