gogsl

README

gogsl

A (nearly) complete binding of the GNU Scientific Library for Go

---

Using gogsl

To use the gogsl bindings in your program, you'll need to do the following:

• Install libgsl:

  You will need the development headers in place at /usr/include/gsl. (This location can be changed in generator.go.) Your Linux distribution probably makes this step easy for you - for example, for a typical Fedora system:

            yum install gsl-devel
  

  will suffice.

• Get the distribution:

            go get github.com/dtromb/gogsl
  

• Generate the bindings:

            cd dtromb/gogsl; go generate
  

  This step is necessary because the datatype sizes on various machines will differ, and the bindings need to be generated based on these. This necessarily means code will not be portable across architectures (the alternative would have been to use per-binding size-matched types, however Go would then require explicit casts when these were used!)

  If you are on an x86-64 platform, you can skip this step as the generated code that ships with the project is for this architecture.

• Import and use the bindings:

          import "github.com/dtromb/gogsl/<package>"
  

  The bindings very closely follow the API, you should be able to use them in your code simply using the GSL Manual as a reference.

---

Memory management, other "gotchas"

Not-insignificant dissonances occur between the call patterns and data use cases in the C library and the Go bindings. Resolving these was the primary difficulty that need to be overcome, to create the proper "smoothness". In some cases end users need to be aware of these issues. They will be summarized here:

• No need to clean up...

Go is a garbage-collected language, and we attempt to take full advantage of this facility. GSL kindly uses the *_[c]alloc(), *_free() pattern to lifecycle most of its managed-memory objects, and that allocation pattern is mapped to the bindings - there are respectively *(A|Ca)lloc() and automated object cleanup available. Any functions created with an alloc call do not need the corresponding free in Go - simply let these fall unreachable and the corresponding GSL-managed memory will be freed.

• ...but careful to not make a mess.

Now the bad: these objects sometimes reference each other in non-obvious ways, and callers must in some cases stop referencing "live" objects if others are no longer reachable. This isn't as horrible as it sounds - to be safe there are just a couple of rules to follow. First, for vector and matrix view types, make sure that the underlying object (Go slice/array, gogsl object, etc) is not collected when the view is still active. Secondly, do not in any case store references to the special objects returned by functions with a trailing underscore, such as GslVector's Slice_() operation - use these only as function call arguments to "cast" values (for example, maybe you have a vector, but the function you want to pass its data to requires a Go slice - use Slice_(), but do not keep the slice around for later).

These limitations exist because of the reasonable (in C, anyway) assumption on the part of GSL that you will be casting pointers between types and passing them around, as well as using other C-like "memory block" features. Right now breaking these "rules" will get you a segfault, or worse. It's a TODO to make this a bit nicer - holding Go-side references to objects "in use" by the C side memory, and using the GslErrorHandler mechanism to recoverably fail instead of signaling. See the /<package>/test directories for proper use patterns.

---

License

The code is made available under the version 2 GNU Public License (Copyleft). If you use it, you must release your source with your product and follow certain other restrictions. See the LICENSE file in the distribution for details.

To say hello, or for a non-copyleft license, please contact me at dave.trombley@gmail.com. I'd love to know who you are and what you're using gogsl for!

Documentation

Overview

//////// AUTOMATICALLY GENERATED CODE - DO NOT EDIT //////////

Index

• Variables
• func Error(reason string, gslErrno GslError)
• func GetCIntSize() int
• func GetCLongLongSize() int
• func GetCLongSize() int
• func GetCShortSize() int
• func GetCSizeTSize() int
• func GetIntSize() int
• func GetNumberType(signed bool, n int) (reflect.Type, error)
• func GetUintptrSize() int
• func GslAcosh(x float64) float64
• func GslAsinh(x float64) float64
• func GslAtanh(x float64) float64
• func GslExpm1(x float64) float64
• func GslFcmp(x float64, y float64, epsilon float64) int32
• func GslFinite(x float64) int32
• func GslFrexp(x float64) (float64, int32)
• func GslHypot(x float64, y float64) float64
• func GslHypot3(x float64, y float64, z float64) float64
• func GslIsinf(x float64) int32
• func GslIsnan(x float64) int32
• func GslLdexp(x float64, e int32) float64
• func GslLog1p(x float64) float64
• func GslPow2(x float64) float64
• func GslPow3(x float64) float64
• func GslPow4(x float64) float64
• func GslPow5(x float64) float64
• func GslPow6(x float64) float64
• func GslPow7(x float64) float64
• func GslPow8(x float64) float64
• func GslPow9(x float64) float64
• func GslPowInt(x float64, n int32) float64
• func GslPowUint(x float64, n uint32) float64
• func GslReferenceFinalizer(ref CReference)
• func InitializeGslFunction(ptr *GslFunction)
• func InitializeGslFunctionFdf(ptr *GslFunctionFdf)
• func InitializeGslMonteFunction(ptr *GslMonteFunction)
• func InitializeGslReference(ref CReference, ptr uintptr) error
• func InitializeGslStatic(ref CStaticReference, ptr uintptr) error
• func InitializeGslStruct(ref CReference, ptr uintptr) error
• type CReference
• type CStaticReference
• type FileMode
  • func (fm *FileMode) Ptr() uintptr
