music21/

voiceleading.rs

//! Two-voice voice-leading checks, a port of music21's `VoiceLeadingQuartet`.
//!
//! A quartet is two consecutive notes in an upper voice and two in a lower
//! voice. It classifies how the voices move between them and finds the
//! parallel and hidden perfect intervals that common-practice counterpoint
//! forbids.

use crate::{
    defaults::{FloatType, IntegerType},
    error::{Error, Result},
    interval::{Interval, IntervalDirection},
    key::Key,
    pitch::Pitch,
    scale::{Scale, ScaleType},
    stream::{Stream, StreamElement, StreamKind},
};

use crate::interval::constants::{
    PERFECT_FIFTH_UP as PERFECT_FIFTH, PERFECT_OCTAVE, PERFECT_UNISON,
};

/// How two voices move relative to each other.
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum MotionType {
    /// Contrary motion between two spellings of the same simple interval,
    /// such as a fifth opening out to a twelfth. Only reported when asked for.
    AntiParallel,
    /// The voices move in opposite directions.
    Contrary,
    /// Neither voice moves.
    NoMotion,
    /// One voice holds while the other moves.
    Oblique,
    /// The voices move the same way and keep the same generic interval.
    Parallel,
    /// The voices move the same way through different intervals.
    Similar,
}

impl MotionType {
    /// Returns music21's label for the motion.
    pub fn as_str(self) -> &'static str {
        match self {
            Self::AntiParallel => "Anti-Parallel",
            Self::Contrary => "Contrary",
            Self::NoMotion => "No Motion",
            Self::Oblique => "Oblique",
            Self::Parallel => "Parallel",
            Self::Similar => "Similar",
        }
    }
}

impl std::fmt::Display for MotionType {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.write_str(self.as_str())
    }
}

/// What a caller may ask of a parallel motion.
///
/// music21 takes either: a number is how wide the interval must be, whatever
/// it is spelled — `3` for parallel thirds of any quality — and an interval
/// is the interval itself, spelling and all.
#[derive(Clone, Debug, PartialEq)]
pub enum ParallelRequirement {
    /// However many steps wide, counted inclusively.
    Wide(IntegerType),
    /// This interval exactly.
    Named(Box<Interval>),
}

impl From<Interval> for ParallelRequirement {
    fn from(interval: Interval) -> Self {
        Self::Named(Box::new(interval))
    }
}

impl From<IntegerType> for ParallelRequirement {
    fn from(steps: IntegerType) -> Self {
        Self::Wide(steps)
    }
}

/// Two consecutive notes in each of two voices. Voice one is the upper voice.
#[derive(Clone, Debug)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[must_use]
pub struct VoiceLeadingQuartet {
    v1n1: Pitch,
    v1n2: Pitch,
    v2n1: Pitch,
    v2n2: Pitch,
    vertical: [Interval; 2],
    horizontal: [Interval; 2],
    key: Option<Key>,
}

impl VoiceLeadingQuartet {
    /// Builds a quartet from the first and second pitch of the upper voice,
    /// then the first and second pitch of the lower voice.
    pub fn new(v1n1: Pitch, v1n2: Pitch, v2n1: Pitch, v2n2: Pitch) -> Result<Self> {
        let vertical = [
            Interval::between_pitches(&v1n1, &v2n1)?,
            Interval::between_pitches(&v1n2, &v2n2)?,
        ];
        let horizontal = [
            Interval::between_pitches(&v1n1, &v1n2)?,
            Interval::between_pitches(&v2n1, &v2n2)?,
        ];
        Ok(Self {
            v1n1,
            v1n2,
            v2n1,
            v2n2,
            vertical,
            horizontal,
            key: None,
        })
    }

    /// Builds a quartet from pitch names, in the same order as [`Self::new`].
    pub fn from_names(v1n1: &str, v1n2: &str, v2n1: &str, v2n2: &str) -> Result<Self> {
        Self::new(
            Pitch::from_name(v1n1)?,
            Pitch::from_name(v1n2)?,
            Pitch::from_name(v2n1)?,
            Pitch::from_name(v2n2)?,
        )
    }

    /// Attaches the key the progression is heard in, which
    /// [`Self::is_proper_resolution`] and [`Self::clausula_vera`] consult.
    pub fn with_key(mut self, key: Key) -> Self {
        self.key = Some(key);
        self
    }

    /// The key the progression is heard in, if one was given.
    pub fn key(&self) -> Option<&Key> {
        self.key.as_ref()
    }

    /// Attaches a key, or takes one away.
    pub fn set_key(&mut self, key: Option<Key>) {
        self.key = key;
    }

    /// Moves or respells the four pitches and keeps the intervals as they
    /// were: music21 works its intervals out when a note is set and reads
    /// the notes as they stand everywhere else, so a note edited in place
    /// crosses voices without changing the motion.
    pub fn set_pitches(&mut self, v1n1: Pitch, v1n2: Pitch, v2n1: Pitch, v2n2: Pitch) {
        self.v1n1 = v1n1;
        self.v1n2 = v1n2;
        self.v2n1 = v2n1;
        self.v2n2 = v2n2;
    }

