Skip to content
Symi Docs
Rust

The Rust manual covers the recommended facade. The complete native crate is documented in the native Rust API reference.

On this page

Trigonometric and complex rewrites

Trigonometric, logarithmic, exponential, and complex rewrites are separated from general simplification because their identities depend on domains and branch behavior.

expand_complex#

api::algebra::Session method

pub fn expand_complex(
    &self,
    input_expression: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::expand_complex

pub fn expand_complex(&self) -> Result<Expression, ApiError>

Decompose an expression exactly as real_part(expression) + i*imaginary_part(expression). Products, integer powers, and exp, sin, cos, sinh, and cosh are expanded through their Cartesian identities. Symbol assumptions determine which atoms are real. Unknown atoms and branch-sensitive operations such as logarithms and non-integer powers remain represented by symbolic real- and imaginary-part calls. The directed operation also expands a supported modulus under real assumptions: abs(x + i*y) becomes sqrt(x^2 + y^2), and exact integer powers under the modulus preserve their original poles while expanding the Cartesian norm. Oversized or unsupported modulus arguments remain unchanged or wrapper-bearing.

real_part#

api::Session method

pub fn real_part(
    &self,
    target: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::Expression method: api::Expression::real_part

pub fn real_part(&self) -> Result<Expression, ApiError>

Return the exact real component of an expression. For example, if y is declared real, real_part(exp(i*y)) is cos(y). An atom whose reality is unknown returns a symbolic real_part(atom) call. The returned expression is always known to be real.

imaginary_part#

api::Session method

pub fn imaginary_part(
    &self,
    target: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::Expression method: api::Expression::imaginary_part

pub fn imaginary_part(&self) -> Result<Expression, ApiError>

Return the exact imaginary component of an expression. For example, if y is declared real, imaginary_part(exp(i*y)) is sin(y). An atom whose reality is unknown returns a symbolic imaginary_part(atom) call. The returned expression is always known to be real.

combine_powers#

api::algebra::Session method

pub fn combine_powers(
    &self,
    input_expression: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::combine_powers

pub fn combine_powers(&self) -> Result<Expression, ApiError>

Combine same-exponent powers into a single power of the merged base (x^a * y^a -> (x*y)^a) at every product node where the rewrite is provably valid. This identity is false across the branch cut of the complex logarithm — at x = y = -1 and a = 1/2 the left side is i*i = -1 while the right side is sqrt(1) = 1 — so it fires only when the exponent is provably an integer or when every combined base is provably positive. Positivity of the merged base is not enough: (-2)^x * (-3)^x is left alone, because at x = 1/2 combining it to 6^x would flip the sign of the result. Positive numeric-literal bases need no assumptions at all, so 2^x * 3^x becomes 6^x and (1/2)^x * 3^x becomes (3/2)^x. With n declared an integer, x^n * y^n becomes (x*y)^n; the exponent gate recurses structurally, so a compound exponent like 2*n gates the same way. There is no force mode: a site whose gate is not provable is left unchanged, and an expression with no provable site is returned as-is.

expand_power_base#

api::algebra::Session method

pub fn expand_power_base(
    &self,
    input_expression: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::expand_power_base

pub fn expand_power_base(&self) -> Result<Expression, ApiError>

Split a power whose base is structurally a product into a product of powers ((x*y)^a -> x^a * y^a) at every power node whose exponent is provably an integer — the only unconditionally valid gate for this direction, since the split introduces x^a and y^a individually and each needs its own base off the cut. With n declared an integer, (x*y)^n becomes x^n * y^n. Kahan's example (x*y)^(1/2) over unconstrained x, y is left unchanged, as is any other unprovable site; there is no force mode. A base that is not structurally a product is never decomposed, so 6^x is not split into 2^x * 3^x.

denest_powers#

api::algebra::Session method

pub fn denest_powers(
    &self,
    input_expression: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::denest_powers

pub fn denest_powers(&self) -> Result<Expression, ApiError>

Flatten a power of a power into a single power ((x^a)^b -> x^(a*b)) at every power node whose outer exponent is provably an integer, which is valid on the principal branch because an integer power never routes through log. With n declared an integer, (x^a)^n becomes x^(a*n). A fractional outer exponent is left unchanged — ((-1)^2)^(1/2) is 1 while (-1)^(2*(1/2)) is -1 — and there is no force mode. A base that is not structurally a power is untouched.

simplify_trigonometric#

api::Session method

pub fn simplify_trigonometric(
    &self,
    target: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::Expression method: api::Expression::simplify_trigonometric

pub fn simplify_trigonometric(&self) -> Result<Expression, ApiError>

Fu-style trigonometric simplification toward fewer/cheaper trig calls.

expand_trigonometric#

api::Session method

pub fn expand_trigonometric(
    &self,
    target: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::Expression method: api::Expression::expand_trigonometric

pub fn expand_trigonometric(&self) -> Result<Expression, ApiError>

Expand trig/hyperbolic functions of sums and positive integer literal multiple angles. The directed operation may increase expression size; unsupported, symbolic, noninteger, or over-budget multipliers remain unchanged. A successful expansion is structurally idempotent, and recursively admitted sums are expanded in the same pass.

combine_trigonometric#

api::Session method

pub fn combine_trigonometric(
    &self,
    target: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::Expression method: api::Expression::combine_trigonometric

pub fn combine_trigonometric(&self) -> Result<Expression, ApiError>

Inverse direction of expand_trigonometric: product-to-sum and angle-recombination rules.

combine_logarithm#

api::algebra::Session method

pub fn combine_logarithm(
    &self,
    input_expression: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::combine_logarithm

pub fn combine_logarithm(&self) -> Result<Expression, ApiError>

log⁡a+log⁡b→log⁡(ab)\log a + \log b \rightarrow \log(a b) and nlog⁡a→log⁡(an)n\log a \rightarrow \log(a^n) when the transformation preserves the expression's domain.

expand_logarithm#

api::algebra::Session method

pub fn expand_logarithm(
    &self,
    input_expression: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::expand_logarithm

pub fn expand_logarithm(&self) -> Result<Expression, ApiError>

log⁡(ab)→log⁡a+log⁡b\log(a b) \rightarrow \log a + \log b and log⁡(an)→nlog⁡a\log(a^n) \rightarrow n\log a, applied only where the operands are provably positive. Operands of unknown sign pass through unchanged.

rewrite_as_exponential#

api::algebra::Session method

pub fn rewrite_as_exponential(
    &self,
    input_expression: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::rewrite_as_exponential

pub fn rewrite_as_exponential(&self) -> Result<Expression, ApiError>

Euler-form rewriter: replace every trigonometric/hyperbolic call with the equivalent complex-exponential expression (bottom-up).

rewrite_as_trigonometric#

api::algebra::Session method

pub fn rewrite_as_trigonometric(
    &self,
    input_expression: &Expression,
) -> Result<Expression, ApiError>
Calling forms

api::expression_operations::Expression method: api::expression_operations::Expression::rewrite_as_trigonometric

pub fn rewrite_as_trigonometric(&self) -> Result<Expression, ApiError>

Inverse of rewrite_as_exponential. Recognition is shape-strict: canonical Euler forms collapse back to trig/hyperbolic calls, anything else passes through unchanged, so the round trip is the identity.

rewrite_trigonometric_basis#

api::Session method

pub fn rewrite_trigonometric_basis(
    &self,
    target: &Expression,
    basis: TrigonometricBasis,
) -> Result<Expression, ApiError>
Calling forms

api::Expression method: api::Expression::rewrite_trigonometric_basis

pub fn rewrite_trigonometric_basis(
    &self,
    basis: TrigonometricBasis,
) -> Result<Expression, ApiError>

Rewrite trigonometric and hyperbolic calls toward one of five named bases: sine_cosine, tangent, exponential, trigonometric, or hyperbolic. The sine/cosine basis maps tan(x) to sin(x)/cos(x) and reciprocal calls to reciprocal powers; the tangent basis recognizes existing exact quotients such as sin(x)/cos(x) but leaves a bare sin(x) unchanged; the exponential basis maps sin(x) to its Euler form; the trigonometric basis recognizes those canonical Euler forms; and the hyperbolic basis maps explicit imaginary arguments such as sin(i*x) to i*sinh(x). Only identities with the same singularities on the whole complex domain are offered. In particular, the half-angle rewrite of a bare sine into tangent is excluded because it introduces undefined points. An unknown basis name is an error, and nodes without a valid rewrite are returned unchanged.

Example#

Directed rewrites between trigonometric, exponential, and complex forms.

Rust
use symi::api::prelude::*;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let session = Session::new();
    let value = session.parse("exp(i*x)")?;

    println!("{}", session.real_part(&value)?);
    println!("{}", session.imaginary_part(&value)?);
    Ok(())
}

Additional API#

TrigonometricBasis#

api re_export

pub use options::TrigonometricBasis;

A canonical target basis for trigonometric rewrites.

Calling forms

Type: api::options::TrigonometricBasis

pub enum TrigonometricBasis

TrigonometricBasis.Exponential#

api::options::TrigonometricBasis variant

Exponential,

Rewrite toward exponentials.

TrigonometricBasis.Hyperbolic#

api::options::TrigonometricBasis variant

Hyperbolic,

Rewrite toward hyperbolic functions.

TrigonometricBasis.SineCosine#

api::options::TrigonometricBasis variant

SineCosine,

Rewrite toward sine and cosine.

TrigonometricBasis.Tangent#

api::options::TrigonometricBasis variant

Tangent,

Rewrite toward tangent.

TrigonometricBasis.Trigonometric#

api::options::TrigonometricBasis variant

Trigonometric,

Rewrite toward ordinary trigonometric functions.

TrigonometricBasis.from_name#

api::options::TrigonometricBasis method

pub fn from_name(name: &str) -> Result<Self, ApiError>

Resolves the stable binding spelling of a trigonometric basis.

TrigonometricBasis.into_core#

api::options::TrigonometricBasis method

pub fn into_core(self) -> crate::trigonometry::TrigonometricBasis

Converts this binding-neutral value to the engine representation.

TrigonometricBasis.name#

api::options::TrigonometricBasis method

pub fn name(self) -> &'static str

Returns the stable binding spelling of this trigonometric basis.