Usage

Usage

This page provides practical examples of how to use the rssn library in your own Rust projects. The core workflow typically involves creating or parsing Expr objects and then using various functions from the symbolic, numerical, or other modules to manipulate them.

Home

Getting Started

First, add rssn as a dependency in your Cargo.toml:

[dependencies]
rssn = "0.1" # Check for the latest version on crates.io

Basic Symbolic Differentiation

One of the most common tasks in symbolic computation is differentiation. rssn makes this straightforward. The following example shows how to define an expression and find its derivative.

This example corresponds to the symbolic_differentiation_modern.rs file in the examples directory.

use rssn::symbolic::calculus::differentiate;
use rssn::symbolic::core::Expr;

fn main() {
    // Define a variable 'x'. This creates a symbolic representation of 'x'.
    let x = Expr::new_variable("x");

    // Define the expression sin(x) using convenient method syntax.
    // This is equivalent to `Expr::new_sin(x.clone())`.
    let expr = x.sin();

    // Differentiate the expression with respect to 'x'.
    // The `differentiate` function takes the expression and the variable name.
    let derivative = differentiate(&expr, "x");

    // The result of differentiating sin(x) is cos(x).
    // The `Display` trait is implemented for `Expr` for easy printing.
    println!(
        "The derivative of {} is: {}",
        expr,
        derivative
    );
}

Expected Output:

The derivative of sin(x) is: cos(x)

Advanced: Gröbner Basis Computation

rssn includes powerful features for advanced algebra, such as computing the Gröbner basis of a system of polynomial equations. This is a fundamental tool for solving systems of polynomial equations.

This example, based on grobner_basis_demo_1.rs, finds the Gröbner basis for the intersection points of two circles.

The Problem

Find the solution to the system:

1. x^2 + y^2 - 1 = 0 (A circle centered at the origin with radius 1)
2. (x-1)^2 + y^2 - 1 = 0 (A circle centered at (1, 0) with radius 1)

The Code

use rssn::input::parser::parse_expr;
use rssn::symbolic::core::Expr;
use rssn::symbolic::grobner::{buchberger, MonomialOrder};
use rssn::symbolic::polynomial::expr_to_sparse_poly;
use rssn::symbolic::polynomial::sparse_poly_to_expr;

fn main() {
    // 1. Define the polynomials as strings and parse them into `Expr` objects.
    let f1_expr = parse_expr("x^2 + y^2 - 1").unwrap().1;
    let f2_expr = parse_expr("x^2 - 2*x + y^2").unwrap().1;

    println!("Original Polynomials:");
    println!("  f1: {}", f1_expr);
    println!("  f2: {}", f2_expr);

    // 2. Convert the expressions into an internal sparse polynomial representation.
    //    This is more efficient for polynomial algorithms.
    let variables = &["x", "y"];
    let f1_sparse = expr_to_sparse_poly(&f1_expr, variables);
    let f2_sparse = expr_to_sparse_poly(&f2_expr, variables);

    // 3. Set up the basis for the algorithm.
    let basis = vec![f1_sparse, f2_sparse];

    // 4. Compute the Gröbner basis using Buchberger's algorithm with Lexicographical order.
    println!("\nComputing Gröbner basis...");
    let grobner_basis = buchberger(&basis, MonomialOrder::Lexicographical).unwrap();

    // 5. Print the resulting basis. The new basis makes the system easier to solve.
    println!("\nGröbner Basis:");
    for (i, poly) in grobner_basis.iter().enumerate() {
        println!(
            "  g{}: {}",
            i + 1,
            sparse_poly_to_expr(poly)
        );
    }
}

Expected Output:

Original Polynomials:
  f1: x^2 + y^2 - 1
  f2: x^2 - 2*x + y^2

Computing Gröbner basis...

Gröbner Basis:
  g1: x - 1/2
  g2: y^2 - 3/4

This result provides a much simpler, "triangular" system. From g1, we can see that x = 1/2. Substituting this into g2 gives y^2 = 3/4, so y = ±sqrt(3)/2. The Gröbner basis has successfully solved the system.