    /// Whether a dissonant first interval resolves the way voice-leading
    /// rules expect: music21's `isProperResolution`. A fourth wants the upper
    /// voice to fall or stay; a tritone or a minor seventh wants the
    /// leading tone up, the seventh down and the right contrary motion — and
    /// with a key set, only when the notes really are those scale degrees.
    /// Anything else, and no motion at all, is proper.
    pub fn is_proper_resolution(&self) -> Result<bool> {
        if self.no_motion() {
            return Ok(true);
        }
        let (lower_degree_before, lower_degree_after) = match &self.key {
            Some(key) => {
                // music21 counts in `key.getScale(key.mode)`, the scale the
                // key's signature implies, which a tonic moved by hand
                // leaves behind; it has no such scale for a church mode, for
                // which the crate counts in the mode itself.
                let scale = match key.mode() {
                    "major" | "minor" => key.key_signature().scale(key.mode())?,
                    _ => key.scale(),
                };
                let mut before = scale.degree_of(&self.v2n1)?;
                let after = scale.degree_of(&self.v2n2)?;
                if key.mode() == "minor" && before.is_none() {
                    before =
                        Scale::new(ScaleType::MelodicMinor, key.tonic()).degree_of(&self.v2n1)?;
                }
                (before, after)
            }
            None => (None, None),
        };
        let keyed = self.key.is_some();
        let first = self.vertical[0].simple_name();
        let second = self.vertical[1].generic().simple_undirected();
        Ok(match first.as_str() {
            "P4" => self.v1n1.ps() >= self.v1n2.ps(),
            "A4" => {
                if keyed && lower_degree_before != Some(4) {
                    true
                } else if keyed && lower_degree_after != Some(3) {
                    false
                } else {
                    self.outward_contrary_motion() && second == 6
                }
            }
            "d5" => {
                if keyed && lower_degree_before != Some(7) {
                    true
                } else if keyed && lower_degree_after != Some(1) {
                    false
                } else {
                    self.inward_contrary_motion() && second == 3
                }
            }
            "m7" => {
                if keyed && lower_degree_before != Some(5) {
                    true
                } else if keyed && lower_degree_after != Some(1) {
                    false
                } else {
                    second == 3
                }
            }
            _ => true,
        })
    }

    /// Whether one voice leaps while the other neither steps nor holds:
    /// music21's `leapNotSetWithStep`. Two thirds in contrary motion are let
    /// through.
    pub fn leap_not_set_with_step(&self) -> bool {
        if self.no_motion() {
            return false;
        }
        let [upper, lower] = &self.horizontal;
        let steps_or_holds =
            |interval: &Interval| interval.is_diatonic_step() || interval.is_unison();
        if upper.generic().undirected() == 3
            && lower.generic().undirected() == 3
            && self.contrary_motion()
        {
            return false;
        }
        if upper.is_skip() {
            !steps_or_holds(lower)
        } else if lower.is_skip() {
            !steps_or_holds(upper)
        } else {
            false
        }
    }

    /// Whether the two voices open the way sixteenth-century counterpoint
    /// opens: music21's `modalOpening`. Errors without a key.
    ///
    /// One of the two harmonic intervals must be a unison or a fifth — the
    /// second may be, to allow for an anacrusis — and the pair must establish
    /// the tonic or the dominant. Which of the two says so is whichever can
    /// be read at all: music21 asks the first, and only falls to the second
    /// when the first says nothing.
    pub fn modal_opening(&self) -> Result<bool> {
        let Some(key) = &self.key else {
            return Err(Error::Analysis(
                "modalOpening requires a key to be set on the VoiceLeadingQuartet".to_string(),
            ));
        };
        let opening = ["P1", "P5"];
        let sounds_open = opening.contains(&self.vertical[0].simple_name().as_str())
            || opening.contains(&self.vertical[1].simple_name().as_str());
        let function_of = |first: &Pitch, second: &Pitch| -> Result<Option<bool>> {
            let chord = crate::chord::Chord::new([first.clone(), second.clone()].as_slice())?;
            Ok(
                crate::roman::identify_as_tonic_or_dominant(&chord, key)?.map(|figure| {
                    figure
                        .chars()
                        .next()
                        .is_some_and(|numeral| matches!(numeral.to_ascii_uppercase(), 'I' | 'V'))
                }),
            )
        };
        let established = match function_of(&self.v1n1, &self.v2n1)? {
            Some(established) => established,
            None => function_of(&self.v1n2, &self.v2n2)?.unwrap_or(false),
        };
        Ok(sounds_open && established)
    }

    /// The opposite of [`Self::modal_opening`]: music21's `opensIncorrectly`.
    pub fn opens_incorrectly(&self) -> Result<bool> {
        self.modal_opening().map(|opens| !opens)
    }

    /// The opposite of [`Self::clausula_vera`]: music21's `closesIncorrectly`.
    pub fn closes_incorrectly(&self) -> Result<bool> {
        self.clausula_vera().map(|closes| !closes)
    }

    /// Whether the two voices close a clausula vera: stepwise contrary
    /// motion, one voice by a semitone and the other by a tone, onto a unison
    /// or octave on the tonic. Errors without a key.
    pub fn clausula_vera(&self) -> Result<bool> {
        let Some(key) = &self.key else {
            return Err(Error::Analysis(
                "clausulaVera requires a key to be set on the VoiceLeadingQuartet".to_string(),
            ));
        };
        let tonic = key.tonic().name();
        let mut horizontal = [
            self.horizontal[0].short_name(),
            self.horizontal[1].short_name(),
        ];
        horizontal.sort_unstable();
        Ok(horizontal == ["M2", "m2"]
            && self.contrary_motion()
            && matches!(self.vertical[1].short_name().as_str(), "P1" | "P8")
            && self.v1n2.name() == tonic
            && self.v2n2.name() == tonic)
    }

