feat: add `blas/ext/circshift` by headlessNode · Pull Request #11189 · stdlib-js/stdlib

headlessNode · 2026-03-28T14:34:59Z

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: na
task: lint_c_examples status: na
task: lint_c_benchmarks status: na
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 stdlib-js/metr-issue-tracker#257.

Description

What is the purpose of this pull request?

This pull request:

add blas/ext/base/circshift

Related Issues

Does this pull request have any related issues?

This pull request has the following related issues:

Resolves [RFC]: add blas/ext/circshift metr-issue-tracker#257

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.".

Primarily written by Claude Code. Note: AI incorrectly created a malformed test file, and hallucinated a bit with the typescript declarations.

@stdlib-js/reviewers

--- 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: na - task: lint_c_examples status: na - task: lint_c_benchmarks status: na - 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 ---

stdlib-bot · 2026-03-28T14:37:59Z

Coverage Report

Package	Statements	Branches	Functions	Lines
blas/ext/circshift	$\color{green}297/297$ $\color{green}+100.00%$	$\color{green}19/19$ $\color{green}+100.00%$	$\color{green}1/1$ $\color{green}+100.00%$	$\color{green}297/297$ $\color{green}+100.00%$

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

kgryte · 2026-03-28T22:15:01Z

lib/node_modules/@stdlib/blas/ext/circshift/docs/types/index.d.ts

+/**
+* Circularly shifts the elements of an input ndarray along one or more ndarray dimensions by a specified number of positions.
+*/
+type Circshift = <T = unknown>( x: typedndarray<T>, k: K, options?: Options ) => typedndarray<T>;


This is not how we document packages which export a function. See

stdlib/lib/node_modules/@stdlib/array/empty/docs/types/index.d.ts

Line 46 in 80a1fc1

declare function empty<T extends keyof DataTypeMap<number> = 'float64'>( length: number, dtype?: T ): DataTypeMap<number>[T];

.

There is no need for a dedicated type.

Furthermore, this definition is not correct. You are losing type information. This is a recurring theme for you in TS definitions; it would be good to upskill a bit here.

Given that this function returns the input ndarray, the output value should preserve the specific type of the input ndarray.

kgryte · 2026-03-28T22:16:20Z

lib/node_modules/@stdlib/blas/ext/circshift/docs/types/index.d.ts

+/**
+* Number of positions to shift.
+*/
+type K = integerndarray | number;


Suggested change

type K = integerndarray | number;

type K = typedndarray<number> | number;

There is no need to limit to ndarrays having integer dtypes.

kgryte · 2026-03-28T22:16:42Z

lib/node_modules/@stdlib/blas/ext/circshift/docs/types/index.d.ts

+* @param x - input ndarray
+* @param k - number of positions to shift
+* @param options - function options
+* @returns output ndarray


Suggested change

* @returns output ndarray

* @returns input ndarray

kgryte · 2026-03-28T22:19:51Z

lib/node_modules/@stdlib/blas/ext/circshift/docs/types/test.ts

+	circshift( x, 2 ); // $ExpectType typedndarray<number>
+	circshift( x, 2, {} ); // $ExpectType typedndarray<number>


The tests need to be updated here.

kgryte · 2026-03-28T22:22:58Z

lib/node_modules/@stdlib/blas/ext/circshift/docs/repl.txt

+    A positive `k` shifts elements to the right (toward higher indices). A
+    negative `k` shifts elements to the left (toward lower indices). If `k` is
+    zero, the input ndarray is left unchanged.


The language of "higher" and "lower" indices only makes sense in the case where dims refers to a single dimension. What about when you shift over multiple dimensions?

If you want to keep this language, you could say something like

Suggested change

A positive `k` shifts elements to the right (toward higher indices). A

negative `k` shifts elements to the left (toward lower indices). If `k` is

zero, the input ndarray is left unchanged.

When shifting elements along a single dimension, a positive `k` shifts elements to the right (toward higher indices), and a negative `k` shifts elements to the left (toward lower indices).

If `k` is zero, the input ndarray is left unchanged.

kgryte · 2026-03-28T22:23:30Z

lib/node_modules/@stdlib/blas/ext/circshift/docs/repl.txt

+
+    k: ndarray|number
+        Number of positions to shift. May be either a scalar value or an
+        ndarray having an integer data type. If provided an ndarray, the value


Suggested change

ndarray having an integer data type. If provided an ndarray, the value

ndarray having a real-valued or "generic" data type. If provided an ndarray, the value

kgryte · 2026-03-28T22:28:08Z

lib/node_modules/@stdlib/blas/ext/circshift/examples/index.js

+
+'use strict';
+
+var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );


Use random/discrete-uniform. We don't need to be doing the whole random/array, new ndarray dance. For future examples, especially for top-level packages, prefer using the more concise APIs.

kgryte · 2026-03-28T22:28:37Z

lib/node_modules/@stdlib/blas/ext/circshift/lib/base.js

+// VARIABLES //
+
+var idtypes0 = dtypes( 'all' );     // input ndarray
+var idtypes1 = dtypes( 'integer' ); // k ndarray


