rstmt-nrt 0.1.0

this crate focuses on providing support for the neo-riemannian theory of music
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

/*
    Appellation: tonnetz <module>
    Created At: 2025.12.28:10:54:06
    Contrib: @FL03
*/
//! The tonnetz is a conceptual lattice representation of tonal space first proposed in 1739 by
//! Leonhard Euler as a means of visualizing relationships between triads. Over the centuries,
//! researchers have expanded upon Euler's initial concept, eventually culminating in the
//! development of the long-awaited _**generalized tonnetz**_.
//!
//! # Resources
//!
//! Listed below are some useful resources for understanding the tonnetz, its history, and its
//! applications in music theory and beyond.
//!
//! - [The Generalized Tonnetz](https://dmitri.mycpanel.princeton.edu/tonnetzes.pdf)
//! - [Wikipedia: Tonnetz](https://en.wikipedia.org/wiki/Tonnetz)
mod impl_hyper_tonnetz;

use crate::triad::TriadBase;
use crate::{LPR, TriChord, TriadRepr, TriadType, Triads};
use hashbrown::HashMap;
use rshyper::{EdgeId, RawIndex, UnHyperMap};
use rspace_traits::RawSpace;

/// a type alias for a [`HashMap`] that maps an [`EdgeId`] to a [`TriadBase`]
pub(crate) type EdgeMap<S = TriChord, K = Triads, T = <S as RawSpace>::Elem, Ix = usize> =
    HashMap<EdgeId<Ix>, TriadBase<S, K, T>>;
/// a type alias for a [`HashMap`] that maps an [`EdgeId`] to a [`HashMap`] of [`LPR`]
/// transformations.
pub(crate) type LprMap<I = usize> = HashMap<EdgeId<I>, HashMap<LPR, EdgeId<I>>>;
/// a type alias for the underlying hypergraph structure used in the tonnetz
pub(crate) type NoteGraph<T = isize, E = (), Ix = usize> = UnHyperMap<T, E, Ix>;

/// A type alias for the tonnetz using triads represented by `[T; 3]` and dynamic triad type
/// [`Triads`].
pub type StdHyperTonnetz<T = isize, Ix = usize> = HyperTonnetz<[T; 3], Triads, T, Ix>;

/// The [`HyperTonnetz`] implementation relies on a _hypergraph_ to define the relationships
/// between various notes and triads within the tonal space. Hypergraphs generalize the concept
/// of a graph by allowing edges to connect any number of vertices, making them well-suited
/// for modeling complex relationships and topologies such as those found in music theory.
#[derive(Clone, Debug)]
pub struct HyperTonnetz<S = TriChord, K = Triads, T = <S as RawSpace>::Elem, Ix = usize>
where
    K: TriadType,
    S: TriadRepr<Elem = T>,
    Ix: RawIndex,
{
    /// a hypergraph representing the tonal space
    pub(crate) graph: NoteGraph<T, (), Ix>,
    /// Maps EdgeIds to Triad for efficient access
    pub(crate) triads: EdgeMap<S, K, T, Ix>,
    /// Tracks adjacency between triads via transformations
    pub(crate) transformations: LprMap<Ix>,
}