libitofin 0.52.1

use crate::errors::QlResult;
use crate::require;

/// Maximum supported sample dimension.
pub const MAX_SEQUENCE_DIMENSION: usize = 256;
/// Maximum row/component-pair work for a matrix query.
pub const MAX_SEQUENCE_MATRIX_WORK: usize = 100_000_000;

/// Vector or matrix statistic computed from weighted sample rows.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum SequenceStatistic {
    /// Weighted arithmetic mean per component.
    Mean,
    /// Count-corrected variance per component.
    Variance,
    /// Square root of the component variances.
    StandardDeviation,
    /// Component standard deviations divided by the square root of row count.
    ErrorEstimate,
    /// Minimum component values, including zero-weight rows.
    Minimum,
    /// Maximum component values, including zero-weight rows.
    Maximum,
    /// Count-corrected covariance in flattened row-major matrix order.
    Covariance,
    /// Correlation in flattened row-major matrix order.
    Correlation,
}

/// Validate sample shape and bounded query work, returning the output length.
///
/// # Errors
///
/// Rejects empty rows, dimensions outside `1..=MAX_SEQUENCE_DIMENSION`,
/// overflowing products, and matrix work above [`MAX_SEQUENCE_MATRIX_WORK`].
/// Like QuantLib's `SequenceStatistics`, the row count is otherwise unbounded.
pub fn validate_sequence_shape(
    rows: usize,
    dimension: usize,
    measure: SequenceStatistic,
) -> QlResult<usize> {
    require!(
        dimension > 0 && dimension <= MAX_SEQUENCE_DIMENSION,
        "sequence dimension must be in 1..={MAX_SEQUENCE_DIMENSION}"
    );
    require!(rows > 0, "sequence rows must be positive");
    require!(
        rows.checked_mul(dimension).is_some(),
        "sequence component count overflow"
    );
    if matches!(
        measure,
        SequenceStatistic::Covariance | SequenceStatistic::Correlation
    ) {
        let size = dimension * dimension;
        require!(
            rows.checked_mul(size)
                .is_some_and(|work| work <= MAX_SEQUENCE_MATRIX_WORK),
            "sequence matrix work limit exceeded"
        );
        Ok(size)
    } else {
        Ok(dimension)
    }
}