Skip to main content

Toolbox that provides functions and data structures to generate and handle ultrametric matrices.

Project description

Ultrametric matrix tools

This toolbox provides functions and data structures to construct and handle ultrametric matrices in Rust and Python. The aim of the project is to provide efficient tools for ultrametric matrices and ultrametric trees. Currently, the project has the following features.

Features:

  • Generate a random ultrametric matrix
  • Test ultramtic matrix property
  • Construct the ultrametric tree from the ultrametric matrix
  • Get properties of ultrametric tree
  • Fast multiplication of ultrametric matrix with vector

The implementation is written in Rust and can be cross-compiled to Python.

Table of Contents

Quickstart

Quickstart Rust

Add the following to the Cargo.toml file:

[dependencies]
# TODO: replace the * by the latest version.
ultrametric_matrix_tools = "*"

An example of the usage of is:

use ultrametric_matrix_tools::na::{DMatrix, DVector};
use ultrametric_matrix_tools::UltrametricTree;

fn main() {
    let matrix = DMatrix::from_vec(
        4,
        4,
        vec![
            0.0, 1.0, 3.0, 1.0, 1.0, 3.0, 1.0, 1.0, 3.0, 1.0, 5.0, 1.0, 1.0, 1.0, 1.0, 1.0,
        ],
    );
    let vector = DVector::from_vec(vec![4.0, 2.0, 7.0, 5.0]);

    let tree = UltrametricTree::from_matrix(&matrix);
    let product = tree * vector;
}

More examples can be found in ./examples/.

Quickstart Python

You can install the current release by running:

pip install ultrametric_matrix_tools

An example of the construction of the ultrametric tree and multiplication with it is:

from ultrametric_matrix_tools import UltrametricTree
import numpy as np

matrix = np.array([[0.0, 1.0, 3.0, 1.0], [1.0, 3.0, 1.0, 1.0], [
                  3.0, 1.0, 5.0, 1.0], [1.0, 1.0, 1.0, 1.0]])
vector = np.array([4.0, 2.0, 7.0, 5.0])

tree = UltrametricTree(matrix)
product = tree.mult(vector)

More examples can be found in ./examples/.

Build

Build Rust Library

The Rust library is build by running:

cargo build --release

The compiled Rust library is located in ./target/release/ and can be copied from there.

Build Python Module

The Python module is build from the Rust code using the PyO3. To build the Python module, you need to install Cargo and run:

cargo build --release

The compiled Python module is located in ./target/release/ and can be copied from there.

To export the Python wheels from a Linux host system run the following commands:

Linux (requires docker):

docker run --rm -v $(pwd):/io konstin2/maturin build --release

Windows (requires mingw32-python and mingw64-python):

make python_package_windows

Currently, cross-compiling to macOS is not supported.

Examples

Rust Example

You can try out the Rust examples, you need to install Cargo. You can try out the Python examples located in ./examples/ by running the following command:

cargo run --release --example [example_name]

E.g. to run the multiplication example run:

cargo run --release --example multiplication

Python Example

To run the Python examples, you need to install Cargo. You can try out the Python examples located in ./examples/ by running the following command:

make python_example name=[example_name]

E.g. to run the multiplication example run:

make python_example name=multiplication

Alternatively, if you have the Python package already installed via pip, then you can run the examples directly:

python [example_name].py

License

This project is under the Apache-2.0 license.

Benchmarks

The benchmarks use criterion for cargo, which can be installed by running:

cargo install cargo-criterion

The benchmarks can be found in ./benches and are run by:

cargo criterion --bench [benchmark_name]

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

ultrametric_matrix_tools-0.1.1.tar.gz (31.3 kB view details)

Uploaded Source

Built Distribution

ultrametric_matrix_tools-0.1.1-cp36-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.whl (568.0 kB view details)

Uploaded CPython 3.6+ manylinux: glibc 2.5+ x86-64

File details

Details for the file ultrametric_matrix_tools-0.1.1.tar.gz.

File metadata

  • Download URL: ultrametric_matrix_tools-0.1.1.tar.gz
  • Upload date:
  • Size: 31.3 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.26.0 requests-toolbelt/0.9.1 urllib3/1.26.6 tqdm/4.62.2 importlib-metadata/4.6.3 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.9.9

File hashes

Hashes for ultrametric_matrix_tools-0.1.1.tar.gz
Algorithm Hash digest
SHA256 e1ac41b9a65f1423ee300becac15fc141372244c65fd03f5a0f40a6e9c509a57
MD5 f86875b71ef2d075d64fb5ad4eb0cc4a
BLAKE2b-256 e0f3a2cea70cf9cf049d00bf0e229ad6ec42b990ced25cedb395c82e08597bff

See more details on using hashes here.

File details

Details for the file ultrametric_matrix_tools-0.1.1-cp36-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.whl.

File metadata

  • Download URL: ultrametric_matrix_tools-0.1.1-cp36-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.whl
  • Upload date:
  • Size: 568.0 kB
  • Tags: CPython 3.6+, manylinux: glibc 2.5+ x86-64
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.26.0 requests-toolbelt/0.9.1 urllib3/1.26.6 tqdm/4.62.2 importlib-metadata/4.6.3 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.9.9

File hashes

Hashes for ultrametric_matrix_tools-0.1.1-cp36-abi3-manylinux_2_5_x86_64.manylinux1_x86_64.whl
Algorithm Hash digest
SHA256 b3340288fc1f01eb450bb00e606e98455227421cfa6be813576d3977255e1064
MD5 9f54a75bdb341246e24caf52436e9362
BLAKE2b-256 4f1e968962755293e556bb8fc70f106ecbc42cf583529df33df04f33e8cf1063

See more details on using hashes here.

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page