Struct ModuleString

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

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.

Implementations

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

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<'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> Add<RHS> for ModuleString<R, T, A>

where T: Hash + Eq, A: ?Sized, Self: AddAssign<RHS>,

type Output = ModuleString<R, T, A>

The resulting type after applying the + operator.

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

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> + 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 + Clone, A: ?Sized, Self: AddAssign<T>,

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

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<T: Hash + Eq, R: AddAssign, A: ?Sized> AddAssign for ModuleString<R, T, A>

fn add_assign(&mut self, rhs: Self)

Performs the += operation.

impl<R, T, A: ?Sized> Clone for ModuleString<R, T, A>

where R: Clone, T: Clone + Hash + Eq,

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, A: ?Sized> Debug for ModuleString<R, T, A>

where R: Debug, T: Debug + Hash + Eq,

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

Formats the value using the given formatter.

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: 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<'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> Div<RHS> for ModuleString<R, T, A>

where T: Hash + Eq, A: ?Sized, Self: DivAssign<RHS>,

type Output = ModuleString<R, T, A>

The resulting type after applying the / operator.

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

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: DivAssign + Clone, A: ?Sized> DivAssign<R> for ModuleString<R, T, A>

fn div_assign(&mut self, rhs: R)

Performs the /= operation.

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.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

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

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

Converts to this type from the input type.

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

fn from(t: T) -> Self

Converts to this type from the input type.

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, 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 + 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<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, Self: Sized,

Feeds a slice of this type into the given Hasher.

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<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 = Map<IntoIter<T, R>, fn((T, R)) -> (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<'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<RHS, T, R, A> Mul<RHS> for ModuleString<R, T, A>

where T: Hash + Eq, A: ?Sized, Self: MulAssign<RHS>,

type Output = ModuleString<R, T, A>

The resulting type after applying the * operator.

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

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, R: MulAssign + Clone, A: ?Sized> MulAssign<R> for ModuleString<R, T, A>

fn mul_assign(&mut self, rhs: R)

Performs the *= operation.

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

fn mul_assign(&mut self, rhs: Self)

Performs the *= 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 as Neg>::Output, T, A>

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

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

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

The resulting type after applying the - operator.

fn neg(self) -> Self::Output

Performs the unary - operation.

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<R, T, A: ?Sized> PartialEq for ModuleString<R, T, A>

where R: PartialEq, T: PartialEq + Hash + Eq,

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<Z, R, T, A> Pow<Z> for ModuleString<R, T, A>

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

type Output = ModuleString<R, T, A>

The result after applying the operator.

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

Returns self to the power rhs.

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

Takes an iterator and generates Self from the elements by multiplying the items.

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> Sub<RHS> for ModuleString<R, T, A>

where T: Hash + Eq, A: ?Sized, Self: SubAssign<RHS>,

type Output = ModuleString<R, T, A>

The resulting type after applying the - operator.

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

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> + 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 + Clone, A: ?Sized, Self: SubAssign<T>,

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

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<T: Hash + Eq, R: AddAssign + Neg<Output = R>, A: ?Sized> SubAssign for ModuleString<R, T, A>

fn sub_assign(&mut self, rhs: Self)

Performs the -= operation.

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

Takes an iterator and generates Self from the elements by “summing up” 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.

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: 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: Distributive, A: ?Sized> Distributive for ModuleString<R, T, A>

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

where R: Eq, T: Eq + Hash + Eq,

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>