Struct free_algebra::module::ModuleString

pub struct ModuleString<R, T: Hash + Eq, A: ?Sized> { /* fields omitted */ }

Creates free-arithmetic constructions based upon order-invariant addition of terms of type C with multiplication with scalar coefficients of type R

Basic Construction

Given type parameters R, T, and A, the construction goes as follows:

• Internally, each instance contains a map from instances of T to coefficients from R
• Addition is then implemented by merging the arguments' HashMaps where repeated terms have their coefficients added together
• Multiplication with R values is applied by each term's coefficient with the given scalar
• Multiplication between terms is performed by multiplying the coefficients and apply the rule defined by type A
• Then, full multiplication is defined by distributing over each pair of terms and summing

With this system, using different A rules and T/R types, a number of variants can be defined:

• FreeModule<R,T> defines a vector-space over R using the default addition and R-multiplication without having a multiplication rule
• FreeAlgebra<R,T> is a FreeModule<R,T> but where the multiplication rule between terms is built as with a FreeMonoid<T>
• MonoidRing<R,T> is a FreeModule<R,T> but where the multiplication rule for terms simply uses the intrinsic multiplication of T

Other impls

In addition to the basic arithmetic operations, ModuleString implements a number of other notable traits depending on the type arguments:

• Sub, SubAssign, Neg, etc. These apply by negating each coefficient whenever R is negatable
• Index gets coefficient references from a term reference
• MulAssociative and MulCommutative whenever R is and A implements AssociativeMonoidRule or CommutativeMonoidRule
• Distributive whenever R is
• Extend, FromIterator, and Sum all are implemented using repeated addition.

A note on IterMut

The method [ModuleString.iter_mut()] will give an valid iterator over mutable references to each element of the object, but it is of note that because of the nature of some of the AlgebraRule's, the method will reallocate internal storage and iterate through every element, even if dropped.

The reason for this is that if it did not, it would be possible to modify a ModuleString into an invalid state. Hence, to mitigate this, the iterator must remultiply every element again as it iterates over the references.

Methods

impl<T: Hash + Eq, R, A: ?Sized> ModuleString<R, T, A>

pub fn len(&self) -> usize

Returns the number of terms in this module element

Examples

use maths_traits::algebra::Zero;
use free_algebra::FreeModule;

let p = FreeModule::zero();
let q = &p + (3.5, 'x');
let r = &q + (2.0, 'y');
let s = &r + (2.0, 'x'); //adds to first term without increasing length

assert_eq!(p.len(), 0);
assert_eq!(q.len(), 1);
assert_eq!(r.len(), 2);
assert_eq!(s.len(), 2);

pub fn get_ref<Q: Hash + Eq>(&self, t: &Q) -> Option<&R> where
    T: Borrow<Q>, 

Retrieves a reference to the coefficient of a term, if it is non-zero

Examples

use maths_traits::algebra::Zero;
use free_algebra::FreeModule;

let p = FreeModule::zero() + (3.5, 'x') + (2.0, 'y') + (1.0, 'z');

assert_eq!(p.get_ref(&'x'), Some(&3.5));
assert_eq!(p.get_ref(&'y'), Some(&2.0));
assert_eq!(p.get_ref(&'z'), Some(&1.0));
assert_eq!(p.get_ref(&'w'), None);

pub fn get<Q: Hash + Eq>(&self, t: &Q) -> R where
    T: Borrow<Q>,
    R: Zero + Clone, 

Clones a the coefficient of a term or returns zero if it doesn't exist

Examples

use maths_traits::algebra::Zero;
use free_algebra::FreeModule;

let p = FreeModule::zero() + (3.5, 'x') + (2.0, 'y') + (1.0, 'z');

assert_eq!(p.get(&'x'), 3.5);
assert_eq!(p.get(&'y'), 2.0);
assert_eq!(p.get(&'z'), 1.0);
assert_eq!(p.get(&'w'), 0.0);

