refactor tanh, add docs, tests on all real precisions

Author: jalvesz

doc/specs/stdlib_specialfunctions_activations.md

@@ -762,4 +762,85 @@ Elemental function
 
 ### Return value
 
+The function returns a value with the same type and kind as input argument.
+
+## `Fast tanh` - Approximation of the hyperbolic tangent function
+
+### Status
+
+Experimental
+
+### Description
+
+Computes an approximated but faster solution to:
+$$f(x)=\tanh(x)$$
+
+### Syntax
+
+`result = ` [[stdlib_specialfunctions(module):fast_tanh(interface)]] ` (x)`
+
+### Class
+
+Elemental function
+
+### Arguments
+
+`x`: Shall be a scalar or array of any `real` kind. 
+
+### Return value
+
+The function returns a value with the same type and kind as input argument.
+
+## `fast_tanh_grad` - Gradient of the approximation of the hyperbolic tangent function
+
+### Status
+
+Experimental
+
+### Description
+
+Computes the gradient of the `fast_tanh` function:
+$$f(x)=1 - \fast_tanh(x)^2$$
+
+### Syntax
+
+`result = ` [[stdlib_specialfunctions(module):fast_tanh_grad(interface)]] ` (x)`
+
+### Class
+
+Elemental function
+
+### Arguments
+
+`x`: Shall be a scalar or array of any `real` kind. 
+
+### Return value
+
+The function returns a value with the same type and kind as input argument.
+
+## `Fast erf` - Approximation of the error function
+
+### Status
+
+Experimental
+
+### Description
+
+Computes an approximated but faster solution to:
+$$f(x)=\erf(x)$$
+
+### Syntax
+
+`result = ` [[stdlib_specialfunctions(module):fast_erf(interface)]] ` (x)`
+
+### Class
+
+Elemental function
+
+### Arguments
+
+`x`: Shall be a scalar or array of any `real` kind. 
+
+### Return value
+
 The function returns a value with the same type and kind as input argument.

src/stdlib_specialfunctions.fypp

@@ -315,32 +315,6 @@ module stdlib_specialfunctions
     end interface
     public :: step_grad
 
-    interface tanh
-        !! Version: experimental
-        !!
-        !! gaussian function
-        #:for rk, rt in REAL_KINDS_TYPES
-        elemental module function tanh_${rk}$( x ) result( y )
-            ${rt}$, intent(in) :: x
-            ${rt}$ :: y
-        end function
-        #:endfor
-    end interface
-    public :: tanh
-
-    interface tanh_grad
-        !! Version: experimental
-        !!
-        !! gradient of the hyperbolic tangent function
-        #:for rk, rt in REAL_KINDS_TYPES
-        elemental module function tanh_grad_${rk}$( x ) result( y )
-            ${rt}$, intent(in) :: x
-            ${rt}$ :: y
-        end function
-        #:endfor
-    end interface
-    public :: tanh_grad
-
     interface softmax
         !! Version: experimental
         !!
@@ -435,32 +409,43 @@ module stdlib_specialfunctions
     end interface
     public :: softplus_grad
 
-    interface ftanh 
+    interface fast_tanh 
         !! Version: experimental
         !!
         !! Fast approximation of the tanh function
-        !! Source: https://fortran-lang.discourse.group/t/fastgpt-faster-than-pytorch-in-300-lines-of-fortran/5385/31
         #:for rk, rt in REAL_KINDS_TYPES
-        elemental module function ftanh_${rk}$( x ) result( y )
+        elemental module function fast_tanh_${rk}$( x ) result( y )
+            ${rt}$, intent(in) :: x
+            ${rt}$ :: y
+        end function
+        #:endfor
+    end interface
+    public :: fast_tanh
+
+    interface fast_tanh_grad
+        !! Version: experimental
+        !!
+        !! gradient of the hyperbolic tangent function
+        #:for rk, rt in REAL_KINDS_TYPES
+        elemental module function fast_tanh_grad_${rk}$( x ) result( y )
             ${rt}$, intent(in) :: x
             ${rt}$ :: y
         end function
         #:endfor
     end interface
