wasora

wasora's an advanced suite for optimization & reactor analysis

wasora

logo wasora is a free computational tool designed to aid a cognizant expert—i.e. you, whether an engineer, scientist, technician, geek, etc—to analyze complex systems by solving mathematical problems by means of a high-level plain-text input file containing algebraic expressions, data for function interpolation, differential equations and output instructions amongst other facilities.

At a first glance, it may look as another high-level interpreted programming language, but—hopefully—it is not: wasora should be seen as a syntactically-sweetened way to ask a computer to perform a certain mathematical calculation. For example, see below to see how the famous Lorenz system may be solved by writing the three differential equations into a plain-text input file as humanly-friendly as possible. Although its ultimate subject is optimization of nuclear reactors, it may hopefully help you with the tough calculations that usually appear when working with problems that have some kind of complexity, allowing the user to focus on what humans perform best—expert judgment and reaching conclusions.

Explaining what a certain piece of software does—especially if it is a technical one—is very hard, as shown by the cryptic description most scientific software package present at their web pages, version control system logs, README files and repository sources. This is by no means an exception, so please before flying away take the time to look at the quick start and examples to see. Maybe after all wasora can help you.

Last modification: Wed, 18 Jun 2014 19:25:50 -0400.

download

The recommended way to get wasora is to download the latest (0.2.141) source tarball and compile wasora from scratch. However, libraries may be tricky to get running so binary versions are also provided:

Please note that the GNU Scientific Library (both the library and the headers) is mandatory to compile the source code. It may be installed with
$ apt-get install libgsl0-dev
Other non-standard libraries such as SUNDIALS or Readline are optional. See the projects wasora relies on.

bazaar repository

bazaar If you plan to contribute to wasora, modify its sources or just want to get updated versions easily, you will need to branch the development tree of wasora, which is hosted at Launchpad using bazaar as a control revision tool. The wasora tree can be browsed online or branched into a local copy with
$ bzr branch lp:wasora
If you use bzr to get the development version, you will need automake, autoconf, libtool and GNU m4. See details in the README file. Regular users just downloading the tarballs listed above will not need such advanced tools.

quickstart

First, download the source code, uncompress, configure, make, check, install and go to examples directory:

$ wget http://www.talador.com.ar/jeremy/wasora/downloads/wasora-0.2.141.tar.gz $ tar xvzf wasora-0.2.141.tar.gz $ cd wasora-0.2.141 $ ./configure $ make $ make check $ sudo make install $
See the documentation for detailed installation instructions and configuration options. If you do not like compiling source code, try downloading one of the binary versions of wasora.

the fibonacci sequence

Compute the first 15 elements of the Fibonacci sequence:
VECTOR f SIZE 15

f(i)<1:2> = 1
f(i)<3:vecsize(f)> = f(i-2) + f(i-1)

PRINT_VECTOR f FORMAT %g
$ wasora fibonacci.was 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 $
See The Fibonacci sequence at the wasora Real Book for two other ways of computing the same sequence.

the logistic map

Solve the logistic map for 1000 values of the parameter r in the range [2.6:4] (chosen from the commandline) using a reverse Halton quasi-random sequence of numbers:
# the logistic map
PARAMETRIC r $1 $2 1000 TYPE REVERSEHALTON
static_steps = 800

x_init = 0.5
x = r*x*(1-x)

IF step_static>static_steps-50
 PRINT %g r x 
ENDIF
$ wasora logistic.was 2.6 4 | gnuplot -p -e "plot '<cat' pt 0" $

logistic

Click on the bitmap to access a mouseable vector figure generated with gnuplot's html5 canvas terminal out of wasora's output.

the lorenz system

Build your own version of the Lorenz attractor by first stating which variables belong to the phase space, setting the integration time, defining the constant parameters and the initial conditions. Finally write down the differential equations as naturally as it is possible to do so in a plain-text computer file:
# lorenz' seminal dynamical system
PHASE_SPACE x y z
end_time = 40

CONST sigma r b  
sigma = 10            # parameters
r = 28
b = 8/3

x_0 = -11             # initial conditions
y_0 = -16
z_0 = 22.5

# the dynamical system
x_dot .= sigma*(y - x)
y_dot .= x*(r - z) - y
z_dot .= x*y - b*z

PRINT t x y z

# exercise: play with the system! change
# the parameters and plot, plot plot!
$ wasora lorenz.was | gnuplot -p -e "splot '<cat' u 2:3:4 w l" $

lorenz

This example illustrates the kind of syntactic sugar wasora tries to provide. See also the section about The Lorenz chaotic system and The chaotic Lorenzian waterwheel amongst other further examples in The wasora Real Book.

documentation

Currently wasora has a serious lack of complete and up-to-date documentation. There exist a kind of manual which is half-written and refers mainly to version 0.1, although the functions and functionals reference are correct. In principle, the documentation about syntax of the keywords should be updated by the wasora developer at the same time a modification in the code is done, but time is something he is really missing these days. Indeed, the manual section that describes the syntax is generated with scripts that parse the source code. Sadly, this task is not complete.

