Struct Context 

pub struct Context { /* private fields */ }

A Context holds a set of deduplicated constants, variables, and operations.

It should be used like an arena allocator: it grows over time, then frees all of its contents when dropped. There is no reference counting within the context.

Items in the context are accessed with Node keys, which are simple handles into an internal map. Inside the context, operations are represented with the Op type.

Implementations

impl Context

pub fn new() -> Self

Build a new empty context

pub fn clear(&mut self)

Clears the context

All Node handles from this context are invalidated.

let mut ctx = Context::new();
let x = ctx.x();
ctx.clear();
assert!(ctx.eval_xyz(x, 1.0, 0.0, 0.0).is_err());

pub fn len(&self) -> usize

Returns the number of Op nodes in the context

let mut ctx = Context::new();
let x = ctx.x();
assert_eq!(ctx.len(), 1);
let y = ctx.y();
assert_eq!(ctx.len(), 2);
ctx.clear();
assert_eq!(ctx.len(), 0);

pub fn is_empty(&self) -> bool

Checks whether the context is empty

pub fn get_const(&self, n: Node) -> Result<f64, Error>

Looks up the constant associated with the given node.

If the node is invalid for this tree, returns an error; if the node is not a constant, returns Ok(None).

pub fn get_var(&self, n: Node) -> Result<Var, Error>

Looks up the Var associated with the given node.

If the node is invalid for this tree or not an Op::Input, returns an error.

pub fn x(&mut self) -> Node

Constructs or finds a Var::X node

let mut ctx = Context::new();
let x = ctx.x();
let v = ctx.eval_xyz(x, 1.0, 0.0, 0.0).unwrap();
assert_eq!(v, 1.0);

pub fn y(&mut self) -> Node

Constructs or finds a Var::Y node

pub fn z(&mut self) -> Node

Constructs or finds a Var::Z node

pub fn var(&mut self, v: Var) -> Node

Constructs or finds a variable input node

To make an anonymous variable, call this function with Var::new():

let mut ctx = Context::new();
let v1 = ctx.var(Var::new());
let v2 = ctx.var(Var::new());
assert_ne!(v1, v2);

let mut vars = HashMap::new();
vars.insert(ctx.get_var(v1).unwrap(), 3.0);
assert_eq!(ctx.eval(v1, &vars).unwrap(), 3.0);
assert!(ctx.eval(v2, &vars).is_err()); // v2 isn't in the map

pub fn axes(&mut self) -> [Node; 3]

Returns a 3-element array of X, Y, Z nodes

pub fn constant(&mut self, f: f64) -> Node

Returns a node representing the given constant value.

let v = ctx.constant(3.0);
assert_eq!(ctx.eval_xyz(v, 0.0, 0.0, 0.0).unwrap(), 3.0);

pub fn add<A: IntoNode, B: IntoNode>( &mut self, a: A, b: B, ) -> Result<Node, Error>

Builds an addition node

let x = ctx.x();
let op = ctx.add(x, 1.0).unwrap();
let v = ctx.eval_xyz(op, 1.0, 0.0, 0.0).unwrap();
assert_eq!(v, 2.0);

pub fn mul<A: IntoNode, B: IntoNode>( &mut self, a: A, b: B, ) -> Result<Node, Error>

Builds an multiplication node

let x = ctx.x();
let op = ctx.mul(x, 5.0).unwrap();
let v = ctx.eval_xyz(op, 2.0, 0.0, 0.0).unwrap();
assert_eq!(v, 10.0);

pub fn min<A: IntoNode, B: IntoNode>( &mut self, a: A, b: B, ) -> Result<Node, Error>

Builds an min node

let x = ctx.x();
let op = ctx.min(x, 5.0).unwrap();
let v = ctx.eval_xyz(op, 2.0, 0.0, 0.0).unwrap();
assert_eq!(v, 2.0);

pub fn max<A: IntoNode, B: IntoNode>( &mut self, a: A, b: B, ) -> Result<Node, Error>

Builds an max node

