argmin-math 0.5.1

argmin math abstractions
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154

use crate::ArgminDot;
use faer::{mat::AsMatRef, Mat, MatRef};
use faer_traits::ComplexField;
use std::ops::Mul;

//@note(geo): the order is important here.
// the way it is implemented with nalgebra suggests that this calculates
// self.conjugate() * other
// which is in contrast to the documentation of the trait itself,
// where it says "dot product of T and Self"

/// ArgminDot implementation for matrix multiplication: Matrix . Matrix -> Matrix
/// In these cases, ArgminDot means the matrix-matrix product
mod matrix_matrix_multiplication {
    use super::*;

    /// MatRef . MatRef -> Mat
    impl<'a, E: ComplexField> ArgminDot<MatRef<'a, E>, Mat<E>> for MatRef<'_, E> {
        #[inline]
        fn dot(&self, other: &MatRef<'a, E>) -> Mat<E> {
            self * other
        }
    }

    /// MatRef . Mat -> Mat
    impl<E: ComplexField> ArgminDot<Mat<E>, Mat<E>> for MatRef<'_, E> {
        #[inline]
        fn dot(&self, other: &Mat<E>) -> Mat<E> {
            <_ as ArgminDot<_, _>>::dot(self, &other.as_mat_ref())
        }
    }

    /// Mat . MatRef -> Mat
    impl<'a, E: ComplexField> ArgminDot<MatRef<'a, E>, Mat<E>> for Mat<E> {
        #[inline]
        fn dot(&self, other: &MatRef<'a, E>) -> Mat<E> {
            <_ as ArgminDot<_, _>>::dot(&self.as_mat_ref(), other)
        }
    }

    /// Mat . Mat -> Mat
    impl<E: ComplexField> ArgminDot<Mat<E>, Mat<E>> for Mat<E> {
        #[inline]
        fn dot(&self, other: &Mat<E>) -> Mat<E> {
            <_ as ArgminDot<_, _>>::dot(&self.as_mat_ref(), &other.as_mat_ref())
        }
    }
}

/// contains implementations for the scalar product of two column vectors of
/// the same length. This is v^H . u for two column vectors v,u.
//@note(geo-ant) the corresponding nalgebra implementations allow taking a scalar
// product of any two matrices of same shape ("as vectors"). I've opted to not
// reproduce this behavior here, since it's likely invoked in error.
mod scalar_product {
    use faer_traits::Conjugate;

    use super::*;
    /// MatRef . MatRef -> Mat
    impl<'a, E: ComplexField + Conjugate<Conj = E>> ArgminDot<MatRef<'a, E>, E> for MatRef<'_, E> {
        #[inline]
        fn dot(&self, other: &MatRef<'a, E>) -> E {
            //@note(geo): we allow the scalar dot product between two vectors
            // of same length (but possibly different shape).
            assert!(
                (self.nrows() == 1 || self.ncols() == 1)
                    && (other.nrows() == 1 || other.ncols() == 1),
                "arguments for dot product must be vectors"
            );
            let count = std::cmp::max(self.nrows(), self.ncols());
            let count_rhs = std::cmp::max(other.nrows(), other.ncols());
            assert_eq!(
                count, count_rhs,
                "vectors for dot product must have same number of elements"
            );

            let value: Mat<E> = <_ as ArgminDot<_, _>>::dot(
                &self.as_shape(count, 1).conjugate().transpose(),
                &other.as_shape(count, 1),
            );
            debug_assert_eq!(value.nrows(), 1);
            debug_assert_eq!(value.ncols(), 1);
            value[(0, 0)].clone()
        }
    }

    /// MatRef . Mat -> Mat
    impl<E: ComplexField + Conjugate<Conj = E>> ArgminDot<Mat<E>, E> for MatRef<'_, E> {
        #[inline]
        fn dot(&self, other: &Mat<E>) -> E {
            <_ as ArgminDot<_, _>>::dot(self, &other.as_mat_ref())
        }
    }

    /// Mat . MatRef -> Mat
    impl<'a, E: ComplexField + Conjugate<Conj = E>> ArgminDot<MatRef<'a, E>, E> for Mat<E> {
        #[inline]
        fn dot(&self, other: &MatRef<'a, E>) -> E {
            <_ as ArgminDot<_, _>>::dot(&self.as_mat_ref(), other)
        }
    }

    /// Mat . Mat -> Mat
    impl<E: ComplexField + Conjugate<Conj = E>> ArgminDot<Mat<E>, E> for Mat<E> {
        #[inline]
        fn dot(&self, other: &Mat<E>) -> E {
            <_ as ArgminDot<_, _>>::dot(&self.as_mat_ref(), &other.as_mat_ref())
        }
    }
}

//@note(geo) implemented for compatibility with the nalgebra implementations,
// but this should probably not have to exist, since the functionality is
// already covered with ArgminMul
// Scalar . Matrix -> Matrix
// and Matrix . Scalar -> Matrix
mod multiply_matrix_with_scalar {
    use super::*;
    use crate::ArgminMul;
    use faer_traits::ComplexField;
    use std::ops::Mul;

    // MatRef . Scalar -> Mat
    impl<E: ComplexField> ArgminDot<E, Mat<E>> for MatRef<'_, E> {
        #[inline]
        fn dot(&self, other: &E) -> Mat<E> {
            <Self as ArgminMul<E, _>>::mul(self, other)
        }
    }

    // Mat . Scalar -> Mat
    impl<E: ComplexField> ArgminDot<E, Mat<E>> for Mat<E> {
        #[inline]
        fn dot(&self, other: &E) -> Mat<E> {
            <_ as ArgminDot<E, _>>::dot(&self.as_mat_ref(), other)
        }
    }

    // MatRef . Scalar -> Mat
    impl<'a, E: ComplexField> ArgminDot<MatRef<'a, E>, Mat<E>> for E {
        #[inline]
        fn dot(&self, other: &MatRef<'a, E>) -> Mat<E> {
            <E as ArgminMul<MatRef<'a, E>, _>>::mul(self, other)
        }
    }

    // Mat . Scalar -> Mat
    impl<E: ComplexField> ArgminDot<Mat<E>, Mat<E>> for E {
        #[inline]
        fn dot(&self, other: &Mat<E>) -> Mat<E> {
            <E as ArgminDot<_, _>>::dot(self, &other.as_mat_ref())
        }
    }
}