• type GslCFunction
• type GslCFunctionFdf
• type GslCMonteFunction
• type GslError
  • func (ge GslError) String() string
• type GslErrorHandler
  • func SetErrorHandler(handler *GslErrorHandler) *GslErrorHandler
  • func SetErrorHandlerOff() *GslErrorHandler
• type GslErrorHandlerType
• type GslFunction
  • func (gf GslFunction) CPtr() uintptr
• type GslFunctionFdf
  • func (gf GslFunctionFdf) CPtr() uintptr
• type GslFunctionFdfType
• type GslFunctionType
• type GslMonteFunction
  • func (gf GslMonteFunction) CPtr() uintptr
• type GslMonteFunctionType
• type GslReference
  • func (ref *GslReference) AliasGroup() *ReferenceList
  • func (ref *GslReference) Ptr() uintptr
• type ReferenceList

Variables

var GOGSL_C16_TYPE reflect.Type

var GOGSL_C32_TYPE reflect.Type

var GOGSL_C64_TYPE reflect.Type

var GOGSL_INT_TYPE reflect.Type

var GOGSL_LONG_LONG_TYPE reflect.Type

var GOGSL_LONG_TYPE reflect.Type

var GOGSL_SHORT_TYPE reflect.Type

var GOGSL_SIZE_T_TYPE reflect.Type

var GOGSL_UINT_TYPE reflect.Type

var GOGSL_ULONG_LONG_TYPE reflect.Type

var GOGSL_ULONG_TYPE reflect.Type

var GOGSL_USHORT_TYPE reflect.Type

Functions

func Error

func Error(reason string, gslErrno GslError)

func GetCIntSize

func GetCIntSize() int

func GetCLongLongSize

func GetCLongLongSize() int

func GetCLongSize

func GetCLongSize() int

func GetCShortSize

func GetCShortSize() int

func GetCSizeTSize

func GetCSizeTSize() int

func GetIntSize

func GetIntSize() int

func GetNumberType

func GetNumberType(signed bool, n int) (reflect.Type, error)

func GetUintptrSize

func GetUintptrSize() int

func GslAcosh

func GslAcosh(x float64) float64

func GslAsinh

func GslAsinh(x float64) float64

func GslAtanh

func GslAtanh(x float64) float64

func GslExpm1

func GslExpm1(x float64) float64

func GslFcmp

func GslFcmp(x float64, y float64, epsilon float64) int32

func GslFinite

func GslFinite(x float64) int32

func GslFrexp

func GslFrexp(x float64) (float64, int32)

func GslHypot

func GslHypot(x float64, y float64) float64

func GslHypot3

func GslHypot3(x float64, y float64, z float64) float64

func GslIsinf

func GslIsinf(x float64) int32

func GslIsnan

func GslIsnan(x float64) int32

func GslLdexp

func GslLdexp(x float64, e int32) float64

func GslLog1p

func GslLog1p(x float64) float64

func GslPow2

func GslPow2(x float64) float64

func GslPow3

func GslPow3(x float64) float64

func GslPow4

func GslPow4(x float64) float64

func GslPow5

func GslPow5(x float64) float64

func GslPow6

func GslPow6(x float64) float64

func GslPow7

func GslPow7(x float64) float64

func GslPow8

func GslPow8(x float64) float64

func GslPow9

func GslPow9(x float64) float64

func GslPowInt

func GslPowInt(x float64, n int32) float64

func GslPowUint

func GslPowUint(x float64, n uint32) float64

func GslReferenceFinalizer

func GslReferenceFinalizer(ref CReference)

func InitializeGslFunction

func InitializeGslFunction(ptr *GslFunction)

These structures are allocated in the usual fashion and initialized from desired call parameters.

func InitializeGslFunctionFdf

func InitializeGslFunctionFdf(ptr *GslFunctionFdf)

func InitializeGslMonteFunction

func InitializeGslMonteFunction(ptr *GslMonteFunction)

func InitializeGslReference

func InitializeGslReference(ref CReference, ptr uintptr) error

func InitializeGslStatic

func InitializeGslStatic(ref CStaticReference, ptr uintptr) error

func InitializeGslStruct

func InitializeGslStruct(ref CReference, ptr uintptr) error

Types

type CReference

type CReference interface {
	Ptr() uintptr
	AliasGroup() *ReferenceList
	Dispose()
}

type CStaticReference

type CStaticReference interface {
	CReference
	Data() []byte
}

type FileMode

type FileMode string

var APPEND_ONLY FileMode = "a"

var READ_APPEND FileMode = "a+"

var READ_ONLY FileMode = "r"

var READ_WRITE FileMode = "r+"

var TRUNC_READ_WRITE FileMode = "w+"

var TRUNC_WRITE_ONLY FileMode = "w"

func (*FileMode) Ptr

func (fm *FileMode) Ptr() uintptr

type GslCFunction

type GslCFunction uintptr

type GslCFunctionFdf

type GslCFunctionFdf uintptr