let x = ctx.x();
let op = ctx.max(x, 5.0).unwrap();
let v = ctx.eval_xyz(op, 2.0, 0.0, 0.0).unwrap();
assert_eq!(v, 5.0);

pub fn and<A: IntoNode, B: IntoNode>( &mut self, a: A, b: B, ) -> Result<Node, Error>

Builds an and node

If both arguments are non-zero, returns the right-hand argument. Otherwise, returns zero.

This node can be simplified using a tracing evaluator:

• If the left-hand argument is zero, simplify to just that argument
• If the left-hand argument is non-zero, simplify to the other argument

let x = ctx.x();
let y = ctx.y();
let op = ctx.and(x, y).unwrap();
let v = ctx.eval_xyz(op, 1.0, 0.0, 0.0).unwrap();
assert_eq!(v, 0.0);
let v = ctx.eval_xyz(op, 1.0, 1.0, 0.0).unwrap();
assert_eq!(v, 1.0);
let v = ctx.eval_xyz(op, 1.0, 2.0, 0.0).unwrap();
assert_eq!(v, 2.0);

pub fn or<A: IntoNode, B: IntoNode>( &mut self, a: A, b: B, ) -> Result<Node, Error>

Builds an or node

If the left-hand argument is non-zero, it is returned. Otherwise, the right-hand argument is returned.

This node can be simplified using a tracing evaluator.

let x = ctx.x();
let y = ctx.y();
let op = ctx.or(x, y).unwrap();
let v = ctx.eval_xyz(op, 1.0, 0.0, 0.0).unwrap();
assert_eq!(v, 1.0);
let v = ctx.eval_xyz(op, 0.0, 0.0, 0.0).unwrap();
assert_eq!(v, 0.0);
let v = ctx.eval_xyz(op, 0.0, 3.0, 0.0).unwrap();
assert_eq!(v, 3.0);

pub fn not<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a logical negation node

The output is 1 if the argument is 0, and 0 otherwise.

pub fn neg<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a unary negation node

let x = ctx.x();
let op = ctx.neg(x).unwrap();
let v = ctx.eval_xyz(op, 2.0, 0.0, 0.0).unwrap();
assert_eq!(v, -2.0);

pub fn recip<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a reciprocal node

let x = ctx.x();
let op = ctx.recip(x).unwrap();
let v = ctx.eval_xyz(op, 2.0, 0.0, 0.0).unwrap();
assert_eq!(v, 0.5);

pub fn abs<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which calculates the absolute value of its input

let x = ctx.x();
let op = ctx.abs(x).unwrap();
let v = ctx.eval_xyz(op, 2.0, 0.0, 0.0).unwrap();
assert_eq!(v, 2.0);
let v = ctx.eval_xyz(op, -2.0, 0.0, 0.0).unwrap();
assert_eq!(v, 2.0);

pub fn sqrt<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which calculates the square root of its input

let x = ctx.x();
let op = ctx.sqrt(x).unwrap();
let v = ctx.eval_xyz(op, 4.0, 0.0, 0.0).unwrap();
assert_eq!(v, 2.0);

pub fn sin<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which calculates the sine of its input (in radians)

let x = ctx.x();
let op = ctx.sin(x).unwrap();
let v = ctx.eval_xyz(op, std::f64::consts::PI / 2.0, 0.0, 0.0).unwrap();
assert_eq!(v, 1.0);

pub fn cos<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which calculates the cosine of its input (in radians)

pub fn tan<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which calculates the tangent of its input (in radians)

pub fn asin<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which calculates the arcsine of its input (in radians)

pub fn acos<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which calculates the arccosine of its input (in radians)

pub fn atan<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which calculates the arctangent of its input (in radians)

pub fn exp<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which calculates the exponent of its input

pub fn ln<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which calculates the natural log of its input

pub fn square<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which squares its input

let x = ctx.x();
let op = ctx.square(x).unwrap();
let v = ctx.eval_xyz(op, 2.0, 0.0, 0.0).unwrap();
assert_eq!(v, 4.0);

