eryon_rt/frag/

fragment.rs

/*
    Appellation: fragment <module>
    Contrib: @FL03
*/
use core::hash::Hash;
use eryon_actors::prelude::{Driver, VNode};
use rshyper::{EdgeId, HyperMap, VertexId, Weight};
use rstmt::Aspn;
use rstmt::nrt::{LPR, Triad};
use std::collections::HashMap;

/// [`FragTonnetz`] represents a fragment of the tonal space that can be managed by a local
/// runtime. Each partition is a VNode that contains a plant and associated memory system.
#[derive(Clone, Debug)]
pub struct FragTonnetz<D>
where
    D: Driver<Triad>,
{
    /// The underlying hypergraph structure
    pub(crate) graph: HyperMap<Aspn, VNode<D>>,
    /// Maps EdgeIds to VNodes for efficient access
    pub(crate) partitions: HashMap<EdgeId, VNode<D>>,
    /// Tracks adjacency between triads via transformations
    pub(crate) transformations: HashMap<EdgeId, HashMap<LPR, EdgeId>>,
}

impl<D> Default for FragTonnetz<D>
where
    D: Driver<Triad>,
{
    fn default() -> Self {
        Self::new()
    }
}

impl<D> FragTonnetz<D>
where
    D: Driver<Triad>,
{
    /// Create a new Tonnetz structure
    pub fn new() -> Self {
        FragTonnetz {
            graph: HyperMap::new(),
            partitions: HashMap::new(),
            transformations: HashMap::new(),
        }
    }
    /// returns an immutable reference to the graph
    pub const fn graph(&self) -> &HyperMap<Aspn, VNode<D>> {
        &self.graph
    }
    /// returns a mutable reference to the graph
    pub const fn graph_mut(&mut self) -> &mut HyperMap<Aspn, VNode<D>> {
        &mut self.graph
    }
    /// returns an immutable reference to the partitions
    pub const fn partitions(&self) -> &HashMap<EdgeId, VNode<D>> {
        &self.partitions
    }
    /// returns a mutable reference to the partitions
    pub const fn partitions_mut(&mut self) -> &mut HashMap<EdgeId, VNode<D>> {
        &mut self.partitions
    }
    /// returns an immutable reference to the transformations
    pub const fn transformations(&self) -> &HashMap<EdgeId, HashMap<LPR, EdgeId>> {
        &self.transformations
    }
    /// returns a mutable reference to the transformations
    pub const fn transformations_mut(&mut self) -> &mut HashMap<EdgeId, HashMap<LPR, EdgeId>> {
        &mut self.transformations
    }
    /// Add a hyperedge to the graph and return its edge ID
    pub fn add_edge<I>(&mut self, vertices: I) -> eryon::Result<EdgeId>
    where
        I: IntoIterator<Item = VertexId>,
    {
        let id = self.graph_mut().add_link(vertices)?;
        Ok(id)
    }
    /// Add a note to the graph and return its vertex ID
    pub fn add_note(&mut self, note: Aspn) -> eryon::Result<VertexId> {
        let id = self.graph_mut().add_node(Weight(note))?;
        Ok(id)
    }
    /// register a [`VNode`] with the system
    pub fn add_vnode(&mut self, key: EdgeId, vnode: VNode<D>) -> Option<VNode<D>> {
        // insert the partition
        self.partitions_mut().insert(key, vnode)
    }
    /// returns true if the edge exists
    pub fn contains_edge(&self, id: &EdgeId) -> bool {
        self.graph().contains_edge(id)
    }
    /// returns true if the node exists
    pub fn contains_node(&self, id: &VertexId) -> bool {
        self.graph().contains_node(id)
    }
    /// returns true if the given node is a child of the edge
    pub fn contains_node_in_edge<Q>(&self, edge: &EdgeId, key: &Q) -> bool
    where
        Q: Hash + Eq,
        VertexId: core::borrow::Borrow<Q>,
    {
        self.graph().is_node_in_domain(edge, key)
    }
    /// returns true if the partition exists
    pub fn contains_partition<Q>(&self, key: &Q) -> bool
    where
        Q: Hash + Eq + ?Sized,
        EdgeId: core::borrow::Borrow<Q>,
    {
        self.partitions().contains_key(key)
    }
    /// returns a reference to the node if it exists
    pub fn get_note<Q>(&self, key: &Q) -> Option<&Weight<Aspn>>
    where
        Q: Hash + Eq,
        VertexId: core::borrow::Borrow<Q>,
    {
        self.graph().get_node_weight(key).ok()
    }
    /// returns a mutable reference to the node if it exists
    pub fn get_note_mut<Q>(&mut self, key: &Q) -> Option<&mut Weight<Aspn>>
    where
        Q: Hash + Eq,
        VertexId: core::borrow::Borrow<Q>,
    {
        self.graph_mut().get_node_weight_mut(key).ok()
    }
    /// returns a reference to the partition if it exists
    pub fn get_partition<Q>(&self, key: &Q) -> Option<&VNode<D>>
    where
        Q: Hash + Eq + ?Sized,
        EdgeId: core::borrow::Borrow<Q>,
    {
        self.partitions().get(key)
    }
    /// returns a mutable reference to the partition if it exists
    pub fn get_partition_mut<Q>(&mut self, key: &Q) -> Option<&mut VNode<D>>
    where
        Q: Hash + Eq + ?Sized,
        EdgeId: core::borrow::Borrow<Q>,
    {
        self.partitions_mut().get_mut(key)
    }
    /// returns the total number of edges
    pub fn total_edges(&self) -> usize {
        self.graph().size()
    }
    /// returns the total number of vertices
    pub fn total_nodes(&self) -> usize {
        self.graph().order()
    }
    /// returns the number of partitions
    pub fn total_partitions(&self) -> usize {
        self.partitions().len()
    }
}

#[allow(deprecated)]
impl<D> FragTonnetz<D>
where
    D: Driver<Triad>,
{
    #[deprecated(
        since = "0.0.3",
        note = "use `get_note` instead; this will be removed in the next major release"
    )]
    pub fn get_node<Q>(&self, key: &Q) -> Option<&Weight<Aspn>>
    where
        Q: Hash + Eq,
        VertexId: core::borrow::Borrow<Q>,
    {
        self.get_note(key)
    }
    #[deprecated(
        since = "0.0.3",
        note = "use `total_partitions` instead; this will be removed in the next major release"
    )]
    pub fn partition_count(&self) -> usize {
        self.partitions().len()
    }
    #[deprecated(
        since = "0.0.3",
        note = "use `total_edges` instead; this will be removed in the next major release"
    )]
    pub fn edge_count(&self) -> usize {
        self.graph().total_edges()
    }
    #[deprecated(
        since = "0.0.3",
        note = "use `total_nodes` instead; this will be removed in the next major release"
    )]
    pub fn vertex_count(&self) -> usize {
        self.graph().total_nodes()
    }
    #[deprecated(
        since = "0.0.3",
        note = "use `add_vnode` instead; this will be removed in the next major release"
    )]
    pub fn add_partition(&mut self, key: EdgeId, vnode: VNode<D>) -> Option<VNode<D>> {
        // insert the partition
        self.partitions_mut().insert(key, vnode)
    }
}