diff --git a/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/README.md b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/README.md new file mode 100644 index 000000000000..106ada8c89e2 --- /dev/null +++ b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/README.md @@ -0,0 +1,244 @@ + + +# structFactory + +> Create a new [`struct`][@stdlib/dstructs/struct] constructor tailored to a specified floating-point data type. + + + +
+ +
+ + + + + +
+ +## Usage + +```javascript +var structFactory = require( '@stdlib/ml/base/sgd/params/struct-factory' ); +``` + +#### structFactory( dtype ) + +Returns a new [`struct`][@stdlib/dstructs/struct] constructor tailored to a specified floating-point data type. + +```javascript +var Struct = structFactory( 'float64' ); +// returns + +var s = new Struct(); +// returns +``` + +The function supports the following parameters: + +- **dtype**: floating-point data type for storing floating-point parameters. Must be either `'float64'` or `'float32'`. + +A returned [`struct`][@stdlib/dstructs/struct] constructor supports the following fields: + +- **penalty**: regularization function to be used, provided as an enumeration constant (see [`@stdlib/ml/base/sgd/penalty-resolve-enum`][@stdlib/ml/base/sgd/penalty-resolve-enum]). Must be one of the following: + + - `'l1'`: L1 regularization (also called LASSO) which leads to sparse models by adding a penalty based on the absolute value of coefficients. + - `'l2'`: L2 regularization (also called ridge regression) which encourages smaller, more evenly distributed weights by adding a penalty based on the square of the coefficients. + - `'elasticnet'`: regularization method which linearly combines the L1 and L2 penalties of the lasso and ridge methods. + - `'none'`: no regularization. + +- **penaltyParams**: parameters specific to the regularization function being used. Must be a list having length `2`, with any unused elements set to zero. The expected list contents depend on `penalty`: + + - `'l1'`, `'l2'`: `[ lambda, 0.0 ]` + - `'elasticnet'`: `[ lambda, l1Ratio ]` + - `'none'`: `[ 0.0, 0.0 ]` (may be omitted) + + where + + - **lambda**: regularization parameter which determines the amount of shrinkage inflicted on the model coefficients. Higher values reduce the variance of the model coefficient estimates at the expense of introducing bias. + - **l1Ratio**: mixing parameter on the interval `[0,1]` which determines the relative contribution of the L1 and L2 penalties, according to the formula `(l1Ratio*L1) + ((1-l1Ratio)*L2)`. A value of `0` corresponds to pure L2 regularization, and a value of `1` corresponds to pure L1 regularization. + +- **learningRate**: learning rate scheduler to be used, provided as an enumeration constant (see [`@stdlib/ml/base/sgd/learning-rate-resolve-enum`][@stdlib/ml/base/sgd/learning-rate-resolve-enum]). The learning rate scheduler decides how fast or slow the model coefficients are updated toward the optimal coefficients. Must be one of the following: + + - `'basic'`: basic learning rate function according to the formula `10/(10+t)`, where `t` is the current iteration. + - `'constant'`: constant learning rate function. + - `'invscaling'`: inverse scaling learning rate function according to the formula `eta0/pow(t, powerT)`. + - `'pegasos'`: [Pegasos][@shalevshwartz:2011a] learning rate function according to the formula `1/(lambda*t)`, where `t` is the current iteration. + +- **learningRateParams**: parameters specific to the learning rate scheduler being used. Must be a list having length `2`, with any unused elements set to zero. The expected list contents depend on `learningRate`: + + - `'basic'`: `[ 0.0, 0.0 ]` (may be omitted) + - `'constant'`: `[ eta0, 0.0 ]` + - `'invscaling'`: `[ eta0, powerT ]` + - `'pegasos'`: `[ lambda, 0.0 ]` + + where + + - **eta0**: initial learning rate. When `learningRate` is `'constant'`, the learning rate is held fixed at `eta0` for all iterations. + - **powerT**: exponent controlling how quickly the learning rate decreases. Higher values cause the learning rate to decay more rapidly. + - **lambda**: regularization parameter. As the Pegasos scheduler derives its learning rate from the regularization parameter, one should provide the same value as provided for the corresponding element of `penaltyParams`. + +- **lossFunction**: loss function to be used, provided as an enumeration constant (see [`@stdlib/ml/base/sgd/loss-function-resolve-enum`][@stdlib/ml/base/sgd/loss-function-resolve-enum]). Must be one of the following: + + - `'epsilon-insensitive'`: penalty is the absolute value of the error whenever the absolute error exceeds `epsilon` and zero otherwise. + - `'hinge'`: hinge loss function. Corresponds to a soft-margin linear Support Vector Machine (SVM), which can handle non-linearly separable data. + - `'huber'`: squared-error loss for observations with error smaller than `threshold` in magnitude, linear loss otherwise. Should be used in order to decrease the influence of outliers on the model fit. + - `'log'`: logistic loss function. Corresponds to Logistic Regression. + - `'modified-huber'`: Huber loss function [variant][@zhang:2004a] for classification. + - `'perceptron'`: hinge loss function without a margin. Corresponds to the original perceptron by Rosenblatt (1957). + - `'squared-epsilon-insensitive'`: squared epsilon insensitive loss function. + - `'squared-error'`: squared error loss (i.e., the squared difference of the observed and fitted values). + - `'squared-hinge'`: squared hinge loss function SVM (L2-SVM). + +- **lossFunctionParams**: parameters specific to the loss function being used. Must be a list having length `1`. The expected list contents depend on `lossFunction`: + + - `'epsilon-insensitive'`, `'squared-epsilon-insensitive'`: `[ epsilon ]` + - `'huber'`: `[ threshold ]` + - all other loss functions: `[ 0.0 ]` (may be omitted) + + where + + - **epsilon**: insensitivity parameter. Errors whose absolute value is less than `epsilon` incur no penalty. + - **threshold**: error magnitude at which the loss transitions from squared-error loss to linear loss. Observations whose absolute error is less than `threshold` incur squared-error loss, and all other observations incur linear loss. Smaller values decrease the influence of outliers on the model fit. + +- **fitIntercept**: boolean indicating whether to include an intercept. If `true`, an element equal to one is implicitly added to each provided feature vector (note, however, that the model does not perform regularization of the intercept term). If `false`, the model assumes that feature vectors are already centered. + +- **intercept**: initial intercept value. Only applicable when `fitIntercept` is `true`. + +- **maxIter**: maximum number of iterations to run. + +
+ + + + + +
+ +## Notes + +- A [`struct`][@stdlib/dstructs/struct] provides a fixed-width composite data structure for storing SGD trainer parameters and provides an ABI-stable data layout for JavaScript-C interoperation. +- Each parameter list is a fixed-length array which is large enough to accommodate the option requiring the most parameters (`penaltyParams`: `2`, `learningRateParams`: `2`, `lossFunctionParams`: `1`). Accordingly, one must provide a list having the expected length, with any unused elements set to zero (e.g., `[ lambda, 0.0 ]`), as providing a list having an unexpected length, including an empty list, raises an exception. As struct instances are zero-filled upon initialization, one may omit a list when the corresponding option requires no parameters. +- Consumers should only read as many elements as are applicable to the corresponding penalty, learning rate scheduler, or loss function, with any remaining elements being unused. + +
+ + + + + +
+ +## Examples + + + +```javascript +var resolveLREnum = require( '@stdlib/ml/base/sgd/learning-rate-resolve-enum' ); +var resolveLossFunctionEnum = require( '@stdlib/ml/base/sgd/loss-function-resolve-enum' ); +var resolvePenaltyEnum = require( '@stdlib/ml/base/sgd/penalty-resolve-enum' ); +var Float64Array = require( '@stdlib/array/float64' ); +var Float32Array = require( '@stdlib/array/float32' ); +var structFactory = require( '@stdlib/ml/base/sgd/params/struct-factory' ); + +// Note: hinge loss requires no parameters, and thus we may omit the respective parameter list. +var Struct = structFactory( 'float64' ); +var params = new Struct({ + 'penaltyParams': new Float64Array( [ 2.5, 0.0 ] ), + 'learningRateParams': new Float64Array( [ 0.01, 0.0 ] ), + 'intercept': 0.0, + 'maxIter': 500, + 'penalty': resolvePenaltyEnum( 'l2' ), + 'learningRate': resolveLREnum( 'constant' ), + 'lossFunction': resolveLossFunctionEnum( 'hinge' ), + 'fitIntercept': true +}); + +var str = params.toString({ + 'format': 'linear' +}); +console.log( str ); + +Struct = structFactory( 'float32' ); +params = new Struct({ + 'penaltyParams': new Float32Array( [ 2.5, 0.0 ] ), + 'learningRateParams': new Float32Array( [ 0.01, 0.0 ] ), + 'intercept': 0.0, + 'maxIter': 500, + 'penalty': resolvePenaltyEnum( 'l2' ), + 'learningRate': resolveLREnum( 'constant' ), + 'lossFunction': resolveLossFunctionEnum( 'hinge' ), + 'fitIntercept': true +}); + +str = params.toString({ + 'format': 'linear' +}); +console.log( str ); +``` + +
+ + + + + +* * * + +
+ +## References + +- Rosenblatt, Frank. 1957. "The Perceptron–a perceiving and recognizing automaton." 85-460-1. Buffalo, NY, USA: Cornell Aeronautical Laboratory. +- Zhang, Tong. 2004. "Solving Large Scale Linear Prediction Problems Using Stochastic Gradient Descent Algorithms." In _Proceedings of the Twenty-First International Conference on Machine Learning_, 116. New York, NY, USA: Association for Computing Machinery. doi:[10.1145/1015330.1015332][@zhang:2004a]. +- Shalev-Shwartz, Shai, Yoram Singer, Nathan Srebro, and Andrew Cotter. 2011. "Pegasos: primal estimated sub-gradient solver for SVM." _Mathematical Programming_ 127 (1): 3–30. doi:[10.1007/s10107-010-0420-4][@shalevshwartz:2011a]. + +
+ + + + + + + + + + + + + + diff --git a/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/benchmark/benchmark.js b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/benchmark/benchmark.js new file mode 100644 index 000000000000..f06fde75adee --- /dev/null +++ b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/benchmark/benchmark.js @@ -0,0 +1,54 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var bench = require( '@stdlib/bench' ); +var isFunction = require( '@stdlib/assert/is-function' ); +var pkg = require( './../package.json' ).name; +var factory = require( './../lib' ); + + +// MAIN // + +bench( pkg, function benchmark( b ) { + var values; + var v; + var i; + + values = [ + 'float64', + 'float32' + ]; + + b.tic(); + for ( i = 0; i < b.iterations; i++ ) { + v = factory( values[ i%values.length ] ); + if ( typeof v !== 'function' ) { + b.fail( 'should return a function' ); + } + } + b.toc(); + if ( !isFunction( v ) ) { + b.fail( 'should return a function' ); + } + b.pass( 'benchmark finished' ); + b.end(); +}); diff --git a/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/docs/repl.txt b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/docs/repl.txt new file mode 100644 index 000000000000..44d00f06a186 --- /dev/null +++ b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/docs/repl.txt @@ -0,0 +1,24 @@ + +{{alias}}( dtype ) + Returns a new struct constructor tailored to a specified floating-point data + type. + + Parameters + ---------- + dtype: string + Floating-point data type for storing floating-point parameters. + + Returns + ------- + fcn: Function + Struct constructor. + + Examples + -------- + > var S = {{alias}}( 'float64' ); + > var r = new S(); + > r.toString() + + + See Also + -------- diff --git a/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/docs/types/index.d.ts b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/docs/types/index.d.ts new file mode 100644 index 000000000000..198de9efca84 --- /dev/null +++ b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/docs/types/index.d.ts @@ -0,0 +1,267 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +// TypeScript Version: 4.1 + +/** +* Interface describing SGD trainer parameters. +*/ +interface Params { + /** + * Parameters specific to the regularization function being used. + * + * ## Notes + * + * - Must be a list having length `2`, with any unused elements set to zero. The expected list contents depend on the penalty: + * + * - `l1`, `l2`: `[ lambda, 0.0 ]` + * - `elasticnet`: `[ lambda, l1Ratio ]` + * - `none`: `[ 0.0, 0.0 ]` (may be omitted) + * + * where: + * - `lambda`: regularization parameter which determines the amount of shrinkage inflicted on the model coefficients. + * - `l1Ratio`: mixing parameter on the interval `[0,1]` which determines the relative contribution of the L1 and L2 penalties. + */ + penaltyParams?: T; + + /** + * Parameters specific to the learning rate scheduler being used. + * + * ## Notes + * + * - Must be a list having length `2`, with any unused elements set to zero. The expected list contents depend on the learning rate scheduler: + * + * - `basic`: `[ 0.0, 0.0 ]` (may be omitted) + * - `constant`: `[ eta0, 0.0 ]` + * - `invscaling`: `[ eta0, powerT ]` + * - `pegasos`: `[ lambda, 0.0 ]` + * + * where: + * - `eta0`: initial learning rate. + * - `powerT`: exponent controlling how quickly the learning rate decreases. + * - `lambda`: regularization parameter. + */ + learningRateParams?: T; + + /** + * Parameters specific to the loss function being used. + * + * ## Notes + * + * - Must be a list having length `1`. The expected list contents depend on the loss function: + * + * - `epsilon-insensitive`, `squared-epsilon-insensitive`: `[ epsilon ]` + * - `huber`: `[ threshold ]` + * - all other loss functions: `[ 0.0 ]` (may be omitted) + * + * where: + * - `epsilon`: insensitivity parameter (i.e., errors whose absolute value is less than `epsilon` incur no penalty). + * - `threshold`: error magnitude at which the loss transitions from squared-error loss to linear loss. + */ + lossFunctionParams?: T; + + /** + * Initial intercept value. + * + * ## Notes + * + * - Only applicable when `fitIntercept` is `true`. + */ + intercept?: number; + + /** + * Maximum number of iterations to run. + */ + maxIter?: number; + + /** + * Regularization function to be used. + * + * ## Notes + * + * - Must be provided as an enumeration constant (see `@stdlib/ml/base/sgd/penalty-resolve-enum`) resolved from one of the following: + * + * - `l1`: L1 regularization (also called LASSO) which leads to sparse models by adding a penalty based on the absolute value of coefficients. + * - `l2`: L2 regularization (also called ridge regression) which encourages smaller, more evenly distributed weights by adding a penalty based on the square of the coefficients. + * - `elasticnet`: regularization method which linearly combines the L1 and L2 penalties of the lasso and ridge methods. + * - `none`: no regularization. + */ + penalty?: number; + + /** + * Learning rate scheduler to be used. + * + * ## Notes + * + * - Must be provided as an enumeration constant (see `@stdlib/ml/base/sgd/learning-rate-resolve-enum`) resolved from one of the following: + * + * - `basic`: basic learning rate function according to the formula `10/(10+t)`, where `t` is the current iteration. + * - `constant`: constant learning rate function. + * - `invscaling`: inverse scaling learning rate function according to the formula `eta0/pow(t, powerT)`. + * - `pegasos`: Pegasos learning rate function according to the formula `1/(lambda*t)`, where `t` is the current iteration. + */ + learningRate?: number; + + /** + * Loss function to be used. + * + * ## Notes + * + * - Must be provided as an enumeration constant (see `@stdlib/ml/base/sgd/loss-function-resolve-enum`) resolved from one of the following: + * + * - `epsilon-insensitive`: penalty is the absolute value of the error whenever the absolute error exceeds `epsilon` and zero otherwise. + * - `hinge`: hinge loss function. Corresponds to a soft-margin linear Support Vector Machine (SVM), which can handle non-linearly separable data. + * - `huber`: squared-error loss for observations with error smaller than `threshold` in magnitude, linear loss otherwise. + * - `log`: logistic loss function. Corresponds to Logistic Regression. + * - `modified-huber`: Huber loss function variant for classification. + * - `perceptron`: hinge loss function without a margin. Corresponds to the original perceptron by Rosenblatt. + * - `squared-epsilon-insensitive`: squared epsilon insensitive loss function. + * - `squared-error`: squared error loss (i.e., the squared difference of the observed and fitted values). + * - `squared-hinge`: squared hinge loss function SVM (L2-SVM). + */ + lossFunction?: number; + + /** + * Boolean indicating whether to include intercept. + * + * ## Notes + * + * - If `true`, an element equal to one is implicitly added to each provided feature vector. If `false`, the model assumes that feature vectors are already centered. + */ + fitIntercept?: boolean; +} + +/** +* Interface describing a struct data structure. +*/ +declare class Struct { + /** + * Struct constructor. + * + * @param arg - buffer or data object + * @param byteOffset - byte offset + * @param byteLength - maximum byte length + * @returns struct + */ + constructor( arg?: ArrayBuffer | Params, byteOffset?: number, byteLength?: number ); + + /** + * Parameters specific to the regularization function being used. + */ + penaltyParams: T; + + /** + * Parameters specific to the learning rate scheduler being used. + */ + learningRateParams: T; + + /** + * Parameters specific to the loss function being used. + */ + lossFunctionParams: T; + + /** + * Initial intercept value. + */ + intercept: number; + + /** + * Maximum number of iterations to run. + */ + maxIter: number; + + /** + * Regularization function to be used. + */ + penalty: number; + + /** + * Learning rate scheduler to be used. + */ + learningRate: number; + + /** + * Loss function to be used. + */ + lossFunction: number; + + /** + * Boolean indicating whether to include intercept. + */ + fitIntercept: boolean; +} + +/** +* Interface defining a struct constructor which is both "newable" and "callable". +*/ +interface StructConstructor { + /** + * Struct constructor. + * + * @param arg - buffer or data object + * @param byteOffset - byte offset + * @param byteLength - maximum byte length + * @returns struct + */ + new( arg?: ArrayBuffer | Params, byteOffset?: number, byteLength?: number ): Struct; + + /** + * Struct constructor. + * + * @param arg - buffer or data object + * @param byteOffset - byte offset + * @param byteLength - maximum byte length + * @returns struct + */ + ( arg?: ArrayBuffer | Params, byteOffset?: number, byteLength?: number ): Struct; +} + +/** +* Returns a new struct constructor tailored to a specified floating-point data type. +* +* @param dtype - floating-point data type for storing floating-point params +* @returns struct constructor +* +* @example +* var Struct = structFactory( 'float64' ); +* // returns +* +* var s = new Struct(); +* // returns +*/ +declare function structFactory( dtype: 'float64' ): StructConstructor; + +/** +* Returns a new struct constructor tailored to a specified floating-point data type. +* +* @param dtype - floating-point data type for storing floating-point params +* @returns struct constructor +* +* @example +* var Struct = structFactory( 'float32' ); +* // returns +* +* var s = new Struct(); +* // returns +*/ +declare function structFactory( dtype: 'float32' ): StructConstructor; + + +// EXPORTS // + +export = structFactory; diff --git a/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/docs/types/test.ts b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/docs/types/test.ts new file mode 100644 index 000000000000..1857d7901cfb --- /dev/null +++ b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/docs/types/test.ts @@ -0,0 +1,54 @@ +/* +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +import structFactory = require( './index' ); + + +// TESTS // + +// The function returns a function... +{ + structFactory( 'float64' ); // $ExpectType StructConstructor + structFactory( 'float32' ); // $ExpectType StructConstructor +} + +// The compiler throws an error if not provided a supported data type... +{ + structFactory( 10 ); // $ExpectError + structFactory( true ); // $ExpectError + structFactory( false ); // $ExpectError + structFactory( null ); // $ExpectError + structFactory( undefined ); // $ExpectError + structFactory( [] ); // $ExpectError + structFactory( {} ); // $ExpectError + structFactory( ( x: number ): number => x ); // $ExpectError +} + +// The function returns a function which returns a struct object... +{ + const Struct = structFactory( 'float64' ); + + // eslint-disable-next-line @typescript-eslint/no-unused-vars + const s1 = new Struct( new ArrayBuffer( 92 ) ); // $ExpectType Struct + + // eslint-disable-next-line @typescript-eslint/no-unused-vars + const s2 = new Struct( new ArrayBuffer( 100 ), 8 ); // $ExpectType Struct + + // eslint-disable-next-line @typescript-eslint/no-unused-vars + const s3 = new Struct( new ArrayBuffer( 100 ), 8, 92 ); // $ExpectType Struct +} diff --git a/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/examples/index.js b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/examples/index.js new file mode 100644 index 000000000000..45691140aab6 --- /dev/null +++ b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/examples/index.js @@ -0,0 +1,61 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +var resolveLREnum = require( '@stdlib/ml/base/sgd/learning-rate-resolve-enum' ); +var resolveLossFunctionEnum = require( '@stdlib/ml/base/sgd/loss-function-resolve-enum' ); +var resolvePenaltyEnum = require( '@stdlib/ml/base/sgd/penalty-resolve-enum' ); +var Float64Array = require( '@stdlib/array/float64' ); +var Float32Array = require( '@stdlib/array/float32' ); +var structFactory = require( './../lib' ); + +// Note: hinge loss requires no parameters, and thus we may omit the respective parameter list. +var Struct = structFactory( 'float64' ); +var params = new Struct({ + 'penaltyParams': new Float64Array( [ 2.5, 0.0 ] ), + 'learningRateParams': new Float64Array( [ 0.01, 0.0 ] ), + 'intercept': 0.0, + 'maxIter': 500, + 'penalty': resolvePenaltyEnum( 'l2' ), + 'learningRate': resolveLREnum( 'constant' ), + 'lossFunction': resolveLossFunctionEnum( 'hinge' ), + 'fitIntercept': true +}); + +var str = params.toString({ + 'format': 'linear' +}); +console.log( str ); + +Struct = structFactory( 'float32' ); +params = new Struct({ + 'penaltyParams': new Float32Array( [ 2.5, 0.0 ] ), + 'learningRateParams': new Float32Array( [ 0.01, 0.0 ] ), + 'intercept': 0.0, + 'maxIter': 500, + 'penalty': resolvePenaltyEnum( 'l2' ), + 'learningRate': resolveLREnum( 'constant' ), + 'lossFunction': resolveLossFunctionEnum( 'hinge' ), + 'fitIntercept': true +}); + +str = params.toString({ + 'format': 'linear' +}); +console.log( str ); diff --git a/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/lib/index.js b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/lib/index.js new file mode 100644 index 000000000000..578ebbe3aaed --- /dev/null +++ b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/lib/index.js @@ -0,0 +1,43 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +/** +* Create a new struct constructor tailored to a specified floating-point data type. +* +* @module @stdlib/ml/base/sgd/params/struct-factory +* +* @example +* var structFactory = require( '@stdlib/ml/base/sgd/params/struct-factory' ); +* +* var Struct = structFactory( 'float64' ); +* // returns +* +* var s = new Struct(); +* // returns +*/ + +// MODULES // + +var main = require( './main.js' ); + + +// EXPORTS // + +module.exports = main; diff --git a/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/lib/main.js b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/lib/main.js new file mode 100644 index 000000000000..778cae8c2448 --- /dev/null +++ b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/lib/main.js @@ -0,0 +1,118 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var struct = require( '@stdlib/dstructs/struct' ); + + +// VARIABLES // + +var PENALTY_PARAMS_LENGTH = 2; +var LEARNING_RATE_PARAMS_LENGTH = 2; +var LOSS_FUNCTION_PARAMS_LENGTH = 1; + + +// MAIN // + +/** +* Returns a new struct constructor tailored to a specified floating-point data type. +* +* ## Notes +* +* - Each parameter list is a fixed-length array which is zero-filled upon initialization. Consumers should only read as many elements as are applicable to the corresponding penalty, learning rate scheduler, or loss function, with any remaining elements being unused. +* +* @param {string} dtype - floating-point data type +* @returns {Function} struct constructor +* +* @example +* var Struct = factory( 'float64' ); +* // returns +* +* var s = new Struct(); +* // returns +*/ +function factory( dtype ) { + var schema = [ + { + 'name': 'penaltyParams', + 'description': 'parameters specific to the regularization function being used', + 'type': dtype, + 'length': PENALTY_PARAMS_LENGTH, + 'castingMode': 'mostly-safe' + }, + { + 'name': 'learningRateParams', + 'description': 'parameters specific to the learning rate scheduler being used', + 'type': dtype, + 'length': LEARNING_RATE_PARAMS_LENGTH, + 'castingMode': 'mostly-safe' + }, + { + 'name': 'lossFunctionParams', + 'description': 'parameters specific to the loss function being used', + 'type': dtype, + 'length': LOSS_FUNCTION_PARAMS_LENGTH, + 'castingMode': 'mostly-safe' + }, + { + 'name': 'intercept', + 'description': 'initial intercept value', + 'type': dtype, + 'castingMode': 'mostly-safe' + }, + { + 'name': 'maxIter', + 'description': 'maximum number of iterations to run', + 'type': 'int32', + 'castingMode': 'mostly-safe' + }, + { + 'name': 'penalty', + 'description': 'regularization function to be used', + 'type': 'int8', + 'castingMode': 'none' + }, + { + 'name': 'learningRate', + 'description': 'learning rate scheduler to be used', + 'type': 'int8', + 'castingMode': 'none' + }, + { + 'name': 'lossFunction', + 'description': 'loss function to be used', + 'type': 'int8', + 'castingMode': 'none' + }, + { + 'name': 'fitIntercept', + 'description': 'boolean indicating whether to include intercept', + 'type': 'bool', + 'castingMode': 'none' + } + ]; + return struct( schema ); +} + + +// EXPORTS // + +module.exports = factory; diff --git a/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/package.json b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/package.json new file mode 100644 index 000000000000..089cf5b84b66 --- /dev/null +++ b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/package.json @@ -0,0 +1,68 @@ +{ + "name": "@stdlib/ml/base/sgd/params/struct-factory", + "version": "0.0.0", + "description": "Create a new struct constructor tailored to a specified floating-point data type.", + "license": "Apache-2.0", + "author": { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + }, + "contributors": [ + { + "name": "The Stdlib Authors", + "url": "https://github.com/stdlib-js/stdlib/graphs/contributors" + } + ], + "main": "./lib", + "directories": { + "benchmark": "./benchmark", + "doc": "./docs", + "example": "./examples", + "lib": "./lib", + "test": "./test" + }, + "types": "./docs/types", + "scripts": {}, + "homepage": "https://github.com/stdlib-js/stdlib", + "repository": { + "type": "git", + "url": "git://github.com/stdlib-js/stdlib.git" + }, + "bugs": { + "url": "https://github.com/stdlib-js/stdlib/issues" + }, + "dependencies": {}, + "devDependencies": {}, + "engines": { + "node": ">=0.10.0", + "npm": ">2.7.0" + }, + "os": [ + "aix", + "darwin", + "freebsd", + "linux", + "macos", + "openbsd", + "sunos", + "win32", + "windows" + ], + "keywords": [ + "stdlib", + "ml", + "machine", + "learning", + "sgd", + "stochastic gradient descent", + "trainer", + "utilities", + "utility", + "utils", + "util", + "struct", + "params", + "parameters" + ], + "__stdlib__": {} +} diff --git a/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/test/test.js b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/test/test.js new file mode 100644 index 000000000000..95ab0064b238 --- /dev/null +++ b/lib/node_modules/@stdlib/ml/base/sgd/params/struct-factory/test/test.js @@ -0,0 +1,219 @@ +/** +* @license Apache-2.0 +* +* Copyright (c) 2026 The Stdlib Authors. +* +* Licensed under the Apache License, Version 2.0 (the "License"); +* you may not use this file except in compliance with the License. +* You may obtain a copy of the License at +* +* http://www.apache.org/licenses/LICENSE-2.0 +* +* Unless required by applicable law or agreed to in writing, software +* distributed under the License is distributed on an "AS IS" BASIS, +* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +* See the License for the specific language governing permissions and +* limitations under the License. +*/ + +'use strict'; + +// MODULES // + +var tape = require( 'tape' ); +var isSameFloat64Array = require( '@stdlib/assert/is-same-float64array' ); +var isSameFloat32Array = require( '@stdlib/assert/is-same-float32array' ); +var Float64Array = require( '@stdlib/array/float64' ); +var Float32Array = require( '@stdlib/array/float32' ); +var resolveLREnum = require( '@stdlib/ml/base/sgd/learning-rate-resolve-enum' ); +var resolveLossFunctionEnum = require( '@stdlib/ml/base/sgd/loss-function-resolve-enum' ); +var resolvePenaltyEnum = require( '@stdlib/ml/base/sgd/penalty-resolve-enum' ); +var f32 = require( '@stdlib/number/float64/base/to-float32' ); +var structFactory = require( './../lib' ); + + +// TESTS // + +tape( 'main export is a function', function test( t ) { + t.ok( true, __filename ); + t.strictEqual( typeof structFactory, 'function', 'main export is a function' ); + t.end(); +}); + +tape( 'the function throws an error if provided a first argument which is not a supported data type', function test( t ) { + var values; + var i; + + values = [ + '5', + 5, + NaN, + true, + false, + null, + void 0, + [], + {}, + function noop() {} + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[ i ] ), TypeError, 'throws an error when provided ' + values[ i ] ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + structFactory( value ); + }; + } +}); + +tape( 'the function returns a constructor for creating a fixed-width parameters object (dtype=float64)', function test( t ) { + var expected; + var actual; + var Struct; + var lambda; + var eta0; + + Struct = structFactory( 'float64' ); + t.strictEqual( typeof Struct, 'function', 'returns expected value' ); + + lambda = 2.5; + eta0 = 0.01; + + actual = new Struct({ + 'penaltyParams': new Float64Array( [ lambda, 0.0 ] ), + 'learningRateParams': new Float64Array( [ eta0, 0.0 ] ), + 'lossFunctionParams': new Float64Array( [ 0.0 ] ), + 'intercept': 0.5, + 'maxIter': 500, + 'penalty': resolvePenaltyEnum( 'l2' ), + 'learningRate': resolveLREnum( 'constant' ), + 'lossFunction': resolveLossFunctionEnum( 'hinge' ), + 'fitIntercept': true + }); + + expected = { + 'penaltyParams': new Float64Array( [ 2.5, 0.0 ] ), + 'learningRateParams': new Float64Array( [ 0.01, 0.0 ] ), + 'lossFunctionParams': new Float64Array( [ 0.0 ] ), + 'intercept': 0.5, + 'maxIter': 500, + 'penalty': resolvePenaltyEnum( 'l2' ), + 'learningRate': resolveLREnum( 'constant' ), + 'lossFunction': resolveLossFunctionEnum( 'hinge' ), + 'fitIntercept': true + }; + + t.strictEqual( actual instanceof Struct, true, 'returns expected value' ); + t.strictEqual( actual.penalty, expected.penalty, 'returns expected value' ); + t.strictEqual( actual.learningRate, expected.learningRate, 'returns expected value' ); + t.strictEqual( actual.lossFunction, expected.lossFunction, 'returns expected value' ); + t.strictEqual( actual.fitIntercept, expected.fitIntercept, 'returns expected value' ); + t.strictEqual( actual.intercept, expected.intercept, 'returns expected value' ); + t.strictEqual( actual.maxIter, expected.maxIter, 'returns expected value' ); + t.strictEqual( isSameFloat64Array( actual.penaltyParams, expected.penaltyParams ), true, 'returns expected value' ); + t.strictEqual( isSameFloat64Array( actual.learningRateParams, expected.learningRateParams ), true, 'returns expected value' ); + t.strictEqual( isSameFloat64Array( actual.lossFunctionParams, expected.lossFunctionParams ), true, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns a constructor for creating a fixed-width parameters object (dtype=float32)', function test( t ) { + var expected; + var actual; + var Struct; + var lambda; + var eta0; + + Struct = structFactory( 'float32' ); + t.strictEqual( typeof Struct, 'function', 'returns expected value' ); + + lambda = 2.5; + eta0 = 0.01; + + actual = new Struct({ + 'penaltyParams': new Float32Array( [ lambda, 0.0 ] ), + 'learningRateParams': new Float32Array( [ eta0, 0.0 ] ), + 'lossFunctionParams': new Float32Array( [ 0.0 ] ), + 'intercept': f32( 0.5 ), + 'maxIter': 500, + 'penalty': resolvePenaltyEnum( 'l2' ), + 'learningRate': resolveLREnum( 'constant' ), + 'lossFunction': resolveLossFunctionEnum( 'hinge' ), + 'fitIntercept': true + }); + + expected = { + 'penaltyParams': new Float32Array( [ 2.5, 0.0 ] ), + 'learningRateParams': new Float32Array( [ 0.01, 0.0 ] ), + 'lossFunctionParams': new Float32Array( [ 0.0 ] ), + 'intercept': f32( 0.5 ), + 'maxIter': 500, + 'penalty': resolvePenaltyEnum( 'l2' ), + 'learningRate': resolveLREnum( 'constant' ), + 'lossFunction': resolveLossFunctionEnum( 'hinge' ), + 'fitIntercept': true + }; + + t.strictEqual( actual instanceof Struct, true, 'returns expected value' ); + t.strictEqual( actual.penalty, expected.penalty, 'returns expected value' ); + t.strictEqual( actual.learningRate, expected.learningRate, 'returns expected value' ); + t.strictEqual( actual.lossFunction, expected.lossFunction, 'returns expected value' ); + t.strictEqual( actual.fitIntercept, expected.fitIntercept, 'returns expected value' ); + t.strictEqual( actual.intercept, expected.intercept, 'returns expected value' ); + t.strictEqual( actual.maxIter, expected.maxIter, 'returns expected value' ); + t.strictEqual( isSameFloat32Array( actual.penaltyParams, expected.penaltyParams ), true, 'returns expected value' ); + t.strictEqual( isSameFloat32Array( actual.learningRateParams, expected.learningRateParams ), true, 'returns expected value' ); + t.strictEqual( isSameFloat32Array( actual.lossFunctionParams, expected.lossFunctionParams ), true, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns a constructor which zero-fills parameter lists which are not provided', function test( t ) { + var expected; + var actual; + var Struct; + + Struct = structFactory( 'float64' ); + + actual = new Struct({ + 'lossFunction': resolveLossFunctionEnum( 'hinge' ) + }); + + expected = { + 'penaltyParams': new Float64Array( [ 0.0, 0.0 ] ), + 'learningRateParams': new Float64Array( [ 0.0, 0.0 ] ), + 'lossFunctionParams': new Float64Array( [ 0.0 ] ) + }; + + t.strictEqual( isSameFloat64Array( actual.penaltyParams, expected.penaltyParams ), true, 'returns expected value' ); + t.strictEqual( isSameFloat64Array( actual.learningRateParams, expected.learningRateParams ), true, 'returns expected value' ); + t.strictEqual( isSameFloat64Array( actual.lossFunctionParams, expected.lossFunctionParams ), true, 'returns expected value' ); + t.end(); +}); + +tape( 'the function returns a constructor which throws an error if provided a parameter list having an unexpected length', function test( t ) { + var Struct; + var values; + var i; + + Struct = structFactory( 'float64' ); + + values = [ + new Float64Array( [] ), + new Float64Array( [ 2.5 ] ), + new Float64Array( [ 2.5, 0.0, 0.0 ] ), + new Float64Array( [ 2.5, 0.0, 0.0, 0.0 ] ) + ]; + for ( i = 0; i < values.length; i++ ) { + t.throws( badValue( values[ i ] ), RangeError, 'throws an error when provided an array having length ' + values[ i ].length ); + } + t.end(); + + function badValue( value ) { + return function badValue() { + return new Struct({ + 'penaltyParams': value + }); + }; + } +});