### ----------------------------------------------------
### -- Math::Libgsl::Function
### -- Licenses: Artistic-2.0
### -- Authors: Fernando Santagata
### -- File: lib/Math/Libgsl/Function.rakumod
### ----------------------------------------------------
### -- Chunk 8 of 8
 used.
To include or exclude the Condon-Shortley phase factor of (−1)ⁿ, set the parameter csphase to either −1 or 1 respectively.
They return a List of Pairs (that can be read as a Hash):

=item :out       array of Pⁿₗ(x) values
=item :derout    array of dPⁿₗ(x)/dx values

=head3 sub legendre-deriv2-array(Int $norm, size_t $lmax where * ≤ 150, Num(Cool) $x where -1 ≤ * ≤ 1 --> List) is export(:legendre)
=head3 sub legendre-deriv2-array-e(Int $norm, UInt $lmax, Num(Cool) $x where -1 ≤ * ≤ 1, Num(Cool) $csphase where * == 1|-1 --> List) is export(:legendre)

These functions calculate all normalized associated Legendre functions and their first and second derivatives up to degree lmax.
The parameter norm specifies the normalization to be used.
They return a List of Pairs (that can be read as a Hash):

=item :out       array of Pⁿₗ(x) values
=item :derout    array of dPⁿₗ(x)/dx values
=item :derout2   array of d²Pⁿₗ(x)/d²x values

=head3 sub legendre-deriv2-alt-array(Int $norm, size_t $lmax where * ≤ 150, Num(Cool) $x where -1 ≤ * ≤ 1 --> List) is export(:legendre)
=head3 sub legendre-deriv2-alt-array-e(Int $norm, UInt $lmax, Num(Cool) $x where -1 ≤ * ≤ 1, Num(Cool) $csphase where * == 1|-1 --> List) is export(:legendre)

These functions calculate all normalized associated Legendre functions and their (alternate) first and second derivatives up to degree lmax.
The parameter norm specifies the normalization to be used.
To include or exclude the Condon-Shortley phase factor of (−1)ⁿ, set the parameter csphase to either −1 or 1 respectively.
They return a List of Pairs (that can be read as a Hash):

=item :out       array of normalized Pⁿₗ(x) values
=item :derout    array of dPⁿₗ(cos(θ))/dθ values
=item :derout2   array of d²Pⁿₗ(cos(θ))/d²θ values

=head3 sub legendre-Plm(UInt $l, UInt $n, Num(Cool) $x where -1 ≤ * ≤ 1 --> Num) is export(:legendre)
=head3 sub legendre-Plm-e(UInt $l, UInt $n, Num(Cool) $x where -1 ≤ * ≤ 1 --> List) is export(:legendre)

These routines compute the associated Legendre polynomial Pⁿₗ(x).

=head3 sub legendre-sphPlm(UInt $l, UInt $m, Num(Cool) $x where -1 ≤ * ≤ 1 --> Num) is export(:legendre)
=head3 sub legendre-sphPlm-e(UInt $l, UInt $m, Num(Cool) $x where -1 ≤ * ≤ 1 --> List) is export(:legendre)

These routines compute the normalized associated Legendre polynomial.

=head3 sub conicalP-half(Num(Cool) $lambda, Num(Cool) $x where * > -1 --> Num) is export(:legendre)
=head3 sub conicalP-half-e(Num(Cool) $lambda, Num(Cool) $x where * > -1 --> List) is export(:legendre)

These routines compute the irregular Spherical Conical Function.

=head3 sub conicalP-mhalf(Num(Cool) $lambda, Num(Cool) $x where * > -1 --> Num) is export(:legendre)
=head3 sub conicalP-mhalf-e(Num(Cool) $lambda, Num(Cool) $x where * > -1 --> List) is export(:legendre)

These routines compute the regular Spherical Conical Function.

=head3 sub conicalP0(Num(Cool) $lambda, Num(Cool) $x where * > -1 --> Num) is export(:legendre)
=head3 sub conicalP0-e(Num(Cool) $lambda, Num(Cool) $x where * > -1 --> List) is export(:legendre)

These routines compute the conical function P⁰.

=head3 sub conicalP1(Num(Cool) $lambda, Num(Cool) $x where * > -1 --> Num) is export(:legendre)
=head3 sub conicalP1-e(Num(Cool) $lambda, Num(Cool) $x where * > -1 --> List) is export(:legendre)

