eryon_surface/

network.rs

/*
    Appellation: network <module>
    Contrib: @FL03
*/

mod impl_network;

use crate::model::{SurfaceModel, SurfaceModelConfig};
use crate::points::Point;
use cnc::nn::ModelFeatures;
use cnc::params::Params;
use ndarray::{Array1, Array2};
use rstmt::nrt::Triad;

/// A neural network capable of dynamic configuration. Essentially, each network is designed to
/// materialize the surface of a 2-simplex (triad) using barycentric coordinates to define
/// three critical points. These critical points define the minimum number of hidden layers
/// within the network and serve as _goalposts_ that guide the learning process. The remaining
/// points continue this trend, simply mapping each extra hidden layer to another position
/// within space. The verticies of the simplex are used to inform the input layer and in
/// finding the _centroid_ of the facet. The centroid defines the output layer of the facet,
/// serving as the final piece in a pseudo sink-source dyanamic.
#[derive(Clone, Debug)]
pub struct SurfaceNetwork<T = f32> {
    pub(crate) headspace: Triad,
    pub(crate) model: SurfaceModel<T>,
    pub(crate) points: Vec<Point<T>>,
}

impl<T> SurfaceNetwork<T> {
    /// Create a new surface network for the given triad
    pub fn new(headspace: Triad) -> Self
    where
        T: num_traits::Float + num_traits::FromPrimitive,
    {
        let config = SurfaceModelConfig::default();
        let features = ModelFeatures::new(3, 64, 3, 1);
        let model = SurfaceModel::zeros(config, features).with_attention();
        Self {
            headspace,
            model,
            points: Vec::new(),
        }
    }
    /// returns an immutable reference to the network's headspace
    pub const fn headspace(&self) -> Triad {
        self.headspace
    }
    /// returns a mutable reference to the network's headspace
    pub fn headspace_mut(&mut self) -> &mut Triad {
        &mut self.headspace
    }
    /// returns an immutable reference to the network's surface
    pub const fn model(&self) -> &SurfaceModel<T> {
        &self.model
    }
    /// returns a mutable reference to the network's surface
    pub fn model_mut(&mut self) -> &mut SurfaceModel<T> {
        &mut self.model
    }
    /// returns an immutable reference to the network's critical points
    pub const fn points(&self) -> &Vec<Point<T>> {
        &self.points
    }
    /// returns a mutable reference to the network's critical points
    pub fn points_mut(&mut self) -> &mut Vec<Point<T>> {
        &mut self.points
    }
    /// returns an immutable reference to the network's primary weights
    pub const fn input(&self) -> &Params<T> {
        self.model().input()
    }
    /// returns a mutable reference to the network's primary weights
    pub fn input_mut(&mut self) -> &mut Params<T> {
        self.model_mut().input_mut()
    }
    /// returns an immutable reference to the model's input layer bias
    pub const fn input_bias(&self) -> &Array1<T> {
        self.model().input().bias()
    }
    /// returns a mutable reference to the model's input layer bias
    pub fn input_bias_mut(&mut self) -> &mut Array1<T> {
        self.model_mut().input_mut().bias_mut()
    }
    /// returns an immutable reference to the model's input layer weights
    pub const fn input_weights(&self) -> &Array2<T> {
        self.model().input().weights()
    }
    /// returns a mutable reference to the model's input layer weights
    pub fn input_weights_mut(&mut self) -> &mut Array2<T> {
        self.model_mut().input_mut().weights_mut()
    }
    /// returns an immutable reference to the model's hidden layers
    pub const fn hidden(&self) -> &Vec<Params<T>> {
        self.model().hidden()
    }
    /// returns a mutable reference to the model's hidden layers
    #[inline]
    pub fn hidden_mut(&mut self) -> &mut Vec<Params<T>> {
        self.model_mut().hidden_mut()
    }
    /// returns an immutable reference to the network's secondary weights
    pub const fn output(&self) -> &Params<T> {
        self.model().output()
    }
    /// returns a mutable reference to the network's secondary weights
    #[inline]
    pub fn output_mut(&mut self) -> &mut Params<T> {
        self.model_mut().output_mut()
    }
    /// returns an immutable reference to the model's output layer bias
    pub const fn output_bias(&self) -> &Array1<T> {
        self.model().output().bias()
    }
    /// returns a mutable reference to the model's output layer bias
    #[inline]
    pub fn output_bias_mut(&mut self) -> &mut Array1<T> {
        self.model_mut().output_mut().bias_mut()
    }
    /// returns an immutable reference to the model's output layer weights
    pub const fn output_weights(&self) -> &Array2<T> {
        self.model().output().weights()
    }
    /// returns a mutable reference to the model's output layer weights
    #[inline]
    pub fn output_weights_mut(&mut self) -> &mut Array2<T> {
        self.model_mut().output_mut().weights_mut()
    }

    pub fn extend_surface<I>(&mut self, iter: I)
    where
        I: IntoIterator<Item = Point<T>>,
    {
        self.points.extend(iter);
    }
    /// set the critical points of the network
    pub fn set_points<I>(&mut self, iter: I)
    where
        I: IntoIterator<Item = Point<T>>,
    {
        self.points = Vec::from_iter(iter);
    }
    /// enable the attention mechanism in the model
    pub fn with_attention(self) -> Self
    where
        T: num_traits::FromPrimitive,
    {
        Self {
            model: self.model.with_attention(),
            ..self
        }
    }
    /// consumes the current instance and returns another with the given points
    pub fn with_points<I>(self, iter: I) -> Self
    where
        I: IntoIterator<Item = Point<T>>,
    {
        Self {
            points: Vec::from_iter(iter),
            ..self
        }
    }
}

impl<T> PartialEq for SurfaceNetwork<T>
where
    T: PartialEq,
    SurfaceModel<T>: PartialEq,
{
    fn eq(&self, other: &Self) -> bool {
        self.headspace == other.headspace
            && self.model == other.model
            && self.points == other.points
    }
}