conspire/math/tensor/
mod.rs

1pub mod test;
2
3pub mod rank_0;
4pub mod rank_1;
5pub mod rank_2;
6pub mod rank_3;
7pub mod rank_4;
8
9use super::{SquareMatrix, Vector};
10use crate::defeat_message;
11use rank_0::TensorRank0;
12use std::{
13    fmt::{self, Debug, Display, Formatter},
14    ops::{Add, AddAssign, Div, DivAssign, Index, IndexMut, Mul, MulAssign, Sub, SubAssign},
15};
16
17/// A scalar.
18pub type Scalar = TensorRank0;
19
20/// Possible errors for tensors.
21#[derive(PartialEq)]
22pub enum TensorError {
23    NotPositiveDefinite,
24}
25
26impl Debug for TensorError {
27    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
28        let error = match self {
29            Self::NotPositiveDefinite => "\x1b[1;91mResult is not positive definite.".to_string(),
30        };
31        write!(f, "\n{error}\n\x1b[0;2;31m{}\x1b[0m\n", defeat_message())
32    }
33}
34
35impl Display for TensorError {
36    fn fmt(&self, f: &mut Formatter<'_>) -> fmt::Result {
37        let error = match self {
38            Self::NotPositiveDefinite => "\x1b[1;91mResult is not positive definite.".to_string(),
39        };
40        write!(f, "{error}\x1b[0m")
41    }
42}
43
44/// Common methods for solutions.
45pub trait Solution
46where
47    Self: From<Vector> + Tensor,
48{
49    /// Decrements the solution from another vector.
50    fn decrement_from(&mut self, other: &Vector);
51    /// Decrements the solution chained with a vector from another vector.
52    fn decrement_from_chained(&mut self, other: &mut Vector, vector: Vector);
53    /// Decrements the solution from another vector on retained entries.
54    fn decrement_from_retained(&mut self, _retained: &[bool], _other: &Vector) {
55        unimplemented!()
56    }
57}
58
59/// Common methods for Jacobians.
60pub trait Jacobian
61where
62    Self:
63        From<Vector> + Tensor + Sub<Vector, Output = Self> + for<'a> Sub<&'a Vector, Output = Self>,
64{
65    /// Fills the Jacobian into a vector.
66    fn fill_into(self, vector: &mut Vector);
67    /// Fills the Jacobian chained with a vector into another vector.
68    fn fill_into_chained(self, other: Vector, vector: &mut Vector);
69    /// Return only the retained indices.
70    fn retain_from(self, _retained: &[bool]) -> Vector {
71        unimplemented!()
72    }
73    /// Zero out the specified indices.
74    fn zero_out(&mut self, _indices: &[usize]) {
75        unimplemented!()
76    }
77}
78
79/// Common methods for Hessians.
80pub trait Hessian
81where
82    Self: Tensor,
83{
84    /// Fills the Hessian into a square matrix.
85    fn fill_into(self, square_matrix: &mut SquareMatrix);
86    /// Return only the retained indices.
87    fn retain_from(self, _retained: &[bool]) -> SquareMatrix {
88        unimplemented!()
89    }
90}
91
92/// Common methods for rank-2 tensors.
93pub trait Rank2
94where
95    Self: Sized,
96{
97    /// The type that is the transpose of the tensor.
98    type Transpose;
99    /// Returns the deviatoric component of the rank-2 tensor.
100    fn deviatoric(&self) -> Self;
101    /// Returns the deviatoric component and trace of the rank-2 tensor.
102    fn deviatoric_and_trace(&self) -> (Self, TensorRank0);
103    /// Checks whether the tensor is a diagonal tensor.
104    fn is_diagonal(&self) -> bool;
105    /// Checks whether the tensor is the identity tensor.
106    fn is_identity(&self) -> bool;
107    /// Checks whether the tensor is a symmetric tensor.
108    fn is_symmetric(&self) -> bool;
109    /// Returns the second invariant of the rank-2 tensor.
110    fn second_invariant(&self) -> TensorRank0 {
111        0.5 * (self.trace().powi(2) - self.squared_trace())
112    }
113    /// Returns the trace of the rank-2 tensor squared.
114    fn squared_trace(&self) -> TensorRank0;
115    /// Returns the trace of the rank-2 tensor.
116    fn trace(&self) -> TensorRank0;
117    /// Returns the transpose of the rank-2 tensor.
118    fn transpose(&self) -> Self::Transpose;
119}
120
121/// Common methods for tensors.
122pub trait Tensor
123where
124    for<'a> Self: Sized
125        + Debug
126        + Default
127        + Display
128        + Add<Self, Output = Self>
129        + Add<&'a Self, Output = Self>
130        + AddAssign
131        + AddAssign<&'a Self>
132        + Clone
133        + Div<TensorRank0, Output = Self>
134        + DivAssign<TensorRank0>
135        + Mul<TensorRank0, Output = Self>
136        + MulAssign<TensorRank0>
137        + Sub<Self, Output = Self>
138        + Sub<&'a Self, Output = Self>
139        + SubAssign
140        + SubAssign<&'a Self>,
141    Self::Item: Tensor,
142{
143    /// The type of item encountered when iterating over the tensor.
144    type Item;
145    /// Returns number of different entries given absolute and relative tolerances.
146    fn error_count(&self, other: &Self, tol_abs: &Scalar, tol_rel: &Scalar) -> Option<usize> {
147        let error_count = self
148            .iter()
149            .zip(other.iter())
150            .filter_map(|(self_entry, other_entry)| {
151                self_entry.error_count(other_entry, tol_abs, tol_rel)
152            })
153            .sum();
154        if error_count > 0 {
155            Some(error_count)
156        } else {
157            None
158        }
159    }
160    /// Returns the full contraction with another tensor.
161    fn full_contraction(&self, tensor: &Self) -> TensorRank0 {
162        self.iter()
163            .zip(tensor.iter())
164            .map(|(self_entry, tensor_entry)| self_entry.full_contraction(tensor_entry))
165            .sum()
166    }
167    /// Checks whether the tensor is the zero tensor.
168    fn is_zero(&self) -> bool {
169        self.iter().filter(|entry| !entry.is_zero()).count() == 0
170    }
171    /// Returns an iterator.
172    ///
173    /// The iterator yields all items from start to end. [Read more](https://doc.rust-lang.org/std/iter/)
174    fn iter(&self) -> impl Iterator<Item = &Self::Item>;
175    /// Returns an iterator that allows modifying each value.
176    ///
177    /// The iterator yields all items from start to end. [Read more](https://doc.rust-lang.org/std/iter/)
178    fn iter_mut(&mut self) -> impl Iterator<Item = &mut Self::Item>;
179    /// Returns the tensor norm.
180    fn norm(&self) -> TensorRank0 {
181        self.norm_squared().sqrt()
182    }
183    /// Returns the infinity norm.
184    fn norm_inf(&self) -> TensorRank0 {
185        unimplemented!()
186    }
187    /// Returns the tensor norm squared.
188    fn norm_squared(&self) -> TensorRank0 {
189        self.full_contraction(self)
190    }
191    /// Normalizes the tensor.
192    fn normalize(&mut self) {
193        *self /= self.norm()
194    }
195    /// Returns the tensor normalized.
196    fn normalized(self) -> Self {
197        let norm = self.norm();
198        self / norm
199    }
200    /// Returns the total number of entries.
201    fn num_entries(&self) -> usize {
202        unimplemented!()
203    }
204    /// Returns the positive difference of the two tensors.
205    fn sub_abs(&self, other: &Self) -> Self {
206        let mut difference = self.clone();
207        difference
208            .iter_mut()
209            .zip(self.iter().zip(other.iter()))
210            .for_each(|(entry, (self_entry, other_entry))| {
211                *entry = self_entry.sub_abs(other_entry)
212            });
213        difference
214    }
215    /// Returns the relative difference of the two tensors.
216    fn sub_rel(&self, other: &Self) -> Self {
217        let mut difference = self.clone();
218        difference
219            .iter_mut()
220            .zip(self.iter().zip(other.iter()))
221            .for_each(|(entry, (self_entry, other_entry))| {
222                *entry = self_entry.sub_rel(other_entry)
223            });
224        difference
225    }
226}
227
228/// Common methods for tensors derived from arrays.
229pub trait TensorArray {
230    /// The type of array corresponding to the tensor.
231    type Array;
232    /// The type of item encountered when iterating over the tensor.
233    type Item;
234    /// Returns the tensor as an array.
235    fn as_array(&self) -> Self::Array;
236    /// Returns the identity tensor.
237    fn identity() -> Self;
238    /// Returns a tensor given an array.
239    fn new(array: Self::Array) -> Self;
240    /// Returns the zero tensor.
241    fn zero() -> Self;
242}
243
244/// Common methods for tensors derived from Vec.
245pub trait TensorVec
246where
247    Self: FromIterator<Self::Item> + Index<usize, Output = Self::Item> + IndexMut<usize>,
248{
249    /// The type of element encountered when iterating over the tensor.
250    type Item;
251    /// The type of slice corresponding to the tensor.
252    type Slice<'a>;
253    /// Moves all the elements of other into self, leaving other empty.
254    fn append(&mut self, other: &mut Self);
255    /// Returns the total number of elements the vector can hold without reallocating.
256    fn capacity(&self) -> usize;
257    /// Returns `true` if the vector contains no elements.
258    fn is_empty(&self) -> bool;
259    /// Returns the number of elements in the vector, also referred to as its ‘length’.
260    fn len(&self) -> usize;
261    /// Returns a tensor given a slice.
262    fn new(slice: Self::Slice<'_>) -> Self;
263    /// Appends an element to the back of the Vec.
264    fn push(&mut self, item: Self::Item);
265    /// Removes an element from the Vec and returns it, shifting elements to the left.
266    fn remove(&mut self, _index: usize) -> Self::Item;
267    /// Retains only the elements specified by the predicate.
268    fn retain<F>(&mut self, f: F)
269    where
270        F: FnMut(&Self::Item) -> bool;
271    /// Removes an element from the Vec and returns it, replacing it with the last element.
272    fn swap_remove(&mut self, _index: usize) -> Self::Item;
273    /// Returns the zero tensor.
274    fn zero(len: usize) -> Self;
275}
conspire/math/tensor/mod.rs

conspire/math/tensor/
mod.rs