pub fn floor<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which takes the floor of its input

let x = ctx.x();
let op = ctx.floor(x).unwrap();
let v = ctx.eval_xyz(op, 1.2, 0.0, 0.0).unwrap();
assert_eq!(v, 1.0);

pub fn ceil<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which takes the ceiling of its input

let x = ctx.x();
let op = ctx.ceil(x).unwrap();
let v = ctx.eval_xyz(op, 1.2, 0.0, 0.0).unwrap();
assert_eq!(v, 2.0);

pub fn round<A: IntoNode>(&mut self, a: A) -> Result<Node, Error>

Builds a node which rounds its input to the nearest integer

let x = ctx.x();
let op = ctx.round(x).unwrap();
let v = ctx.eval_xyz(op, 1.2, 0.0, 0.0).unwrap();
assert_eq!(v, 1.0);
let v = ctx.eval_xyz(op, 1.6, 0.0, 0.0).unwrap();
assert_eq!(v, 2.0);
let v = ctx.eval_xyz(op, 1.5, 0.0, 0.0).unwrap();
assert_eq!(v, 2.0); // rounds away from 0.0 if ambiguous

pub fn sub<A: IntoNode, B: IntoNode>( &mut self, a: A, b: B, ) -> Result<Node, Error>

Builds a node which performs subtraction.

let x = ctx.x();
let y = ctx.y();
let op = ctx.sub(x, y).unwrap();
let v = ctx.eval_xyz(op, 3.0, 2.0, 0.0).unwrap();
assert_eq!(v, 1.0);

pub fn div<A: IntoNode, B: IntoNode>( &mut self, a: A, b: B, ) -> Result<Node, Error>

Builds a node which performs division.

let x = ctx.x();
let y = ctx.y();
let op = ctx.div(x, y).unwrap();
let v = ctx.eval_xyz(op, 3.0, 2.0, 0.0).unwrap();
assert_eq!(v, 1.5);

pub fn atan2<A: IntoNode, B: IntoNode>( &mut self, y: A, x: B, ) -> Result<Node, Error>

Builds a node which computes atan2(y, x)

let x = ctx.x();
let y = ctx.y();
let op = ctx.atan2(y, x).unwrap();
let v = ctx.eval_xyz(op, 0.0, 1.0, 0.0).unwrap();
assert_eq!(v, std::f64::consts::FRAC_PI_2);

pub fn compare<A: IntoNode, B: IntoNode>( &mut self, a: A, b: B, ) -> Result<Node, Error>

Builds a node that compares two values

The result is -1 if a < b, +1 if a > b, 0 if a == b, and NaN if either side is NaN.

let x = ctx.x();
let op = ctx.compare(x, 1.0).unwrap();
let v = ctx.eval_xyz(op, 0.0, 0.0, 0.0).unwrap();
assert_eq!(v, -1.0);
let v = ctx.eval_xyz(op, 2.0, 0.0, 0.0).unwrap();
assert_eq!(v, 1.0);
let v = ctx.eval_xyz(op, 1.0, 0.0, 0.0).unwrap();
assert_eq!(v, 0.0);

pub fn less_than<A: IntoNode, B: IntoNode>( &mut self, lhs: A, rhs: B, ) -> Result<Node, Error>

Builds a node that is 1 if lhs < rhs and 0 otherwise

let x = ctx.x();
let y = ctx.y();
let op = ctx.less_than(x, y).unwrap();
let v = ctx.eval_xyz(op, 0.0, 1.0, 0.0).unwrap();
assert_eq!(v, 1.0);
let v = ctx.eval_xyz(op, 1.0, 1.0, 0.0).unwrap();
assert_eq!(v, 0.0);
let v = ctx.eval_xyz(op, 2.0, 1.0, 0.0).unwrap();
assert_eq!(v, 0.0);

pub fn less_than_or_equal<A: IntoNode, B: IntoNode>( &mut self, lhs: A, rhs: B, ) -> Result<Node, Error>

