1 General questions

1.1 Why wasora?

“Do you pine for the nice days of minix-1.1, when men were men and wrote their own device drivers?” Linus Torvalds

Because back in 2009 when I needed something like wasora there was nothing around (and I think that it is still the case). So I started coding it the way I personally would like scientific/engineering codes to be coded. Of course the source should have to be open to increase the number of eyeballs in order to render all bugs shallow. And it should be (and remain) free so I will be able to look back and not find that I made the world a worse place.

“…porque veo al final de mi rudo camino que yo fui el arquitecto de mi propio destino” En Paz, Amado Nervo

1.2 What is wasora?

Wasora is a computational tool designed to perform complex mathematical computations by entering high-level instructions and equations into a text file as naturally as possible. In particular, 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.

Wasora should be seen as a syntactically-sweetened way to ask a computer to perform a certain mathematical calculation. For example, the famous Lorenz system

$\begin{cases} \dot{x} &= \sigma \cdot (y-x) \\ \dot{y} &= x \cdot (r-x) - y\\ \dot{z} &= xy - bz\\ \end{cases}$

may be solved by writing the three differential equations into a plain-text input file as humanly-friendly as possible:

# 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 HEADER

Some of the main features of wasora include

You may see wasora as a high-level interface to some of the functionality of GNU Scientific Library and SUNDIALS IDA Library. It is high level in the sense that the problem is written as naturally as possible in a text file and wasora solves it at run-time.

1.3 What is not wasora?

Wasora is not a programming language. Although it has definitions, instructions, conditionals and loops, if there is a problem that specifically calls for an algorithm, please do not use wasora. Or better, code your algorithm in C, generate an object and dynamically load and run it from within wasora.

1.4 What does wasora mean?

Wasora means wasora’s and advanced suite for reactor analysis. It as another recursive acronym.1 It is aimed primarily at nuclear reactors because that is my main field of expertise, but hopefully other fields of knowledge can use wasora as well. There is also a joke in the name which does not make much sense outside the author’s closest circle of friends.

1.5 How do you spell wasora?

Always using lowercase unless it starts a sentence. Do not capitalize all the letters because

• words written in uppercase letters ANNOY READERS
• names written in uppercase letters remind of old-fashioned inflexible poorly-coded Fortran-based engineering programs

1.6 How do you pronounce wasora?

The name is originally Spanish, so it should be pronounced /wɒ’sɔɹɑ/ although the English variation /wɒ’soʊɹɑ/ and even the German version /vɒ’sɔɹɑ/ are accepted.

1.7 Who wrote wasora? Why?

Wasora was written from scratch in 2009 by Germán G. Theler (a.k.a jeremy theler) because he (i.e. I) found that there was not a single piece of software that performed what he (i.e. I) needed, especially a free-as-in-freedom one. Virtually every feature included in wasora comes from a particular need of a nuclear engineer working in the nuclear industry. See the appendices of report CIT-WSWA-TD-9E3D for details about the history of the development.

Currently, the wasora tree has contributions from the following people besides the original author:

It uses third-party freely distributed code from:

2 Getting wasora

2.1 What is the easiest way to get wasora?

Go to the download page of the Bitbucket repository and get a binary tarball for your architecture. The current ones are:

• linux-amd64: 64-bit static ELF binary for GNU/Linux
• win32-mingw: 32-bit executable for Windows compiled with MinGW
• win32-cygwin: 32-bit executable for Windows compiled with Cygiwn

Notes:

2.2 What if the binary version does not work?

Go to the download page of the Bitbucket repository and get the latest source tarball (the one that does not have the architecture name on it such as wasora-0.4.19.tar.gz). Then untar, configure and make:

$tar xvzf wasora-0.4.19.tar.gz$ cd wasora-0.4.19
$./configure [...] Now proceed to compile with 'make'$ make
[...]
Happy engineering hacking with wasora!

make[1]: Leaving directory '/home/gtheler/tmp/wasora-0.4.19'
$ If the configure script complains about some missing library, read the INSTALL file in the distribution tarball to find how to solve the issue. 2.3 What is the best way to get wasora? Clone the wasora repository hosted on Bitbucket using Mercurial: $ hg clone https://bitbucket.org/wasora/wasora

The repository has to be bootstraped before being able to configure and make (note that autoconf and friends are needed):

$cd wasora$ ./autogen.sh 

Then proceed to the usual configure and make:

$./configure$ make

Keep your local repo up to date by pulling and updating:

$hg pull [...]$ hg update

If something goes wrong, read the INSTALL file or ask for help as explained below.

3 Getting help

3.1 Where is the documentation?

First, it is very incomplete. Second, it is scarcely distributed. But the good news is that 2016’s main objective is to complete a decent set of documentation files. For now, try the following locations:

• The README and INSTALL files contained in the distribution
• The wasora wiki, that has updated links to other sources of documentation.
• The technical report CIT-WSWA-TD-9E3D “Description of the computational tool wasora”
• The subdirectory doc in the wasora tree

3.2 Can I see some examples of application?

Yes. See

Contributions to cases of applications are welcome.

3.3 Where can I ask for help?

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

3.4 I need a certain feature. Can it be added to wasora?

From a technical point of view, probably. From an practical point of view, also probable. Just keep in mind that wasora is developed with as an open-source project. To sump up, contact the author and/or the mailing list and ask for the feature to be added and we will see.

3.5 How to report a bug or error?

The preferred way to report a bug, error or just complain about something is to open a ticket in wasora’s issue tracker so we can keep an centralized list, follow and solve each issue. If you do not have a Bitbucket account or are afraid of the cloud, the second preferred way is to write to the mailing list so at least the issue gets documented and archived. If you are afraid of public expose, write me privately and I will take the shot for you.

4 Syntax highlighting

4.1 How do I get syntax highlighting for Kate?

Kate bases its syntax highlight in an XML file with the definition of the language. There is a script that parses some of the wasora source files and generates such XML file with the format Kate expects. So the answer is, generate an XML file with wasora’s syntax definition using the script doc/syntax-kate.sh in the wasora source tree and store the output it in $HOME/.kde/share/apps/katepart/syntax/wasora.xml (note that the diretory may not exist): $ cd doc
$mkdir -p$HOME/.kde/share/apps/katepart/syntax
$./syntax-kate.sh >$HOME/.kde/share/apps/katepart/syntax/wasora.xml

Next time you open Kate, it should highlight all files with extension .was. To explicitly ask the editor to highlight an open file, go to Tools -> Highlighting -> Scientific -> Wasora.

To be explained.

To be explained.

To be explained.

To be explained.

To be explained.

5 Licensing

5.1 Under what terms is wasora distributed?

Wasora is distributed under the terms of the GNU GPL version 3 or, if you want, any later version if version 3 is superseeded and this document is not updated. See

Essentially, this means that wasora is free software so you get the four essential freedoms:

1. the freedom to use the software for any purpose,
2. the freedom to change the software to suit your needs,
3. the freedom to share the software with your friends and neighbors, and
4. the freedom to share the changes you make.

Bottomline: you can run wasora as you want, you can modify as you want, you can share it as you want and you can distribute your modifications.
Caveat: if you do distribute your modifications, you should do so under the same terms of the GPLv3+, i.e. you cannot make a closed-source program out of wasora sources.

See What is free software for a nice TEDx talk by RMS about the subject.

To be explained.

5.3 I need a BSD-friendly version of wasora or any of its plugins. Can I have one?

To be explained.

wasora is copyright (C) 2009–2016 Germán (jeremy) Theler
See the file COPYING for copying conditions.