Get Started

Symbolica can be used as a library in Rust and Python. The C/C++/Mathematica bindings currently allow for fast multivariate polynomial arithmetic only.

What language should I use?

The Python API makes the most sense for beginners, as it is convenient to use. The Rust library makes sense for advanced users who want to develop a new feature. Rust will give the highest performance, and the greatest flexibility. This comes at the cost of more verbosity.

The recommended setup is Visual Studio Code with:

• Jupyter extension
• Pylance extension
• (optional) Github Copilot

With this setup you will get inline documentation, auto-completion and LaTeX rendering of output.

Live demo

A live demo of Symbolica in a Python Jupyter notebook is available on Google Colab.

You can easily make modifications to the code and run it on the Google Colab servers without any local installation.

Installation

Python

Symbolica can be installed for Python >3.5 using pip:

pip install symbolica

The installation may take some time, as it may have to compile Symbolica.

Manual installation

One can build and install the Python module of Symbolica using maturin:

git clone https://github.com/benruijl/symbolica.git
cd symbolica
maturin build

Then Symbolica can be installed into a virtual environment (e.g., python3 -m venv .venv) using:

maturin develop --release

Testing

To see if it works, open a Python session and try:

from symbolica import Expression

If you get no import error, the installation was successful.

Rust

If you are using Symbolica as a library in Rust, simply include it in the Cargo.toml:

[dependencies]
symbolica = { "*" }

To use the latest development version, import it from git:

[dependencies]
symbolica = { git = "https://github.com/benruijl/symbolica.git" }

You can try some Rust examples in the examples folder.

Apart from the documentation on this website, the Rust documentation can also be accessed on docs.rs.

C++

Download and compile Symbolica with:

git clone https://github.com/benruijl/symbolica.git
cd symbolica
cargo rustc --release --crate-type=cdylib

to generate a dynamically linked library. Use --crate-type=staticlib to generate a static one.

If you use the library statically, the feature --features=faster_alloc can be added to the compilation command for extra performance.

Now try the following example C code:

C

test.c

#include <stdio.h>

typedef struct SYMBOLICA* Symbolica;

extern Symbolica *init();
extern void set_vars(Symbolica* symbolica, const char *vars);
extern void set_options(Symbolica *symbolica, const bool input_has_rational_numbers, bool exp_fits_in_u8);
extern char* simplify(Symbolica* symbolica, const char *input, unsigned long long prime, char explicit_rat);
extern void drop(Symbolica *symbolica);


int main() {
    char* in = "(x+5)/(x+6) + 35/y";
    char* in2 = "(x*y^2*5+5)^2/(2*x+5)+(x+4)/(6*x^2+1)";

    Symbolica* s = init();
    set_vars(s, "x,y,z");
    char* out = simplify(s, in, 0, 1);
    printf("%s\n", out);

    out = simplify(s, in2, 5, 1);
    printf("%s\n", out);

    drop(s);

    return 0;
}

It can be compiled with dynamic linking:

gcc -O3 test.c -L target/release -lsymbolica -o test

or with static linking:

gcc -O3 test.c -L target/release -l:libsymbolica.a -lm -o test

C++

test.cpp

#include <iostream>

typedef struct SYMBOLICA *Symbolica;

extern "C"
{
    extern Symbolica *init();
    extern void set_vars(Symbolica *symbolica, const char *vars);
    extern void set_options(Symbolica *symbolica, char input_has_rational_numbers, char exp_fits_in_u8);
    extern const char *simplify(Symbolica *symbolica, const char *input, unsigned long long prime, char explicit_rat);
    extern void drop(Symbolica *symbolica);
}

int main()
{
    const char *in = "(x+5)/(x+6) + 35/y";
    const char *in2 = "(x*y^2*5+5)^2/(2*x+5)+(x+4)/(6*x^2+1)";

    Symbolica *s = init();
    set_vars(s, "x,y,z");
    const char *out = simplify(s, in, 0ull, 0);
    std::cout << out <<  std::endl;

    out = simplify(s, in2, 5ull, 0);
    std::cout << out <<  std::endl;

    drop(s);

    return 0;
}

It can be compiled with dynamic linking:

g++ -O3  test.cpp -L target/release -lsymbolica -o test

or with static linking:

g++ -O3  test.cpp -L target/release -l:libsymbolica.a -lm -o test

Running the file ./test (or LD_LIBRARY_PATH=target/release ./test for the dynamically linked compilation) should give:

(210+5*y+35*x+x*y)/(6*y+x*y)
(-1+x)/(1+x^2)

License

If you run Symbolica without a valid license key you are running in unlicensed mode. In this mode Symbolica is limited to one instance and one core.

Professional users

Professional users (for example PhD students, researchers, professors) are not allowed to use the unlicensed mode and will have to get a professional license or request a free 30-day trial:

Python

from symbolica import request_trial_license
request_trial_license('NAME', 'EMAIL', 'COMPANY')

Rust

use symbolica::LicenseManager;

fn main() {
    LicenseManager::request_trial_license("Name", "Email", "Company").unwrap();
}

The license key will be e-mailed to you immediately. If the trial expires and you want to keep trying Symbolica, you can reach out to license@symbolica.io for an extension.

Non-professional users

Non-professional users (for example hobbyists or bachelor/master students) are permitted to use the unlicensed mode, but it is also very easy and free to request an annual hobbyist license by providing your name and e-mail address:

Python

from symbolica import request_hobbyist_license
request_hobbyist_license('YOUR_NAME', 'YOUR_EMAIL')