    /// The upper voice's first pitch.
    pub fn v1n1(&self) -> &Pitch {
        &self.v1n1
    }

    /// The upper voice's second pitch.
    pub fn v1n2(&self) -> &Pitch {
        &self.v1n2
    }

    /// The lower voice's first pitch.
    pub fn v2n1(&self) -> &Pitch {
        &self.v2n1
    }

    /// The lower voice's second pitch.
    pub fn v2n2(&self) -> &Pitch {
        &self.v2n2
    }

    /// The harmonic intervals from the upper voice to the lower voice, at the
    /// first and second moment.
    pub fn vertical_intervals(&self) -> &[Interval; 2] {
        &self.vertical
    }

    /// The melodic intervals each voice moves through, upper voice first.
    pub fn horizontal_intervals(&self) -> &[Interval; 2] {
        &self.horizontal
    }

    /// Classifies the motion. Anti-parallel motion is reported as contrary
    /// unless `allow_anti_parallel` is set.
    pub fn motion_type(&self, allow_anti_parallel: bool) -> MotionType {
        if self.oblique_motion() {
            MotionType::Oblique
        } else if self.parallel_motion(None, false) {
            MotionType::Parallel
        } else if self.similar_motion() {
            MotionType::Similar
        } else if allow_anti_parallel && self.anti_parallel_motion(None) {
            MotionType::AntiParallel
        } else if self.contrary_motion() {
            MotionType::Contrary
        } else {
            MotionType::NoMotion
        }
    }

    /// Returns whether neither voice moves.
    pub fn no_motion(&self) -> bool {
        self.horizontal.iter().all(Interval::is_perfect_unison)
    }

    /// Returns whether exactly one voice holds its pitch.
    pub fn oblique_motion(&self) -> bool {
        !self.no_motion() && self.horizontal.iter().any(Interval::is_perfect_unison)
    }

    /// Returns whether both voices move in the same direction.
    pub fn similar_motion(&self) -> bool {
        !self.no_motion() && self.horizontal[0].direction() == self.horizontal[1].direction()
    }

    /// Returns whether the voices move in the same direction keeping the same
    /// generic interval. With `required`, the interval must also be that one;
    /// `allow_octave_displacement` accepts a fifth answered by a twelfth.
    pub fn parallel_motion(
        &self,
        required: Option<&ParallelRequirement>,
        allow_octave_displacement: bool,
    ) -> bool {
        let [first, second] = &self.vertical;
        if !self.similar_motion() {
            return false;
        }
        if first.generic().directed() != second.generic().directed() && !allow_octave_displacement {
            return false;
        }
        if first.generic().semi_simple_undirected() != second.generic().semi_simple_undirected() {
            return false;
        }
        match required {
            None => true,
            Some(ParallelRequirement::Wide(steps)) => {
                first.generic().semi_simple_undirected() == *steps
            }
            Some(ParallelRequirement::Named(required)) => {
                first.semi_simple_key() == required.semi_simple_key()
                    && second.semi_simple_key() == required.semi_simple_key()
            }
        }
    }

    /// Returns whether the voices move in opposite directions.
    pub fn contrary_motion(&self) -> bool {
        !self.no_motion()
            && !self.oblique_motion()
            && self.horizontal[0].direction() != self.horizontal[1].direction()
    }

    /// Returns whether the voices move apart.
    pub fn outward_contrary_motion(&self) -> bool {
        self.contrary_motion() && self.horizontal[0].direction() == IntervalDirection::Ascending
    }

    /// Returns whether the voices move towards each other.
    pub fn inward_contrary_motion(&self) -> bool {
        self.contrary_motion() && self.horizontal[0].direction() == IntervalDirection::Descending
    }

    /// Returns whether contrary motion lands on the same simple interval it
    /// left, such as a fifth opening out to a twelfth. With `required`, that
    /// interval must also be the given one.
    pub fn anti_parallel_motion(&self, required: Option<&Interval>) -> bool {
        let [first, second] = &self.vertical;
        self.contrary_motion()
            && first.simple_key() == second.simple_key()
            && required.is_none_or(|required| first.simple_key() == required.simple_key())
    }

    /// Returns whether the voices move in parallel or anti-parallel through
    /// the given interval, in any octave.
    pub fn parallel_interval(&self, interval: &Interval) -> bool {
        let required = ParallelRequirement::Named(Box::new(interval.clone()));
        self.parallel_motion(Some(&required), true) || self.anti_parallel_motion(Some(interval))
    }

    /// Returns whether the voices move in parallel fifths.
    pub fn parallel_fifth(&self) -> bool {
        self.parallel_interval(&PERFECT_FIFTH)
    }

    /// Returns whether the voices move in parallel octaves.
    pub fn parallel_octave(&self) -> bool {
        self.parallel_interval(&PERFECT_OCTAVE)
    }

    /// Returns whether the voices move in parallel unisons.
    pub fn parallel_unison(&self) -> bool {
        self.parallel_interval(&PERFECT_UNISON)
    }

    /// Returns whether the voices move in parallel unisons or octaves.
    pub fn parallel_unison_or_octave(&self) -> bool {
        self.parallel_unison() || self.parallel_octave()
    }

    /// Returns whether similar motion arrives at the given interval without
    /// having started from it.
    pub fn hidden_interval(&self, interval: &Interval) -> bool {
        if self.parallel_motion(None, true) || !self.similar_motion() {
            return false;
        }
        self.vertical[1].simple_key() == interval.simple_key()
    }