These routines compute the conical function P¹.

=head3 sub conicalP-sph-reg(Int $l where * ≥ -1, Num(Cool) $lambda, Num(Cool) $x where * > -1 --> Num) is export(:legendre)
=head3 sub conicalP-sph-reg-e(Int $l where * ≥ -1, Num(Cool) $lambda, Num(Cool) $x where * > -1 --> List) is export(:legendre)

These routines compute the Regular Spherical Conical Function.

=head3 sub conicalP-cyl-reg(Int $m where * ≥ -1, Num(Cool) $lambda, Num(Cool) $x where * > -1 --> Num) is export(:legendre)
=head3 sub conicalP-cyl-reg-e(Int $m where * ≥ -1, Num(Cool) $lambda, Num(Cool) $x where * > -1 --> List) is export(:legendre)

These routines compute the Regular Cylindrical Conical Function.

=head3 sub legendre-H3d0(Num(Cool) $lambda, Num(Cool) $eta where * ≥ 0 --> Num) is export(:legendre)
=head3 sub legendre-H3d0-e(Num(Cool) $lambda, Num(Cool) $eta where * ≥ 0 --> List) is export(:legendre)

These routines compute the zeroth radial eigenfunction of the Laplacian on the 3-dimensional hyperbolic space.

=head3 sub legendre-H3d1(Num(Cool) $lambda, Num(Cool) $eta where * ≥ 0 --> Num) is export(:legendre)
=head3 sub legendre-H3d1-e(Num(Cool) $lambda, Num(Cool) $eta where * ≥ 0 --> List) is export(:legendre)

These routines compute the first radial eigenfunction of the Laplacian on the 3-dimensional hyperbolic space.

=head3 sub legendre-H3d(UInt $l, Num(Cool) $lambda, Num(Cool) $eta where * ≥ 0 --> Num) is export(:legendre)
=head3 sub legendre-H3d-e(UInt $l, Num(Cool) $lambda, Num(Cool) $eta where * ≥ 0 --> List) is export(:legendre)

These routines compute the l-th radial eigenfunction of the Laplacian on the 3-dimensional hyperbolic space.

=head3 sub legendre-H3d-array(UInt $lmax, Num(Cool) $lambda, Num(Cool) $eta where * ≥ 0 --> List) is export(:legendre)

This function computes an array of radial eigenfunctions.

=head3 sub gsl-log(Num(Cool) $x where * > 0 --> Num) is export(:log)
=head3 sub gsl-log-e(Num(Cool) $x where * > 0 --> List) is export(:log)

These routines compute the logarithm of x.

=head3 sub gsl-log-abs(Num(Cool) $x where * ≠ 0 --> Num) is export(:log)
=head3 sub gsl-log-abs-e(Num(Cool) $x where * ≠ 0 --> List) is export(:log)

These routines compute the logarithm of the magnitude of x.

=head3 sub gsl-log-complex-e(Num(Cool) $zr, Num(Cool) $zi --> List) is export(:log)

This routine computes the complex logarithm of z = zᵣ + izᵢ.
The returned parameters are the radial part, its error, θ in the range [−π, π], and its error.

=head3 sub gsl-log1plusx(Num(Cool) $x where * > -1 --> Num) is export(:log)
=head3 sub gsl-log1plusx-e(Num(Cool) $x where * > -1 --> List) is export(:log)

These routines compute log(1 + x).

=head3 sub gsl-log1plusx-mx(Num(Cool) $x where * > -1 --> Num) is export(:log)
=head3 sub gsl-log1plusx-mx-e(Num(Cool) $x where * > -1 --> List) is export(:log)

These routines compute log(1 + x) − x.

=head3 sub mathieu-a(Int $n, Num(Cool) $q --> Num) is export(:mathieu)
=head3 sub mathieu-a-e(Int $n, Num(Cool) $q --> List) is export(:mathieu)
=head3 sub mathieu-b(Int $n, Num(Cool) $q --> Num) is export(:mathieu)
=head3 sub mathieu-b-e(Int $n, Num(Cool) $q --> List) is export(:mathieu)

These routines compute the characteristic values aₙ(q), bₙ(q) of the Mathieu functions ceₙ(q, x) and seₙ(q, x), respectively.

