Wiki » History » Revision 19

Revision 18 (Thomas Capricelli, 12/07/2009 02:20 PM) → Revision 19/28 (Thomas Capricelli, 12/08/2009 12:58 AM)


h1. Introduction

Symia is a piece of software that helps programmers to perform "symbolic computation":, also known as *symbolic calculus*. calculs*. The main characteristics are
* Symia is a library : the target audience is programmers.
* Symia is written in C++.
* Symia is released under the "GNU Lesser General Public License":, so that even close-source software can make use of it.
* Symia uses "unit tests": as a mean to prevent regression, to ensure robustness, and to provide working examples that the user can rely on.

The only other C++ library we are aware of is "Ginac":, which is released under the "GNU General Public License":, which prevent it from being used in the industry.

Symia is far from being able to do as much as, say, Maple or Ginac, but if your needs are basic, you can rely on the robust and "tested": Symia library.

Symia is developed and released by "Sylphide Consulting": If you need some more features in Symia, you can either abandon the idea of using Symia, implement the missing features by yourself (and provide the code back, as the "GNU LGPL": says), or pay someone to do the job. Of course, *Sylphide Consulting* is an obvious choice for such a task, and we would be delighted if you "contact us": about it.

h1. Design

The design is the same as most software performing symbolic calculus. A "class tree": of objects implement constants, symbols, basic operations and functions. A generic class "Expression" is used to keep track of allocated objects and is the basic element manipulated by the user.

h1. Examples

The following code highlights the most important features of Symia.

<pre><code class="c">
Expression x("x"), y("y"), a("a"), b("b"), c("c"); // create symbols

// Operators and most classical functions are overloaded, so you can construct
// complex expressions the way you expect.
Expression e = a*x+b*x*x*exp(-c*(x+1)/(x*x));

// Helpers are provided to display an expression
QString e_as_text = e.toString();
// now e_as_text is "a*x+b*x*x*exp(-c*(x+1)/(x*x))"

// You can substitute an expression to any symbol
e = e.replace(x, b+log(c))
// e now is "a*(b+log(c))+b*(b+log(c))*(b+log(c))*exp(-c*(b+log(c)+1)/((b+log(c))*(b+log(c))))"
// yes, this is ugly, and this is the reason what you are happy a computer handles it for you.

// Evaluation is about using replace() as well
e = e.replace(a,-3).replace(c,1).replace(b,.78);
// e now is "-2.31455"

// symia provides a way to compute the derivative with respect to a symbol:
e = sqrt(a+log(x)*b)+exp(cos(x));
e = e.derivative(x);
// e now is "b/x*0.5/sqrt(a+log(x)*b)-sin(x)*exp(cos(x))"


h1. Dependencies

Symia makes of the build system "cmake": You need this tool in order to compile symia. I recommend using version 2.8.0 or higher, previous version do not have support for flex/bison.

The library depends only on the standard c++ library. It is tested under unix/linux and windows using several compilers (gcc, icc, msvc). The library makes use of flex/bison to generate the parser, but the generated files are included for convenience : cmake will auto-detect if you have lex and/or bison. If found, the tools are used, and if not found, the pre-generated files are used. If you intend to modify the lex/bison files, then of course you'll need to have flex/bison installed on your computer.

The unit tests are based on "Nokia QtestLib": and will detect if Qt tests are present on your system. If found, then the tests are compiled.

h1. Compilation under unix/linux

This is a quick description of the steps needed to compile symia. If you know cmake already, this is the typical cmake stuff.

You need to create a 'build' directory, from which to start cmake. 'build' is often put in the main symia directory, but you dont have to

symia-0.x$ mkdir build
symia-0.x/build$ cd build
symia-0.x/build$ cmake .. # you need to give cmake the path to the root of the symia source tree, here '..'
symia-0.x/build$ make

If the QTestLib is present, the tests are built in build/tests/, you can check them by issuing:

symia-0.x/build$ ./tests/tests
********* Start testing of Symia::TestSymia *********
Config: Using QTest library 4.6.0, Qt 4.6.0
PASS : Symia::TestSymia::initTestCase()
PASS : Symia::TestSymia::teststdstream()
PASS : Symia::TestSymia::testElement()
PASS : Symia::TestSymia::testBinaryOperators()
PASS : Symia::TestSymia::testFunctions()
PASS : Symia::TestSymia::testDebug()
PASS : Symia::TestSymia::testReplace()
PASS : Symia::TestSymia::testSimplify()
PASS : Symia::TestSymia::testEvaluation()
PASS : Symia::TestSymia::testDerivative()
PASS : Symia::TestSymia::testRegression1()
PASS : Symia::TestSymia::testParser()
PASS : Symia::TestSymia::cleanupTestCase()
Totals: 13 passed, 0 failed, 0 skipped
********* Finished testing of Symia::TestSymia *********

h1. Compilation under windows

This should work with either mingw (gcc) or Microsoft Visual C++. You need to start cmake from the windows menu, and configure paths for source and build dir. Then from a console, go to the build dir and start the compilation. If you use mingw, this means 'mingw32-make'. The following picture show both the cmake GUI and a successful build in the console.


h1. Frequently Asked Questions

Where does the name come from ?
This is short for *symbolia*, which has already too much hits in google.