Cova

A Rust ecosystem for mathematical abstractions and computations, focusing on rigorous implementations of algebraic structures, topological spaces, and computational mathematics.

Overview

Cova provides a collection of crates that implement various mathematical structures and algorithms with a focus on type safety, correctness, and composability. The project aims to provide foundational mathematical tools that can be used in scientific computing, computational topology, abstract algebra, and other domains requiring robust mathematical implementations.

Examples & Demos

Cova includes interactive demos to help you get started:

🌐 Interactive Web Demos

Vietoris-Rips Complex Demo: An interactive WebAssembly demo showcasing real-time topological data analysis. Click to place points and watch simplicial complexes emerge as you adjust the distance threshold.

Design Philosophy

Type Safety: Mathematical properties are encoded in the type system where possible
Correctness: Implementations prioritize mathematical correctness over performance
Composability: Structures are designed to work together seamlessly
Documentation: Extensive mathematical documentation and examples

Crates

`cova`

The cova crate is a meta crate that re-exports the cova-space and cova-algebra crates.

`cova-space`

The cova-space crate implements topological spaces, simplicial complexes, and graph structures, providing a foundation for computational topology and geometry. It includes:

Topological Spaces: Sets, metric spaces, normed spaces, and inner product spaces
Simplicial Complexes: Simplex representation, chain complexes, and homology computations
Graph Theory: Flexible directed and undirected graph data structures
Sheaf Theory: Advanced categorical constructions for topology
Filtrations: Tools for persistent homology and topological data analysis

`cova-algebra`

The cova-algebra crate provides implementations of algebraic structures with proper type constraints and mathematical rigor. It includes:

Modular Arithmetic: Custom modular number types with the modular! macro
Abstract Algebra: Groups, rings, fields, modules, and vector spaces
Category Theory: Fundamental categorical constructions and morphisms
Tensors: Tensor algebra and operations
Linear Algebra: Vector spaces and linear transformations

Getting Started

Prerequisites

Cova requires Rust 1.70 or later.

Installation

Add the desired crates to your Cargo.toml:

[dependencies]
cova = "*"
# or if you only need one of the crates
cova-space = "*"
cova-algebra = "*"

Development Setup

Clone the repository:

git clone https://github.com/harnesslabs/cova.git
cd cova

Install just (if not already installed):

# macOS
brew install just

# Linux
curl --proto '=https' --tlsv1.2 -sSf https://just.systems/install.sh | bash -s -- --to /usr/local/bin

Run the development setup:
```
just setup
```
Build and test:
```
just test
```

Viewing Documentation

The project provides two types of documentation:

API Documentation: View the Rust API documentation for all crates:
```
just docs
```
This will build and open the Rust API documentation in your browser.
Book Documentation: View the comprehensive book documentation:
```
just book
```
This will serve the book documentation locally and open it in your browser. The book includes detailed explanations of mathematical concepts, examples, and usage guides.

For more development commands, run just --list.

Documentation

Contributing

We welcome contributions! Please check our CONTRIBUTING.md for guidelines on how to contribute to the project.

License

This project is licensed under the AGPLv3 License.

Cova Algebra

A comprehensive Rust library for abstract algebra, providing rigorous implementations of algebraic structures from basic arithmetic to advanced category theory and tensor calculus.

Overview

Cova Algebra implements the fundamental structures of abstract algebra with a focus on mathematical correctness, type safety, and composability. The crate provides a hierarchical organization of algebraic concepts, from basic arithmetic operations to advanced constructions in algebra and category theory.

Architecture

The library is structured around core mathematical concepts, with each module building upon more fundamental structures:

Core Modules

`arithmetic`

Foundation layer providing basic arithmetic operations and modular arithmetic. Includes the modular! macro for creating custom modular number types and fundamental arithmetic traits that serve as building blocks for higher-level structures.

`groups`

