$$ \renewcommand{\vec}[1]{\mathbf{#1}} $$

Introduction

To be done.

History and motivation

Initial-value ordinary differential equations arise in a great variety of subjects in science and engineering. Classical mechanics, chemical kinetics, structural dynamics, heat transfer analysis and dynamical systems, amongst other disciplines, heavily rely on equations of the form $$ \dot{\vec{x}} = \vec{F}(\vec{x}) $$

During my years of undergraduate student, whenever I faced these kind of equations, I had to choose one of the following three options:

  1. program an ad-hoc numerical method such as Euler or Runge-Kutta, matching the requirements of the system of equations to solve
  2. use a standard numerical library such as the GNU Scientific Libary and code the equations to solve into a C program (or maybe in Python)
  3. use a high-level system such as octave, maxima, or other non-free and and worse programs like MatLab or Mathematica
Of course, each option has its pros and its cons. But none provided the combination of advantages I was looking for, namely flexibility (option one), efficiency (option two) and reduced input work (partially given by option three). Back in those days I ended up wandering between options one and two, depending on the type of problem I had to solve. However, even though one can with some effor make the code read some parameters from a text file, any other changes usually require a modification in the source code—some times involving a substantial amount of work—and a further recompilation of the code. This was what I most disliked about this way of working, but I could nevertheless live with it.

Regardless of this situation, in my last year of Nuclear Engineering I ran into a nuclear reactor model that especially called my attention and forced me to re-think the ODE-solving problem issue. The model was implemented in Simulink, a software which I had been told was the actual panacea for the engineering community—and yet I was using for the very first time. When I opened the file and took a look at the model, I was not able to understand any of the several screens the model contained. Afterward, somebody explained to me that a set of unintelligible blocks that were somehow interconnected in a rather cumbersome way was how the reactor power was computed. I wish I had a copy of the screen in order to illustrate how shockwing it was to me.

The equation represented by what seemed to me as a complex topology problem was as simple as $$ \frac{dn}{dt} = \frac{\rho - \beta}{\Lambda} + \lambda \cdot c $$

My first reaction was to ask why someone would prefer this instead of writing something like

n_dot = (rho - beta)/Lambda + lambda*c

in a text file. I do not remember what the answer was, and I still do not understand why would somebody prefer to solve a very simple differential equation by drawing blocks with no mathematical sense whatsoever.

That morning I realized that in order to to transform a user-defined string representing a differential equation into something that an ODE-solving library such as the GNU Scientific Library would understand, only a good algebraic parser plus some simple interface routines were needed. The following two years were very time-consuming for me, so I was not able to undertake such a project. Nevertheless, eventually I graduated and my focus shifted away from academic projects and some gaps of time for freelance programming popped up. I started to write wasora from scratch, and one of the first features I included was and adaptation of a small algebraic parser posted in stackoverflow.com (which should be replaced by a more efficent tree-based parser), freely available under the Creative Commons License. Before I became aware, I was very close to arriving at the tool that would have met my needs when I was an engineering student. And, with some luck, at a tool that would meet somebody else's needs as well. Hence, this is the way wasora enters into the scene.

What wasora is

To be done.

What wasora is not

To be done.

Licensing

Wasora is free software—both as in free speech and as in free beer, although the first meaning is far more important than the second one—and is distributed under the terms of the GNU General Public License version 3. In words of the Free Software Foundation,

Nobody should be restricted by the software they use. There are four freedoms that every user should have:

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

When a program offers users all of these freedoms, we call it free software.

Developers who write software can release it under the terms of the GNU GPL. When they do, it will be free software and stay free software, no matter who changes or distributes the program. We call this copyleft: the software is copyrighted, but instead of using those rights to restrict users like proprietary software does, we use them to ensure that every user has freedom.

Not only does wasora provide all the four basic freedoms to the software user, but also encourages her to study, understand, analyze and hack it. And of course, to share the associated discoveries, suggestions, improvements and fixed bugs under the terms of the GNU GPL—especially with wasora's original author. To sum up:

Wasora is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Wasora is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with wasora. If not, see http://www.gnu.org/licenses/.

The codes in the wasora suite rely on different free libraries—all of them available also under different free licenses—depending on the kind of problem each code solves. Nonetheless, the wasora framework and all the particular codes depend on the GNU Scientific Library, released freely under the GNU General Public License version 3. Check the documentation of each particular code in the suite for details of the needed libraries in each case. A copy of the GNU General Public License can be found in each of the code's distribution tarball.

License (see the section sec:licensing for details). These codes may be run as standalone processes or glued together to obtained coupled models. They all are based on a common framework that provides both mathematical—such as algebraic parsing, function definition, data interpolation, differentiation and integration procedures, etc.—and general-purpose routines like input file parsing, writing the obtained results in a concise manner and inter-process communication routines.

means a mature engineering solution. The second one is that no further reference to the PhD thesis is going to be done neither in this document nor in the documentation of the individual codes in the wasora suite—although probably the proper reference will be added to the bibliography of those future versions of this document that are to appear with the word project removed. And finally, as stated above, even though the motivation of the work is the optimization of nuclear reactors, some codes like the DAE solver mochin or the control logic analysis code colach, with the aid of even more luck, may be of interest in other fields of engineering.