# GSL.jl

Julia wrapper for the GNU Scientific Library (GSL), for Julia v1.0+. Currently uses GSL v2.6.

## Structure

The library tries to provide Julia interfaces to all the functions, types and symbols defined in the GSL documentation.

- Functions are interfaced without the
`gsl_`

prefix, e.g.`sf_legendre_Pl`

and`vector_alloc`

. - Types, global variables and most constants are interfaced using their original GSL name, e.g.
`gsl_vector`

,`gsl_root_fdfsolver_newton`

and`GSL_SUCCESS`

. - The physical constants
`GSL_CONST_*`

can be found under the namespace`GSL.Const`

, e.g.`GSL.Const.MKSA_ANGSTROM`

.

Some functions have a secondary wrapper on top of the GSL interface, to make Julia usage more convenient, for example by allocating the output array. The low-level C interface to GSL can still be accessed under the namespace `GSL.C`

. Some examples of functions that are different in the low-level interface:

```
GSL.strerror(gsl_errno) -> String
GSL.C.strerror(gsl_errno) -> Ptr{Cchar}
and
GSL.sf_legendre_array(norm, lmax, x) -> Array{Float64}
GSL.C.sf_legendre_array(norm, lmax, x, result_array) -> Cint
```

Parts of GSL are not interfaced to, since they provide functionality already existing in
Julia. These are functions with prefixes `gsl_spmatrix_`

, `gsl_splinalg_`

, `gsl_spblas_`

,
`gsl_eigen_`

, `gsl_sort`

, `gsl_blas_`

,
`cblas_`

, `gsl_fft_`

, and `gsl_linalg_`

.
In addition, interfaces to `gsl_bst_`

functions are currently missing.

## Examples

See examples in examples/ and tests test/ for more examples.

### Special function with result struct

```
# Direct call
sf_legendre_P3(0.5)
# Output: -0.4375
# With result struct that stores value and error:
sf_legendre_P3_e(0.5)
# Output: gsl_sf_result_struct(-0.4375, 3.3306690738754696e-16)
# Low-level call with result struct as argument:
result = gsl_sf_result(0,0)
GSL.C.sf_legendre_P3_e(0.5, result)
# Output: GSL_SUCCESS
# result = gsl_sf_result_struct(-0.4375, 3.3306690738754696e-16)
```

### Special function with array output

```
x = 0.5
lmax = 4
result = sf_legendre_array(GSL_SF_LEGENDRE_SPHARM, lmax, x)
# Equivalent using low-level interface:
n = sf_legendre_array_n(lmax)
result = Array{Float64}(undef, n)
GSL.C.sf_legendre_array(GSL_SF_LEGENDRE_SPHARM, lmax, x, result)
```

### Root finding

```
f = x -> x^5+1
df = x -> 5*x^4
fdf = @gsl_function_fdf(f, df)
solver = root_fdfsolver_alloc(gsl_root_fdfsolver_newton)
root_fdfsolver_set(solver, fdf, -2)
while abs(f(root_fdfsolver_root(solver))) > 1e-10
root_fdfsolver_iterate(solver)
end
println("x = ", root_fdfsolver_root(solver))
# Output: x = -1.0000000000104232
```

## Documentation

Extra functionality defined in this package:

- Convenice functions
`hypergeom`

and`hypergeom_e`

for the hypergeometric functions. - Function wrapping macros
`@gsl_function`

,`@gsl_function_fdf`

,`@gsl_multiroot_function`

and`@gsl_multiroot_function_fdf`

that are used for packaging Julia functions so that they can be passed to GSL. - Functions
`wrap_gsl_vector`

and`wrap_gsl_matrix`

that return a Julia array or matrix pointing to the data in a`gsl_vector`

or`gsl_matrix`

.

In addition, some effort has been put into giving most types and functions proper docstrings, e.g.

```
help?> GSL.wavelet_free
wavelet_free(w) -> Cvoid
C signature: void gsl_wavelet_free (gsl_wavelet * w)
GSL documentation:
void gsl_wavelet_free (gsl_wavelet * w)
–––––––––––––––––––––––––––––––––––––––––
│ This function frees the wavelet object w.
```

```
help?> GSL.gsl_wavelet
mutable struct gsl_wavelet
type::Ptr{gsl_wavelet_type}
h1::Ptr{Cdouble}
g1::Ptr{Cdouble}
h2::Ptr{Cdouble}
g2::Ptr{Cdouble}
nc::Csize_t
offset::Csize_t
end
GSL documentation:
gsl_wavelet
–––––––––––––
│ This structure contains the filter coefficients defining the wavelet and any associated offset parameters.
```

## Behind the scenes

- All interface code in src/gen is created by running the script gen/makewrappers.jl, which attempts to parse the GSL headers using regular expressions.
- Heuristics for creating convenience functions are in gen/heuristic.jl.
- Docstrings are created from the GSL docs in gen/readdocs.jl.
- Hand-written convenience functions are in src/manual_wrappers.jl.