Julia wrapper for the GNU Scientific Library (GSL), for Julia v1.0+.
NOTE: There have been major changes to this package since v0.4, which are likely to have introduced compability breaks.
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
andvector_alloc
. - Types, global variables and most constants are interfaced using their original GSL name, e.g.
gsl_vector
,gsl_root_fdfsolver_newton
andGSL_SUCCESS
. - The physical constants
GSL_CONST_*
can be found under the namespaceGSL.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_
.
See examples in examples/ and tests test/ for more examples.
# 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)
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)
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
Extra functionality defined in this package:
- Convenice functions
hypergeom
andhypergeom_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
andwrap_gsl_matrix
that return a Julia array or matrix pointing to the data in agsl_vector
orgsl_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.
- 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.