Add complex number support to tanh

[kgryte]

This PR

• adds complex number support to tanh by documenting special cases. The hyperbolic tangent is an analytical function in the complex plane and has no branch cuts.
• updates the input and output array data types to be any floating-point data type, not just real-valued floating-point data types.
• derives special cases from C99 and tested against NumPy (script found below).
• adds a warning concerning two special cases where results may differ depending on which C version an array library compiles against (for those libraries which are C compiled).

import numpy as np
import math

def is_equal_float(x, y):
    """Test whether two floating-point numbers are equal with special consideration for zeros and NaNs.

    Parameters
    ----------
    x : float
        First input number.
    y : float
        Second input number.

    Returns
    -------
    bool
        Boolean indicating whether two floating-point numbers are equal.

    Examples
    --------
    >>> is_equal_float(0.0, -0.0)
    False
    >>> is_equal_float(-0.0, -0.0)
    True
    """
    # Handle +-0:
    if x == 0.0 and y == 0.0:
        return math.copysign(1.0, x) == math.copysign(1.0, y)

    # Handle NaNs:
    if x != x:
        return y != y

    # Everything else, including infinities:
    return x == y


def is_equal(x, y):
    """Test whether two complex numbers are equal with special consideration for zeros and NaNs.

    Parameters
    ----------
    x : complex
        First input number.
    y : complex
        Second input number.

    Returns
    -------
    bool
        Boolean indicating whether two complex numbers are equal.

    Examples
    --------
    >>> import numpy as np
    >>> is_equal(complex(np.nan, np.nan), complex(np.nan, np.nan))
    True
    """
    return is_equal_float(x.real, y.real) and is_equal_float(x.imag, y.imag)


# Strided array consisting of input values and expected values:
values = [
    complex(0.0, 0.0),        # 0
    complex(0.0, 0.0),        # 0
    
    complex(-0.0, -0.0),      # 1
    complex(-0.0, -0.0),      # 1
    
    complex(1.0, np.inf),     # 2
    complex(np.nan, np.nan),  # 2
    
    complex(0.0, np.inf),     # 3
    complex(0.0, np.nan),     # 3, seems to be a bug in NumPy, which returns `NaN + NaN j`; however, this does match old C99 behavior (see https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1892.htm#dr_471)
    
    complex(1.0, np.nan),     # 4
    complex(np.nan, np.nan),  # 4
    
    complex(0.0, np.nan),     # 5
    complex(0.0, np.nan),     # 5 seems to be a bug in NumPy, which returns `NaN + NaN j`; however, this does match old C99 behavior (see https://www.open-std.org/jtc1/sc22/wg14/www/docs/n1892.htm#dr_471)
    
    complex(np.inf, 1.0),     # 6
    complex(1.0, 0.0),        # 6
    
    complex(np.inf, np.inf),  # 7
    complex(1.0, -0.0),       # 7
    
    complex(np.inf, np.nan),  # 8
    complex(1.0, 0.0),        # 8
    
    complex(np.nan, 0.0),     # 9
    complex(np.nan, 0.0),     # 9
    
    complex(np.nan, 1.0),     # 10
    complex(np.nan, np.nan),  # 10

    complex(np.nan, np.nan),  # 11
    complex(np.nan, np.nan)   # 11
]

for i in range(len(values)//2):
    j = i * 2
    v = values[j]
    e = values[j+1]
    actual = np.tanh(v)
    print('Index: {index}'.format(index=str(i)))
    print('Value: {value}'.format(value=str(v)))
    print('Actual: {actual}'.format(actual=str(actual)))
    print('Expected: {expected}'.format(expected=str(e)))
    print('Equal: {is_equal}'.format(is_equal=str(is_equal(actual, e))))
    print('\n')

Index: 0
Value: 0j
Actual: 0j
Expected: 0j
Equal: True


Index: 1
Value: (-0-0j)
Actual: (-0-0j)
Expected: (-0-0j)
Equal: True


Index: 2
Value: (1+infj)
Actual: (nan+nanj)
Expected: (nan+nanj)
Equal: True


Index: 3
Value: infj
Actual: (nan+nanj)
Expected: nanj
Equal: False


Index: 4
Value: (1+nanj)
Actual: (nan+nanj)
Expected: (nan+nanj)
Equal: True


Index: 5
Value: nanj
Actual: (nan+nanj)
Expected: nanj
Equal: False


Index: 6
Value: (inf+1j)
Actual: (1+0j)
Expected: (1+0j)
Equal: True


/path/to/ctanh.py:107: RuntimeWarning: invalid value encountered in tanh
  actual = np.tanh(v)
Index: 7
Value: (inf+infj)
Actual: (1-0j)
Expected: (1-0j)
Equal: True


Index: 8
Value: (inf+nanj)
Actual: (1+0j)
Expected: (1+0j)
Equal: True


Index: 9
Value: (nan+0j)
Actual: (nan+0j)
Expected: (nan+0j)
Equal: True


Index: 10
Value: (nan+1j)
Actual: (nan+nanj)
Expected: (nan+nanj)
Equal: True


Index: 11
Value: (nan+nanj)
Actual: (nan+nanj)
Expected: (nan+nanj)
Equal: True

Notes

• NumPy deviates from special behavior in two cases: 0 + inf j and 0 + NaN j. NumPy adheres to old C99 behavior; however, this was corrected in the C standard in 2014.

[kgryte]

As the changes in this PR are straightforward (no branch cuts, etc) and this PR has been allowed time for review, will go ahead and merge. Any further modifications can be addressed in subsequent PRs...