feat: add stats/strided/distances/dcosine-similarity

[nakul-krishnakumar]

---

type: pre_commit_static_analysis_report
description: Results of running static analysis checks when committing changes. report:

• task: lint_filenames status: passed
• task: lint_editorconfig status: passed
• task: lint_markdown status: passed
• task: lint_package_json status: passed
• task: lint_repl_help status: passed
• task: lint_javascript_src status: passed
• task: lint_javascript_cli status: na
• task: lint_javascript_examples status: passed
• task: lint_javascript_tests status: passed
• task: lint_javascript_benchmarks status: passed
• task: lint_python status: na
• task: lint_r status: na
• task: lint_c_src status: passed
• task: lint_c_examples status: passed
• task: lint_c_benchmarks status: passed
• task: lint_c_tests_fixtures status: na
• task: lint_shell status: na
• task: lint_typescript_declarations status: passed
• task: lint_typescript_tests status: passed
• task: lint_license_headers status: passed ---

Resolves None.

Description

What is the purpose of this pull request?

This pull request:

• Adds stats/strided/distances/dcosine-similarity.

Related Issues

Does this pull request have any related issues?

This pull request has the following related issues:

• None.

Questions

Any questions for reviewers of this pull request?

No.

Other

Any other information relevant to this pull request? This may include screenshots, references, and/or implementation notes.

No.

Checklist

Please ensure the following tasks are completed before submitting this pull request.

• Read, understood, and followed the contributing guidelines.

AI Assistance

When authoring the changes proposed in this PR, did you use any kind of AI assistance?

• Yes
• No

If you answered "yes" above, how did you use AI assistance?

• Code generation (e.g., when writing an implementation or fixing a bug)
• Test/benchmark generation
• Documentation (including examples)
• Research and understanding

Disclosure

If you answered "yes" to using AI assistance, please provide a short disclosure indicating how you used AI assistance. This helps reviewers determine how much scrutiny to apply when reviewing your contribution. Example disclosures: "This PR was written primarily by Claude Code." or "I consulted ChatGPT to understand the codebase, but the proposed changes were fully authored manually by myself.".

None.

---

@stdlib-js/reviewers

[nakul-krishnakumar]

/stdlib update-copyright-years

[stdlib-bot]

Coverage Report

Package	Statements	Branches	Functions	Lines
stats/strided/distances/dcosine-similarity	$\color{green}374/374$ $\color{green}+0.00%$	$\color{green}15/15$ $\color{green}+0.00%$	$\color{green}4/4$ $\color{green}+0.00%$	$\color{green}374/374$ $\color{green}+0.00%$

The above coverage report was generated for the changes in this PR.

[kgryte]

Suggested change

	> Computes the cosine similarity of two double-precision floating-point vectors.
	> Compute the cosine similarity of two double-precision floating-point strided arrays.

[kgryte]

Suggested change

	# dcosine-similarity
	# dcosineSimilarity

[kgryte]

Suggested change

	Calculates the cosine similarity of vectors `x` and `y`.
	Computes the cosine similarity of two double-precision floating-point strided arrays.

[kgryte]

Suggested change

	The `N` and strides parameters determine which elements in the strided arrays are accessed at runtime. For example, to calculate the cosine similarity of every other value in `x` and the first `N` elements of `y` in reverse order,
	The `N` and stride parameters determine which elements in the strided arrays are accessed at runtime. For example, to calculate the cosine similarity of every other value in `x` and the first `N` elements of `y` in reverse order,

[kgryte]

Suggested change

	Calculates the cosine similarity of `x` and `y` using alternative indexing semantics.
	Computes the cosine similarity of two double-precision floating-point strided arrays using alternative indexing semantics.

[kgryte]

Suggested change

	Computes the cosine similarity of two double-precision floating-point vectors.
	Computes the cosine similarity of two double-precision floating-point strided arrays.

[kgryte]

Suggested change

	Computes the cosine similarity of two double-precision floating-point vectors using alternative indexing semantics.
	Computes the cosine similarity of two double-precision floating-point strided arrays using alternative indexing semantics.

[kgryte]

Suggested change

	<!--lint ignore maximum-heading-length-->
	#### stdlib_strided_dcosine_similarity_ndarray( N, \*X, strideX, offsetX, \*Y, strideY, offsetY )
	<!--lint ignore maximum-heading-length-->
	<!--lint disable maximum-heading-length-->
	#### stdlib_strided_dcosine_similarity_ndarray( N, \*X, strideX, offsetX, \*Y, strideY, offsetY )
	<!--lint enable maximum-heading-length-->

[kgryte]

Suggested change

	#ifndef STDLIB_STATS_STRIDED_DCOSINE_SIMILARITY_H
	#ifndef STDLIB_STATS_STRIDED_DISTANCES_DCOSINE_SIMILARITY_H

This needs to match the package path. Applies here and below.

[kgryte]

