{"id":26321232,"url":"https://github.com/asherjingkongchen/floating-distance","last_synced_at":"2025-03-15T16:16:43.935Z","repository":{"id":193333057,"uuid":"687716240","full_name":"AsherJingkongChen/floating-distance","owner":"AsherJingkongChen","description":"Measure distance between floating-point vectors in Rust","archived":false,"fork":false,"pushed_at":"2024-07-23T15:06:25.000Z","size":53,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-02-28T15:01:13.923Z","etag":null,"topics":["algorithm","distance","embedding","mathematics","rust","simd","vector"],"latest_commit_sha":null,"homepage":"https://docs.rs/floating-distance","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AsherJingkongChen.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-09-05T21:21:34.000Z","updated_at":"2023-09-26T07:51:38.000Z","dependencies_parsed_at":"2023-09-07T19:33:38.322Z","dependency_job_id":"29a29ae3-5acd-4522-b659-d0edfc20fbe7","html_url":"https://github.com/AsherJingkongChen/floating-distance","commit_stats":null,"previous_names":["asherjingkongchen/distance"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AsherJingkongChen%2Ffloating-distance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AsherJingkongChen%2Ffloating-distance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AsherJingkongChen%2Ffloating-distance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AsherJingkongChen%2Ffloating-distance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AsherJingkongChen","download_url":"https://codeload.github.com/AsherJingkongChen/floating-distance/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243754071,"owners_count":20342543,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["algorithm","distance","embedding","mathematics","rust","simd","vector"],"created_at":"2025-03-15T16:16:43.007Z","updated_at":"2025-03-15T16:16:43.930Z","avatar_url":"https://github.com/AsherJingkongChen.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Measure distance between floating-point vectors in Rust\n[\u003cimg alt=\"crates.io\" src=\"https://img.shields.io/crates/v/floating-distance.svg?color=fe7d37\u0026logo=rust\" height=\"20\"\u003e](https://crates.io/crates/floating-distance)\n[\u003cimg alt=\"docs.rs\" src=\"https://docs.rs/floating-distance/badge.svg\" height=\"20\"\u003e](https://docs.rs/floating-distance/)\n[\u003cimg alt=\"coverage\" src=\"https://img.shields.io/codecov/c/github/AsherJingkongChen/floating-distance?logo=codecov\" height=\"20\"\u003e](https://app.codecov.io/gh/AsherJingkongChen/floating-distance)\n[\u003cimg alt=\"GitHub Actions\" src=\"https://github.com/AsherJingkongChen/floating-distance/actions/workflows/main.yml/badge.svg\" height=\"20\"\u003e](https://github.com/AsherJingkongChen/floating-distance/actions/workflows/main.yml)\n\n## Hello Rustaceans!\nThis is a Rust library. Here you can do:\n1. Add this crate as a dependency of your Rust project:\n```shell\ncargo add floating-distance\n```\n2. Check out the [documentation](https://docs.rs/floating-distance) and\n[source codes](https://github.com/AsherJingkongChen/floating-distance.git) (click the badges above for more information)\n3. Clone the GitHub repository and run the examples:\n```shell\ncargo run --example default\n```\n\n## Examples\n1. Measure the cosine similarity between two vectors `v0` and `v1`\n```rust\nuse floating_distance::*;\n\nfn main() {\n  let v0: \u0026[f32] = \u0026[1.0, 2.0, 2.0, 1.0, 2.0, 1.0, 1.0];\n  let v1: \u0026[f32] = \u0026[2.0, 1.0, 1.0, 1.0, 2.0, 1.0, 2.0];\n  let metric = Metric::Cosine;\n  let result = metric.measure::\u003cf32\u003e(v0, v1);\n  let expectation: f32 = 14.0 / (4.0 * 4.0);\n\n  assert_eq!(result, expectation);\n}\n```\n\n## feature = [\"simd\"]\n### What's special about SIMD?\nSIMD is the acronym for **S**ingle **I**nstruction **M**ultiple **D**ata\n\nModern CPUs have special instructions. We can use them to accelerate vector computations!\n\n### How to enable SIMD?\nYou can enable `simd` feature in this crate by the following steps:\n1. Specify `features = [\"simd\"]` in `Cargo.toml` manifest:\n```ini\n[dependencies]\nfloating-distance = { version = \"*\", features = [\"simd\"] }\n```\n2. Compile with Rust nightly version. You can add this to `rust-toolchain.toml`, which is next to `Cargo.toml`:\n```ini\n[toolchain]\nchannel = \"nightly\"\n```\n3. **(Optional)** Choose the SIMD instruction sets which are supported by the target architecture. You can use `RUSTFLAGS` environment variable and `-C target-feature` compiler option like these:\n```shell\nRUSTFLAGS=\"-C target-feature=+ssse3\" cargo build\n```\n```shell\nRUSTFLAGS=\"-C target-feature=+avx,+sse3\" cargo build --release\n```\nYou can find all target features of Rust by this:\n```shell\nrustc --print target-features\n```\n\n### How powerful is SIMD?\nI have run a simple benchmark on my laptop (architecture: `aarch64-apple-darwin`).\nThe SIMD instruction set is NEON.\n\nLet's check out the results first!\n\n- SIMD vs No SIMD (single-precision floating-point type):\n```log\nno_simd: 198,306 ns/iter (+/- 5,173)\nsimd:    18,430 ns/iter (+/- 655)\n```\nType | Avarage time (ns/iter) | Rate (relative)\n--- | --- | ---\nNo SIMD | 198306 | 1.00\nSIMD | 18430 | 10.76\n\nAs the data shown, we can see that SIMD can improve the performance significantly!\n\nYou can also benchmark it by repeating the following steps:\n1. Clone the repository and change it to the current directory\n2. Check target features in `.cargo/config.toml`\n3. Run this command:\n```shell\n(cargo +nightly bench -p benchmarks-no-simd \u0026\u0026\n cargo +nightly bench -p benchmarks-simd) 2\u003e /dev/null\n```\n\n### Note for SIMD feature\n1. This feature is built by experimental features of Rust standard library, `portable-simd`.\n2. If a program is built with target features which are not supported by the target architecture, it may lead to runtime errors.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasherjingkongchen%2Ffloating-distance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fasherjingkongchen%2Ffloating-distance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fasherjingkongchen%2Ffloating-distance/lists"}