    /// Returns whether similar motion arrives at a perfect fifth.
    pub fn hidden_fifth(&self) -> bool {
        self.hidden_interval(&PERFECT_FIFTH)
    }

    /// Returns whether similar motion arrives at a perfect octave.
    pub fn hidden_octave(&self) -> bool {
        self.hidden_interval(&PERFECT_OCTAVE)
    }

    /// Returns whether a voice moves past where the other voice just was.
    pub fn voice_overlap(&self) -> bool {
        self.v1n2.ps() < self.v2n1.ps() || self.v2n2.ps() > self.v1n1.ps()
    }

    /// Returns whether the lower voice is above the upper voice at either
    /// moment.
    pub fn voice_crossing(&self) -> bool {
        self.v1n1.ps() < self.v2n1.ps() || self.v1n2.ps() < self.v2n2.ps()
    }
}

/// Which quartets [`iterate_all_voice_leading_quartets`] gives: music21's
/// keyword arguments of the same names, with its defaults.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[non_exhaustive]
pub struct QuartetOptions {
    /// Whether a voice may come to its note out of a rest. Without it, the
    /// note before has to stop exactly where the next one starts.
    pub include_rests: bool,
    /// Whether a voice that holds or repeats its note counts as moving.
    pub include_oblique: bool,
    /// Whether a quartet in which neither voice changes pitch is given.
    pub include_no_motion: bool,
}

impl Default for QuartetOptions {
    fn default() -> Self {
        Self {
            include_rests: true,
            include_oblique: true,
            include_no_motion: false,
        }
    }
}

/// One thing on a part's flattened timeline, as the walk sees it.
struct Span<'a> {
    offset: FloatType,
    end: FloatType,
    part: usize,
    /// Where the element stands in [`Stream::leaves`].
    position: usize,
    element: &'a StreamElement,
}

impl Span<'_> {
    fn is_pitched(&self) -> bool {
        self.element.is_note_or_chord()
    }

    /// music21's `classSortOrder`, which decides what comes first among the
    /// things starting together.
    fn class_sort_order(&self) -> i8 {
        match self.element {
            StreamElement::TextExpression(_) => -30,
            StreamElement::Instrument(_) => -25,
            StreamElement::Clef(_) => 0,
            StreamElement::MetronomeMark(_) | StreamElement::TempoText(_) => 1,
            StreamElement::KeySignature(_) | StreamElement::Key(_) => 2,
            StreamElement::TimeSignature(_) => 4,
            StreamElement::Dynamic(_) => 10,
            StreamElement::ChordSymbol(_) => 19,
            _ => 20,
        }
    }
}

/// Each part of a stream as a flat timeline: every element of the part with
/// its offset from the stream's start and its position in
/// [`Stream::leaves`], in the order `flatten` would give them. A stream
/// holding no parts is one part itself.
fn parts_by_position(stream: &Stream) -> Vec<Vec<(usize, FloatType, &StreamElement)>> {
    let tops: Vec<usize> = stream
        .events()
        .iter()
        .enumerate()
        .filter(|(_, event)| {
            event
                .element()
                .as_stream()
                .is_some_and(|part| matches!(part.kind(), StreamKind::Part | StreamKind::PartStaff))
        })
        .map(|(top, _)| top)
        .collect();
    let leaves = stream.leaves_under_top();
    let mut parts: Vec<Vec<(usize, FloatType, &StreamElement)>> = if tops.is_empty() {
        vec![
            leaves
                .iter()
                .enumerate()
                .map(|(position, &(_, offset, element))| (position, offset, element))
                .collect(),
        ]
    } else {
        tops.iter()
            .map(|&top| {
                leaves
                    .iter()
                    .enumerate()
                    .filter(|(_, (under, _, _))| *under == top)
                    .map(|(position, &(_, offset, element))| (position, offset, element))
                    .collect()
            })
            .collect()
    };
    // Stable, as `flatten` is.
    for part in &mut parts {
        part.sort_by(|left, right| left.1.total_cmp(&right.1));
    }
    parts
}

/// Every [`VoiceLeadingQuartet`] in a stream, generally a score: music21's
/// `iterateAllVoiceLeadingQuartets`.
///
/// Wherever a note starts, each voice that moves there is paired with the
/// note it came from, each voice holding through is paired with itself, and
/// every two such pairs make a quartet. Only notes make one; a pair with a
/// chord in it is passed over, as it is upstream.
///
/// The quartets come in the order of the score: by offset, then by part,
/// the first-named voice being the earlier part. music21 orders the voices
/// within an offset by a counter of when each note object was put into its
/// stream, which says nothing about the music, so its order within an offset
/// can differ; the quartets themselves are the same.
///
/// A voice comes *from* the first thing in its part at the nearest earlier
/// offset where anything in that part starts. If that is not a note or
/// chord -- a rest, or a time signature standing where a note also starts --
/// the voice has no pair there. That is music21's reading and is kept.
pub fn iterate_all_voice_leading_quartets(
    stream: &Stream,
    options: QuartetOptions,
) -> Result<Vec<VoiceLeadingQuartet>> {
    let leaves = stream.leaves();
    let pitch = |position: usize| match leaves[position].1 {
        StreamElement::Note(note) => note.pitch().clone(),
        _ => unreachable!("a quartet is made of notes alone"),
    };
    voice_leading_quartet_positions(stream, options)
        .into_iter()
        .map(|(_, [v1n1, v1n2, v2n1, v2n2])| {
            VoiceLeadingQuartet::new(pitch(v1n1), pitch(v1n2), pitch(v2n1), pitch(v2n2))
        })
        .collect()
}

