solverforge_solver/heuristic/selector/

selection_order.rs

/* Selection order configuration for selectors.

Defines the order in which elements are selected from a selector.
*/

/* Defines the order in which elements are selected from a selector.

This enum controls how entities, values, or moves are ordered when
iterating through a selector.
*/
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Default)]
pub enum SelectionOrder {
    /* Inherit the selection order from the parent configuration.

    If the parent is cached, defaults to `Original`.
    If there is no parent, defaults to `Random`.
    */
    #[default]
    Inherit,

    /* Select elements in their original order.

    Elements are returned in the order they appear in the underlying
    collection. This is deterministic and reproducible.
    */
    Original,

    /* Select elements in random order without shuffling.

    Elements are selected randomly from the pool on each call to next().
    The same element may be selected multiple times.
    This scales well because it does not require caching.
    */
    Random,

    /* Select elements in random order by shuffling.

    Elements are shuffled when a selection iterator is created.
    Each element will be selected exactly once (if all elements are consumed).
    Requires caching (at least step-level).
    */
    Shuffled,

    /* Select elements in sorted order.

    Elements are sorted according to a sorter before iteration.
    Each element will be selected exactly once (if all elements are consumed).
    Requires caching (at least step-level).
    */
    Sorted,

    /* Select elements based on probability weights.

    Elements with higher probability have a greater chance of being selected.
    The same element may be selected multiple times.
    Requires caching (at least step-level).
    */
    Probabilistic,
}

impl SelectionOrder {
    /// Resolves the selection order by inheriting from a parent if necessary.
    ///
    /// # Arguments
    ///
    /// * `inherited` - The selection order to inherit from if this is `Inherit`
    ///
    /// # Returns
    ///
    /// The resolved selection order (never `Inherit`)
    pub fn resolve(self, inherited: SelectionOrder) -> SelectionOrder {
        match self {
            SelectionOrder::Inherit => {
                if inherited == SelectionOrder::Inherit {
                    SelectionOrder::Random
                } else {
                    inherited
                }
            }
            other => other,
        }
    }

    /// Returns `true` if this selection order implies random selection.
    ///
    /// This is used to determine whether a selector should use random iteration
    /// or deterministic iteration.
    pub fn is_random(&self) -> bool {
        matches!(
            self,
            SelectionOrder::Random | SelectionOrder::Shuffled | SelectionOrder::Probabilistic
        )
    }

    /// Returns `true` if this selection order requires caching.
    ///
    /// Some selection orders need to collect all elements before iteration
    /// can begin (e.g., Shuffled, Sorted, Probabilistic).
    pub fn requires_caching(&self) -> bool {
        matches!(
            self,
            SelectionOrder::Shuffled | SelectionOrder::Sorted | SelectionOrder::Probabilistic
        )
    }

    /// Converts from a boolean random selection flag.
    ///
    /// # Arguments
    ///
    /// * `random` - `true` for `Random`, `false` for `Original`
    pub fn from_random_selection(random: bool) -> Self {
        if random {
            SelectionOrder::Random
        } else {
            SelectionOrder::Original
        }
    }

    /// Converts to a boolean random selection flag.
    ///
    /// # Panics
    ///
    /// Panics if this is not `Random` or `Original`.
    pub fn to_random_selection(&self) -> bool {
        match self {
            SelectionOrder::Random => true,
            SelectionOrder::Original => false,
            _ => panic!(
                "Selection order {:?} cannot be converted to a random selection boolean",
                self
            ),
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_resolve_inherit_from_random() {
        let order = SelectionOrder::Inherit;
        assert_eq!(
            order.resolve(SelectionOrder::Random),
            SelectionOrder::Random
        );
    }

    #[test]
    fn test_resolve_inherit_from_original() {
        let order = SelectionOrder::Inherit;
        assert_eq!(
            order.resolve(SelectionOrder::Original),
            SelectionOrder::Original
        );
    }

    #[test]
    fn test_resolve_inherit_from_inherit() {
        let order = SelectionOrder::Inherit;
        // When inheriting from Inherit, default to Random
        assert_eq!(
            order.resolve(SelectionOrder::Inherit),
            SelectionOrder::Random
        );
    }

    #[test]
    fn test_resolve_non_inherit() {
        let order = SelectionOrder::Original;
        // Non-inherit should not change
        assert_eq!(
            order.resolve(SelectionOrder::Random),
            SelectionOrder::Original
        );
    }

    #[test]
    fn test_is_random() {
        assert!(SelectionOrder::Random.is_random());
        assert!(SelectionOrder::Shuffled.is_random());
        assert!(SelectionOrder::Probabilistic.is_random());

        assert!(!SelectionOrder::Original.is_random());
        assert!(!SelectionOrder::Sorted.is_random());
        assert!(!SelectionOrder::Inherit.is_random());
    }

    #[test]
    fn test_requires_caching() {
        assert!(SelectionOrder::Shuffled.requires_caching());
        assert!(SelectionOrder::Sorted.requires_caching());
        assert!(SelectionOrder::Probabilistic.requires_caching());

        assert!(!SelectionOrder::Original.requires_caching());
        assert!(!SelectionOrder::Random.requires_caching());
        assert!(!SelectionOrder::Inherit.requires_caching());
    }

    #[test]
    fn test_from_random_selection() {
        assert_eq!(
            SelectionOrder::from_random_selection(true),
            SelectionOrder::Random
        );
        assert_eq!(
            SelectionOrder::from_random_selection(false),
            SelectionOrder::Original
        );
    }

    #[test]
    fn test_to_random_selection() {
        assert!(SelectionOrder::Random.to_random_selection());
        assert!(!SelectionOrder::Original.to_random_selection());
    }

    #[test]
    #[should_panic(expected = "cannot be converted")]
    fn test_to_random_selection_panics_on_shuffled() {
        SelectionOrder::Shuffled.to_random_selection();
    }

    #[test]
    fn test_default() {
        assert_eq!(SelectionOrder::default(), SelectionOrder::Inherit);
    }
}