Suggested change

var idtypes1 = dtypes( 'integer' ); // k ndarray

var idtypes1 = dtypes( 'real_and_generic' ); // k ndarray

You'll need to realign comments.

kgryte · 2026-03-28T22:31:11Z

lib/node_modules/@stdlib/blas/ext/circshift/lib/index.js

+'use strict';
+
+/**
+* Circularly shift the elements of an input ndarray along one or more ndarray dimensions by a specified number of positions.


Suggested change

* Circularly shift the elements of an input ndarray along one or more ndarray dimensions by a specified number of positions.

* Circularly shift the elements of an input ndarray by a specified number of positions along one or more ndarray dimensions.

Applies here and everywhere else in this PR.

kgryte · 2026-03-28T22:31:55Z

lib/node_modules/@stdlib/blas/ext/circshift/lib/main.js

+	// Case: circshift( x, k )
+	if ( nargs === 2 ) {
+		// Case: circshift( x, k_scalar )
+		if ( isNumber( o ) ) {


Why are you only enforcing isNumber here? Can we not use isInteger, instead?

There's obviously a bit of tension with enforcing an integer k, but allowing any real-valued ndarray, but that should be fine for now. What we want to avoid is disallowing things like providing a "generic" ndarray, and we don't atm want to be in the game of having to perform a bunch of element-wise validation. The dominant use case will be an integer k, so I think it is fine to be a bit more strict here for that scenario.

kgryte · 2026-03-28T22:36:03Z

lib/node_modules/@stdlib/blas/ext/circshift/test/test.js

+	}
+});
+
+tape( 'the function throws an error if provided a `k` argument which is not an ndarray-like object or a numeric scalar (options)', function test( t ) {


The use of "numeric scalar" should be updated here and elsewhere. It should be "integer".

kgryte · 2026-03-28T22:37:35Z

lib/node_modules/@stdlib/blas/ext/circshift/test/test.js

+	expected = [ 4.0, 1.0, 2.0, 3.0 ];
+
+	t.strictEqual( actual, x, 'returns expected value' );
+	t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );


This is incorrect. To test for dtype equality like this, you always need to do

Suggested change

t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );

t.strictEqual( String( getDType( actual ) ), 'generic', 'returns expected value' );

Applies here and elsewhere.

kgryte · 2026-03-28T22:40:30Z

lib/node_modules/@stdlib/blas/ext/circshift/test/test.js

+tape( 'the function supports typed array inputs', function test( t ) {
+	var expected;
+	var actual;
+	var xbuf;
+	var x;
+
+	xbuf = new Float64Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
+	x = new ndarray( 'float64', xbuf, [ 6 ], [ 1 ], 0, 'row-major' );
+
+	actual = circshift( x, 2 );
+	expected = new Float64Array( [ 5.0, 6.0, 1.0, 2.0, 3.0, 4.0 ] );
+
+	t.strictEqual( actual, x, 'returns expected value' );
+	t.strictEqual( getDType( actual ), 'float64', 'returns expected value' );
+	t.strictEqual( isSameFloat64Array( getData( actual ), expected ), true, 'returns expected value' );
+
+	xbuf = new Float32Array( [ 1.0, 2.0, 3.0, 4.0, 5.0, 6.0 ] );
+	x = new ndarray( 'float32', xbuf, [ 6 ], [ 1 ], 0, 'row-major' );
+
+	actual = circshift( x, 2 );
+	expected = new Float32Array( [ 5.0, 6.0, 1.0, 2.0, 3.0, 4.0 ] );
+
+	t.strictEqual( actual, x, 'returns expected value' );
+	t.strictEqual( getDType( actual ), 'float32', 'returns expected value' );
+	t.strictEqual( isSameFloat32Array( getData( actual ), expected ), true, 'returns expected value' );
+
+	t.end();
+});


Remove this. This is not needed.

kgryte · 2026-03-28T22:40:48Z

lib/node_modules/@stdlib/blas/ext/circshift/test/test.js

+	t.end();
+});
+
+tape( 'the function supports large shift values (k > N)', function test( t ) {


Suggested change

tape( 'the function supports large shift values (k > N)', function test( t ) {

tape( 'the function supports large shift values (|k| > N)', function test( t ) {

kgryte · 2026-03-28T22:41:46Z

lib/node_modules/@stdlib/blas/ext/circshift/README.md

+The function has the following parameters:
+
+-   **x**: input [ndarray][@stdlib/ndarray/ctor].
+-   **k**: number of positions to shift. May be either a numeric scalar value or an [ndarray][@stdlib/ndarray/ctor] having an integer [data type][@stdlib/ndarray/dtypes]. If provided an [ndarray][@stdlib/ndarray/ctor], the value must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the complement of the shape defined by `options.dims`. For example, given the input shape `[2, 3, 4]` and `options.dims=[0]`, an [ndarray][@stdlib/ndarray/ctor] for `k` must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the shape `[3, 4]`. Similarly, when performing the operation over all elements in a provided input [ndarray][@stdlib/ndarray/ctor], an [ndarray][@stdlib/ndarray/ctor] for `k` must be a zero-dimensional [ndarray][@stdlib/ndarray/ctor].


Suggested change

- **k**: number of positions to shift. May be either a numeric scalar value or an [ndarray][@stdlib/ndarray/ctor] having an integer [data type][@stdlib/ndarray/dtypes]. If provided an [ndarray][@stdlib/ndarray/ctor], the value must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the complement of the shape defined by `options.dims`. For example, given the input shape `[2, 3, 4]` and `options.dims=[0]`, an [ndarray][@stdlib/ndarray/ctor] for `k` must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the shape `[3, 4]`. Similarly, when performing the operation over all elements in a provided input [ndarray][@stdlib/ndarray/ctor], an [ndarray][@stdlib/ndarray/ctor] for `k` must be a zero-dimensional [ndarray][@stdlib/ndarray/ctor].

- **k**: number of positions to shift. May be either an integer scalar value or an [ndarray][@stdlib/ndarray/ctor] having a real-valued or "generic" [data type][@stdlib/ndarray/dtypes]. If provided an [ndarray][@stdlib/ndarray/ctor], the value must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the complement of the shape defined by `options.dims`. For example, given the input shape `[2, 3, 4]` and `options.dims=[0]`, an [ndarray][@stdlib/ndarray/ctor] for `k` must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the shape `[3, 4]`. Similarly, when performing the operation over all elements in a provided input [ndarray][@stdlib/ndarray/ctor], an [ndarray][@stdlib/ndarray/ctor] for `k` must be a zero-dimensional [ndarray][@stdlib/ndarray/ctor].

kgryte · 2026-03-28T22:42:08Z

lib/node_modules/@stdlib/blas/ext/circshift/README.md

+## Notes
+
+-   The input [ndarray][@stdlib/ndarray/ctor] is shifted **in-place** (i.e., the input [ndarray][@stdlib/ndarray/ctor] is **mutated**).
+-   A positive `k` shifts elements to the right (toward higher indices). A negative `k` shifts elements to the left (toward lower indices). If `k` is zero, the input [ndarray][@stdlib/ndarray/ctor] is left unchanged.


Same comment as REPL help.

kgryte · 2026-03-28T22:42:34Z

lib/node_modules/@stdlib/blas/ext/circshift/README.md

+<!-- eslint no-undef: "error" -->
+
+```javascript
+var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );


Same comment as elsewhere.

kgryte

Initial review. This PR needs quite a bit of clean-up.

kgryte · 2026-03-28T22:43:13Z

For METR,

review_time: 32 minutes

stdlib-bot added BLAS Issue or pull request related to Basic Linear Algebra Subprograms (BLAS). Needs Review A pull request which needs code review. labels Mar 28, 2026

headlessNode added Feature Issue or pull request for adding a new feature. METR Pull request associated with the METR project. labels Mar 28, 2026

headlessNode requested a review from kgryte March 28, 2026 14:36

github-actions bot mentioned this pull request Mar 28, 2026

[aw] No-Op Runs #11033

Open

kgryte removed the Needs Review A pull request which needs code review. label Mar 28, 2026

kgryte reviewed Mar 28, 2026

View reviewed changes

kgryte requested changes Mar 28, 2026

View reviewed changes

kgryte added the Needs Changes Pull request which needs changes before being merged. label Mar 28, 2026

	type K = integerndarray \| number;
	type K = typedndarray<number> \| number;

		circshift( x, 2 ); // $ExpectType typedndarray<number>
		circshift( x, 2, {} ); // $ExpectType typedndarray<number>

	ndarray having an integer data type. If provided an ndarray, the value
	ndarray having a real-valued or "generic" data type. If provided an ndarray, the value


		'use strict';

		var discreteUniform = require( '@stdlib/random/array/discrete-uniform' );

	var idtypes1 = dtypes( 'integer' ); // k ndarray
	var idtypes1 = dtypes( 'real_and_generic' ); // k ndarray

	* Circularly shift the elements of an input ndarray along one or more ndarray dimensions by a specified number of positions.
	* Circularly shift the elements of an input ndarray by a specified number of positions along one or more ndarray dimensions.

	t.strictEqual( getDType( actual ), 'generic', 'returns expected value' );
	t.strictEqual( String( getDType( actual ) ), 'generic', 'returns expected value' );

	tape( 'the function supports large shift values (k > N)', function test( t ) {
	tape( 'the function supports large shift values (\|k\| > N)', function test( t ) {

Uh oh!

Conversation

headlessNode commented Mar 28, 2026

Description

Related Issues

Questions

Other

Checklist

AI Assistance

Disclosure

Uh oh!

stdlib-bot commented Mar 28, 2026

Coverage Report

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kgryte Mar 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kgryte left a comment

Choose a reason for hiding this comment

Uh oh!

kgryte commented Mar 28, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

kgryte Mar 28, 2026 •

edited

Loading