/// Where the four notes of every quartet [`iterate_all_voice_leading_quartets`]
/// finds stand in the stream: each quartet as the offset it is found at and
/// the positions in [`Stream::leaves`] of its `v1n1`, `v1n2`, `v2n1` and
/// `v2n2`, in that order. This is the walk itself, for a caller that keeps
/// something of its own beside each note and wants that back rather than a
/// copy of the pitch; the offset is what music21's `reverse` walks backwards
/// by, since a voice held through has its notes start earlier.
///
/// ```
/// use music21::{voiceleading::{voice_leading_quartet_positions, QuartetOptions}, Note, Stream, StreamKind};
///
/// let mut upper = Stream::with_kind(StreamKind::Part);
/// upper.insert(0.0, Note::from_name("C5")?);
/// upper.insert(1.0, Note::from_name("D5")?);
/// let mut lower = Stream::with_kind(StreamKind::Part);
/// lower.insert(0.0, Note::from_name("C4")?);
/// lower.insert(1.0, Note::from_name("B3")?);
/// let mut score = Stream::with_kind(StreamKind::Score);
/// score.insert(0.0, upper);
/// score.insert(0.0, lower);
/// assert_eq!(voice_leading_quartet_positions(&score, QuartetOptions::default()), [(1.0, [0, 1, 2, 3])]);
/// # Ok::<(), music21::Error>(())
/// ```
pub fn voice_leading_quartet_positions(
    stream: &Stream,
    options: QuartetOptions,
) -> Vec<(FloatType, [usize; 4])> {
    let parts = parts_by_position(stream);
    let mut spans: Vec<Span<'_>> = Vec::new();
    for (part, flat) in parts.iter().enumerate() {
        for &(position, offset, element) in flat {
            spans.push(Span {
                offset,
                end: offset + element.quarter_length(),
                part,
                position,
                element,
            });
        }
    }
    // Stable, so things starting together stay in part order and then in
    // the order their part holds them.
    spans.sort_by(|left, right| {
        left.offset
            .total_cmp(&right.offset)
            .then(left.class_sort_order().cmp(&right.class_sort_order()))
    });

    let mut quartets = Vec::new();
    let mut start = 0;
    while start < spans.len() {
        let offset = spans[start].offset;
        let stop = start
            + spans[start..]
                .iter()
                .take_while(|span| span.offset == offset)
                .count();

        let mut motions: Vec<(&Span<'_>, &Span<'_>)> = Vec::new();
        for starting in spans[start..stop].iter().filter(|span| span.is_pitched()) {
            // The nearest earlier offset where this part starts anything,
            // and the first thing it starts there.
            let Some(nearest) = spans[..start]
                .iter()
                .rev()
                .find(|span| span.part == starting.part)
                .map(|span| span.offset)
            else {
                continue;
            };
            let previous = spans[..start]
                .iter()
                .find(|span| span.part == starting.part && span.offset == nearest);
            let Some(previous) = previous.filter(|span| span.is_pitched()) else {
                continue;
            };
            // A hair of latitude, since offsets here are floats where
            // music21's are fractions.
            if !options.include_rests && (previous.end - offset).abs() > 1e-9 {
                continue;
            }
            if !options.include_oblique && previous.element.pitches() == starting.element.pitches()
            {
                continue;
            }
            motions.push((previous, starting));
        }
        if options.include_oblique {
            for held in spans[..start]
                .iter()
                .filter(|span| span.is_pitched() && span.end - offset > 1e-9)
            {
                motions.push((held, held));
            }
        }

        for (index, first) in motions.iter().enumerate() {
            for second in &motions[index + 1..] {
                if !options.include_no_motion
                    && first.0.element.pitches() == first.1.element.pitches()
                    && second.0.element.pitches() == second.1.element.pitches()
                {
                    continue;
                }
                let four = [first.0, first.1, second.0, second.1];
                if four
                    .iter()
                    .all(|span| matches!(span.element, StreamElement::Note(_)))
                {
                    quartets.push((offset, four.map(|span| span.position)));
                }
            }
        }
        start = stop;
    }
    quartets
}

/// What is sounding or standing in each part at an offset, part by part:
/// music21's `getVerticalityFromObject`, asked by offset since a stream here
/// owns its notes and an offset is what says where one is.
///
/// A thing counts if it starts there or is still going, and a thing of no
/// length counts where it stands. Parts holding nothing there are left out,
/// so each answer carries the index of its part.
pub fn verticality_at(stream: &Stream, offset: FloatType) -> Vec<(usize, Vec<StreamElement>)> {
    let leaves = stream.leaves();
    verticality_positions_at(stream, offset)
        .into_iter()
        .map(|(part, positions)| {
            (
                part,
                positions
                    .into_iter()
                    .map(|position| leaves[position].1.clone())
                    .collect(),
            )
        })
        .collect()
}

/// [`verticality_at`] by position: for each part holding anything at the
/// offset, the part's index and the positions in [`Stream::leaves`] of what
/// it holds there, for a caller that keeps something of its own beside each
/// element.
///
/// ```
/// use music21::{voiceleading::verticality_positions_at, Note, Stream};
///
/// let mut stream = Stream::new();
/// stream.insert(0.0, Note::from_name("C4")?);
/// stream.insert(1.0, Note::from_name("D4")?);
/// assert_eq!(verticality_positions_at(&stream, 0.5), [(0, vec![0])]);
/// # Ok::<(), music21::Error>(())
/// ```
pub fn verticality_positions_at(stream: &Stream, offset: FloatType) -> Vec<(usize, Vec<usize>)> {
    parts_by_position(stream)
        .iter()
        .enumerate()
        .filter_map(|(part, flat)| {
            let positions: Vec<usize> = flat
                .iter()
                .filter(|(_, start, element)| {
                    *start == offset
                        || (*start < offset && offset < *start + element.quarter_length())
                })
                .map(|(position, _, _)| *position)
                .collect();
            (!positions.is_empty()).then_some((part, positions))
        })
        .collect()
}

