build: add scaffolding to generate `math/special/*` packages #8139

gunjjoshi · 2025-09-24T16:37:46Z

Resolves None.

Description

What is the purpose of this pull request?

This pull request:

adds scaffold templates and scripts for generating packages in math/special/*.

Related Issues

Does this pull request have any 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.

@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: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - 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: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---

--- 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: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - 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: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/dtype_ndarray_mappings.json

--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: skipped - 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: na - task: lint_c_benchmarks status: na - task: lint_c_tests_fixtures status: na - task: lint_shell status: missing_dependencies - task: lint_typescript_declarations status: passed - task: lint_typescript_tests status: passed - task: lint_license_headers status: passed ---

--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: skipped - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: na - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: passed - task: lint_javascript_benchmarks status: na - 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: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---

gunjjoshi · 2025-09-30T17:41:28Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/runner.js

+	// for ( i = 0; i < dataKeys.length; i++ ) {
+
+		// dataKey = dataKeys[ i ];
+		dataKey = '@stdlib/math/base/special/acosd';


For testing initially, I didn't generate all of the packages using the for loop. Instead, I have hardcoded acosd, to generate it.

--- type: pre_commit_static_analysis_report description: Results of running static analysis checks when committing changes. report: - task: lint_filenames status: skipped - task: lint_editorconfig status: passed - task: lint_markdown status: na - task: lint_package_json status: na - task: lint_repl_help status: na - task: lint_javascript_src status: passed - task: lint_javascript_cli status: na - task: lint_javascript_examples status: na - task: lint_javascript_tests status: na - task: lint_javascript_benchmarks status: na - task: lint_python status: na - task: lint_r status: na - task: lint_c_src status: passed - 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: na - task: lint_typescript_tests status: na - task: lint_license_headers status: passed ---

gunjjoshi · 2025-09-30T18:25:20Z

Getting some CI failures which might be arising from @stdlib/ndarray/base/unary, specifically from here: https://github.com/stdlib-js/stdlib/blob/develop/lib/node_modules/%40stdlib/ndarray/base/unary/src/c_d_as_z_d.c . Maybe, it must have stdlib_complex128_t instead of stdlib_complex64_t?

kgryte · 2025-10-03T18:29:02Z

@gunjjoshi Yes, I'll try and take a look at ndarray/base/unary tonight.

kgryte · 2025-11-05T05:50:25Z

/stdlib merge

stdlib-bot · 2025-11-05T05:57:05Z

Coverage Report

Package	Statements	Branches	Functions	Lines
math/special/acosd	$\color{green}349/349$ $color{green}+100.00%$	$\color{green}7/7$ $color{green}+100.00%$	$\color{green}0/0$ $color{green}+100.00%$	$\color{green}349/349$ $color{green}+100.00%$

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

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/data/README__md.txt

kgryte · 2025-11-05T06:18:49Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/data/docs/repl__txt.txt

+    Parameters
+    ----------
+    x: ndarray
+        Input array. Must have a numeric or "generic" data type.


@gunjjoshi Looks like we need an "input policy phrase" here. "numeric" is not true for all apis (e.g., those not supporting complex input dtypes).

kgryte · 2025-11-05T06:22:39Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/data/docs/types/index__d__ts.txt

+
+/// <reference types="@stdlib/types"/>
+
+import { typedndarray, {{NDARRAY_IMPORT_TYPES}}, genericndarray, RealAndGenericDataType as DataType, Order } from '@stdlib/types/ndarray';


This isn't correct. RealAndGenericDataType will not be correct for all APIs. opts.dtype is subject to the output dtype policy.

kgryte · 2025-11-05T06:26:58Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/data/docs/types/index__d__ts.txt

+	* var arr = ndarray2array( y );
+	* // returns {{JS_EXAMPLE_RESULTS_2X2}}
+	*/
+	( x: InputArray, options?: Options ): typedndarray<number>; // FIXME: we lose type specificity here, as the output ndarray data type is determined according to the output data type policy in conjunction with the `dtype` option


