Stator Documentation

About the stator library

Stator is a Computer Algebra System (CAS) which focuses on using compile-time (template metaprogramming) or runtime stack-allocated algorithms. This means it is really, really, fast (zero overhead, or even a speed-up thanks to compile-time cancellation of terms, when compared to hand coded expressions). Its not as fully featured as a full CAS (such as Mathematica) though yet.

Not convinced? Take a look at the compile-time example below:

  {//Quick example
    
    Var<vidx<'x'> > x; //Create a variable "x"
    Var<vidx<'y'> > y; //Create a variable "y"
    
    auto f = sin(x) + 2 * cos(x); //Define a function f(x)

    //Perform a substitution
    auto g = sub(f, x = y*y); //g(y)=f(y^2)

    //Print the function to screen
    std::cout << g << std::endl;
    //Output: (sin((y × y)) + (2 × cos((y × y))))

    //Evaluate the function
    double a = sub(g, y = 2.3); // a = g(2.3)
    std::cout << a << std::endl;
    //Output: 0.254279

As everything is performed by the compiler via template metaprogramming, only the last substitution can incur any run-time cost. In fact, all of the code above has the same computational cost as writing:

double a = std::sin(2.3*2.3)+2*std::cos(2.3*2.3);

Most modern compilers will also eliminate the cost of this too, leading to zero run-time cost.

As we have a symbolic representation of the function we transform it. Taking the derivative is also carried out at compile time:

    auto dg_dy = derivative(g, y);  // dg/dy
    std::cout << dg_dy << std::endl;
    //Output: (((y + y) × cos((y × y))) + (2 × ((C<-1>() × (y + y)) × sin((y × y)))))

Basic functionality like this also allows more complex operations, such as creating a truncated sym::taylor_series:

    //Take a 5th order taylor series of the derivative around y=0
    auto poly = expand(taylor_series<5>(dg_dy, C<0>(), y));
    std::cout << poly << std::endl;
    //Output: P(-1 × y^5 + -4 × y³ + 2 × y)

    //Calculate the real roots of this 5th order polynomial
    std::cout << solve_real_roots(poly) << std::endl;
    //Output: StackVector{ -0.67044 0.67044 }

This creates a sym::Polynomial type, which is a std::array of the coefficients again at compile time; however, solving for the roots for a 5th order polynomial like this one requires iterations thus it must be done at run time; however, both are carried out without dynamic allocation and thus are very fast on any modern compiler.

This can all be carried out at runtime too:

    Expr f_rt = "sin(x) + 2 * cos(x)";
    Expr g_rt = sub(f_rt, x=y*y);
    a = simplify(sub(g_rt, y = 2.3)).as<double>(); // a = g(2.3)
    Expr dg_dy_rt = derivative(g_rt, y);

See the guide to the symbolic library for more details on how to use the library.

Using the stator library

First, you will need a modern compiler to use stator. In fact, you will need a version of GCC >= 6, clang >= 3.6, and MSVC >= 2015 for all of the library to work. The MSVC compiler has difficulties with deeply templated expressions thus it is not recommended for use with this library.

The current compiler support on Linux is available at the Travis CI page.

Stator is a header-only C++11 library. In many places it builds upon the Eigen 3 library (http://eigen.tuxfamily.org/), so to use it you must have both added to your compiler include path. For example, on linux

g++ -I /path/to/stator/folder -I /path/to/Eigen/folder