type GslCMonteFunction

type GslCMonteFunction uintptr

type GslError

type GslError int

const (
	GSL_SUCCESS  GslError = 0
	GSL_FAILURE  GslError = -1
	GSL_CONTINUE GslError = -2 /* iteration has not converged */
	GSL_EDOM     GslError = 1  /* input domain error, e.g sqrt(-1) */
	GSL_ERANGE   GslError = 2  /* output range error, e.g. exp(1e100) */
	GSL_EFAULT   GslError = 3  /* invalid poGslErrorer */
	GSL_EINVAL   GslError = 4  /* invalid argument supplied by user */
	GSL_EFAILED  GslError = 5  /* generic failure */
	GSL_EFACTOR  GslError = 6  /* factorization failed */
	GSL_ESANITY  GslError = 7  /* sanity check failed - shouldn't happen */
	GSL_ENOMEM   GslError = 8  /* malloc failed */
	GSL_EBADFUNC GslError = 9  /* problem with user-supplied function */
	GSL_ERUNAWAY GslError = 10 /* iterative process is out of control */
	GSL_EMAXITER GslError = 11 /* exceeded max number of iterations */
	GSL_EZERODIV GslError = 12 /* tried to divide by zero */
	GSL_EBADTOL  GslError = 13 /* user specified an invalid tolerance */
	GSL_ETOL     GslError = 14 /* failed to reach the specified tolerance */
	GSL_EUNDRFLW GslError = 15 /* underflow */
	GSL_EOVRFLW  GslError = 16 /* overflow  */
	GSL_ELOSS    GslError = 17 /* loss of accuracy */
	GSL_EROUND   GslError = 18 /* failed because of roundoff error */
	GSL_EBADLEN  GslError = 19 /* matrix, vector lengths are not conformant */
	GSL_ENOTSQR  GslError = 20 /* matrix not square */
	GSL_ESING    GslError = 21 /* apparent singularity detected */
	GSL_EDIVERGE GslError = 22 /* GslErroregral or series is divergent */
	GSL_EUNSUP   GslError = 23 /* requested feature is not supported by the hardware */
	GSL_EUNIMPL  GslError = 24 /* requested feature not (yet) implemented */
	GSL_ECACHE   GslError = 25 /* cache limit exceeded */
	GSL_ETABLE   GslError = 26 /* table limit exceeded */
	GSL_ENOPROG  GslError = 27 /* iteration is not making progress towards solution */
	GSL_ENOPROGJ GslError = 28 /* jacobian evaluations are not improving the solution */
	GSL_ETOLF    GslError = 29 /* cannot reach the specified tolerance in F */
	GSL_ETOLX    GslError = 30 /* cannot reach the specified tolerance in X */
	GSL_ETOLG    GslError = 31 /* cannot reach the specified tolerance in gradient */
	GSL_EOF      GslError = 32 /* end of file */
)

func (GslError) String

func (ge GslError) String() string

const char * gsl_strerror (const GslError gsl_errno)

type GslErrorHandler

type GslErrorHandler struct {
	Handler GslErrorHandlerType
	// contains filtered or unexported fields
}

func SetErrorHandler

func SetErrorHandler(handler *GslErrorHandler) *GslErrorHandler

gsl_error_handler_t * gsl_set_error_handler (gsl_error_handler_t * new_handler)

func SetErrorHandlerOff

func SetErrorHandlerOff() *GslErrorHandler

gsl_error_handler_t * gsl_set_error_handler_off ()

type GslErrorHandlerType

type GslErrorHandlerType func(reason string, file string, line int, gslError GslError)

type GslFunction

type GslFunction struct {
	Function GslFunctionType
	Params   interface{}
	// contains filtered or unexported fields
}

func (GslFunction) CPtr

func (gf GslFunction) CPtr() uintptr

These pointers can be cast to the package-local types (eg. *C.gsl_function) to perform the call.

type GslFunctionFdf

type GslFunctionFdf struct {
	Function   GslFunctionType
	Derivative GslFunctionType
	Fdf        GslFunctionFdfType
	Params     interface{}
	// contains filtered or unexported fields
}

func (GslFunctionFdf) CPtr

func (gf GslFunctionFdf) CPtr() uintptr

type GslFunctionFdfType

type GslFunctionFdfType func(x float64, params interface{}) (float64, float64)

type GslFunctionType

type GslFunctionType func(x float64, params interface{}) float64

type GslMonteFunction

type GslMonteFunction struct {
	Function GslMonteFunctionType
	Params   interface{}
	Dim      int
	// contains filtered or unexported fields
}

func (GslMonteFunction) CPtr

func (gf GslMonteFunction) CPtr() uintptr

type GslMonteFunctionType

type GslMonteFunctionType func(x []float64, params interface{}) float64

type GslReference

type GslReference struct {
	// contains filtered or unexported fields
}

func (*GslReference) AliasGroup

func (ref *GslReference) AliasGroup() *ReferenceList

func (*GslReference) Ptr

func (ref *GslReference) Ptr() uintptr

type ReferenceList

type ReferenceList struct {
	// contains filtered or unexported fields
}