=head3 sub mathieu-a-array(Int $order-min, Int $order-max, Num(Cool) $q --> List) is export(:mathieu)
=head3 sub mathieu-b-array(Int $order-min, Int $order-max, Num(Cool) $q --> List) is export(:mathieu)

These routines compute a series of Mathieu characteristic values aₙ(q), bₙ(q) for n from order_min to order_max inclusive.

=head3 sub mathieu-ce(Int $n, Num(Cool) $q, Num(Cool) $x --> Num) is export(:mathieu)
=head3 sub mathieu-ce-e(Int $n, Num(Cool) $q, Num(Cool) $x --> List) is export(:mathieu)
=head3 sub mathieu-se(Int $n, Num(Cool) $q, Num(Cool) $x --> Num) is export(:mathieu)
=head3 sub mathieu-se-e(Int $n, Num(Cool) $q, Num(Cool) $x --> List) is export(:mathieu)

These routines compute the angular Mathieu functions ceₙ(q, x) and seₙ(q, x), respectively.

=head3 sub mathieu-ce-array(Int $order-min, Int $order-max, Num(Cool) $q, Num(Cool) $x --> List) is export(:mathieu)
=head3 sub mathieu-se-array(Int $order-min, Int $order-max, Num(Cool) $q, Num(Cool) $x --> List) is export(:mathieu)

These routines compute a series of the angular Mathieu functions ceₙ(q, x) and seₙ(q, x) of order n from nmin to nmax inclusive.

=head3 sub mathieu-Mc(Int $j where * == 1|2, Int $n, Num(Cool) $q, Num(Cool) $x --> Num) is export(:mathieu)
=head3 sub mathieu-Mc-e(Int $j where * == 1|2, Int $n, Num(Cool) $q, Num(Cool) $x --> List) is export(:mathieu)
=head3 sub mathieu-Ms(Int $j where * == 1|2, Int $n, Num(Cool) $q, Num(Cool) $x --> Num) is export(:mathieu)
=head3 sub mathieu-Ms-e(Int $j where * == 1|2, Int $n, Num(Cool) $q, Num(Cool) $x --> List) is export(:mathieu)

These routines compute the radial j-th kind Mathieu functions Mcₙ(q, x) and Msₙ(q, x) of order n.

=head3 sub mathieu-Mc-array(Int $j where * == 1|2, Int $nmin, Int $nmax, Num(Cool) $q, Num(Cool) $x --> List) is export(:mathieu)
=head3 sub mathieu-Ms-array(Int $j where * == 1|2, Int $nmin, Int $nmax, Num(Cool) $q, Num(Cool) $x --> List) is export(:mathieu)

These routines compute a series of the radial Mathieu functions of kind j, with order from nmin to nmax inclusive.

=head3 sub pow-int(Num(Cool) $x, Int $n --> Num) is export(:pow)
=head3 sub pow-int-e(Num(Cool) $x, Int $n --> List) is export(:pow)

These routines compute the power xⁿ for integer n.

=head3 sub psi-int(UInt $n where * > 0 --> Num) is export(:psi)
=head3 sub psi-int-e(UInt $n where * > 0 --> List) is export(:psi)

These routines compute the Digamma function ψ(n) for positive integer n.

=head3 sub psi(Num(Cool) $x where * ≠ 0 --> Num) is export(:psi)
=head3 sub psi-e(Num(Cool) $x where * ≠ 0 --> List) is export(:psi)

These routines compute the Digamma function ψ(x) for general x.

=head3 sub psi1piy(Num(Cool) $y --> Num) is export(:psi)
=head3 sub psi1piy-e(Num(Cool) $y --> List) is export(:psi)

These routines compute the real part of the Digamma function on the line 1 + iy.

=head3 sub psi1-int(UInt $n where * > 0 --> Num) is export(:psi)
=head3 sub psi1-int-e(UInt $n where * > 0 --> List) is export(:psi)

These routines compute the Trigamma function ψ’(n) for positive integer n.

=head3 sub psi1(Num(Cool) $x --> Num) is export(:psi)
=head3 sub psi1-e(Num(Cool) $x --> List) is export(:psi)

These routines compute the Trigamma function ψ’(x) for general x.