Rust

use symbolica::LicenseManager;

fn main() {
    LicenseManager::request_hobbyist_license("Name", "Email").unwrap();
}

The license key will be e-mailed to you immediately.

If you have a license key, simply provide it in an environment variable SYMBOLICA_LICENSE, .e.g

SYMBOLICA_LICENSE=abe2d4f1-3251-5377-b175-ca1912beb982

or provide it at the start of your program, before calling any other Symbolica functions:

Python

from symbolica import Expression, Transformer, set_license_key
set_license_key('abe2c4f1-3851-5177-b075-cb1912beb982')
x_ = Expression.var('x_')

Rust

use symbolica::{state::State, LicenseManager};

fn main() {
    LicenseManager::set_license_key("abe2c4f1-3851-5177-b075-cb1912beb982").unwrap();
    let mut _state = State::new();
}

C++

extern int set_license_key(const char *key);

int main() {
    set_license_key("abe2c4f1-3851-5177-b075-cb1912beb982");
}

Offline keys

Sometimes a Symbolica license key is needed on a machine that is not connected to the internet. For this purpose, an offline key that is valid for 24 hours can be generated from a valid license key on a machine that is connected to the internet.

Python

from symbolica import *
set_license_key('YOUR_KEY')
print(get_offline_license_key())

Rust

use symbolica::LicenseManager;

fn main() {
    LicenseManager::set_license_key("YOUR_KEY").unwrap();
    println!("{}", LicenseManager::get_offline_license_key().unwrap());
}

C++

extern int set_license_key(const char *key);
extern int get_offline_license_key(char *key);

int main() {
    set_license_key("YOUR_KEY");
    char buffer[100];
    get_offline_license_key(buffer);
}

Examples

In the following example we create a Symbolica expression (1+x)^3, and expand it:

Python

from symbolica import Expression
x = Expression.var('x')
e = (1+x)**2
r = e.expand()
print(r)

Rust

use symbolica::atom::Atom;

fn main() {
    let input = Atom::parse("(1+x)^3").unwrap();
    let o = input.expand();

    println!("> Expansion of {}: {}", input, o);
}

which yields 3*x+3*x^2+x^3+1.

Pattern matching

Pattern matching and replacements are an important part of symbolica manipulation. Variables ending with a _ are wildcards and can match any subexpression. In the following example we try to match the pattern f(1,2,y_) and replace it by f(1,2,y_+1).

Python

from symbolica import Expression
x, x_ = Expression.vars('x','x_')
f = Expression.fun('f')
e = f(1,2,x) + f(1,2,3)
r = e.replace_all(f(1,2,x_), f(1,2,x_+1))
print(r)

Rust

use symbolica::{id::Pattern, atom::Atom};

fn main() -> Result<(), String> {
    let expr = Atom::parse(" f(1,2,x) + f(1,2,3)")?;
    let pat = Pattern::parse("f(1,2,y_)")?;
    let rhs = Pattern::parse("f(1,2,y_+1)")?;

    let out = pat.replace_all(expr.as_view(), &rhs, None, None);

    println!("{}", out);
    Ok(())
}

Applying the pattern to the expression f(1,2,x)+f(1,2,3) we get:

f(1,2,x+1) + f(1,2,4)

To learn more about pattern matching, see Pattern matching.

Rational arithmetic

Symbolica is world-class in rational arithmetic, outperforming Mathematica, Maple, Form, Fermat, and other computer algebra packages. Simply convert an expression to a rational polynomial:

Python

from symbolica import Expression
x, y = Expression.vars('x','y')
p = Expression.parse('(x*y^2*5+5)^2/(2*x+5)+(x+4)/(6*x^2+1)').to_rational_polynomial()
print(p)

Rust

use symbolica::{
    atom::Atom,
    rings::{
        integer::IntegerRing, rational::RationalField, rational_polynomial::RationalPolynomial,
    },
};

fn main() -> Result<(), String> {
    let expr = Atom::parse("(x*y^2*5+5)^2/(2*x+5)+(x+4)/(6*x^2+1)")?;
    let rat: RationalPolynomial<IntegerRing, u8> = expr
        .to_rational_polynomial(
            RationalField::new(),
            IntegerRing::new(),
            None,
        )?;

    println!("{}", rat);
    Ok(())
}

C++

The header is omitted, as it is the same as in the installation instructions.

int main()
{
    const char *in = "(x*y^2*5+5)^2/(2*x+5)+(x+4)/(6*x^2+1)";

    Symbolica *s = init();
    set_vars(s, "x,y");
    const char *out = simplify(s, in, 0ull, 0);
    std::cout << out <<  std::endl;

    drop(s);

    return 0;
}

which yields

(45+13*x+50*x*y^2+152*x^2+25*x^2*y^4+300*x^3*y^2+150*x^4*y^4)/(5+2*x+30*x^2+12*x^3)

API reference

It is advised to use an IDE such as Visual Studio Code to make use of in-line documentation and auto-completion:

A complete overview of the language-specific APIs can be found below:

Python

For the Python API a full overview of all the functions and its documentation is provided here.

Rust

Rust documentation can be read at docs.rs. Also make sure to check out the examples.

Learn more

There are several places where you can learn more about Symbolica.

• Browse the guide to learn more about Symbolica features.
• Follow the project on Github to see all changes.
• Read developer and Rust documentation on docs.rs.
• Follow the development and discussions on Zulip.
• Check out the Blog to learn about computer algebra and the inner workings of Symbolica.