pub fn iter<'a>(&'a self) -> Iter<'a, R, T>

Produces an iterator over references to the terms and references in this element

Important traits for IterMut<'a, R, T, A>

impl<'a, T: Hash + Eq, R: AddAssign, A: ?Sized> Iterator for IterMut<'a, R, T, A> type Item = (&'a mut R, &'a mut T);

pub fn iter_mut<'a>(&'a mut self) -> IterMut<'a, R, T, A> where
    R: AddAssign, 

Produces an iterator over mutable references to the terms and references in this element

Examples

use maths_traits::algebra::Zero;
use free_algebra::FreeModule;

let mut p = FreeModule::zero() + (3.5, 'x') + (2.0, 'y') + (1.0, 'z');
for (_, t) in p.iter_mut() {
    *t = 'a';
}

assert_eq!(p.get(&'x'), 0.0);
assert_eq!(p.get(&'y'), 0.0);
assert_eq!(p.get(&'z'), 0.0);
assert_eq!(p.get(&'a'), 6.5);

pub fn commutator(self, rhs: Self) -> Self where
    Self: MulMagma + Sub<Output = Self>, 

Computes the algebraic commutator [a,b] = a*b - b*a

Examples

use maths_traits::algebra::One;
use free_algebra::{FreeAlgebra, FreeMonoid};

let one = FreeMonoid::<char>::one();
let x:FreeMonoid<_> = 'x'.into();
let y:FreeMonoid<_> = 'y'.into();

let p:FreeAlgebra<f32,_> = FreeAlgebra::one() + &x;
let q:FreeAlgebra<f32,_> = FreeAlgebra::one() + &y;

let commutator = p.commutator(q);

assert_eq!(commutator.get(&one), 0.0);
assert_eq!(commutator.get(&x), 0.0);
assert_eq!(commutator.get(&y), 0.0);
assert_eq!(commutator.get(&(&x*&y)), 1.0);
assert_eq!(commutator.get(&(&y*&x)), -1.0);

A property of significance for this product is that when the arguments commute, the output is always 0.

use maths_traits::algebra::{One, Zero};
use free_algebra::{FreeAlgebra, FreeMonoid};

let p = FreeAlgebra::<f32,_>::one() + FreeMonoid::from('x');

let commutator = p.clone().commutator(p);
assert!(commutator.is_zero());

Trait Implementations

impl<T: Hash + Eq, R: One, A: ?Sized> From<T> for ModuleString<R, T, A>

fn from(t: T) -> Self

Performs the conversion.

impl<T: Hash + Eq, R: One, A: ?Sized> From<(R, T)> for ModuleString<R, T, A>

fn from((r, t): (R, T)) -> Self

Performs the conversion.

impl<T: Hash + Eq, R: AddAssign, A: ?Sized> Extend<(R, T)> for ModuleString<R, T, A>

fn extend<I: IntoIterator<Item = (R, T)>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

impl<T: Hash + Eq, R, A: ?Sized> IntoIterator for ModuleString<R, T, A>

type Item = (R, T)

The type of the elements being iterated over.

type IntoIter = IntoIter<R, T>

Which kind of iterator are we turning this into?

fn into_iter(self) -> IntoIter<R, T>

Creates an iterator from a value.

impl<R, T: Hash + Eq, A: ?Sized> Clone for ModuleString<R, T, A> where
    R: Clone,
    T: Clone, 

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.

impl<R, T: Hash + Eq, A: ?Sized> Default for ModuleString<R, T, A>

fn default() -> Self

Returns the "default value" for a type.

impl<R, T: Hash + Eq, A: ?Sized> Eq for ModuleString<R, T, A> where
    R: Eq,
    T: Eq, 

impl<R, T: Hash + Eq, A: ?Sized> PartialEq<ModuleString<R, T, A>> for ModuleString<R, T, A> where
    R: PartialEq,
    T: PartialEq, 

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

This method tests for self and other values to be equal, and is used by ==.