the wasora manual

As incomplete as it is, at least the wasora manual includes a list of keywords, functions and functionals as a reference section. It is converted from a set of source files and a set of scripts that parse the actual wasora source code to different formats using DocOnce:
  • HTML - included in the wasora tarball and installed in /usr/local/doc/wasora after performing the make install step.
  • Sphinx
  • PDF
The source files and the scripts that generate the manual can be accessed at the bazaar repository.

the wasora real book

As with jazz, wasora is best mastered when played. Visit The wasora Real Book which, as the original, will guide you through wasora with fully-usable examples of increasing complexity and difficulty. The examples come with introductions, wasora inputs, terminal mimics, figures, videos and discussions. realbook This book—that is not a book—is a living document that is eager to be fed by users willing to share experiences.

Noteworthy sections include:

The sources and scripts that generate the real book examples can be accessed at the bazaar repository.

the examples subdirectory

Following the idea of the wasora Real Book which consists of examples of application, the wasora source tarball includes a subdirectory called examples which contain some ready-to-use examples. They can be browsed online at the bazaar repository.

plugins

As illustrated in the Finding prime numbers section of the wasora real book, wasora's capabilities can be extended by loading user-provided routines in the form of shared-object files. However, if the desired extension is fairly complex, the best choice is to use the plugins mechanism, which consist of ad-hoc libraries that interact with some sort of API wasora provides (and of course is not yet documented). The two most useful plugins are besssugo and milonga, although more are being written:

  • besssugo plugin to generate scientific videos
  • milonga free nuclear reactor core analysis code
  • fino: simple finite-element-based PDE solver
  • waspy: interface to execute Python code within wasora

mailing list

There exist a mailing list < wasora @ talador.com.ar > where questions can be posted about any aspect of the code, including intallation, usage and development. Besides suscribing and directly asking a question, you can also browse the archives. Bugs reports are also welcome.

plaforms

wasora is free software, and as such it is developed under a free operating system, namely Debian GNU/Linux. The distribution tarball is based on GNU Autoconf & friends, so wasora should build in any POSIX-compliant environment. However, wasora is a fairly complex piece of software, so portability is not guaranteed (but improvements are welcome). Running wasora in non-free operating systems is discouraged, and such topic is not of the interest of the author of wasora. However, contributions and experiences may be well received if discussed in the mailing list.

license

wasora is released under the terms of the GNU General Public License version 3, or at your option, any later version. Bottomline is, you get the four software freedoms

  • The freedom to run the program, for any purpose (freedom 0).
  • The freedom to study how the program works, and change it so it does your computing as you wish (freedom 1). Access to the source code is a precondition for this.
  • The freedom to redistribute copies so you can help your neighbor (freedom 2).
  • The freedom to distribute copies of your modified versions to others (freedom 3). By doing this you can give the whole community a chance to benefit from your changes. Access to the source code is a precondition for this.
The condition is that if you modify the code and/or include it in a larger package and you want to distribute it, you have to release it under the same terms of the GPLv3+. That is to say, you cannot turn any derivative work based on wasora into a privative software. However, private modifications not intended for distribution may be produced and, if desired, never undisclosed at all. See the GPL FAQs or contact the mailing list for further details.

projects wasora relies on

Following good practices in UNIX programming, by design wasora tries to reuse as much as possible already-available high-quality free software (especially regarding numerical methods, which are better analyzed by mathematicians and better coded by professional programmers than by myself).

required libraries

GNU Scientific Library
wasora extensively relies on the GSL to provide numerical integration, differentiation, vectors & matrices, interpolation, root-finding, random number generation, multidimensional optimization, etc. See the GNU Scientific Library examples rewritten section of The wasora Real Book for some particular examples.

Therefore, this library (and its development headers) is mandatory to compile wasora. In Debian-based systems, the needed components can be installed with

$ apt-get install libgsl0-dev

 

optional libraries

SUite of Nonlinear and DIfferential/ALgebraic equation Solvers
In order for wasora to be able to solve systems of Differential-Algebraic-Equations (DAEs) such as the The Lorenz chaotic system, the IDA library (and its development headers) has to be installed. Again, the needed components can be installed with
$ apt-get install libsundials-serial-dev
GNU Readline Library
This library is needed if interactive debugging facilities are desired in wasora (i.e. ability to stop a transient calculation at arbitrary breakpoints and to query values of variables, vectors or matrices). Install it with
$ apt-get install libreadline-dev

 

other useful packages

Pyxplot
Scientific Scripting Language, Graph Plotting Tool and Vector Graphics Suite
quick & dirty plot
a wrapper around pyxplot to generate figures from the commandline
Gnuplot
Gnuplot is a portable command-line driven graphing utility for Linux, OS/2, MS Windows, OSX, VMS, and many other platforms.
Gmsh
A three-dimensional finite element mesh generator with built-in pre- and post-processing facilities
Doconce
Document once, include anywhere

publications

The following technical papers have directly or indirectly used wasora to perform different kinds of computations:

© jeremy theler 2004—2014