#[cfg(test)]
mod tests {

    #[test]
    fn a_resolution_is_counted_in_the_scale_the_signature_implies() {
        // music21 counts in `key.getScale(key.mode)`, which a tonic moved by
        // hand leaves on the signature: under no sharps the lower voice's B
        // is the leading note of C major whatever the tonic says, and the
        // diminished fifth does not resolve. music21 answers False for both.
        let quartet = VoiceLeadingQuartet::from_names("F4", "E4", "B3", "A3").unwrap();
        for key in [
            Key::from_tonic("C").unwrap(),
            Key::from_tonic("F#").unwrap().with_sharps(0),
        ] {
            assert!(
                !quartet
                    .clone()
                    .with_key(key)
                    .is_proper_resolution()
                    .unwrap()
            );
        }
        // Written under its own signature, F# major's B is its fourth.
        let fresh = quartet.with_key(Key::from_tonic("F#").unwrap());
        assert!(fresh.is_proper_resolution().unwrap());
    }

    #[test]
    fn a_quartet_hands_back_its_pitches_intervals_and_key() {
        use super::ParallelRequirement;
        use crate::Interval;

        let mut quartet = VoiceLeadingQuartet::from_names("C5", "D5", "C4", "D4").unwrap();
        assert_eq!(quartet.v1n1().name_with_octave(), "C5");
        assert_eq!(quartet.v1n2().name_with_octave(), "D5");
        assert_eq!(quartet.v2n1().name_with_octave(), "C4");
        assert_eq!(quartet.v2n2().name_with_octave(), "D4");
        let vertical: Vec<String> = quartet
            .vertical_intervals()
            .iter()
            .map(Interval::short_name)
            .collect();
        assert_eq!(vertical, ["P8", "P8"]);
        let horizontal: Vec<String> = quartet
            .horizontal_intervals()
            .iter()
            .map(Interval::short_name)
            .collect();
        assert_eq!(horizontal, ["M2", "M2"]);
        assert!(quartet.parallel_unison_or_octave());
        assert!(quartet.key().is_none());
        quartet.set_key(Some(Key::from_tonic("C").unwrap()));
        assert!(quartet.key().is_some());
        assert!(matches!(
            ParallelRequirement::from(8),
            ParallelRequirement::Wide(8)
        ));
        assert!(matches!(
            ParallelRequirement::from(Interval::from_name("P5").unwrap()),
            ParallelRequirement::Named(_)
        ));
    }

    #[test]
    fn opening_and_closing_incorrectly_are_the_opposites_of_the_rules() {
        let quartet = |v1n1, v1n2, v2n1, v2n2, key: &str| {
            VoiceLeadingQuartet::from_names(v1n1, v1n2, v2n1, v2n2)
                .unwrap()
                .with_key(Key::from_tonic(key).unwrap())
        };
        let opens = quartet("D", "D", "D", "F#", "D");
        assert!(opens.modal_opening().unwrap());
        assert!(!opens.opens_incorrectly().unwrap());
        let closes = quartet("B4", "C5", "D4", "C4", "C");
        assert_eq!(
            closes.closes_incorrectly().unwrap(),
            !closes.clausula_vera().unwrap()
        );
        let unkeyed = VoiceLeadingQuartet::from_names("D", "D", "D", "F#").unwrap();
        assert!(unkeyed.opens_incorrectly().is_err());
        assert!(unkeyed.closes_incorrectly().is_err());
    }

    #[test]
    fn a_modal_opening_needs_a_perfect_interval_and_a_tonic_or_dominant() {
        // music21's own examples.
        let opening = |v1n1, v1n2, v2n1, v2n2, key: &str| {
            VoiceLeadingQuartet::from_names(v1n1, v1n2, v2n1, v2n2)
                .unwrap()
                .with_key(Key::from_tonic(key).unwrap())
                .modal_opening()
                .unwrap()
        };
        assert!(opening("D", "D", "D", "F#", "D"));
        assert!(opening("B", "A", "G#", "A", "A"));
        assert!(opening("A", "A", "F#", "D", "A"));
        assert!(!opening("C#", "C#", "D", "E", "A"));
        assert!(!opening("B", "B", "A", "A", "C"));

        // Without a key there is nothing to be the tonic of.
        assert!(
            VoiceLeadingQuartet::from_names("D", "D", "D", "F#")
                .unwrap()
                .modal_opening()
                .is_err()
        );
    }

