Project

General

Profile

Wiki » History » Version 27

Thomas Capricelli, 10/27/2011 09:44 PM

1 7 Thomas Capricelli
{{toc}}
2
3 14 Thomas Capricelli
h1. Introduction
4 7 Thomas Capricelli
5 19 Thomas Capricelli
Symia is a piece of software that helps programmers to perform "symbolic computation":http://en.wikipedia.org/wiki/Symbolic_computation, also known as *symbolic calculus*. The main characteristics are
6 1 Thomas Capricelli
* Symia is a library : the target audience is programmers.
7
* Symia is written in C++.
8
* Symia is released under the "GNU Lesser General Public License":http://en.wikipedia.org/wiki/LGPL, so that even close-source software can make use of it.
9 2 Thomas Capricelli
* Symia uses "unit tests":http://en.wikipedia.org/wiki/Unit_testing as a mean to prevent regression, to ensure robustness, and to provide working examples that the user can rely on.
10 1 Thomas Capricelli
11
The only other C++ library we are aware of is "Ginac":http://en.wikipedia.org/wiki/GiNaC, which is released under the "GNU General Public License":http://en.wikipedia.org/wiki/Gpl, which prevent it from being used in the industry.
12
13 2 Thomas Capricelli
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":http://en.wikipedia.org/wiki/Unit_testing Symia library.
14 1 Thomas Capricelli
15 9 Thomas Capricelli
Symia is developed and released by "Sylphide Consulting":http://www.sylphide-consulting.com. 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":http://en.wikipedia.org/wiki/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":http://www.sylphide-consulting.com/contact about it.
16 3 Thomas Capricelli
17
18 22 Thomas Capricelli
19 3 Thomas Capricelli
h1. Design
20
21 13 Thomas Capricelli
The design is the same as most software performing symbolic calculus. A "class tree":http://labs.freehackers.org/embedded/symia/inherits.html 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.
22 3 Thomas Capricelli
23 22 Thomas Capricelli
24 3 Thomas Capricelli
h1. Examples
25
26 4 Thomas Capricelli
The following code highlights the most important features of Symia.
27 3 Thomas Capricelli
28
<pre><code class="c">
29
{
30
    Expression x("x"), y("y"), a("a"), b("b"), c("c"); // create symbols
31
32
    // Operators and most classical functions are overloaded, so you can construct
33 10 Thomas Capricelli
    // complex expressions the way you expect.
34 3 Thomas Capricelli
    Expression e = a*x+b*x*x*exp(-c*(x+1)/(x*x));
35
36 1 Thomas Capricelli
    // Helpers are provided to display an expression
37 20 Thomas Capricelli
    std::string e_as_text = e.toString(); 
38 6 Thomas Capricelli
    // now e_as_text is "a*x+b*x*x*exp(-c*(x+1)/(x*x))"
39 3 Thomas Capricelli
40 10 Thomas Capricelli
    // You can substitute an expression to any symbol
41 5 Thomas Capricelli
    e = e.replace(x, b+log(c))
42 3 Thomas Capricelli
    // 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))))"
43 25 Thomas Capricelli
    // yes, this is ugly, and this is the reason why you are happy a computer handles it for you.
44 3 Thomas Capricelli
45
    // Evaluation is about using replace() as well
46
    e = e.replace(a,-3).replace(c,1).replace(b,.78);
47
    // e now is "-2.31455"
48 17 Thomas Capricelli
49 18 Thomas Capricelli
    // symia provides a way to compute the derivative with respect to a symbol:
50 17 Thomas Capricelli
    e = sqrt(a+log(x)*b)+exp(cos(x));
51
    e = e.derivative(x);
52
    // e now is "b/x*0.5/sqrt(a+log(x)*b)-sin(x)*exp(cos(x))"
53
54 3 Thomas Capricelli
}
55
</code></pre>
56 1 Thomas Capricelli
57 27 Thomas Capricelli
h1. Documentation
58
59
There are three kind of documentation. 
60
# The API documentation, available through doxygen in the source code, and also provided in the "API documentation tab" at the top of this page
61
# the directory 'examples' in source code, which despite the plural, only contain one example so far
62
# the file @tests/tests.cpp@ is very complete and test a very large chunk of symia features, so that you can see 'in real life' how all those things are used.
63
64 11 Thomas Capricelli
h1. Dependencies
65 1 Thomas Capricelli
66 26 Thomas Capricelli
Symia makes use of the build system "cmake":http://en.wikipedia.org/wiki/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.
67 11 Thomas Capricelli
68 24 Thomas Capricelli
The library depends only on the standard c++ library. It is tested under unix/linux and windows using several compilers (gcc, Intel ICC, Microsoft Visual C++). 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 instead. If you intend to modify the lex/bison files, then of course you'll need to have flex/bison installed on your computer.
69 11 Thomas Capricelli
70 15 Thomas Capricelli
h1. Compilation under unix/linux
71 11 Thomas Capricelli
72
This is a quick description of the steps needed to compile symia. If you know cmake already, this is the typical cmake stuff.
73
74
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
75
76
<pre>
77
symia-0.x$ mkdir build
78
symia-0.x/build$ cd build
79
symia-0.x/build$ cmake .. # you need to give cmake the path to the root of the symia source tree, here '..'
80
symia-0.x/build$ make
81 1 Thomas Capricelli
</pre>
82
83 23 Thomas Capricelli
h1. Compilation under windows
84
85
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.
86
87
!symia-windows-0.1.png!
88
89 22 Thomas Capricelli
h1. Tests
90
91
The unit tests are based on "Nokia QtestLib":http://doc.trolltech.com/4.6/qtestlib-manual.html. Cmake will detect if Qt tests are present on your system. If found, then the tests are built in build/tests/, you can check them by issuing:
92 11 Thomas Capricelli
93
<pre>
94
symia-0.x/build$ ./tests/tests
95
********* Start testing of Symia::TestSymia *********
96
Config: Using QTest library 4.6.0, Qt 4.6.0
97
PASS   : Symia::TestSymia::initTestCase()
98
PASS   : Symia::TestSymia::teststdstream()
99
PASS   : Symia::TestSymia::testElement()
100
PASS   : Symia::TestSymia::testBinaryOperators()
101
PASS   : Symia::TestSymia::testFunctions()
102
PASS   : Symia::TestSymia::testDebug()
103
PASS   : Symia::TestSymia::testReplace()
104
PASS   : Symia::TestSymia::testSimplify()
105
PASS   : Symia::TestSymia::testEvaluation()
106
PASS   : Symia::TestSymia::testDerivative()
107 15 Thomas Capricelli
PASS   : Symia::TestSymia::testRegression1()
108
PASS   : Symia::TestSymia::testParser()
109
PASS   : Symia::TestSymia::cleanupTestCase()
110
Totals: 13 passed, 0 failed, 0 skipped
111 16 Thomas Capricelli
********* Finished testing of Symia::TestSymia *********
112
</pre>
113 11 Thomas Capricelli
114 1 Thomas Capricelli
h1. Frequently Asked Questions
115 11 Thomas Capricelli
116 14 Thomas Capricelli
Where does the name come from ? 
117 11 Thomas Capricelli
This is short for *symbolia*, which has already too much hits in google.