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

Undefined functions

An undefined function is a named unknown: a function symbol with no definition, such as the y of an ordinary differential equation. It is not an expression. It is a handle from which two things are built — a call y(x), and a structural derivative y′′(x)y''(x) — and those expressions are what the solvers, classifiers, and verifiers read.

Three different operations in this manual are spelled derivative or differentiate. They are not interchangeable:

Task Entry Page
Differentiate an expression now differentiate (Python also diff) Calculus
Wrap an expression in an unevaluated derivative derivative_unevaluated (or derivative) Deferred forms
Build a derivative of a named unknown from argument orders derivative below This page

Constructing a named unknown#

undefined_function#

api::Session method

pub fn undefined_function(
    &self,
    name: impl Into<String>,
) -> UndefinedFunction

A callable proxy for a user-named function. The handle belongs to the context that made it, and every expression built from it belongs to that same context. The module-level undefined_function(name) in Python and undefinedFunction in Kotlin and Swift build the handle in the default context. There is no direct class constructor: the factory is the one way to make a handle, so its context is never ambiguous.

UndefinedFunction#

Type

pub struct UndefinedFunction

The handle itself. It carries no mathematical content beyond its name and its context; all of its meaning appears in the expressions it builds.

Calling the function#

call#

api::UndefinedFunction method

pub fn call<IteratorType>(
    &self,
    arguments: IteratorType,
) -> Result<Expression, ApiError>
where
    IteratorType: IntoIterator<Item = Expression>,

The function-call expression name(arguments...). Argument order is the function's own argument order and is preserved exactly; it is what derivative indexes its orders against. Python spells the same operation as ordinary call syntax, y(x).

Structural derivatives#

derivative#

api::UndefinedFunction method

pub fn derivative<OrderIterator, ArgumentIterator>(
    &self,
    orders: OrderIterator,
    arguments: ArgumentIterator,
) -> Result<Expression, ApiError>
where
    OrderIterator: IntoIterator<Item = usize>,
    ArgumentIterator: IntoIterator<Item = Expression>,

The structural derivative node of the named function — the shape the ODE and PDE classifiers recognise. There is one order per argument, matched positionally against arguments: y.derivative([1], [x]) is y′(x)y'(x), y.derivative([2], [x]) is y′′(x)y''(x), and u.derivative([1, 2], [x, t]) is ∂x∂t2u(x,t)\partial_x \partial_t^2 u(x, t). An order list whose length differs from the argument list is an error rather than a padded guess.

This is distinct from derivative on a context or an expression, which wraps an arbitrary expression in a deferred differentiation placeholder. Equations built from that placeholder are not recognised by the differential-equation classifiers, so an equation whose unknown is a named function must use the operation on this page.

Declared bijections#

With nothing known about ff, the equation f(x)2+f(x)−2=0f(x)^2 + f(x) - 2 = 0 can only be solved up to the preimage condition f(x)∈{1,−2}f(x) \in \{1, -2\}: ff may take either value anywhere. A declaration says more. It is durable for the context, like an assumption, replaces any earlier declaration for the same function, and is seen by every later solve.

declare_bijection#

api::solving::Session method

pub fn declare_bijection(
    &self,
    function: &UndefinedFunction,
    source: &Expression,
    target: &Expression,
) -> Result<(), ApiError>

Declares that function maps the set source — its whole domain — one to one onto the set target. Solving a polynomial equation in the function's values then discards every root proved outside the target: a bijection onto the real line never takes the value ii. Each other root keeps its exact preimage condition, since the preimage has no name.

declare_bijection_with_inverse#

api::solving::Session method

pub fn declare_bijection_with_inverse(
    &self,
    function: &UndefinedFunction,
    source: &Expression,
    target: &Expression,
    inverse: &UndefinedFunction,
) -> Result<(), ApiError>

The same declaration, naming inverse as the function that maps each target point back to its one source point. A root proved inside the target then has exactly the preimage inverse(root), so f(x)2+f(x)−2=0f(x)^2 + f(x) - 2 = 0 with ff a bijection of the complex plane solves to {g(1),g(−2)}\{g(1), g(-2)\} for the inverse gg; with an inner argument, f(3x−1)=1f(3x - 1) = 1 is solved as 3x−1=g(1)3x - 1 = g(1). Over the reals the preimages are named only when the declared source lies in the real line. A root whose membership in the target cannot be decided keeps its preimage condition rather than being named or discarded.

clear_function_declarations#

api::solving::Session method

pub fn clear_function_declarations(
    &self,
    function: &UndefinedFunction,
) -> Result<(), ApiError>

Withdraws everything declared about function, restoring the undeclared preimage answers.

Object identity and lifetime#

These members are owner-qualified here because name, session, and is_stale are member names many unrelated types share; each entry below documents the UndefinedFunction member and nothing else.

UndefinedFunction.name#

api::UndefinedFunction method

pub fn name(&self) -> &str

The name the handle was created with.

UndefinedFunction.session#

api::UndefinedFunction method

pub fn session(&self) -> Session

The context that owns the handle. Expressions built from a handle belong to that context, and mixing contexts is refused rather than silently rebased.

UndefinedFunction.generation#

api::UndefinedFunction method

pub fn generation(&self) -> u64

The context generation the handle was published in, which is what the staleness check below compares against.

UndefinedFunction.is_stale#

api::UndefinedFunction method

pub fn is_stale(&self) -> bool

Whether the owning context has moved past the generation this handle belongs to. The concept, and what to do about it, is explained once in Context safety.

Text output#

UndefinedFunction.repr#

Not part of the recommended symi::api facade; the operation is reachable from the complete native crate in the native Rust API reference. Available as UndefinedFunction.__repr__ in Python.

The Python repr() text naming the undefined function.

UndefinedFunction.toString#

The JavaScript text naming the undefined function.

Example#

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

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let session = Session::new();
    let x = session.symbol("x")?;
    let y = session.undefined_function("y")?;
    let equation = y.derivative([1], [x.clone()])?.subtract(&y.call([x])?)?;
    println!("{equation}");
    Ok(())
}