Skip to content
This repository was archived by the owner on May 24, 2020. It is now read-only.

Commit eb86fd9

Browse files
btraceybtracey
committed
Add intro to Gonum post
1 parent fae087f commit eb86fd9

File tree

1 file changed

+154
-0
lines changed

1 file changed

+154
-0
lines changed

Diff for: ‎blog/content/introtogonum.md

+154
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,154 @@
1+
# The Gonum Numeric Computing Packages
2+
3+
## Gonum -- The Basics
4+
5+
Gonum is a set of packages designed to make writing numeric and scientific
6+
algorithms productive, performant, and scalable.
7+
8+
Gonum is a set of packages written in the
9+
[Go programming language](https://www.golang.org) (more on Go later), and is
10+
not a language on its own.
11+
This makes Gonum similar to [numpy](https://www.numpy.org) and
12+
[scipy](https://www.scipy.org), libraries built on top of
13+
[python](https://www.python.org), and different from
14+
[Julia](https://julialang.org/) and [Matlab](https://www.mathworks.com/)
15+
which are full programming languages.
16+
17+
Gonum contains libraries for [matrices and linear algebra](https://godoc.org/gonum.org/v1/gonum/mat);
18+
[statistics](https://godoc.org/gonum.org/v1/gonum/stat),
19+
[probability](https://godoc.org/gonum.org/v1/gonum/stat/distuv)
20+
[distributions](https://godoc.org/gonum.org/v1/gonum/stat/distmv),
21+
and [sampling](https://godoc.org/gonum.org/v1/gonum/stat/sampleuv); tools for
22+
[function differentiation](https://godoc.org/gonum.org/v1/gonum/diff/fd),
23+
[integration](https://godoc.org/gonum.org/v1/gonum/integrate/quad),
24+
and [optimization](https://godoc.org/gonum.org/v1/gonum/optimize);
25+
[network](https://godoc.org/gonum.org/v1/gonum/graph) creation and analysis; and more.
26+
27+
## Gonum Philosophy
28+
The Gonum packages are designed to be simple, efficient and composable.
29+
There is a tension, especially in scientific computing, between ease and simplicity.
30+
Gonum, [like the Go language itself](https://commandcenter.blogspot.com/2012/06/less-is-exponentially-more.html),
31+
aims first to provide reliable and predictable code, while maintaining
32+
ease-of-use.
33+
Gonum is different from other popular scientific libraries, in that the Go language
34+
does not allow operator or method overloading.
35+
On the surface, this often means that the same algorithm requires a few more
36+
lines of code in Go.
37+
We fully recognize that sexy one-liners are rare with Gonum.
38+
39+
We accept this cost because we believe it comes with an enormous benefit.
40+
The Gonum function and method signatures make the algorithmic outputs clear,
41+
and it is easy to identify the code being executed and examine the implementation.
42+
Science is built on understanding how an experiment was performed and
43+
what the results are.
44+
We believe scientific code should be no different.
45+
In fact, Gonum is partly distinguished from other libraries in that you only need
46+
one programming language to read Gonum code (that said, it is also easy to call
47+
into existing C and Fortran libraries).
48+
This philosophy of simplicity has many follow-on benefits.
49+
For example, dense one-liners can be hard to understand, creating a barrier for
50+
others to confirm correctness, and making future modifications difficult.
51+
Additionally, one-liners often obscure the necessary operations to execute that
52+
line of code.
53+
This creates a tension between code that is terse, and a targeted implementation
54+
that is efficient.
55+
The construction of Gonum encourages users to implement algorithms in a uniform
56+
style, making the code easy to read and consistent between users.
57+
58+
The use of Go as a base language has many benefits beyond simplicity.
59+
Go is fast, approaching the speed of C.
60+
Go's language primitives are great for parallel computing, and in fact Gonum
61+
code can often be made to run in parallel by setting a flag.
62+
Go is designed for ["programming in the large"](https://talks.golang.org/2012/splash.article),
63+
a huge benefit for building an ecosystem of libraries that work with and build
64+
on top of one another.
65+
Go has extremely legible compile errors, full stack traces, trivial package downloading,
66+
automatic makefiles and import resolution, code formatting tools, easy code documentation,
67+
a race detector, and the list goes on.
68+
69+
We encourage you to try Go and Gonum if
70+
- You are tired of sluggish performance, and with fighting vectorization and C
71+
- You are struggling with managing programs as they grow larger and/or
72+
- You struggle to re-use even the code you tried to make reusable
73+
- You would like easy access to parallel computing
74+
- You want code to be fully transparent, and you want the ability to read the source code you use
75+
- You'd like a compiler to catch mistakes early, but hate fighting linker errors and unintelligible compile errors
76+
77+
We believe in a new foundation for scientific computing, and we hope you'll join us.
78+
Please check back for more discussion on the philosophy of Gonum and the design
79+
decisions for specific packages.
80+
81+
## Getting started with Gonum
82+
### Downloading the libraries
83+
First, you need to [install Go](https://golang.org/doc/install) if it is not
84+
already installed on your machine.
85+
It is recommended that you use the most recent version of Go.
86+
Run
87+
```
88+
go get -u -t gonum.org/v1/gonum/...
89+
```
90+
to download the main set of Gonum packages.
91+
That's it!
92+
93+
You can test that everything is working properly with
94+
```
95+
go test gonum.org/v1/...
96+
```
97+
This will take a few minutes.
98+
Packages should all have an "ok" or "?" next to them.
99+
While the tests are running, please feel free to browse the source code!
100+
101+
### Learning Go
102+
The [Go tour](https://tour.golang.org/) is an excellent introduction
103+
to the Go programming language.
104+
For quick experiments with the language, the [Go playground](https://play.golang.org/)
105+
is a very nice sandbox, though unfortunately you cannot import the Gonum librares.
106+
We also recommend reading the [Go FAQ](https://golang.org/doc/faq) and
107+
[effective Go](https://golang.org/doc/effective_go.html) pages.
108+
If you have specific questions, check out the Go language
109+
[specification](https://golang.org/ref/spec), which provides an official description
110+
of the behavior of the language.
111+
The Go specification is remarkably short and legible compared with other
112+
language specifications, and a better situation than for the many languages
113+
without an official specification.
114+
115+
### Learning Gonum
116+
The best way to learn about particular packages and functions is through
117+
the source code documentation.
118+
The godoc [website](https://godoc.org) automatically generates documentation
119+
pages from publically available source code.
120+
For most Go packages (not just Gonum), going to `https://godoc.org/<package-import-path>`
121+
will give you documentation about that particular package.
122+
For example, `https://godoc.org/gonum.org/v1/gonum/mat` will give documentation
123+
about Gonum's matrix package, as well as documentation for specific functions.
124+
Go to `https://godoc.org/gonum.org/v1/gonum/graph/topo` and you will see
125+
documentation about our graph topology routines, for example for finding the
126+
"strongly connected components" of a graph.
127+
Note that sometimes godoc lists functions below the relevant type, for example
128+
the function to create a new dense matrix `mat.NewDense`, is listed under the
129+
`Dense` type.
130+
At the bottom of the index you will see a list of specific code examples,
131+
and at the very bottom of the godoc page, you can see a list of subpackages,
132+
if any (for instance, scroll to the bottom of `https://godoc.org/gonum.org/v1/gonum/stat`).
133+
134+
Please also check future posts on this blog for extended commentary on Gonum
135+
packages and their effective use.
136+
137+
For questions on the Gonum libraries, please join us at the
138+
[Gonum-dev](https://groups.google.com/forum/#!forum/gonum-dev) mailing list.
139+
140+
## How can I help?
141+
The Gonum contributors are a self-assembled group of scientists, engineers and
142+
programmers from around the world.
143+
If you're worried that you don't know us, don't be!
144+
At the time of writing, none of the primary contributors have ever met in person,
145+
and until recently, we all lived in different time zones.
146+
Please file issues you find at our
147+
[github repository](https://github.com/gonum/gonum).
148+
Pull requests are encouraged, please see the [contributing guidelines](https://github.com/gonum/gonum/blob/master/CONTRIBUTING.md)
149+
for more details.
150+
Small changes can be proposed directly, larger changes should be discussed at the
151+
Gonum-dev mailing list (linked above).
152+
153+
154+
*By Brendan Tracey*

0 commit comments

Comments
 (0)