    #[test]
    #[allow(clippy::type_complexity)]
    fn proper_resolution_leaps_and_clausula_vera_match_music21() {
        let quartet = |a: &str, b: &str, c: &str, d: &str, key: Option<&str>| {
            let built = VoiceLeadingQuartet::from_names(a, b, c, d).unwrap();
            match key {
                Some(key) => built.with_key(Key::from_tonic(key).unwrap()),
                None => built,
            }
        };
        let cases: [(
            &str,
            &str,
            &str,
            &str,
            Option<&str>,
            bool,
            bool,
            Option<bool>,
        ); 20] = [
            ("C4", "B3", "F4", "E4", None, true, false, None),
            ("C4", "B3", "F4", "E4", Some("C"), true, false, Some(false)),
            ("B3", "C4", "F4", "E4", Some("C"), true, false, Some(false)),
            ("B3", "C4", "F4", "E4", None, false, false, None),
            ("F4", "E4", "B3", "C4", Some("C"), true, false, Some(false)),
            ("F4", "E4", "B3", "C4", None, true, false, None),
            ("G3", "C4", "F4", "E4", Some("C"), true, false, Some(false)),
            ("G3", "C4", "F4", "E4", Some("G"), true, false, Some(false)),
            ("C4", "C4", "E4", "E4", Some("C"), true, false, Some(false)),
            ("D4", "F4", "F4", "A4", None, true, true, None),
            ("C4", "F4", "E4", "F4", None, true, false, None),
            ("C4", "E4", "E4", "G4", None, true, true, None),
            ("C4", "E4", "E4", "C4", None, true, false, None),
            ("B3", "C4", "D4", "C4", Some("C"), true, false, Some(true)),
            ("B3", "C4", "D4", "C4", Some("G"), true, false, Some(false)),
            ("B3", "C4", "D4", "C5", Some("C"), true, false, Some(false)),
            ("F4", "E4", "G3", "C4", Some("C"), true, false, Some(false)),
            ("F4", "E4", "B3", "C4", Some("F"), true, false, Some(false)),
            ("D4", "C4", "B3", "C4", Some("C"), true, false, Some(true)),
            ("C4", "D4", "G4", "F4", None, true, false, None),
        ];
        for (a, b, c, d, key, proper, leap, clausula) in cases {
            let vlq = quartet(a, b, c, d, key);
            assert_eq!(
                vlq.is_proper_resolution().unwrap(),
                proper,
                "{a} {b} {c} {d} {key:?}"
            );
            assert_eq!(
                vlq.leap_not_set_with_step(),
                leap,
                "{a} {b} {c} {d} {key:?}"
            );
            match clausula {
                Some(expected) => assert_eq!(
                    vlq.clausula_vera().unwrap(),
                    expected,
                    "{a} {b} {c} {d} {key:?}"
                ),
                None => assert!(vlq.clausula_vera().is_err(), "{a} {b} {c} {d}"),
            }
            assert_eq!(vlq.key().is_some(), key.is_some());
        }
    }
    use super::*;

    struct Expected {
        motion: MotionType,
        with_anti_parallel: MotionType,
        flags: [bool; 15],
    }

    #[test]
    fn quartets_match_music21() {
        use MotionType::*;
        let t = true;
        let f = false;
        let cases = [
            (
                ("C4", "D4", "C3", "D3"),
                Expected {
                    motion: Parallel,
                    with_anti_parallel: Parallel,
                    flags: [f, f, t, t, f, f, f, f, f, t, f, f, f, f, f],
                },
            ),
            (
                ("C4", "D4", "E3", "F3"),
                Expected {
                    motion: Parallel,
                    with_anti_parallel: Parallel,
                    flags: [f, f, t, t, f, f, f, f, f, f, f, f, f, f, f],
                },
            ),
            (
                ("C4", "G4", "C3", "C3"),
                Expected {
                    motion: Oblique,
                    with_anti_parallel: Oblique,
                    flags: [f, t, f, f, f, f, f, f, f, f, f, f, f, f, f],
                },
            ),
            (
                ("C4", "C4", "C3", "C3"),
                Expected {
                    motion: NoMotion,
                    with_anti_parallel: NoMotion,
                    flags: [t, f, f, f, f, f, f, f, f, f, f, f, f, f, f],
                },
            ),
            (
                ("C4", "D4", "G3", "F3"),
                Expected {
                    motion: Contrary,
                    with_anti_parallel: Contrary,
                    flags: [f, f, f, f, t, t, f, f, f, f, f, f, f, f, f],
                },
            ),
            (
                ("C4", "C5", "F3", "F4"),
                Expected {
                    motion: Parallel,
                    with_anti_parallel: Parallel,
                    flags: [f, f, t, t, f, f, f, f, t, f, f, f, f, t, f],
                },
            ),
            (
                ("C5", "D5", "C4", "D4"),
                Expected {
                    motion: Parallel,
                    with_anti_parallel: Parallel,
                    flags: [f, f, t, t, f, f, f, f, f, t, f, f, f, f, f],
                },
            ),
            (
                ("C4", "D4", "G4", "A4"),
                Expected {
                    motion: Parallel,
                    with_anti_parallel: Parallel,
                    flags: [f, f, t, t, f, f, f, f, t, f, f, f, f, t, t],
                },
            ),
            (
                ("C5", "D5", "G4", "E5"),
                Expected {
                    motion: Similar,
                    with_anti_parallel: Similar,
                    flags: [f, f, t, f, f, f, f, f, f, f, f, f, f, t, t],
                },
            ),
            (
                ("E4", "F4", "C4", "A3"),
                Expected {
                    motion: Contrary,
                    with_anti_parallel: Contrary,
                    flags: [f, f, f, f, t, t, f, f, f, f, f, f, f, f, f],
                },
            ),
            (
                ("G4", "F4", "C4", "D4"),
                Expected {
                    motion: Contrary,
                    with_anti_parallel: Contrary,
                    flags: [f, f, f, f, t, f, t, f, f, f, f, f, f, f, f],
                },
            ),
            (
                ("C4", "C#4", "C3", "C#3"),
                Expected {
                    motion: Parallel,
                    with_anti_parallel: Parallel,
                    flags: [f, f, t, t, f, f, f, f, f, t, f, f, f, f, f],
                },
            ),
            (
                ("C4", "B3", "F3", "G3"),
                Expected {
                    motion: Contrary,
                    with_anti_parallel: Contrary,
                    flags: [f, f, f, f, t, f, t, f, f, f, f, f, f, f, f],
                },
            ),
            (
                ("D5", "A5", "G3", "D4"),
                Expected {
                    motion: Parallel,
                    with_anti_parallel: Parallel,
                    flags: [f, f, t, t, f, f, f, f, t, f, f, f, f, f, f],
                },
            ),
            (
                ("A4", "B4", "F4", "E4"),
                Expected {
                    motion: Contrary,
                    with_anti_parallel: Contrary,
                    flags: [f, f, f, f, t, t, f, f, f, f, f, f, f, f, f],
                },
            ),
            (
                ("C5", "C5", "E4", "F4"),
                Expected {
                    motion: Oblique,
                    with_anti_parallel: Oblique,
                    flags: [f, t, f, f, f, f, f, f, f, f, f, f, f, f, f],
                },
            ),
        ];
        for ((a, b, c, d), expected) in cases {
            let quartet = VoiceLeadingQuartet::from_names(a, b, c, d).unwrap();
            let label = format!("{a} {b} / {c} {d}");
            assert_eq!(quartet.motion_type(false), expected.motion, "{label}");
            assert_eq!(
                quartet.motion_type(true),
                expected.with_anti_parallel,
                "{label}"
            );
            let actual = [
                quartet.no_motion(),
                quartet.oblique_motion(),
                quartet.similar_motion(),
                quartet.parallel_motion(None, false),
                quartet.contrary_motion(),
                quartet.outward_contrary_motion(),
                quartet.inward_contrary_motion(),
                quartet.anti_parallel_motion(None),
                quartet.parallel_fifth(),
                quartet.parallel_octave(),
                quartet.parallel_unison(),
                quartet.hidden_fifth(),
                quartet.hidden_octave(),
                quartet.voice_overlap(),
                quartet.voice_crossing(),
            ];
            assert_eq!(actual, expected.flags, "{label}");
        }
    }

