Source code for zefir.potential.flows.uniform

"""
Uniform flow implementation.

This module provides the UniformFlow class representing a flow with constant
velocity throughout the entire domain.
"""

import numpy as np
from ...typing import Tuple, CplxNDArray, ParamType
from .base import ComplexPotential, FlowMetadata, InvalidDerivLevel
from zefir.logging import debug, info, error




class UniformFlow(ComplexPotential):
    """Uniform flow with constant velocity.
    
    A uniform flow represents a fluid flow with constant velocity vector
    throughout the entire domain. The complex potential is given by:
    
    .. math:: f(z) = V_\\infty z
    
    where :math:`V_\\infty` is the complex velocity at infinity.
    
    Parameters
    ----------
    infinite_velocity : Tuple[float, float]
        Velocity vector (Vx, Vy) at infinity
        
    Attributes
    ----------
    _vinf : complex
        Complex representation of the velocity at infinity
        
    Examples
    --------
    >>> flow = UniformFlow((1.0, 0.0))
    >>> z = np.array([0+0j, 1+0j, 0+1j])
    >>> potential = flow(z)
    >>> potential
    array([0.+0.j, 1.+0.j, 0.+1.j])
    >>> velocity = flow.velocity(z)
    >>> velocity
    array([1.+0.j, 1.+0.j, 1.+0.j])
    """
    
    metadata = FlowMetadata(
        "Uniform Flow",
        {
            "infinite_velocity": {
                "type": ParamType.VECTOR2,
                "default": [1.0, 0.0],
                "min": -10,
                "max": 10,
                "labels": ["Vx", "Vy"]
            }
        },
        has_position=False
    )
    


    def __init__(self, infinite_velocity:Tuple[float, float]):
        # In complex potential theory: dw/dz = u - iv
        # So we need to negate the y-component when creating the complex velocity
        self._vinf: complex = complex(infinite_velocity[0], -infinite_velocity[1])
        self._infinite_velocity = infinite_velocity
        debug(f"Created UniformFlow with velocity V∞ = ({infinite_velocity[0]:.3f}, {infinite_velocity[1]:.3f})")




    def __call__(
            self, z: CplxNDArray, deriv:int=0) -> CplxNDArray:
        """Evaluate the complex potential or its derivative.
        
        Parameters
        ----------
        z : CplxNDArray
            Complex array of points where the potential is evaluated
        deriv : int, optional
            Derivative level: 0 for potential, 1 for velocity
            
        Returns
        -------
        CplxNDArray
            Complex potential (deriv=0) or velocity (deriv=1)
            
        Raises
        ------
        InvalidDerivLevel
            If deriv is not 0 or 1
        """
        if deriv == 0:
            debug(f"Evaluating uniform flow potential at {z.size} points")
            return self._vinf*z
        elif deriv == 1:
            debug(f"Evaluating uniform flow velocity at {z.size} points")
            return self._vinf*np.ones(z.shape, dtype=z.dtype)
        else: 
            error(f"Invalid derivative level {deriv} requested for UniformFlow")
            raise InvalidDerivLevel()