concision_core/params/
params.rs

1/*
2    Appellation: params <module>
3    Contrib: @FL03
4*/
5use ndarray::prelude::*;
6use ndarray::{Data, DataMut, DataOwned, Dimension, RawData, RemoveAxis, ShapeBuilder};
7
8/// The [`ParamsBase`] struct is a generic container for a set of weights and biases for a
9/// model. The implementation is designed around the [`ArrayBase`] type from the
10/// `ndarray` crate, which allows for flexible and efficient storage of multi-dimensional
11/// arrays.
12pub struct ParamsBase<S, D = ndarray::Ix2>
13where
14    D: Dimension,
15    S: RawData,
16{
17    pub(crate) bias: ArrayBase<S, D::Smaller>,
18    pub(crate) weights: ArrayBase<S, D>,
19}
20
21impl<A, S, D> ParamsBase<S, D>
22where
23    D: Dimension,
24    S: RawData<Elem = A>,
25{
26    /// create a new instance of the [`ParamsBase`] with the given bias and weights
27    pub const fn new(bias: ArrayBase<S, D::Smaller>, weights: ArrayBase<S, D>) -> Self {
28        Self { bias, weights }
29    }
30    /// create a new instance of the [`ModelParams`] from the given shape and element;
31    pub fn from_elems<Sh>(shape: Sh, elem: A) -> Self
32    where
33        A: Clone,
34        D: RemoveAxis,
35        S: DataOwned,
36        Sh: ShapeBuilder<Dim = D>,
37    {
38        let weights = ArrayBase::from_elem(shape, elem.clone());
39        let dim = weights.raw_dim();
40        let bias = ArrayBase::from_elem(dim.remove_axis(Axis(0)), elem);
41        Self::new(bias, weights)
42    }
43    /// create an instance of the parameters with all values set to the default value
44    pub fn default<Sh>(shape: Sh) -> Self
45    where
46        A: Clone + Default,
47        D: RemoveAxis,
48        S: DataOwned,
49        Sh: ShapeBuilder<Dim = D>,
50    {
51        Self::from_elems(shape, A::default())
52    }
53    /// initialize the parameters with all values set to zero
54    pub fn ones<Sh>(shape: Sh) -> Self
55    where
56        A: Clone + num_traits::One,
57        D: RemoveAxis,
58        S: DataOwned,
59        Sh: ShapeBuilder<Dim = D>,
60    {
61        Self::from_elems(shape, A::one())
62    }
63    /// create an instance of the parameters with all values set to zero
64    pub fn zeros<Sh>(shape: Sh) -> Self
65    where
66        A: Clone + num_traits::Zero,
67        D: RemoveAxis,
68        S: DataOwned,
69        Sh: ShapeBuilder<Dim = D>,
70    {
71        Self::from_elems(shape, A::zero())
72    }
73    /// returns an immutable reference to the bias
74    pub const fn bias(&self) -> &ArrayBase<S, D::Smaller> {
75        &self.bias
76    }
77    /// returns a mutable reference to the bias
78    pub const fn bias_mut(&mut self) -> &mut ArrayBase<S, D::Smaller> {
79        &mut self.bias
80    }
81    /// returns an immutable reference to the weights
82    pub const fn weights(&self) -> &ArrayBase<S, D> {
83        &self.weights
84    }
85    /// returns a mutable reference to the weights
86    pub const fn weights_mut(&mut self) -> &mut ArrayBase<S, D> {
87        &mut self.weights
88    }
89    /// assign the bias
90    pub fn assign_bias(&mut self, bias: &ArrayBase<S, D::Smaller>) -> &mut Self
91    where
92        A: Clone,
93        S: DataMut,
94    {
95        self.bias_mut().assign(bias);
96        self
97    }
98    /// assign the weights
99    pub fn assign_weights(&mut self, weights: &ArrayBase<S, D>) -> &mut Self
100    where
101        A: Clone,
102        S: DataMut,
103    {
104        self.weights_mut().assign(weights);
105        self
106    }
107    /// replace the bias and return the previous state; uses [replace](core::mem::replace)
108    pub fn replace_bias(&mut self, bias: ArrayBase<S, D::Smaller>) -> ArrayBase<S, D::Smaller> {
109        core::mem::replace(&mut self.bias, bias)
110    }
111    /// replace the weights and return the previous state; uses [replace](core::mem::replace)
112    pub fn replace_weights(&mut self, weights: ArrayBase<S, D>) -> ArrayBase<S, D> {
113        core::mem::replace(&mut self.weights, weights)
114    }
115    /// set the bias
116    pub fn set_bias(&mut self, bias: ArrayBase<S, D::Smaller>) -> &mut Self {
117        *self.bias_mut() = bias;
118        self
119    }
120    /// set the weights
121    pub fn set_weights(&mut self, weights: ArrayBase<S, D>) -> &mut Self {
122        *self.weights_mut() = weights;
123        self
124    }
125    /// perform a single backpropagation step
126    pub fn backward<X, Y, Z>(&mut self, input: &X, grad: &Y, lr: A) -> crate::Result<Z>
127    where
128        A: Clone,
129        S: Data,
130        Self: crate::Backward<X, Y, Elem = A, Output = Z>,
131    {
132        <Self as crate::Backward<X, Y>>::backward(self, input, grad, lr)
133    }
134    /// forward propagation
135    pub fn forward<X, Y>(&self, input: &X) -> crate::Result<Y>
136    where
137        A: Clone,
138        S: Data,
139        Self: crate::Forward<X, Output = Y>,
140    {
141        <Self as crate::Forward<X>>::forward(self, input)
142    }
143    /// returns the dimensions of the weights
144    pub fn dim(&self) -> D::Pattern {
145        self.weights().dim()
146    }
147    /// an iterator of the parameters; the created iterator zips together an axis iterator over
148    /// the columns of the weights and an iterator over the bias
149    pub fn iter(&self) -> super::iter::Iter<'_, A, D>
150    where
151        D: RemoveAxis,
152        S: Data,
153    {
154        super::iter::Iter {
155            bias: self.bias().iter(),
156            weights: self.weights().axis_iter(Axis(1)),
157        }
158    }
159    /// a mutable iterator of the parameters
160    pub fn iter_mut(
161        &mut self,
162    ) -> core::iter::Zip<
163        ndarray::iter::AxisIterMut<'_, A, D::Smaller>,
164        ndarray::iter::IterMut<'_, A, D::Smaller>,
165    >
166    where
167        D: RemoveAxis,
168        S: DataMut,
169    {
170        self.weights
171            .axis_iter_mut(Axis(1))
172            .zip(self.bias.iter_mut())
173    }
174    /// returns an iterator over the bias
175    pub fn iter_bias(&self) -> ndarray::iter::Iter<'_, A, D::Smaller>
176    where
177        S: Data,
178    {
179        self.bias().iter()
180    }
181    /// returns a mutable iterator over the bias
182    pub fn iter_bias_mut(&mut self) -> ndarray::iter::IterMut<'_, A, D::Smaller>
183    where
184        S: DataMut,
185    {
186        self.bias_mut().iter_mut()
187    }
188    /// returns an iterator over the weights
189    pub fn iter_weights(&self) -> ndarray::iter::Iter<'_, A, D>
190    where
191        S: Data,
192    {
193        self.weights().iter()
194    }
195    /// returns a mutable iterator over the weights; see [`iter_mut`](ArrayBase::iter_mut) for more
196    pub fn iter_weights_mut(&mut self) -> ndarray::iter::IterMut<'_, A, D>
197    where
198        S: DataMut,
199    {
200        self.weights_mut().iter_mut()
201    }
202    /// returns true if both the weights and bias are empty; uses [`is_empty`](ArrayBase::is_empty)
203    pub fn is_empty(&self) -> bool {
204        self.is_weights_empty() && self.is_bias_empty()
205    }
206    /// returns true if the weights are empty
207    pub fn is_weights_empty(&self) -> bool {
208        self.weights().is_empty()
209    }
210    /// returns true if the bias is empty
211    pub fn is_bias_empty(&self) -> bool {
212        self.bias().is_empty()
213    }
214    /// the total number of elements within the weight tensor
215    pub fn count_weight(&self) -> usize {
216        self.weights().len()
217    }
218    /// the total number of elements within the bias tensor
219    pub fn count_bias(&self) -> usize {
220        self.bias().len()
221    }
222    /// returns the raw dimensions of the weights;
223    pub fn raw_dim(&self) -> D {
224        self.weights().raw_dim()
225    }
226    /// returns the shape of the parameters; uses the shape of the weight tensor
227    pub fn shape(&self) -> &[usize] {
228        self.weights().shape()
229    }
230    /// returns the shape of the bias tensor; the shape should be equivalent to that of the
231    /// weight tensor minus the "zero-th" axis
232    pub fn shape_bias(&self) -> &[usize] {
233        self.bias().shape()
234    }
235    /// returns the total number of parameters within the layer
236    pub fn size(&self) -> usize {
237        self.weights().len() + self.bias().len()
238    }
239    /// returns an owned instance of the parameters
240    pub fn to_owned(&self) -> ParamsBase<ndarray::OwnedRepr<A>, D>
241    where
242        A: Clone,
243        S: DataOwned,
244    {
245        ParamsBase::new(self.bias().to_owned(), self.weights().to_owned())
246    }
247    /// change the shape of the parameters; the shape of the bias parameters is determined by
248    /// removing the "zero-th" axis of the given shape
249    pub fn to_shape<Sh>(
250        &self,
251        shape: Sh,
252    ) -> crate::Result<ParamsBase<ndarray::CowRepr<'_, A>, Sh::Dim>>
253    where
254        A: Clone,
255        S: DataOwned,
256        Sh: ShapeBuilder,
257        Sh::Dim: Dimension + RemoveAxis,
258    {
259        let shape = shape.into_shape_with_order();
260        let dim = shape.raw_dim().clone();
261        let bias = self.bias().to_shape(dim.remove_axis(Axis(0)))?;
262        let weights = self.weights().to_shape(dim)?;
263        Ok(ParamsBase::new(bias, weights))
264    }
265    /// returns a "view" of the parameters; see [view](ArrayBase::view) for more information
266    pub fn view(&self) -> ParamsBase<ndarray::ViewRepr<&'_ A>, D>
267    where
268        S: Data,
269    {
270        ParamsBase::new(self.bias().view(), self.weights().view())
271    }
272    /// returns mutable view of the parameters; see [view_mut](ArrayBase::view_mut) for more information
273    pub fn view_mut(&mut self) -> ParamsBase<ndarray::ViewRepr<&'_ mut A>, D>
274    where
275        S: ndarray::DataMut,
276    {
277        ParamsBase::new(self.bias.view_mut(), self.weights.view_mut())
278    }
279}
280
281impl<A, S> ParamsBase<S, Ix1>
282where
283    S: RawData<Elem = A>,
284{
285    pub fn from_scalar_bias(bias: A, weights: ArrayBase<S, Ix1>) -> Self
286    where
287        A: Clone,
288        S: DataOwned,
289    {
290        Self {
291            bias: ArrayBase::from_elem((), bias),
292            weights,
293        }
294    }
295
296    pub fn nrows(&self) -> usize {
297        self.weights.len()
298    }
299}
300
301impl<A, S> ParamsBase<S, Ix2>
302where
303    S: RawData<Elem = A>,
304{
305    pub fn ncols(&self) -> usize {
306        self.weights.ncols()
307    }
308
309    pub fn nrows(&self) -> usize {
310        self.weights.nrows()
311    }
312}
313
314impl<A, S, D> Clone for ParamsBase<S, D>
315where
316    D: Dimension,
317    S: ndarray::RawDataClone<Elem = A>,
318    A: Clone,
319{
320    fn clone(&self) -> Self {
321        Self::new(self.bias().clone(), self.weights().clone())
322    }
323}
324
325impl<A, S, D> Copy for ParamsBase<S, D>
326where
327    D: Dimension + Copy,
328    <D as Dimension>::Smaller: Copy,
329    S: ndarray::RawDataClone<Elem = A> + Copy,
330    A: Copy,
331{
332}
333
334impl<A, S, D> PartialEq for ParamsBase<S, D>
335where
336    D: Dimension,
337    S: Data<Elem = A>,
338    A: PartialEq,
339{
340    fn eq(&self, other: &Self) -> bool {
341        self.bias() == other.bias() && self.weights() == other.weights()
342    }
343}
344
345impl<A, S, D> Eq for ParamsBase<S, D>
346where
347    D: Dimension,
348    S: Data<Elem = A>,
349    A: Eq,
350{
351}
352
353impl<A, S, D> core::fmt::Debug for ParamsBase<S, D>
354where
355    D: Dimension,
356    S: Data<Elem = A>,
357    A: core::fmt::Debug,
358{
359    fn fmt(&self, f: &mut core::fmt::Formatter) -> core::fmt::Result {
360        f.debug_struct("ModelParams")
361            .field("bias", self.bias())
362            .field("weights", self.weights())
363            .finish()
364    }
365}
366
367// impl<A, S, D> PartialOrd for ModelParams<S, D>
368// where
369//     D: Dimension,
370//     S: Data<Elem = A>,
371//     A: PartialOrd,
372// {
373//     fn partial_cmp(&self, other: &Self) -> Option<core::cmp::Ordering> {
374//         match self.bias.iter().partial_cmp(&other.bias.iter()) {
375//             Some(core::cmp::Ordering::Equal) => self.weights.iter().partial_cmp(&other.weights.iter()),
376//             other => other,
377//         }
378//     }
379// }
concision_core/params/params.rs

concision_core/params/
params.rs