    #[test]
    fn anti_parallel_fifths_are_contrary_unless_asked_for() {
        let quartet = VoiceLeadingQuartet::from_names("G4", "D5", "C4", "G3").unwrap();
        assert_eq!(quartet.motion_type(false), MotionType::Contrary);
        assert_eq!(quartet.motion_type(true), MotionType::AntiParallel);
        assert!(quartet.parallel_fifth());
        assert_eq!(MotionType::AntiParallel.to_string(), "Anti-Parallel");
    }

    #[test]
    fn hidden_intervals_need_similar_motion_into_a_perfect_interval() {
        let quartet = VoiceLeadingQuartet::from_names("E4", "G4", "C4", "C3").unwrap();
        assert!(!quartet.hidden_fifth());
        let quartet = VoiceLeadingQuartet::from_names("E4", "D5", "C4", "G4").unwrap();
        assert!(quartet.hidden_fifth());
        assert!(!quartet.hidden_octave());
        let quartet = VoiceLeadingQuartet::from_names("E4", "C5", "C4", "C4").unwrap();
        assert!(!quartet.hidden_octave());
    }

    /// The walk over whole scores is checked against music21 by
    /// `voice_leading_parity`; this is the shape of it on two bars.
    #[test]
    fn a_score_is_walked_into_its_quartets() {
        use crate::{Duration, Note, Rest};

        let line = |notes: &[(&str, FloatType)]| {
            let mut part = Stream::with_kind(StreamKind::Part);
            for (name, length) in notes {
                let duration = Duration::new(*length).unwrap();
                if name.is_empty() {
                    part.push(Rest::new(duration));
                } else {
                    part.push(Note::from_name(*name).unwrap().with_duration(duration));
                }
            }
            part
        };
        let mut score = Stream::with_kind(StreamKind::Score);
        score.insert(
            0.0,
            line(&[("C5", 1.0), ("D5", 1.0), ("", 1.0), ("E5", 1.0)]),
        );
        score.insert(0.0, line(&[("C4", 2.0), ("G3", 2.0)]));

        let names = |options| -> Vec<String> {
            iterate_all_voice_leading_quartets(&score, options)
                .unwrap()
                .iter()
                .map(|quartet| {
                    [
                        quartet.v1n1(),
                        quartet.v1n2(),
                        quartet.v2n1(),
                        quartet.v2n2(),
                    ]
                    .map(Pitch::name_with_octave)
                    .join(" ")
                })
                .collect()
        };
        // The upper voice moves while the lower holds; then the lower moves
        // under a rest, which leaves it nothing to be paired with; and the
        // upper voice comes back out of a rest it has no note to come from.
        assert_eq!(names(QuartetOptions::default()), ["C5 D5 C4 C4"]);
        let strict = QuartetOptions {
            include_oblique: false,
            ..QuartetOptions::default()
        };
        assert!(names(strict).is_empty());

        let sounding = verticality_at(&score, 1.5);
        assert_eq!(sounding.len(), 2);
        assert_eq!(sounding[0].1[0].pitches()[0].name_with_octave(), "D5");
        assert_eq!(sounding[1].1[0].pitches()[0].name_with_octave(), "C4");
        assert!(verticality_at(&score, 9.0).is_empty());
    }
}