-    public :: ftanh
+    public :: fast_tanh_grad
 
-    interface ferf 
+    interface fast_erf 
         !! Version: experimental
         !!
         !! Fast approximation of the erf function
-        !! Source: https://fortran-lang.discourse.group/t/fastgpt-faster-than-pytorch-in-300-lines-of-fortran/5385/31
         #:for rk, rt in REAL_KINDS_TYPES
-        elemental module function ferf_${rk}$( x ) result( y )
+        elemental module function fast_erf_${rk}$( x ) result( y )
             ${rt}$, intent(in) :: x
             ${rt}$ :: y
         end function
         #:endfor
     end interface
-    public :: ferf
+    public :: fast_erf
 
-end module stdlib_specialfunctions
+end module stdlib_specialfunctions

src/stdlib_specialfunctions_activations.fypp

@@ -108,13 +108,13 @@ end function
 elemental module function gelu_approx_${rk}$( x ) result( y )
     ${rt}$, intent(in) :: x
     ${rt}$ :: y
-    y = 0.5_${rk}$ * x * (1._${rk}$ + ferf(x * isqrt2_${rk}$))
+    y = 0.5_${rk}$ * x * (1._${rk}$ + fast_erf(x * isqrt2_${rk}$))
 end function
 
 elemental module function gelu_approx_grad_${rk}$( x ) result( y )
     ${rt}$, intent(in) :: x
     ${rt}$ :: y
-    y = 0.5_${rk}$ * (1._${rk}$ + ferf(x * isqrt2_${rk}$) )
+    y = 0.5_${rk}$ * (1._${rk}$ + fast_erf(x * isqrt2_${rk}$) )
     y = y + x * isqrt2_${rk}$ * exp( - 0.5_${rk}$ * x**2 )
 end function
 
@@ -198,24 +198,6 @@ end function
 
 #:endfor
 
-!==================================================
-! tanh
-!==================================================
-#:for rk, rt in REAL_KINDS_TYPES
-elemental module function tanh_${rk}$( x ) result( y )
-    ${rt}$, intent(in) :: x
-    ${rt}$ :: y
-    y = ftanh(x)
-end function
-
-elemental module function tanh_grad_${rk}$( x ) result( y )
-    ${rt}$, intent(in) :: x
-    ${rt}$ :: y
-    y = 1._${rk}$ - ftanh(x)**2
-end function
-
-#:endfor
-
 !==================================================
 ! softmax
 !==================================================
@@ -352,7 +334,8 @@ end function
 !==================================================
 
 #:for rk, rt in REAL_KINDS_TYPES
-elemental module function ftanh_${rk}$( x ) result( y )
+! Source: https://fortran-lang.discourse.group/t/fastgpt-faster-than-pytorch-in-300-lines-of-fortran/5385/31
+elemental module function fast_tanh_${rk}$( x ) result( y )
     ${rt}$, intent(in) :: x
     ${rt}$ :: y
     ${rt}$ :: x2, a, b
@@ -363,7 +346,14 @@ elemental module function ftanh_${rk}$( x ) result( y )
     y = merge( a / b , sign(1._${rk}$,x) , x2 <= 25._${rk}$ )
 end function
 
-elemental module function ferf_${rk}$( x ) result( y )
+elemental module function fast_tanh_grad_${rk}$( x ) result( y )
+    ${rt}$, intent(in) :: x
+    ${rt}$ :: y
+    y = 1._${rk}$ - fast_tanh(x)**2
+end function
+
+! Source: https://fortran-lang.discourse.group/t/fastgpt-faster-than-pytorch-in-300-lines-of-fortran/5385/31
+elemental module function fast_erf_${rk}$( x ) result( y )
     ${rt}$, intent(in) :: x
     ${rt}$ :: y
     ${rt}$ :: abs_x