Suggested change

	* Computes the cosine similarity of two double-precision floating-point vectors.
	* Computes the cosine similarity of two double-precision floating-point strided arrays.

[kgryte]

Suggested change

	* Computes the cosine similarity of two double-precision floating-point vectors using alternative indexing semantics.
	* Computes the cosine similarity of two double-precision floating-point strided arrays using alternative indexing semantics.

[kgryte]

Suggested change

	* Computes the cosine similarity of two double-precision floating-point vectors using alternative indexing semantics.
	* Computes the cosine similarity of two double-precision floating-point strided arrays using alternative indexing semantics.

This change applies here and everywhere else in this PR.

[kgryte]

Suggested change

	* @param {integer} N - number of indexed elements
	* @param {NonNegativeInteger} N - number of indexed elements

This is more to signal that users should not be providing negative integers, as they are likely the result of an error in upstream computation.

[kgryte]

Suggested change

	var den;
	if (N <= 0) {
	return 0.0;
	}
	num = ddot( N, x, strideX, offsetX, y, strideY, offsetY );
	xnrm = dnrm2( N, x, strideX, offsetX );
	ynrm = dnrm2( N, y, strideY, offsetY );
	den = xnrm * ynrm;
	return num / den;
	if ( N <= 0 ) {
	return 0.0;
	}
	dot = ddot( N, x, strideX, offsetX, y, strideY, offsetY );
	xnrm = dnrm2( N, x, strideX, offsetX );
	ynrm = dnrm2( N, y, strideY, offsetY );
	return dot / ( xnrm * ynrm );

[kgryte]

Suggested change

	var num;
	var dot;

[kgryte]

Suggested change

	"description": "Computes the cosine similarity of two double-precision floating-point vectors.",
	"description": "Compute the cosine similarity of two double-precision floating-point strided arrays.",

[kgryte]

Left some initial comments.

[kgryte]

This equation markup is not correct, but it looks like I will need to update.

[nakul-krishnakumar]

Could you please point me to the correct markup? I did not really get you. :)

[kgryte]

This example doesn't actually show anything different than the first example.

[kgryte]

Your line wrapping is off.

[kgryte]

Same comment. Doesn't show anything different.

[kgryte]

@nakul-krishnakumar How did you calculate these expected values? Did you compute via a reference implementation? Compute by hand? Something else? What we want to avoid is computing expected values via the implementation itself, in order to avoid circular testing.

[nakul-krishnakumar]

I used the below reference implementation:

function cosinesim(A, B) {
    var dot = 0;
    var mA = 0;
    var mB = 0;

    for(var i = 0; i < A.length; i++) {
        dot += A[i] * B[i];
        mA += A[i] * A[i];
        mB += B[i] * B[i];
    }

    mA = Math.sqrt(mA);
    mB = Math.sqrt(mB);
    var sim = dot / (mA * mB);

    return sim;
}


var array1 = [ 3.0, -4.0, 1.0 ];
var array2 = [ 1.0, -2.0, 3.0 ];

var p = cosinesim(array1, array2);

console.log(p);

[kgryte]

This test can be removed, as it is not applicable based on the implementation.

[kgryte]

Same comment.

[kgryte]

Same comment.

[kgryte]

Same comment.

[kgryte]

Left another round of comments. This PR is getting there. Just a bit more clean-up needed.

[nakul-krishnakumar]

Suggested change

	tape( 'if both strides are equal to `1`, the function efficiently calculates the cosine similarity', function test( t ) {
	var expected;
	var xnrm2;
	var ynrm2;
	var sim;
	var x;
	var y;
	var i;
	expected = 0.0;
	xnrm2 = 0.0;
	ynrm2 = 0.0;
	x = new Float64Array( 100 );
	y = new Float64Array( x.length );
	for ( i = 0; i < x.length; i++ ) {
	x[ i ] = i;
	y[ i ] = x.length - i;
	expected += x[ i ] * y[ i ];
	xnrm2 += x[ i ] * x[ i ];
	ynrm2 += y[ i ] * y[ i ];
	}
	expected /= sqrt( xnrm2 ) * sqrt( ynrm2 );
	sim = dcosineSimilarity( x.length, x, 1, y, 1 );
	t.strictEqual( sim, expected, 'returns expected value' );
	expected = 0.0;
	xnrm2 = 0.0;
	ynrm2 = 0.0;
	x = new Float64Array( 240 );
	y = new Float64Array( x.length );
	for ( i = 0; i < x.length; i++ ) {
	x[ i ] = i;
	y[ i ] = x.length - i;
	expected += x[ i ] * y[ i ];
	xnrm2 += x[ i ] * x[ i ];
	ynrm2 += y[ i ] * y[ i ];
	}
	expected /= sqrt( xnrm2 ) * sqrt( ynrm2 );
	sim = dcosineSimilarity( x.length, x, 1, y, 1 );
	t.strictEqual( sim, expected, 'returns expected value' );
	t.end();
	});

[nakul-krishnakumar]