Builds a node that is 1 if lhs <= rhs and 0 otherwise

let x = ctx.x();
let y = ctx.y();
let op = ctx.less_than_or_equal(x, y).unwrap();
let v = ctx.eval_xyz(op, 0.0, 1.0, 0.0).unwrap();
assert_eq!(v, 1.0);
let v = ctx.eval_xyz(op, 1.0, 1.0, 0.0).unwrap();
assert_eq!(v, 1.0);
let v = ctx.eval_xyz(op, 2.0, 1.0, 0.0).unwrap();
assert_eq!(v, 0.0);

pub fn modulo<A: IntoNode, B: IntoNode>( &mut self, a: A, b: B, ) -> Result<Node, Error>

Builds a node that takes the modulo (least non-negative remainder)

pub fn if_nonzero_else<Condition: IntoNode, A: IntoNode, B: IntoNode>( &mut self, condition: Condition, a: A, b: B, ) -> Result<Node, Error>

Builds a node that returns the first node if the condition is not equal to zero, else returns the other node

The result is a if condition != 0, else the result is b.

let x = ctx.x();
let y = ctx.y();
let z = ctx.z();

let if_else = ctx.if_nonzero_else(x, y, z).unwrap();

assert_eq!(ctx.eval_xyz(if_else, 0.0, 2.0, 3.0).unwrap(), 3.0);
assert_eq!(ctx.eval_xyz(if_else, 1.0, 2.0, 3.0).unwrap(), 2.0);
assert_eq!(ctx.eval_xyz(if_else, 0.0, f64::NAN, 3.0).unwrap(), 3.0);
assert_eq!(ctx.eval_xyz(if_else, 1.0, 2.0, f64::NAN).unwrap(), 2.0);

pub fn eval_xyz(&self, root: Node, x: f64, y: f64, z: f64) -> Result<f64, Error>

Evaluates the given node with the provided values for X, Y, and Z.

This is extremely inefficient; consider converting the node into a Shape and using its evaluators instead.

let x = ctx.x();
let y = ctx.y();
let z = ctx.z();
let op = ctx.mul(x, y).unwrap();
let op = ctx.div(op, z).unwrap();
let v = ctx.eval_xyz(op, 3.0, 5.0, 2.0).unwrap();
assert_eq!(v, 7.5); // (3.0 * 5.0) / 2.0

pub fn eval(&self, root: Node, vars: &HashMap<Var, f64>) -> Result<f64, Error>

Evaluates the given node with a generic set of variables

This is extremely inefficient; consider converting the node into a Shape and using its evaluators instead.

pub fn from_text<R: Read>(r: R) -> Result<(Self, Node), Error>

Parses a flat text representation of a math tree. For example, the circle (- (+ (square x) (square y)) 1) can be parsed from

let txt = "
# This is a comment!
0x600000b90000 var-x
0x600000b900a0 square 0x600000b90000
0x600000b90050 var-y
0x600000b900f0 square 0x600000b90050
0x600000b90140 add 0x600000b900a0 0x600000b900f0
0x600000b90190 sqrt 0x600000b90140
0x600000b901e0 const 1
";
let (ctx, _node) = Context::from_text(&mut txt.as_bytes()).unwrap();
assert_eq!(ctx.len(), 7);

This representation is loosely defined and only intended for use in quick experiments.

pub fn dot(&self) -> String

Converts the entire context into a GraphViz drawing

pub fn get_op(&self, node: Node) -> Option<&Op>

Looks up an operation by Node handle

pub fn import(&mut self, tree: &Tree) -> Node

Imports the given tree, deduplicating and returning the root

pub fn export(&self, n: Node) -> Result<Tree, Error>

Converts from a context-specific node into a standalone Tree

pub fn deriv(&mut self, n: Node, v: Var) -> Result<Node, Error>

Takes the symbolic derivative of a node with respect to a variable

Trait Implementations

impl Debug for Context

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Context

fn default() -> Context

Returns the “default value” for a type.