#[must_use] fn ne(&self, other: &Rhs) -> bool

This method tests for !=.

impl<R: Display, T: Hash + Eq + Display, A: ?Sized> Display for ModuleString<R, T, A>

Formats the ModuleString as a sequence of factors separated by +'s

Examples

use maths_traits::algebra::{One, Zero};
use free_algebra::{FreeAlgebra, FreeMonoid};

let one = FreeMonoid::one();
let x:FreeMonoid<_> = 'x'.into();
let y:FreeMonoid<_> = 'y'.into();

let mut p = FreeAlgebra::zero();
assert_eq!(format!("{}", p), "0");

p += (1.0, one.clone());
assert_eq!(format!("{}", p), "1");

p += (2.5, one);
assert_eq!(format!("{}", p), "3.5");

p += x;
assert!(format!("{}", p) == "(3.5 + x)" || format!("{}", p) == "(x + 3.5)");

p *= (1.0, y);
assert!(format!("{}", p) == "(3.5*y + x*y)" || format!("{}", p) == "(x*y + 3.5*y)");
assert!(format!("{:#}", p) == "(3.5y + xy)" || format!("{:#}", p) == "(xy + 3.5y)");

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

Formats the value using the given formatter.

impl<R, T: Hash + Eq, A: ?Sized> Debug for ModuleString<R, T, A> where
    R: Debug,
    T: Debug, 

fn fmt(&self, __f: &mut Formatter) -> Result

Formats the value using the given formatter.

impl<RHS, T, R, A> Div<RHS> for ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    Self: DivAssign<RHS>, 

type Output = Self

The resulting type after applying the / operator.

fn div(self, rhs: RHS) -> Self

Performs the / operation.

impl<'a, RHS, T, R, A> Div<RHS> for &'a ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    ModuleString<R, T, A>: Clone + Div<RHS>, 

type Output = <ModuleString<R, T, A> as Div<RHS>>::Output

The resulting type after applying the / operator.

fn div(self, rhs: RHS) -> Self::Output

Performs the / operation.

impl<RHS, T, R, A> Sub<RHS> for ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    Self: SubAssign<RHS>, 

type Output = Self

The resulting type after applying the - operator.

fn sub(self, rhs: RHS) -> Self

Performs the - operation.

impl<'a, RHS, T, R, A> Sub<RHS> for &'a ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    ModuleString<R, T, A>: Clone + Sub<RHS>, 

type Output = <ModuleString<R, T, A> as Sub<RHS>>::Output

The resulting type after applying the - operator.

fn sub(self, rhs: RHS) -> Self::Output

Performs the - operation.

impl<RHS, T, R, A> Add<RHS> for ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    Self: AddAssign<RHS>, 

type Output = Self

The resulting type after applying the + operator.

fn add(self, rhs: RHS) -> Self

Performs the + operation.

impl<'a, RHS, T, R, A> Add<RHS> for &'a ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    ModuleString<R, T, A>: Clone + Add<RHS>, 

type Output = <ModuleString<R, T, A> as Add<RHS>>::Output

The resulting type after applying the + operator.

fn add(self, rhs: RHS) -> Self::Output

Performs the + operation.

impl<RHS, T, R, A> Mul<RHS> for ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    Self: MulAssign<RHS>, 

type Output = Self

The resulting type after applying the * operator.

fn mul(self, rhs: RHS) -> Self

Performs the * operation.

impl<'a, RHS, T, R, A> Mul<RHS> for &'a ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    ModuleString<R, T, A>: Clone + Mul<RHS>, 

type Output = <ModuleString<R, T, A> as Mul<RHS>>::Output

The resulting type after applying the * operator.

fn mul(self, rhs: RHS) -> Self::Output

Performs the * operation.

impl<T: Hash + Eq, R: Neg, A: ?Sized> Neg for ModuleString<R, T, A>

type Output = ModuleString<R::Output, T, A>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<'a, T: Hash + Eq, R: Neg, A: ?Sized> Neg for &'a ModuleString<R, T, A> where
    ModuleString<R, T, A>: Clone, 

