Enum Expression 

pub enum Expression {
    Address(MemoryReference),
    FunctionCall(FunctionCallExpression),
    Infix(InfixExpression),
    Number(Complex64),
    PiConstant(),
    Prefix(PrefixExpression),
    Variable(String),
}

The type of Quil expressions.

Quil expressions take advantage of structural sharing; if a Quil expression contains the same subexpression twice, such as x + y in (x + y) * (x + y), the two children of the * node will be the same pointer. This is implemented through interning, also known as hash-consing; the recursive references to child nodes are done via ArcIntern<Expression>s. Creating an ArcIntern from an Expression will always return the same pointer for the same expression.

The structural sharing means that equality, cloning, and hashing on Quil expressions are all very cheap, as they do not need to be recursive: equality of ArcInterns is a single-pointer comparison, cloning of ArcInterns is a pointer copy and an atomic increment, and hashing of ArcInterns hashes a single pointer. It is also very cheap to key HashMaps by an ArcIntern<Expression>, which can allow for cheap memoization of operations on Expressions.

The structural sharing also means that Quil expressions are fundamentally immutable; it is impossible to get an owned or &mut reference to the child Expressions of any Expression, as the use of interning means there may be multiple references to that Expression at any time.

Note that when comparing Quil expressions, any embedded NaNs are treated as equal to other NaNs, not unequal, in contravention of the IEEE 754 spec.

Variants

Address(MemoryReference)

FunctionCall(FunctionCallExpression)

Infix(InfixExpression)

Number(Complex64)

PiConstant()

Prefix(PrefixExpression)

Variable(String)

Implementations

impl Expression

pub fn simplify(&mut self)

Simplify the expression as much as possible, in-place.

Example

use quil_rs::expression::Expression;
use std::str::FromStr;
use num_complex::Complex64;

let mut expression = Expression::from_str("cos(2 * pi) + 2").unwrap();
expression.simplify();

assert_eq!(expression, Expression::Number(Complex64::from(3.0)));

pub fn into_simplified(self) -> Self

Consume the expression, simplifying it as much as possible.

Example

use quil_rs::expression::Expression;
use std::str::FromStr;
use num_complex::Complex64;

let simplified = Expression::from_str("cos(2 * pi) + 2").unwrap().into_simplified();

assert_eq!(simplified, Expression::Number(Complex64::from(3.0)));

pub fn evaluate<K1, K2>( &self, variables: &HashMap<K1, Complex64>, memory_references: &HashMap<K2, Vec<f64>>, ) -> Result<Complex64, EvaluationError>

where K1: Borrow<str> + Hash + Eq, K2: Borrow<str> + Hash + Eq,

Evaluate an expression, expecting that it may be fully reduced to a single complex number. If it cannot be reduced to a complex number, return an error.

Example

use quil_rs::expression::Expression;
use std::str::FromStr;
use std::collections::HashMap;
use num_complex::Complex64;

let expression = Expression::from_str("%beta + theta[0]").unwrap();

let mut variables = HashMap::with_capacity(1);
variables.insert(String::from("beta"), Complex64::from(1.0));

let mut memory_references = HashMap::with_capacity(1);
memory_references.insert("theta", vec![2.0]);

let evaluated = expression.evaluate(&variables, &memory_references).unwrap();

assert_eq!(evaluated, Complex64::from(3.0))

pub fn substitute_variables<K>( &self, variable_values: &HashMap<K, Expression>, ) -> Self

where K: Borrow<str> + Hash + Eq,

Substitute an expression in the place of each matching variable.

Example

use quil_rs::expression::Expression;
use std::str::FromStr;
use std::collections::HashMap;
use num_complex::Complex64;

let expression = Expression::from_str("%x + %y").unwrap();

let mut variables = HashMap::with_capacity(1);
variables.insert(String::from("x"), Expression::Number(Complex64::from(1.0)));

let evaluated = expression.substitute_variables(&variables);

assert_eq!(evaluated, Expression::from_str("1.0 + %y").unwrap())

impl Expression

pub fn to_real(&self) -> Result<f64, EvaluationError>

If this is a number with imaginary part “equal to” zero (of small absolute value), return that number. Otherwise, error with an evaluation error of a descriptive type.

impl Expression

pub fn get_memory_references(&self) -> Vec<&MemoryReference>

Return, if any, the memory references contained within this Expression.

Trait Implementations

impl Add<ArcIntern<Expression>> for Expression

type Output = Expression

The resulting type after applying the + operator.

fn add(self, other: ArcIntern<Expression>) -> Self

Performs the + operation.

impl Add<Expression> for ArcIntern<Expression>

type Output = Expression

The resulting type after applying the + operator.

fn add(self, other: Expression) -> Expression

Performs the + operation.

impl Add for Expression

type Output = Expression

The resulting type after applying the + operator.

fn add(self, other: Self) -> Self

Performs the + operation.