This isn't correct. E.g., what happens if a unary function returns a complex number? Meaning, number is not always correct. I don't have a great solution for this. We may need to do conditional overloads. Meaning, for those apis accepting and returning complex numbers, we may need an overload for when x is a complex array, as then the output should also be a complex array. In short, the structure of this file depends on the output dtype policy.

kgryte · 2025-11-05T06:27:49Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/data/docs/types/test__ts.txt

+		'dtype': 'float64'
+	});
+
+	{{ALIAS}}( x ); // $ExpectType typedndarray<number>


Same thing. The output array may or may not contain numbers depending on the API and the input array dtype.

kgryte · 2025-11-05T06:29:42Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/data/docs/types/test__ts.txt

+		'dtype': 'float64'
+	});
+
+	{{ALIAS}}.assign( x, x ); // $ExpectType float64ndarray


This works so long as an api accepts floating-point ndarrays. That may not always be true. The use of float64 throughout this file and examples assumes floating-point support.

kgryte · 2025-11-05T06:31:38Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/data/README__md.txt

+var ndarray2array = require( '@stdlib/ndarray/to-array' );
+var array = require( '@stdlib/ndarray/array' );
+
+var x = array( {{JS_EXAMPLE_VALUES_2X2}} );


This is a little tricky, as it assumes that x is allowed to be a float64 array. I am not sure that will always be the case. E.g., we could have a ufunc which only accept integer arrays or complex number arrays, etc. I am not sure the most robust solution here.

Can you confirm that, for all ufuncs in math special, we will support float64, float32, and generic?

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/data/test/test__main__js.txt

...node_modules/@stdlib/_tools/scaffold/math-special-unary/data/test/test__main__native__js.txt

kgryte · 2025-11-05T06:41:19Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/dtype_ndarray_mappings.json