type Output = ModuleString<R::Output, T, A>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

impl<T: Hash + Eq, R: AddAssign, A: ?Sized> AddAssign<ModuleString<R, T, A>> for ModuleString<R, T, A>

fn add_assign(&mut self, rhs: Self)

Performs the += operation.

impl<T: Hash + Eq, R: AddAssign, A: ?Sized> AddAssign<(R, T)> for ModuleString<R, T, A>

fn add_assign(&mut self, rhs: (R, T))

Performs the += operation.

impl<T: Hash + Eq, R: AddAssign + One, A: ?Sized> AddAssign<T> for ModuleString<R, T, A>

fn add_assign(&mut self, rhs: T)

Performs the += operation.

impl<'a, T, R, A> AddAssign<&'a ModuleString<R, T, A>> for ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    Self: AddAssign<Self>,
    Self: Clone, 

fn add_assign(&mut self, rhs: &'a Self)

Performs the += operation.

impl<'a, T, R, A> AddAssign<&'a T> for ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    Self: AddAssign<T>,
    T: Clone, 

fn add_assign(&mut self, rhs: &'a T)

Performs the += operation.

impl<T: Hash + Eq, R: AddAssign + Neg<Output = R>, A: ?Sized> SubAssign<ModuleString<R, T, A>> for ModuleString<R, T, A>

fn sub_assign(&mut self, rhs: Self)

Performs the -= operation.

impl<T: Hash + Eq, R: AddAssign + Neg<Output = R>, A: ?Sized> SubAssign<(R, T)> for ModuleString<R, T, A>

fn sub_assign(&mut self, rhs: (R, T))

Performs the -= operation.

impl<T: Hash + Eq, R: AddAssign + Neg<Output = R> + One, A: ?Sized> SubAssign<T> for ModuleString<R, T, A>

fn sub_assign(&mut self, rhs: T)

Performs the -= operation.

impl<'a, T, R, A> SubAssign<&'a ModuleString<R, T, A>> for ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    Self: SubAssign<Self>,
    Self: Clone, 

fn sub_assign(&mut self, rhs: &'a Self)

Performs the -= operation.

impl<'a, T, R, A> SubAssign<&'a T> for ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    Self: SubAssign<T>,
    T: Clone, 

fn sub_assign(&mut self, rhs: &'a T)

Performs the -= operation.

impl<T: Hash + Eq, R: MulAssign + Clone, A: ?Sized> MulAssign<R> for ModuleString<R, T, A>

fn mul_assign(&mut self, rhs: R)

Performs the *= operation.

impl<'a, T, R, A> MulAssign<&'a R> for ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    Self: MulAssign<R>,
    R: Clone, 

fn mul_assign(&mut self, rhs: &'a R)

Performs the *= operation.

impl<T: Hash + Eq + Clone, R: MulMagma + AddMagma, A: ?Sized + AlgebraRule<R, T>> MulAssign<(R, T)> for ModuleString<R, T, A>

fn mul_assign(&mut self, (r1, t1): (R, T))

Performs the *= operation.

impl<T: Hash + Eq + Clone, R: Semiring, A: ?Sized + AlgebraRule<R, T>> MulAssign<ModuleString<R, T, A>> for ModuleString<R, T, A>

fn mul_assign(&mut self, rhs: Self)

Performs the *= operation.

impl<T: Hash + Eq, R: DivAssign + Clone, A: ?Sized> DivAssign<R> for ModuleString<R, T, A>

fn div_assign(&mut self, rhs: R)

Performs the /= operation.

impl<'a, T, R, A> DivAssign<&'a R> for ModuleString<R, T, A> where
    T: Hash + Eq,
    A: ?Sized,
    Self: DivAssign<R>,
    R: Clone, 

fn div_assign(&mut self, rhs: &'a R)

Performs the /= operation.

impl<T: Hash + Eq, R, A: ?Sized, I> Index<I> for ModuleString<R, T, A> where
    HashMap<T, R>: Index<I>, 

type Output = <HashMap<T, R> as Index<I>>::Output

The returned type after indexing.

fn index(&self, i: I) -> &Self::Output

Performs the indexing (container[index]) operation.

impl<R, T: Hash + Eq, A: ?Sized> Hash for ModuleString<R, T, A> where
    HashMap<T, R>: Hash, 

fn hash<__HRTA>(&self, __state: &mut __HRTA) where
    __HRTA: Hasher, 

Feeds this value into the given [Hasher].

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

Feeds a slice of this type into the given [Hasher].

impl<T: Hash + Eq, R: AddAssign, A: ?Sized> FromIterator<(R, T)> for ModuleString<R, T, A>

fn from_iter<I: IntoIterator<Item = (R, T)>>(iter: I) -> Self

Creates a value from an iterator.

impl<T: Hash + Eq, R: AddAssign + One, A: ?Sized> FromIterator<T> for ModuleString<R, T, A>

fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self

Creates a value from an iterator.

impl<T: Hash + Eq, R: AddAssign, A: ?Sized> FromIterator<ModuleString<R, T, A>> for ModuleString<R, T, A>

fn from_iter<I: IntoIterator<Item = Self>>(iter: I) -> Self

Creates a value from an iterator.

impl<T: Hash + Eq, R: AddAssign, A: ?Sized, K> Sum<K> for ModuleString<R, T, A> where
    Self: FromIterator<K>, 

fn sum<I: Iterator<Item = K>>(iter: I) -> Self

Method which takes an iterator and generates Self from the elements by "summing up" the items.

impl<T: Hash + Eq, R, A: ?Sized, K> Product<K> for ModuleString<R, T, A> where
    Self: Mul<K, Output = Self> + One, 

fn product<I: Iterator<Item = K>>(iter: I) -> Self

Method which takes an iterator and generates Self from the elements by multiplying the items.

impl<T: Hash + Eq, R: AddAssign, A: ?Sized> Zero for ModuleString<R, T, A>

fn zero() -> Self

Returns the additive identity element of Self, 0. # Purity

fn is_zero(&self) -> bool

Returns true if self is equal to the additive identity.

fn set_zero(&mut self)

Sets self to the additive identity element of Self, 0.

impl<T: Clone + Hash + Eq, R: PartialEq + UnitalSemiring, A: UnitalAlgebraRule<R, T> + ?Sized> One for ModuleString<R, T, A>

fn one() -> Self

Returns the multiplicative identity element of Self, 1.

fn is_one(&self) -> bool

Returns true if self is equal to the multiplicative identity.

fn set_one(&mut self)

Sets self to the multiplicative identity element of Self, 1.

impl<Z, R, T, A: ?Sized> Pow<Z> for ModuleString<R, T, A> where
    Z: Natural,
    T: Hash + Eq + Clone,
    R: PartialEq + UnitalSemiring,
    A: UnitalAlgebraRule<R, T> + AssociativeAlgebraRule<R, T>, 

type Output = Self

The result after applying the operator.

fn pow(self, p: Z) -> Self

Returns self to the power rhs.

impl<T: Hash + Eq, R: AddAssociative, A: ?Sized> AddAssociative for ModuleString<R, T, A>

impl<T: Hash + Eq, R: AddCommutative, A: ?Sized> AddCommutative for ModuleString<R, T, A>

impl<T: Hash + Eq, R: MulAssociative, A: ?Sized + AssociativeAlgebraRule<R, T>> MulAssociative for ModuleString<R, T, A>

impl<T: Hash + Eq, R: MulCommutative, A: ?Sized + CommutativeAlgebraRule<R, T>> MulCommutative for ModuleString<R, T, A>

impl<T: Hash + Eq, R: Distributive, A: ?Sized> Distributive<ModuleString<R, T, A>> for ModuleString<R, T, A>