Group theory implementations covering both commutative (Abelian) and non-commutative groups. Provides the fundamental structure for understanding symmetry and transformation in algebra, with proper distinctions between additive and multiplicative group operations.

`rings`

Ring theory abstractions including rings, fields, and semirings. Establishes the algebraic foundation for structures that support both addition and multiplication, with fields providing division operations for advanced algebraic computations.

`modules`

Module theory over rings, including vector spaces, semimodules, and specialized constructions like tropical modules. Provides the framework for linear algebra and generalizes vector spaces to work over arbitrary rings.

Advanced Modules

`algebras`

Higher-order algebraic structures that combine vector spaces with multiplication operations. Includes Boolean algebra for logical operations and Clifford algebras for geometric applications in physics and computer graphics.

`tensors`

Multi-dimensional tensor implementations with both compile-time fixed dimensions and runtime dynamic sizing. Supports tensor operations fundamental to linear algebra, differential geometry, and machine learning applications.

`category`

Category theory primitives providing abstract mathematical frameworks for composition and morphisms. Enables advanced mathematical constructions and provides a unifying language for describing mathematical structures and their relationships.

Design Principles

Mathematical Rigor: All implementations follow strict mathematical definitions and maintain algebraic properties
Type Safety: Leverages Rust's type system to encode mathematical constraints and prevent invalid operations
Composability: Structures are designed to work together seamlessly, allowing complex mathematical constructions
Performance: Balances mathematical correctness with computational efficiency through careful API design

Usage

Add to your Cargo.toml:

[dependencies]
cova-algebra = "*"

The crate provides a comprehensive prelude for convenient importing:

#![allow(unused)]
fn main() {
use cova_algebra::prelude::*;
}

Module Hierarchy

The algebraic structures follow a natural mathematical hierarchy:

Arithmetic Operations
    ├── Groups (symmetry and transformation)
    ├── Rings & Fields (number systems)
    └── Modules & Vector Spaces (linear structures)
        ├── Algebras (vector spaces with multiplication)
        ├── Tensors (multi-dimensional arrays)

Documentation

Complete API documentation is available on docs.rs.

Contributing

Contributions are welcome! Please ensure mathematical correctness and include appropriate documentation for any new algebraic structures.

License

This project is licensed under the AGPLv3 License - see the LICENSE file for details.

Cova Space

A comprehensive Rust library for computational topology and geometric analysis, providing rigorous implementations of topological spaces, simplicial complexes, homology computation, and topological data analysis.

Overview

Cova Space implements fundamental structures and algorithms from computational topology with a focus on mathematical rigor, type safety, and performance. The crate provides a comprehensive toolkit for topological computation, from basic set operations to advanced persistent homology and sheaf-theoretic constructions.

Architecture

The library is organized around core topological concepts, building from foundational structures to sophisticated computational tools:

Core Foundations

`set`

Foundation layer providing collection abstractions and partially ordered sets (posets). Implements basic set operations, ordering relationships, and the mathematical framework for more complex topological structures.

`definitions`

Fundamental trait hierarchy for mathematical spaces including topological spaces, metric spaces, normed spaces, and inner product spaces. Establishes the interface for geometric and topological operations with proper mathematical abstractions.

Topological Complexes

`complexes`

Comprehensive implementation of cell complexes including simplicial and cubical complexes. Provides generic complex containers, automatic face relation management, and efficient storage with ID-based lattice structures for computational topology applications.

Submodules:

simplicial: Simplex definitions and simplicial complex operations
cubical: Cube definitions and cubical complex operations

`graph`

Flexible graph data structures supporting both directed and undirected graphs with comprehensive operations for vertices, edges, and topological relationships. Designed for integration with complex and homological computations.

Computational Topology

`homology`

Complete homology computation framework including chain complexes, boundary operators, and Betti number calculations. Implements formal chains with ring coefficients and supports homology computation over arbitrary fields for topological analysis.

`sheaf`