@@ -0,0 +1,12 @@
+{
+	"input_dtypes": {


As discussed during a previous call, you can build out this table for completeness to include other dtype mappings.

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/generate_files.js

kgryte · 2025-11-05T06:46:37Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/generate_files.js

+	matches = result.reorderedMatches;
+
+	cOut = header;
+	cOut += Object.keys( uniqueIncludes ).join( '\n' ) + '\n';


@gunjjoshi Use @stdlib/utils/keys.

kgryte · 2025-11-05T06:47:49Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/generate_files.js

+
+		cOut += '\t// ' + inputType + ' (' + outputTypes.length + ')\n';
+		for ( j = 0; j < outputTypes.length; j++ ) {
+			cOut += '\tSTDLIB_NDARRAY_' + matches[ functionIndex ][ 0 ].toUpperCase() + ', STDLIB_NDARRAY_' + matches[ functionIndex ][ 1 ].toUpperCase();


@gunjjoshi Use uppercase string utility. stdlib/string/base/uppercase.

kgryte · 2025-11-05T06:51:02Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/generate_files.js

+
+	// Generate types.js:
+	jsOut = generateTypesFile( matches, header );
+	writeFileSync( join( destDir, 'lib/types.js' ), jsOut, {


You make heavy use of string concatenation to generate entire files, including license headers. I wonder if we could use template files with handlebar template strings {{}} similar to what we do for other files. That might reduce the visual noise in this file.

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/output_policy_phrases.json

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/runner.js

kgryte · 2025-11-05T06:56:29Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/runner.js

+		v = values[ i ];
+		results = func( v );
+		results = round( results * 100 ) / 100; // Rounding results to 2 decimal places
+		vals.push( '~' + results.toString() );


I think you only want to round if the result is not exact (i.e., an integer value). Otherwise, if results are exact, you don't need a ~. Furthermore, if integer-valued, you also need to include trailing .0 characters to the results if the array type is floating-point.

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/runner.js

kgryte · 2025-11-05T06:58:31Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/runner.js

+
+	// Using the scalar kernels to compute the dependencies:
+	scalarKernels = funcData.scalar_kernels;
+	keys = Object.keys( scalarKernels );


Use utils/keys.

kgryte · 2025-11-05T06:59:13Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/runner.js

+
+	for ( i = 0; i < keys.length; i++ ) {
+		kernelPath = scalarKernels[ keys[ i ] ];
+		if ( kernelPath.startsWith( '/' ) ) {


Use string/[base/]starts-with.

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/runner.js

kgryte · 2025-11-05T07:01:49Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/runner.js

+		pkgDesc = 'Compute the ' + o.short_desc + ' for each element in an ndarray.';
+		moduleDesc = 'Compute the ' + o.short_desc + '.';
+		mainDesc = 'Computes the ' + o.short_desc + ' for each element in an ndarray.';
+		testDesc = 'computes the ' + o.short_desc + ' for each element in an ndarray';


Remind me: what is our plan for functions like round?

kgryte · 2025-11-05T07:02:33Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/runner.js

+			keywords = keywords.concat( o.extra_keywords );
+		}
+		envs.push( 'KEYWORDS=\'' + keywords.join( ',' ) + '\'' );
+		envs.push( 'YEAR=\'' + new Date().getFullYear() + '\'' );


Use time/current-year.

kgryte · 2025-11-05T07:07:02Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/script.js

+			/*
+			* For the first iteration:
+			*
+			* allowedCasts = [


'float32' and 'float64' are not mostly safe casts for 'complex64'

kgryte · 2025-11-05T07:08:07Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/script.js

+		// Remove the dtypes which are not allowed for output, according to the output policy:
+		filtered = [];
+		for ( k = 0; k < allowedCasts.length; k++ ) {
+			if ( odt.indexOf( allowedCasts[ k ] ) !== -1 ) {


Prefer using array/base/assert/contains rather than indexOf here and elsewhere when searching for needles in arrays.

kgryte · 2025-11-05T07:10:02Z

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/script.js

+
+			// Extract the function name from the scalar kernel path and create C function name:
+			cFunctionName = scalarKernel.split( '/' ).pop(); // Get last part (Ex: 'acosd')
+			cFunctionName = 'stdlib_base_' + cFunctionName;


This isn't always correct. E.g., stdlib_base_float64_identity.

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/runner.js

Signed-off-by: Athan <[email protected]>

kgryte

Left an initial review. Main concerns revolve around edge cases.

gunjjoshi added 3 commits September 24, 2025 10:14

chore: initial scaffold setup

c7e0f03

chore: initial scripts

32865ab

refactor: update scripts

39bf63d

stdlib-bot added Tools Issue or pull request related to project tooling. Needs Review A pull request which needs code review. labels Sep 24, 2025

gunjjoshi marked this pull request as draft September 24, 2025 16:38

stdlib-bot removed the Needs Review A pull request which needs code review. label Sep 24, 2025

gunjjoshi added 3 commits September 24, 2025 22:12

refactor: update scripts and templates

82c5939

gunjjoshi commented Sep 30, 2025

View reviewed changes

lib/node_modules/@stdlib/_tools/scaffold/math-special-unary/scripts/dtype_ndarray_mappings.json Show resolved Hide resolved

gunjjoshi added 2 commits September 30, 2025 22:55

gunjjoshi commented Sep 30, 2025

View reviewed changes

gunjjoshi marked this pull request as ready for review September 30, 2025 18:17

stdlib-bot added the Needs Review A pull request which needs code review. label Sep 30, 2025

refactor: add handlebars for output policy phrases

033dc3f

stdlib-bot added the bot: In Progress Pull request is currently awaiting automation. label Nov 5, 2025

Merge remote-tracking branch 'upstream/develop' into scaffolds

a6f8e92

stdlib-bot removed the bot: In Progress Pull request is currently awaiting automation. label Nov 5, 2025