=head3 sub psin(UInt $n, Num(Cool) $x where * > 0 --> Num) is export(:psi)
=head3 sub psin-e(UInt $n, Num(Cool) $x where * > 0 --> List) is export(:psi)

These routines compute the polygamma function ψ⁽ⁿ⁾(x).

=head3 sub synchrotron1(Num(Cool) $x where * ≥ 0 --> Num) is export(:sync)
=head3 sub synchrotron1-e(Num(Cool) $x where * ≥ 0 --> List) is export(:sync)

These routines compute the first synchrotron function.

=head3 sub synchrotron2(Num(Cool) $x where * ≥ 0 --> Num) is export(:sync)
=head3 sub synchrotron2-e(Num(Cool) $x where * ≥ 0 --> List) is export(:sync)

These routines compute the second synchrotron function.

=head3 sub transport2(Num(Cool) $x where * ≥ 0 --> Num) is export(:transport)
=head3 sub transport2-e(Num(Cool) $x where * ≥ 0 --> List) is export(:transport)

These routines compute the transport function J(2, x).

=head3 sub transport3(Num(Cool) $x where * ≥ 0 --> Num) is export(:transport)
=head3 sub transport3-e(Num(Cool) $x where * ≥ 0 --> List) is export(:transport)

These routines compute the transport function J(3, x).

=head3 sub transport4(Num(Cool) $x where * ≥ 0 --> Num) is export(:transport)
=head3 sub transport4-e(Num(Cool) $x where * ≥ 0 --> List) is export(:transport)

These routines compute the transport function J(4, x).

=head3 sub transport5(Num(Cool) $x where * ≥ 0 --> Num) is export(:transport)
=head3 sub transport5-e(Num(Cool) $x where * ≥ 0 --> List) is export(:transport)

These routines compute the transport function J(5, x).

=head3 sub gsl-sin(Num(Cool) $x --> Num) is export(:trig)
=head3 sub gsl-sin-e(Num(Cool) $x --> List) is export(:trig)

These routines compute the sine function sin(x).

=head3 sub gsl-cos(Num(Cool) $x --> Num) is export(:trig)
=head3 sub gsl-cos-e(Num(Cool) $x --> List) is export(:trig)

These routines compute the cosine function cos(x).

=head3 sub gsl-hypot(Num(Cool) $x, Num(Cool) $y --> Num) is export(:trig)
=head3 sub gsl-hypot-e(Num(Cool) $x, Num(Cool) $y --> List) is export(:trig)

These routines compute the hypotenuse function.

=head3 sub gsl-sinc(Num(Cool) $x --> Num) is export(:trig)
=head3 sub gsl-sinc-e(Num(Cool) $x --> List) is export(:trig)

These routines compute sinc(x) = sin(πx)/(πx).

=head3 sub gsl-complex-sin-e(Num(Cool) $zr, Num(Cool) $zi --> List) is export(:trig)

This function computes the complex sine.

=head3 sub gsl-complex-cos-e(Num(Cool) $zr, Num(Cool) $zi --> List) is export(:trig)

This function computes the complex cosine.

=head3 sub gsl-complex-logsin-e(Num(Cool) $zr, Num(Cool) $zi --> List) is export(:trig)

This function computes the logarithm of the complex sine.

=head3 sub gsl-lnsinh(Num(Cool) $x where * > 0 --> Num) is export(:trig)
=head3 sub gsl-lnsinh-e(Num(Cool) $x where * > 0 --> List) is export(:trig)

These routines compute log(sinh(x)).

=head3 sub gsl-lncosh(Num(Cool) $x --> Num) is export(:trig)
=head3 sub gsl-lncosh-e(Num(Cool) $x --> List) is export(:trig)

These routines compute log(cosinh(x)).

=head3 sub polar-to-rect(Num(Cool) $r, Num(Cool) $θ where -π ≤ * ≤ π --> List) is export(:trig)

This function converts the polar coordinates (r, θ) to rectilinear coordinates (x, y).

=head3 sub rect-to-polar(Num(Cool) $x, Num(Cool) $y --> List) is export(:trig)

This function converts the rectilinear coordinates (x, y) to polar coordinates (r, θ).

=head3 sub angle-restrict-symm(Num(Cool) $θ --> Num) is export(:trig)
=head3 sub angle-restrict-symm-e(Num(Cool) $θ --> Num) is export(:trig)