Advanced sheaf theory implementations providing categorical constructions over topological spaces. Includes restriction morphisms, global section verification, and coboundary operators for sophisticated topological data analysis.

Topological Data Analysis

`filtration`

Filtration frameworks for persistent homology including Vietoris-Rips constructions. Supports both serial and parallel computation of filtered complexes for analyzing multi-scale topological features in data.

`cloud`

Point cloud analysis tools designed for topological data analysis applications. Provides the foundation for building filtered complexes from geometric data sets.

`lattice`

Sophisticated lattice structures for efficient representation of partial orders and face relationships in complexes. Implements join/meet operations and provides the computational backbone for complex operations.

Design Principles

Mathematical Rigor: All implementations follow strict topological definitions and maintain structural invariants
Type Safety: Leverages Rust's type system to encode topological properties and prevent invalid operations
Computational Efficiency: Optimized data structures and algorithms for large-scale topological computations
Composability: Modular design allows complex topological constructions from fundamental building blocks

Usage

Add to your Cargo.toml:

[dependencies]
cova-space = "*"

The crate provides a comprehensive prelude for convenient importing:

#![allow(unused)]
fn main() {
use cova_space::prelude::*;
}

Feature Highlights

Generic Complex Framework: Unified interface for simplicial, cubical, and general cell complexes
Homology Computation: Full chain complex machinery with boundary operators and Betti number calculation
Persistent Homology: Filtration frameworks for multi-scale topological analysis
Sheaf Theory: Advanced categorical constructions for topological data analysis
High Performance: Efficient lattice-based storage and optional parallel computation support

Optional Features

parallel: Enables parallel computation for filtrations and large-scale operations using Rayon

Mathematical Scope

The library covers essential areas of computational topology:

Set Theory & Posets
    ├── Topological Spaces (metric, normed, inner product)
    ├── Cell Complexes (simplicial, cubical, general)
    ├── Homological Algebra (chains, boundaries, homology)
    ├── Sheaf Theory (categorical constructions)
    └── Topological Data Analysis (filtrations, persistence)

Documentation

Complete API documentation is available on docs.rs.

Contributing

Contributions are welcome! Please ensure mathematical correctness and include appropriate documentation for topological algorithms and data structures.

License

This project is licensed under the AGPLv3 License - see the LICENSE file for details.

Cova Examples

This directory contains interactive examples and demonstrations of the Cova computational topology library.

Available Examples

🌐 Vietoris-Rips Interactive Demo

Location: examples/vietoris_web/

An interactive web-based demonstration of Vietoris-Rips complexes that lets you:

Click to add points to a 2D plane
Right-click to remove points
Adjust the distance threshold (epsilon) with a slider
Watch simplicial complexes form in real-time

Features:

Real-time visualization of vertices, edges, and triangles
Live statistics showing complex properties
Educational tool for understanding topological data analysis

How to run:

cd examples/vietoris_web
cargo run

Then open your browser to http://localhost:3030

Technologies used:

Rust backend with cova-space for topology computation
WebAssembly for browser integration
HTML5 Canvas for visualization
Built-in web server using warp

Adding New Examples

To add a new example:

Create a new directory under examples/
Add a standalone Cargo.toml with path dependencies to the workspace crates:
```
[dependencies]
cova = { path = "../../cova" }
```
Implement your example in src/main.rs
Update this README with documentation

Requirements

Rust 2021 edition or later
For web examples: Modern browser with WebAssembly support

Educational Value

These examples are designed to:

Demonstrate practical applications of computational topology
Provide interactive learning experiences
Show integration patterns for the Cova library
Serve as starting points for your own projects

Happy exploring! 🎭✨

Vietoris-Rips Complex Web Demo

An interactive web demonstration of Vietoris-Rips complexes using the cova library.

Features

