# Gosl – Go scientific library

Gosl is a library written in Go to develop high-performance scientific
computations. The library tries to be as general and *easy* as possible. Gosl considers the use of
both Go concurrency routines and parallel computing using the message passing interface. Gosl has
several modules (sub-packages) for a variety of tasks in scientific computing, image analysis, and
data post-processing. For example, it includes high-performant linear algebra functions (wrapping
MKL, OpenBLAS, LAPACK, SuiteSparse, UMFPACK...), fast Fourier transform algorithms (wrapping FFTW),
numerical integration (wrapping QUADPACK), functions and structures for geometry calculations (e.g.
3D transfinite interpolation, grid search, octree...), random numbers generation (SFMT and DSFMT)
and probability distributions, optimisation and graph algorithms, plotting and visualisation using
the VTK, and much more. Gosl has also solvers to (stiff or not) ordinary differential equations and
several tools for 2D/3D mesh generation to assist on the development of solvers for partial
differential equations.

See the documentation for more details (e.g. how to call functions and use structures).

Welcome to contributing + TODO list.

## Contents

Gosl includes the following *packages*:

- chk – Check code and unit test tools
- io – Input/output, read/write files, and print commands
- utl – Utilities. Lists. Dictionaries. Simple Numerics
- plt – Plotting and drawing (png and eps)
- mpi – Message Passing Interface for parallel computing
- la – Linear Algebra: vector, matrix, efficient sparse solvers, eigenvalues, decompositions, etc.
- la/mkl – Lower level linear algebra using Intel MKL
- la/oblas – Lower level linear algebra using OpenBLAS
- num/qpck – Go wrapper to QUADPACK for numerical integration
- num – Fundamental numerical methods such as root solvers, non-linear solvers, numerical derivatives and quadrature
- fun – Special functions, DFT, FFT, Bessel, elliptical integrals, orthogonal polynomials, interpolators
- fun/dbf – Database of functions of a scalar and a vector like f(t,{x}) (e.g. time-space)
- fun/fftw – Go wrapper to FFTW for fast Fourier Transforms
- gm – Geometry algorithms and structures
- gm/msh – Mesh structures and interpolation functions for FEA, including quadrature over polyhedra
- gm/tri – Mesh generation: triangles and Delaunay triangulation (wrapping Triangle)
- gm/rw – Mesh generation: read/write routines
- graph – Graph theory structures and algorithms
- opt – Solvers for optimisation problems (e.g. interior point method)
- rnd – Random numbers and probability distributions
- rnd/dsfmt – Go wrapper to dSIMD-oriented Fast Mersenne Twister
- rnd/sfmt – Go wrapper to SIMD-oriented Fast Mersenne Twister
- vtk – 3D Visualisation with the VTK tool kit
- ode – Solvers for ordinary differential equations

## Examples

Selected:

- Compute (fast) discrete Fourier transform
- Generate and draw a NURBS toroidal surface
- Generating normally distributed pseudo-random numbers
- Solution of sparse linear system
- Solution of sparse linear system with complex numbers
- Numerical differentiation
- Drawing iso-surfaces with VTK
- Plotting a contour
- Root finding problems
- B-splines: curve, control, and basis
- Orthogonal polynomials
- Chebyshev interpolation
- Fourier interpolation
- Solving ordinary differential equations

## Installation

Since Gosl needs some other C and Fortran codes, **not** all sub-packages can be directly installed
using `go get ...`

. Nonetheless, **Gosl is pretty easy to install!** See links below:

The following subpackages are available on Linux only at the moment: *mpi*, *la/mkl*, and *vtk*. The
following subpackages are not available for Windows at the moment: *gm/tri*, *rnd/sfmt*, and
*rnd/dsfmt*. Help to compile these packages in all platforms is much welcome and appreciated.

## About the filenames

`t_something_test.go`

is a**unit test**. We have several of them! Some usage information can be learned from these files.`t_something_main.go`

is a test with a main function to be run with`go run ...`

or`mpirun -np ? go run ...`

(replace ? with the number of cpus). There very few of these files.`t_b_something_test.go`

is a benchmark test. There a few of them. Run benchmarks with`go test -run=XXX -bench=.`

## Design strategies

Here, we call *structure* any *user-defined type*. These are simply Go `types`

defined as `struct`

.
One may think of these *structures* as *classes*. Gosl has several global functions as well and
tries to avoid complicated constructions.

An allocated structure (instance) is called an **object** and functions attached to this object are
called **methods**. In Gosl, the variable holding the pointer to an object is always named **o**
(lower case "o"). This variable is similar to the `self`

or `this`

keywords in other languages
(Python, C++, respectively).

Functions that allocate a pointer to a structure are prefixed with `New`

; for instance:
`NewIsoSurf`

. Some structures require an explicit call to another function to release allocated
memory. Be aware of this requirement! In this case, the function is named `Free`

and appears in a
few sub-packages that use CGO. Also, some objects may need to be initialised before use. In this
case, functions named `Init`

have to be called.

The directories corresponding to each package has a README.md file that should help with
understanding the library. Also, there are links to `godoc.org`

where all functions, structures, and
variables are well explained.

## Bibliography

The following works take advantage of Gosl:

- Pedroso DM, Bonyadi MR, Gallagher M (2017) Parallel evolutionary algorithm for single and multi-objective optimisation: differential evolution and constraints handling, Applied Soft Computing http://dx.doi.org/10.1016/j.asoc.2017.09.006
- Pedroso DM (2017) FORM reliability analysis using a parallel evolutionary algorithm, Structural Safety 65:84-99 http://dx.doi.org/10.1016/j.strusafe.2017.01.001
- Pedroso DM, Zhang YP, Ehlers W (2017) Solution of liquid-gas-solid coupled equations for porous media considering dynamics and hysteretic retention behaviour, Journal of Engineering Mechanics 04017021 http://dx.doi.org/10.1061/(ASCE)EM.1943-7889.0001208
- Pedroso DM (2015) A solution to transient seepage in unsaturated porous media. Computer Methods in Applied Mechanics and Engineering, 285:791-816 http://dx.doi.org/10.1016/j.cma.2014.12.009
- Pedroso DM (2015) A consistent u-p formulation for porous media with hysteresis. Int. Journal for Numerical Methods in Engineering, 101(8):606-634 http://dx.doi.org/10.1002/nme.4808

## Authors and license

See the AUTHORS file.

Unless otherwise noted, the Gosl source files are distributed under the BSD-style license found in the LICENSE file.