These routines force the angle θ to lie in the range (−π, π].

=head3 sub angle-restrict-pos(Num(Cool) $θ --> Num) is export(:trig)
=head3 sub angle-restrict-pos-e(Num(Cool) $θ --> Num) is export(:trig)

These routines force the angle θ to lie in the range [0, 2π).

=head3 sub gsl-sin-err-e(Num(Cool) $x, Num(Cool) $dx --> List) is export(:trig)

This routine computes the sine of an angle x with an associated absolute error dx, sin(x ± dx).

=head3 sub gsl-cos-err-e(Num(Cool) $x, Num(Cool) $dx --> List) is export(:trig)

This routine computes the cosine of an angle x with an associated absolute error dx, cosin(x ± dx).

=head3 sub zeta-int(Int $n where * ≠ 1 --> Num) is export(:zeta)
=head3 sub zeta-int-e(Int $n where * ≠ 1 --> List) is export(:zeta)

These routines compute the Riemann zeta function ζ(n).

=head3 sub zeta(Num(Cool) $s where * ≠ 1 --> Num) is export(:zeta)
=head3 sub zeta-e(Num(Cool) $s where * ≠ 1 --> List) is export(:zeta)

These routines compute the Riemann zeta function ζ(s) for arbitrary s.

=head3 sub zetam1-int(Int $n where * ≠ 1 --> Num) is export(:zeta)
=head3 sub zetam1-int-e(Int $n where * ≠ 1 --> List) is export(:zeta)

These routines compute ζ(n) − 1 for integer n.

=head3 sub zetam1(Num(Cool) $s where * ≠ 1 --> Num) is export(:zeta)
=head3 sub zetam1-e(Num(Cool) $s where * ≠ 1 --> List) is export(:zeta)

These routines compute ζ(s) − 1 for arbitrary s.

=head3 sub hzeta(Num(Cool) $t where * > 1, Num(Cool) $q where * > 0 --> Num) is export(:zeta)
=head3 sub hzeta-e(Num(Cool) $t where * > 1, Num(Cool) $q where * > 0 --> List) is export(:zeta)

These routines compute the Hurwitz zeta function ζ(t, q).

=head3 sub eta-int(Int $n --> Num) is export(:zeta)
=head3 sub eta-int-e(Int $n --> List) is export(:zeta)

These routines compute the eta function η(n) for integer n.

=head3 sub eta(Num(Cool) $s --> Num) is export(:zeta)
=head3 sub eta-e(Num(Cool) $s --> List) is export(:zeta)

These routines compute the eta function η(s) for arbitrary s.

=head1 C Library Documentation

For more details on libgsl see L<https://www.gnu.org/software/gsl/>.
The excellent C Library manual is available here L<https://www.gnu.org/software/gsl/doc/html/index.html>, or here L<https://www.gnu.org/software/gsl/doc/latex/gsl-ref.pdf> in PDF format.

=head1 Prerequisites

This module requires the libgsl library to be installed. Please follow the instructions below based on your platform:

=head2 Debian Linux and Ubuntu 20.04

=begin code
sudo apt install libgsl23 libgsl-dev libgslcblas0
=end code

That command will install libgslcblas0 as well, since it's used by the GSL.

=head2 Ubuntu 18.04

libgsl23 and libgslcblas0 have a missing symbol on Ubuntu 18.04.
I solved the issue installing the Debian Buster version of those three libraries:

=item L<http://http.us.debian.org/debian/pool/main/g/gsl/libgslcblas0_2.5+dfsg-6_amd64.deb>
=item L<http://http.us.debian.org/debian/pool/main/g/gsl/libgsl23_2.5+dfsg-6_amd64.deb>
=item L<http://http.us.debian.org/debian/pool/main/g/gsl/libgsl-dev_2.5+dfsg-6_amd64.deb>

=head1 Installation

To install it using zef (a module management tool):

=begin code
$ zef install Math::Libgsl::Function
=end code

=head1 AUTHOR

Fernando Santagata <nando.santagata@gmail.com>

=head1 COPYRIGHT AND LICENSE

Copyright 2020 Fernando Santagata

This library is free software; you can redistribute it and/or modify it under the Artistic License 2.0.

=end pod