Interactive Point Placement: Click to add points, right-click to remove
Real-time Complex Computation: Uses cova to compute Vietoris-Rips complexes
Visual Simplicial Complex: See vertices, epsilon bubbles, edges, and triangles
Adjustable Epsilon: Slider to control the distance threshold

Project Structure

vietoris_web/
├── src/
│   ├── lib.rs          # WASM library using cova
│   └── main.rs         # Simple web server binary
├── index.html          # Web interface
└── Cargo.toml          # Dependencies and configuration

Quick Start

Build WASM module:
```
wasm-pack build --target web
```
Start the server:
```
cargo run --bin server
```
Open browser: Navigate to http://localhost:3030

Dependencies

The project uses target-specific dependencies:

Core: cova - The unified mathematical library
Server (native only): tokio, warp - Async web server
WASM (wasm32 only): wasm-bindgen, web-sys - WebAssembly bindings

Usage

Click anywhere on the canvas to add points
Right-click near a point to remove it
Adjust the epsilon slider to see how the complex changes
Watch as triangles form when three points are within epsilon distance

The demo showcases how cova computes Vietoris-Rips complexes in real-time!

Contributing to Cova

Thank you for your interest in contributing to Cova! This document provides guidelines and instructions for contributing to the project.

Code of Conduct

By participating in this project, you agree to abide by our Code of Conduct. Please be respectful and considerate of others.

Getting Started

Fork the repository

Clone your fork:

git clone https://github.com/yourusername/cova.git
cd cova

Set up the development environment:

# Install Rust (if not already installed)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# Install development tools
rustup component add rustfmt clippy

Development Workflow

Create a new branch for your feature/fix:

git checkout -b type/area/description
# Example: git checkout -b feat/algebra/vector-spaces

Make your changes following the Code Style guidelines

Run tests and checks:

cargo test
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings

Commit your changes following the Commit Message Format
Push your branch and create a Pull Request

Documentation

Harness provides two types of documentation that you should be familiar with:

API Documentation

The Rust API documentation for all crates can be viewed using:

just docs

This will build and open the Rust API documentation in your browser. This documentation is automatically generated from your code comments and should be kept up to date.

Book Documentation

The comprehensive book documentation can be viewed using:

just book

This will serve the book documentation locally and open it in your browser. The book includes detailed explanations of mathematical concepts, examples, and usage guides.

When contributing, please:

Keep API documentation up to date with your code changes
Update the book documentation if you add new features or change existing behavior
Add examples to both API docs and the book where appropriate
Ensure mathematical definitions and references are accurate

Issue Guidelines

When creating issues, please use the provided templates and follow these guidelines:

Title Format

type(area): brief description

Where:

type is one of: feat, fix, refactor, docs, test, chore
area is one of: algebra, space

Labels

Please use appropriate labels to categorize your issue:

Area labels: area: algebra, area: space
Priority labels: priority: critical/high/medium/low
Type labels: type: enhancement, type: refactor
Technical labels: tech: performance, tech: security, tech: testing

Pull Request Guidelines

Use the provided PR template
Ensure your PR title follows the format: type(area): description
Link related issues using closes #issue_number
Keep PRs focused and small when possible
Include tests for new features or bug fixes
Update documentation as needed

Code Style

Follow Rust's official style guide
Use rustfmt for formatting
Run cargo clippy to catch common mistakes
Document public APIs thoroughly
Use meaningful variable and function names
Keep functions focused and small

Testing

Write unit tests for all new functionality
Include examples in documentation
Run all tests before submitting PRs
Consider edge cases and error conditions

Commit Message Format

Follow this format for commit messages:

type(area): description

[optional body]

[optional footer]

Where:

type is one of: feat, fix, refactor, docs, test, chore
area is one of: algebra, space
Description is a brief summary of changes
Body provides additional context if needed
Footer references issues or PRs

Questions?

If you have any questions, feel free to:

Open an issue with the question label
Join our community discussions
Contact the maintainers

Keyboard shortcuts

Cova: Abstract Mathematics made Computational