You should be using the API to generate random ndarrays directly.

I see that we are doing this in blas/ext/cusum, but that should likely be updated in order to use top-level APIs. Feel free to make a METR task to update the top-level blas/ext/* APIs (where appropriate).

Why are alpha and beta optional parameters? This seems odd to me. I would expect them to be mandatory, as that is the entire point of axpb.

Instead of separate types, I would suggest doing something like type ScalarArgument = ndarray | ... and then, in your signatures, do alpha: ScalarArgument, beta: ScalarArgument, etc.

Yeah, this sort of signature is going to lead to all sorts of argument juggling, especially as you have no way of distinguishing between alpha and beta when wanting to only provide beta.

TL;DR: make alpha and beta mandatory arguments, similar to have the searchElement argument in index-of is mandatory.

Use the top-level random/discrete-uniform package. Then you can avoid all this manual ndarray creation noise.

Why is this necessary?

Given this change, you'll need to rewrap this description.

Rewrap.

I would just copy, paste, and modify the broadcasting semantics description from alpha. This makes very explicit that broadcasting is purely related to x and options.dims, and that there are no broadcasting semantics between alpha and beta.

This means "flattening" during the operation, which I think is the right behavior, by default, for this API.

Why are we limited to floating-point data types here?

Couldn't I reasonably have, say, an int32 input array x, alpha = 5, and beta = 3 and have that delegate to gaxpb?

Minimize future copy-paste mistakes.

You do a lot of repeated isScalar( alpha ) and isScalar( beta ) here. Call once for both and assign the result to internal variables (e.g., isScalarAlpha = isScalar( alpha ), etc).

And then can do explicit alpha and beta validation.

if ( !isScalarAlpha && !isndarrayLike( alpha ) ) {
	throw new TypeError( format( 'invalid argument. Second argument must be an ndarray, a number, or a complex number. Value: `%s`.', alpha ) );
}

And you can do all this before you hit L129. Meaning, you can take care of your validation up front, rather than have it intermingled with delegation and broadcasting logic.

Looking at the various conditionals, you have a decent amount of repeated logic. You should have a series of four conditionals after caching whether alpha and beta are scalars:

• if isScalarAlpha, broadcastScalar
• else maybeBroadcastArray
• if isScalarBeta, broadcastScalar
• else maybeBroadcastArray

That should be it. No combined conditions (e.g., if scalar alpha AND ndarray beta, do x and y and if ndarray alpha and ndarray beta, do z and y, etc etc). If you do things up front, you can handle each argument on its own.

Also, recognize that isndarrayLike checks are relatively expensive, as they involve materializing various meta data. If we do them, we want to only do them once, and, if the knowledge is needed again, make sure we cache the result in a variable.

I would also be more explicit regarding the broadcasting behavior, rather than just referring to alpha. If you want to avoid duplication, consider moving the broadcast discussion to the ## Notes section below and then saying "Must have a shape which is [broadcast-compatible][@stdlib/ndarray/base/broadcast-shapes] with the complement of the shape defined by options.dims. For more discussion, see the notes below." for both alpha and beta.

These examples are a bit weak. Instead, I suggest consolidating into a single example which demonstrates the behavior when alpha and/or beta are/is real-valued and x is complex-valued. This highlights both that complex arrays are accepted and that real-values are casted to the dtype of x.

One thing which is not handled here is when alpha and beta are real-valued ndarrays and x is complex-valued. For real scalars, they are converted to complex-valued ndarrays. However, it doesn't seem that is the case for alpha and beta which are already ndarrays.

However, this also applies to blas/ext/cusum where we do real-to-complex conversion for scalar initial values, but not ndarray initial values.

Not sure the best approach, as we will want to consistently apply the same logic across relevant packages.