deep_causality_linear 0.2.2

Linear algebra for the deep_causality crates: sparse, dense and bit-packed GF(2) matrices, vectors, and the algorithms over them.
Documentation
/*
 * SPDX-License-Identifier: MIT
 * Copyright (c) 2023 - 2026. The DeepCausality Authors and Contributors. All Rights Reserved.
 */

use crate::types::dense_vector::DenseVector;
use deep_causality_haft::{
    Convolutional, Foldable, Functor, HKT, MonoidalApplicative, Semigroupal,
};

/// The elementwise higher-kinded view of [`DenseVector`].
///
/// This witness stands for the same container as
/// [`DenseVectorWitness`](crate::DenseVectorWitness) and differs only in what `apply` means. The
/// two cannot be one witness, and the reason is a law rather than a preference.
///
/// `DenseVectorWitness` carries [`Monad`](deep_causality_haft::Monad), whose `bind` is list
/// concatenation. That owes the applicative/monad coherence law
/// `apply(ff, fa) == bind(ff, |f| fmap(fa, f))`, and `bind` runs the continuation once per
/// function, so coherence admits only the cartesian product: every function against every value.
/// Pairing position by position is the reading a caller usually wants from a vector, and it is a
/// different applicative, so it lives here.
///
/// # Why there is no `Pure` and no `LaxMonoidal`
///
/// The unit of a positional zip is the infinite repeat: the value that pairs with every element of
/// any vector, at any length. A finite `DenseVector` cannot represent it. Anything else invented
/// for `unit` fails the unit laws at every non-matching length rather than in some corner, so this
/// witness implements [`Semigroupal`] and stops there.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct ZipDenseVectorWitness;

impl HKT for ZipDenseVectorWitness {
    type Type<T> = DenseVector<T>;
}

impl Functor<ZipDenseVectorWitness> for ZipDenseVectorWitness {
    fn fmap<A, B, Func>(fa: DenseVector<A>, f: Func) -> DenseVector<B>
    where
        Func: FnMut(A) -> B,
    {
        DenseVector::from_vec(fa.into_data().into_iter().map(f).collect())
    }
}

impl Semigroupal<ZipDenseVectorWitness> for ZipDenseVectorWitness {
    /// Pairs the two vectors position by position, stopping at the shorter.
    ///
    /// Truncation keeps both laws: `min` is associative, so `zip` associates, and naturality holds
    /// because `fmap` does not change a vector's length.
    fn zip_with<A, B, C, Func>(
        fa: DenseVector<A>,
        fb: DenseVector<B>,
        mut f: Func,
    ) -> DenseVector<C>
    where
        Func: FnMut(A, B) -> C,
    {
        DenseVector::from_vec(
            fa.into_data()
                .into_iter()
                .zip(fb.into_data())
                .map(|(a, b)| f(a, b))
                .collect(),
        )
    }
}

impl Foldable<ZipDenseVectorWitness> for ZipDenseVectorWitness {
    /// Reduces left to right, identically to
    /// [`DenseVectorWitness`](crate::DenseVectorWitness).
    ///
    /// # Why this is not redundant
    ///
    /// The two witnesses project to the same `DenseVector<T>`, so `DenseVectorWitness::fold`
    /// already accepts whatever `zip_with` returns, with no conversion. This instance is not for
    /// reaching the elements.
    ///
    /// It is for a generic function bounded on **one** witness, `W: Semigroupal<W> + Foldable<W>`,
    /// which zips and then reduces through the same parameter. Without it such a function cannot
    /// be instantiated here, and the workaround needs two witness parameters plus a
    /// `W::Type<T> == F::Type<T>` constraint that Rust cannot express.
    ///
    /// `fold` involves no applicative, which is the only thing the two witnesses disagree about,
    /// so agreeing with `DenseVectorWitness` element for element and in order is a requirement
    /// rather than a coincidence.
    fn fold<A, B, Func>(fa: DenseVector<A>, init: B, f: Func) -> B
    where
        Func: FnMut(B, A) -> B,
    {
        fa.into_data().into_iter().fold(init, f)
    }
}

impl Convolutional<ZipDenseVectorWitness> for ZipDenseVectorWitness {}

impl MonoidalApplicative<ZipDenseVectorWitness> for ZipDenseVectorWitness {}