impl AddAssign<ArcIntern<Expression>> for Expression

fn add_assign(&mut self, other: ArcIntern<Expression>)

Performs the += operation.

impl AddAssign for Expression

fn add_assign(&mut self, other: Self)

Performs the += operation.

impl BitXor<ArcIntern<Expression>> for Expression

type Output = Expression

The resulting type after applying the ^ operator.

fn bitxor(self, other: ArcIntern<Expression>) -> Self

Performs the ^ operation.

impl BitXor<Expression> for ArcIntern<Expression>

type Output = Expression

The resulting type after applying the ^ operator.

fn bitxor(self, other: Expression) -> Expression

Performs the ^ operation.

impl BitXor for Expression

type Output = Expression

The resulting type after applying the ^ operator.

fn bitxor(self, other: Self) -> Self

Performs the ^ operation.

impl BitXorAssign<ArcIntern<Expression>> for Expression

fn bitxor_assign(&mut self, other: ArcIntern<Expression>)

Performs the ^= operation.

impl BitXorAssign for Expression

fn bitxor_assign(&mut self, other: Self)

Performs the ^= operation.

impl Clone for Expression

fn clone(&self) -> Expression

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Expression

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

Formats the value using the given formatter.

impl Div<ArcIntern<Expression>> for Expression

type Output = Expression

The resulting type after applying the / operator.

fn div(self, other: ArcIntern<Expression>) -> Self

Performs the / operation.

impl Div<Expression> for ArcIntern<Expression>

type Output = Expression

The resulting type after applying the / operator.

fn div(self, other: Expression) -> Expression

Performs the / operation.

impl Div for Expression

type Output = Expression

The resulting type after applying the / operator.

fn div(self, other: Self) -> Self

Performs the / operation.

impl DivAssign<ArcIntern<Expression>> for Expression

fn div_assign(&mut self, other: ArcIntern<Expression>)

Performs the /= operation.

impl DivAssign for Expression

fn div_assign(&mut self, other: Self)

Performs the /= operation.

impl FromStr for Expression

type Err = ParseProgramError<Expression>

The associated error which can be returned from parsing.

fn from_str(s: &str) -> Result<Self, Self::Err>

Parses a string s to return a value of this type.

impl Hash for Expression

fn hash<H: Hasher>(&self, state: &mut H)

Feeds this value into the given Hasher.

fn hash_slice<H>(data: &[Self], state: &mut H)

where H: Hasher, Self: Sized,

Feeds a slice of this type into the given Hasher.

impl Mul<ArcIntern<Expression>> for Expression

type Output = Expression

The resulting type after applying the * operator.

fn mul(self, other: ArcIntern<Expression>) -> Self

Performs the * operation.

impl Mul<Expression> for ArcIntern<Expression>

type Output = Expression

The resulting type after applying the * operator.

fn mul(self, other: Expression) -> Expression

Performs the * operation.

impl Mul for Expression

type Output = Expression

The resulting type after applying the * operator.

fn mul(self, other: Self) -> Self

Performs the * operation.

impl MulAssign<ArcIntern<Expression>> for Expression

fn mul_assign(&mut self, other: ArcIntern<Expression>)

Performs the *= operation.

impl MulAssign for Expression

fn mul_assign(&mut self, other: Self)

Performs the *= operation.

impl Neg for Expression

type Output = Expression

The resulting type after applying the - operator.

fn neg(self) -> Self

Performs the unary - operation.

impl PartialEq for Expression

fn eq(&self, other: &Self) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl Quil for Expression

fn write( &self, f: &mut impl Write, fall_back_to_debug: bool, ) -> Result<(), ToQuilError>

Write the Quil representation of the item to the given writer. If fall_back_to_debug is true, then it must not return an error.

fn to_quil(&self) -> Result<String, ToQuilError>

Return a string in valid Quil syntax or an error if the item cannot be represented with valid Quil.

fn to_quil_or_debug(&self) -> String

Return a string in valid Quil syntax if possible. Any individual component of this object which cannot be represented in Quil will be replaced with a Debug representation of that component.

impl Sub<ArcIntern<Expression>> for Expression

type Output = Expression

The resulting type after applying the - operator.

fn sub(self, other: ArcIntern<Expression>) -> Self

Performs the - operation.

impl Sub<Expression> for ArcIntern<Expression>

type Output = Expression

The resulting type after applying the - operator.

fn sub(self, other: Expression) -> Expression

Performs the - operation.

impl Sub for Expression

type Output = Expression

The resulting type after applying the - operator.

fn sub(self, other: Self) -> Self

Performs the - operation.

impl SubAssign<ArcIntern<Expression>> for Expression

fn sub_assign(&mut self, other: ArcIntern<Expression>)

Performs the -= operation.

impl SubAssign for Expression

fn sub_assign(&mut self, other: Self)

Performs the -= operation.

impl Eq for Expression