Suggested change

	tape( 'if both strides are equal to `1`, the function efficiently calculates the cosine similarity', opts, function test( t ) {
	var expected;
	var xnrm2;
	var ynrm2;
	var sim;
	var x;
	var y;
	var i;
	expected = 0.0;
	xnrm2 = 0.0;
	ynrm2 = 0.0;
	x = new Float64Array( 100 );
	y = new Float64Array( x.length );
	for ( i = 0; i < x.length; i++ ) {
	x[ i ] = i;
	y[ i ] = x.length - i;
	expected += x[ i ] * y[ i ];
	xnrm2 += x[ i ] * x[ i ];
	ynrm2 += y[ i ] * y[ i ];
	}
	expected /= sqrt( xnrm2 ) * sqrt( ynrm2 );
	sim = dcosineSimilarity( x.length, x, 1, y, 1 );
	t.strictEqual( sim, expected, 'returns expected value' );
	expected = 0.0;
	xnrm2 = 0.0;
	ynrm2 = 0.0;
	x = new Float64Array( 240 );
	y = new Float64Array( x.length );
	for ( i = 0; i < x.length; i++ ) {
	x[ i ] = i;
	y[ i ] = x.length - i;
	expected += x[ i ] * y[ i ];
	xnrm2 += x[ i ] * x[ i ];
	ynrm2 += y[ i ] * y[ i ];
	}
	expected /= sqrt( xnrm2 ) * sqrt( ynrm2 );
	sim = dcosineSimilarity( x.length, x, 1, y, 1 );
	t.strictEqual( sim, expected, 'returns expected value' );
	t.end();
	});

[nakul-krishnakumar]

Suggested change

	tape( 'if both strides are equal to `1`, the function efficiently calculates the cosine similarity', function test( t ) {
	var expected;
	var xnrm2;
	var ynrm2;
	var sim;
	var x;
	var y;
	var i;
	expected = 0.0;
	xnrm2 = 0.0;
	ynrm2 = 0.0;
	x = new Float64Array( 100 );
	y = new Float64Array( x.length );
	for ( i = 0; i < x.length; i++ ) {
	x[ i ] = i;
	y[ i ] = x.length - i;
	expected += x[ i ] * y[ i ];
	xnrm2 += x[ i ] * x[ i ];
	ynrm2 += y[ i ] * y[ i ];
	}
	expected /= sqrt( xnrm2 ) * sqrt( ynrm2 );
	sim = dcosineSimilarity( x.length, x, 1, 0, y, 1, 0 );
	t.strictEqual( sim, expected, 'returns expected value' );
	expected = 0.0;
	xnrm2 = 0.0;
	ynrm2 = 0.0;
	x = new Float64Array( 240 );
	y = new Float64Array( x.length );
	for ( i = 0; i < x.length; i++ ) {
	x[ i ] = i;
	y[ i ] = x.length - i;
	expected += x[ i ] * y[ i ];
	xnrm2 += x[ i ] * x[ i ];
	ynrm2 += y[ i ] * y[ i ];
	}
	expected /= sqrt( xnrm2 ) * sqrt( ynrm2 );
	sim = dcosineSimilarity( x.length, x, 1, 0, y, 1, 0 );
	t.strictEqual( sim, expected, 'returns expected value' );
	t.end();
	});

[nakul-krishnakumar]

Suggested change

	tape( 'if both strides are equal to `1`, the function efficiently calculates the cosine similarity', opts, function test( t ) {
	var expected;
	var xnrm2;
	var ynrm2;
	var sim;
	var x;
	var y;
	var i;
	expected = 0.0;
	xnrm2 = 0.0;
	ynrm2 = 0.0;
	x = new Float64Array( 100 );
	y = new Float64Array( x.length );
	for ( i = 0; i < x.length; i++ ) {
	x[ i ] = i;
	y[ i ] = x.length - i;
	expected += x[ i ] * y[ i ];
	xnrm2 += x[ i ] * x[ i ];
	ynrm2 += y[ i ] * y[ i ];
	}
	expected /= sqrt( xnrm2 ) * sqrt( ynrm2 );
	sim = dcosineSimilarity( x.length, x, 1, 0, y, 1, 0 );
	t.strictEqual( sim, expected, 'returns expected value' );
	expected = 0.0;
	xnrm2 = 0.0;
	ynrm2 = 0.0;
	x = new Float64Array( 240 );
	y = new Float64Array( x.length );
	for ( i = 0; i < x.length; i++ ) {
	x[ i ] = i;
	y[ i ] = x.length - i;
	expected += x[ i ] * y[ i ];
	xnrm2 += x[ i ] * x[ i ];
	ynrm2 += y[ i ] * y[ i ];
	}
	expected /= sqrt( xnrm2 ) * sqrt( ynrm2 );
	sim = dcosineSimilarity( x.length, x, 1, 0, y, 1, 0 );
	t.strictEqual( sim, expected, 'returns expected value' );
	t.end();
	});