[2.0] Proposal: A standard policy for vector dimension mismatches

[GregStanton]

[2.0] Proposal: A standard policy for vector dimension mismatches

The goal: A consistent policy for vector operations

With the introduction of $n$-dimensional vectors in p5.js 2.0, we have an exciting opportunity to align p5.js with modern math and machine-learning libraries. This can provide an accessible, creative onramp for users to learn fundamental data-science concepts. In fact, this was the original motivation for introducing $n$-dimensional vectors to p5.

A core concept in these libraries is broadcasting, a standard set of rules for handling operations between vectors, matrices, or tensors of different dimensions. These rules are used everywhere from math libraries like math.js, to machine-learning libraries like TensorFlow.js.

This issue proposes that p5.js adopt the standard broadcasting rules to ensure our math library is consistent, predictable, and extensible for future features like p5.Matrix. Let's explore what that means.

How broadcasting works

For now, it will help to consider how broadcasting works in the special case of vectors. Here, broadcasting tells us that two vectors can be operated on if they have matching dimensions, or if one of the vectors is 1D. That's it. Let's look at some examples of why this rule is so useful.

Addition and subtraction:
createVector(10, 10, 10).add(2) produces components [12, 12, 12]

The 2 in the 1D vector [2] is broadcast to higher dimensions, so that we're really adding [10, 10, 10] and [2, 2, 2]. This is a useful operation in data processing, statistics, etc. For example, given a list of exam grades like [92, 83, 61, 97, 72, 75, 64, 95, 100, 82], we can center it around zero by subtracting the average (82.1) from every number in the list. This makes it clear which scores are below average and which are above average.

Multiplication and division:
createVector(10, 10, 10).mult(2) produces components [20, 20, 20]

As before, the 1D vector [2] becomes [2, 2, 2], and the operation is applied elementwise. This isn't just predictable. It's also very useful. This is scalar multiplication: the vector is scaled by 2, making it twice as long.

[Edit] Performance clarification:
To clarify, the explanation above describes the conceptual model that users can rely on to predict the results of broadcasting. Efficient broadcasting implementations would never actually expand a 1D vector like [2] to a 3D vector [2, 2, 2].

The problem: Current behavior is inconsistent

Currently, p5.js does not follow standard broadcasting rules, which creates several problems:

• Internal inconsistency: p5.js is inconsistent with itself—mult(2) applies to all components (correct), but add(2) applies only to the first component. It offers no such shortcut for the second component.
• External inconsistency: The custom behavior in p5 is different from every major math and ML library, making p5.js less of an onramp, and forcing users to unlearn p5's rules to advance. It's also inconsistent with creative-coding libraries. For example, openFrameworks uses standard broadcasting for operations among vectors.
• Confusing padding rules: For multi-element multipliers like in createVector(1, 1, 1).mult(2, 2), v1.x pads the missing component with 1 (resulting in [2, 2, 1]), which is an unpredictable special case. Users might guess [2, 2, 2].

[Update] Added point about openFrameworks.

How could p5 work? The options.

As we stabilize the p5.Vector feature set for p5.js 2.0, we have the opportunity to reassess the rules that p5 should follow. Several options have been described by @limzykenneth:

1. Refuse to operate on incompatible vectors (ie. throwing an error when this is tried)
2. Perform broadcasting where possible and refuse to operate thereafter
3. Automatically convert all vectors to the highest common dimension with 0 padding before operating
4. Some combination of the above

Weighing the options: Options 2 and 4 seem most viable

The first option is likely not viable, as it would disallow common operations like scalar multiplication. That leaves Options 2, 3, and 4. Option 3 introduces additional forms of complexity, as noted previously, and it goes against the original reason for introducing $n$-dimensional vectors to p5, since advanced math and machine-learning libraries do not work this way. That leaves Options 2 and 4. Perhaps, in a creative-coding context, Option 4 might be useful?

The trouble with Option 4

For Option 4, it seems sensible to at least follow standard broadcasting rules when one of the vectors is 1D. Then the question is, how do we handle mismatches where neither of the vectors is 1D? If we look at a concrete example, we start to see how confusing it might be. In the example below, there is no obvious way to proceed, and users are left guessing.

Example: createVector(2, 3).mult(4, 5, 6)
Do we extend [2, 3] to [2, 3, 0], since that's the most natural way to extend a 2D vector to a 3D vector?
Do we extend [2, 3] to [2, 3, 3], extending the broadcasting approach by repeating the last entry?
Do we extend [2, 3] to [2, 3, 1], since 1 is the multiplicative identity?
Does the user want the vector [2, 3] to turn into a 3D vector at all?

This is just one simple vector example. If we consider matrices or tensors, the situation may become more complicated.

Proposal: Adopt Standard Broadcasting (Option 2)

Based on the analysis above, I propose that p5.js adopt the standard, widely-used broadcasting rules:

1. Operations are allowed if vector dimensions match.
2. Operations are allowed if one operand is a scalar (a 1D vector or a single number).
3. All other dimension mismatches will throw an error.

This approach is simple, consistent, and avoids the ambiguity of custom padding rules (as shown in the "trouble with Option 4" example). It also aligns with the original motivation for $n$-dimensional vectors, by preparing users for advanced math and machine learning libraries. And it ensures our API will be extensible to p5.Matrix and even p5.Tensor.

[Update] Additional benefits:
The proposed policy would also resolve existing issues beyond vector algebra. An example is outlined in #8189.

Abundance of evidence indicates zero disruption

This would be a breaking change, but major releases are the appropriate time to fix confusing or inconsistent APIs. The key cost to consider is user disruption. To assess this, I collected two forms of data, which together provide a robust body of evidence that indicates zero disruption.

• Empirical data: I did a Google Search for site:https://editor.p5js.org/ "createVector" "add" and manually reviewed the first 50 results that called the add() method. Of these, precisely zero used dimension mismatches. ¹ I repeated the same methodology for the mult() method, and similarly found that zero of 50 sketches using mult() called it with a nonstandard dimension mismatch (the only dimension mismatch detected was multiplication by a scalar, a case which is unchanged by the current proposal).
• Domain Knowledge: This 0% finding is what we'd expect. The non-standard behavior is not documented by any reference examples, it has a more writable and readable alternative (e.g. v.x += 2), it has no clear use cases, and it is inconsistent with every single major library, across languages and domains—even Processing's PVector does not behave this way.

A more rigorous, Bayesian analysis (for the curious)

For those interested in statistical rigor, this is a textbook case for a beta-binomial model. Given the $0$ observed uses in our $n=50$ sample for add(), and a very generous prior belief that maybe 1 in 1,000 sketches using add() rely on the nonstandard behavior (0.1%), we can be 97.5% confident that the true usage rate in the wild is, at most, 0.351% (or about 1 in 284 sketches that use add()). Also, if there are any sketches that use the non-standard behavior, that code would only break if it's migrated to 2.x; many sketches will be left as is and won't switch to an upgraded version. So it's likely that the true proportion of sketches that would be broken is extremely small, and may well be exactly zero.

Just in case, we can clearly document the breaking change in the compatibility README, which contains the official list of breaking changes made in the upgrade from 1.x to 2.x.

Updates:

1. Added results of the mult() analysis.
2. Added supporting domain knowledge.
3. Added statistical model. (See #8203 for original version.)

Discussion

What do you think, everyone? How would you handle dimension mismatches? Are there any use cases I didn't cover that you think are important?

Invitation for comment

Many other community members have been actively involved in related discussions, and I'd love to hear their thoughts. These include @ksen0, @limzykenneth, @inaridarkfox4231, @sidwellr, @Ahmed-Armaan, @davepagurek, @holomorfo, @nickmcintyre, @RandomGamingDev, and many others. Everyone is welcome to share their ideas!

Footnotes

1. In a technical sense, one sketch used a dimension mismatch due to the way vectors are represented in 1.x, but if this sketch were upgraded to 2.x, there would be no dimension mismatch, so the code would not break. Specifically, the code had the form add(number1, number2) and was adding to a vector that was intended to be 2D. In 1.x, vectors are represented internally as 3D vectors, so this involved a mismatch. However, with true 2D vectors in 2.x, there'd be no dimension mismatch, so the change to standard broadcasting rules wouldn't break this code. ↩

[davepagurek]

My one thing to add for partial broadcasting is that I'd broadcast with whatever leaves the remaining values untouched -- so if you're multiplying or dividing, it'd mean padding with 1; if you're adding or subtracting, it'd mean padding with 0.

That said, I generally agree that those silent choices have a lot of potential for confusion. e.g. outside of the vector API, drawing a 3D model with scale(n, n) accidentally doesn't scale the z axis at all, which can be hard to notice if you don't orbit, and can be hard to trace down the cause for.

So my preference is to also go with what you suggested, allowing operations with scalars but nothing else.

The only thing that gives me a bit of pause is the fact that we're going to be introducing more errors, which could be as simple as adding a 1 or 0 to a createVector, but sometimes the spot you have to add it is not the spot where the error takes place, because the vector in question was created elsewhere. That's probably fine for now? But let's be open to ideas for how to improve messaging there (or possibly different convenience methods to convert between dimensions, e.g. myVec2.pad(0).toDim(3), so you could offer in the error that a user add that directly at the spot causing the error.)

[GregStanton]

Thanks for the great discussion on this @davepagurek. It seems we're in agreement, but I'm glad you mentioned the alternative idea of "partial broadcasting," by padding with an identity element (e.g., 0 for addition). It is really appealing because it feels like it could be a helpful shortcut. It also aligns with some of p5's 1.x behavior, which is an important consideration. So, I thought it was worth a closer look. My analysis validates the standard-broadcasting approach and shows that your idea for improving the error experience is the perfect complement to it.

Motivation

To make sure we're making the best long-term decision, I did a deeper dive into the potential trade-offs of the custom approach versus the universal standard for broadcasting. I'll share my findings here for anyone reading along, and also to serve as a more complete public record of the design rationale.

A deeper look at broadcasting: The case for a standard, error-throwing approach

My analysis suggests that while well-intentioned, custom broadcasting adds features with limited utility and high costs in consistency, writability, extensibility, and cognitive load.

Key costs

Here are the key costs as I currently understand them:

1. The "intuitive" trap (consistency & predictability)

A custom rule to pad [2, 3] with a 0 when adding it to [4, 5, 6] seems helpful, but this appears to be a hypothetical problem—my review of 50 sketches that call add() found this usage zero times. This suggests that if this feature is used, there's a decent chance it's unintentional. In a far more common operation, scalar multiplication, padding with an identity is likely to cause confusion.

Internal inconsistency: In p5.js, createVector(x, y, z).mult(2) correctly broadcasts the scalar to all components (i.e., [2, 2, 2]). A user would logically infer that createVector(x, y, z).mult([2, 2]) should behave the same way—by repeating the last component. Another possibility is that they might associate [2, 2] with [2, 2, 0], as this is the usual way to map two-space into three-space. In both of these cases, padding with the multiplicative identity (1) amounts to incorrectly guessing user intent.

External inconsistency: This custom behavior does not appear to exist in any major math or ML library. This undercuts our goal of being a creative onramp to these tools.

These inconsistencies result in an API that violates the principle of least surprise.

2. Hidden bugs (writability)

Incorrect inferences

Partial broadcasting hides the bug. It silently "fixes" the data by guessing what the user meant, and it's likely to guess wrong, as noted above. A system that allows users to write code that isn't explicit can also lead to strange visual glitches (as in the scale(n, n) issue you mentioned). In contrast, standard broadcasting throws an error when it sees an invalid operation like createVector(2, 3).add(4, 5, 6). This error is a feature! It tells the user, "Your data shapes don't match, you likely have a bug."

Corrective tools

Your idea to provide tools to easily fix the reported errors, like pad(), is inspired ✨This way, we get the best of both worlds: a system that prevents hidden bugs by default, with thoughtful tools to help users fix them. It perfectly aligns with the Friendly Error System. If we all agree on this path, I think the next step would be to implement the standard error-throwing behavior. The good news is that the repair kit you imagined is already being designed! The matrix proposals I've been working on provide a cohesive set of common functions like pad().

3. Brittleness (extensibility)

The identity-padding approach is not a scalable system. It fails for rem(), which has no identity element. It also fails for fundamental elementwise operations like min(), max(), and equals().

This creates a two-tier API where users must memorize a list of which functions have p5.js-specific magic and which ones throw errors. Standard broadcasting provides one simple, universal rule for everything.

4. Cognitive load (readability)

Every custom rule adds to the cognitive load on learners, likely without adding significant power, since the most powerful libraries work without additional, custom rules.

Standard broadcasting: Users learn one rule that is universal, powerful, and transferable outside of p5.js.

Partial broadcasting: Users must learn the standard rule, plus a list of p5.js-specific exceptions and their corresponding identity elements.

Assessing the impact of breaking changes: Zero disruption detected

The primary argument for keeping the 1.x behavior appears to be backward compatibility. My analysis of existing usage suggests the disruption from adopting the standard would be zero, or near-zero. (See the methodology and results in the top post.)

Summary of trade-offs

Criteria	Standard broadcasting (proposal)	Partial broadcasting by identity (alternative)
Consistency	One universal rule. Consistent internally and with all external libraries.	Many exceptions. Inconsistent with itself and all external libraries.
Writability	Throws helpful errors, revealing bugs to the user.	Silently fails, hiding bugs and causing hard-to-diagnose glitches.
Extensibility	A robust system. Works for all current and future elementwise operations.	A brittle patch. Fails for many operations beyond basic arithmetic.
Readability	Low cognitive load. Easy to learn, teach, and document.	High cognitive load. Users must memorize a list of p5.js-specific special cases.

[sidwellr]

To me, a 1D vector is not a scalar. For example, the scalar 2 is different from the vector [2]. Multiplication of a vector by a scalar a is not done by creating a new vector [a, a, ...] of the same dimension and computing the Hadamard product; it is done by simply multiplying each element of the vector by a. Broadcasting is not applicable.

If we want multiplication of two vectors where one is 1D to be treated as scalar multiplication, we could implement that. But p5.js doesn't do that now. This is an important part of what @GregStanton is proposing. It could be implemented using broadcasting, or more simply by treating the 1D vector as a scalar.

I prefer to think of this as option 1, throw an error when vector dimensions don't match, but with a possible exception.

For compatibility with version 1, we need one more exception: If one vector is 2D and the other is 3D with a z component of 0, convert the 3D vector to a 2D vector by removing the z component so the operation can be performed. This is likely to happen when a user creates a sketch with mostly 2D vectors but uses createVector() with no parameters, which currently creates a 3D vector. (@shiffman does this frequently in his Nature of Code book, so I expect it to be a widespread practice.) I do think it appropriate to generate a warning when this happens (a suggestion by @limzykenneth on issue #8117). This may not be needed if we can do some magic with createVector(); see subissue #8156.

[RandomGamingDev]

Thanks for inviting me, I'd love to contribute :D

Agreements & Disagreements

1. Refuse to operate on incompatible vectors (ie. throwing an error when this is tried)
2. Perform broadcasting where possible and refuse to operate thereafter
3. Automatically convert all vectors to the highest common dimension with 0 padding before operating
4. Some combination of the above

While I absolutely do agree about performing broadcasting where possible and refusing to operate otherwise (this is especially since I do come from a background of stricter languages e.g. with static typing alone), but I don't see why we can't have multiple options to suit each group, and possibly benefit both in their individual scenarios when needed.

Suiting Multiple Needs

@davepagurek:

That said, I generally agree that those silent choices have a lot of potential for confusion. e.g. outside of the vector API, drawing a 3D model with scale(n, n) accidentally doesn't scale the z axis at all, which can be hard to notice if you don't orbit, and can be hard to trace down the cause for.

@GregStanton:

Partial broadcasting hides the bug. It silently "fixes" the data by guessing what the user meant, and it's likely to guess wrong, as noted above.

I absolutely agree with these, but I think an issue being ignored here is not just that people might want their applications to be automatically redundant (as per Javascript's philosophy/principle with things like type coercion), but also the fact that many features like adding a vec2 to a vec3 can be done out of a concern for performance rather than as a mistake (creating a larger vector when dealing with millions is a great way to send any intensive program into a halt), and especially if we have any future plans to batch things like these which can be a pain to implement manually. Plus, there's the fact that throwing a warning (which I think that we should do over throwing an error by default in order to correspond with Javascript's philosophy of making whatever assumptions needed to avoid erroring out) requires checking for mismatches, an operation that can be expensive for what's meant to be an optimized math library meant to handle graphics (and hopefully far more with p5's 2.0 release :D).

Generalization

Take for example numpy, the most popular math library and de facto standard we seem to be basing a lot of things off of. Even they have modes for being more permissible with errors via numpy.seterr in lieu of other solutions.

While they don't have options for broadcasting via numpy.seterr, that's largely because it isn't something absent. Assuming that we don't implement methods for broadcasting that rival it (which we probably shouldn't be considering our position within the JS ecosystem and the manpower cost), it seems the clear choice is to not choose one, but to give the users everything needed to cover all use cases:

1. "Perform broadcasting where possible and refuse to operate thereafter": Improves debugging, helping people to learn and avoid dumb issues at the cost of an increased performance penalty.
2. "Automatically [broadcast] all vectors to the highest common dimension": Horrible debugging, bad for those trying to learn, but increased performance and redundancy.

This relates to what @davepagurek said:

The only thing that gives me a bit of pause is the fact that we're going to be introducing more errors, which could be as simple as adding a 1 or 0 to a createVector, but sometimes the spot you have to add it is not the spot where the error takes place, because the vector in question was created elsewhere. That's probably fine for now? But let's be open to ideas for how to improve messaging there (or possibly different convenience methods to convert between dimensions, e.g. myVec2.pad(0).toDim(3), so you could offer in the error that a user add that directly at the spot causing the error.)

Of course, if we were to implement options for broadcasting on the scale of numpy we should solely go with the first, but again, it's unrealistic in our current position.

To be honest, I don't think @davepagurek suggestion:

My one thing to add for partial broadcasting is that I'd broadcast with whatever leaves the remaining values untouched -- so if you're multiplying or dividing, it'd mean padding with 1; if you're adding or subtracting, it'd mean padding with 0.

would be enough.

There's also the aforementioned idea that Javascript and our community within it is far different from that of math libraries like numpy:

"JS is also an example of the 'worse is better' pattern in software engineering" - Eric Lippert

Even if it's a principle that I personally disagree with (I think Javascript should've used strict types and severely disincentivized type coercion from the very start as Brendan Eich said "I regret the implicit conversions that make == not an equivalence relation with disparate types on left and right"), I think there's something to be said for continuing Javascript's principle of redundancy without numpy-level broadcasting in our Javascript library while offering a stricter option as the default if unwanted.

P.S. Why choose one? Choose both.

[GregStanton]

Thanks for raising these points, @sidwellr! This is a great opportunity to clarify some of the subtle but important details for everyone following along.

To me, a 1D vector is not a scalar... Multiplication of a vector by a scalar a is not done by creating a new vector [a, a, ...]... Broadcasting is not applicable.

This point is crucial. In scientific computing, there is a clear distinction between a scalar (2) and a 1D vector ([2]). The challenge for p5.js is that our own API often makes it impossible for us to know which one the user intends. Throughout most of the p5.Vector API, users can specify vectors with separate number arguments, an array of numbers, or a vector instance. Consequently, a user may reasonably view vec.mult(2) and vec.mult([2]) as two ways of multiplying by a 1D vector.

Fortunately, this is a classic problem that standard broadcasting solves elegantly. The conceptual model is simple: for any operation between a scalar and a vector, the scalar is "promoted" to a 1D vector, and then the broadcasting rules take over. This ensures that whether the user provides 2 or [2], the result is the same. It turns a potential source of ambiguity into a point of consistency.

This is also why the implementation details don't matter to the user. While an efficient broadcasting implementation would never actually create a new [a, a, ...] array, that simple conceptual model makes the rule easy to understand and predict.

Adopting this standard also resolves confusing inconsistencies in the current API. In 2.x, vec.mult(2) and vec.mult([2]) produce different results, which is an undocumented behavior that requires users to learn separate rules, without a significant benefit. This also breaks backward compatibility with 1.x, which produces the same result in each case. Standard broadcasting unifies disparate rules and restores backward compatibility in this case, ensuring that no matter how a user specifies the scalar/1D vector, the outcome is predictable and correct.

Hope this clarifies the thinking behind this part of the proposal! It's a great example of how adopting a well-established standard can help us resolve tricky API ambiguities.

[GregStanton]

Thank you for sharing such detailed thoughts, @RandomGamingDev, and for your offer to contribute! This is shaping up to be a terrifically productive conversation.

It's great that we're aligned on the core preference for standard broadcasting rules. I'll focus my reply on the new points you've surfaced about performance, error handling, and the idea of offering multiple modes.

...many features like adding a vec2 to a vec3 can be done out of a concern for performance rather than as a mistake (creating a larger vector when dealing with millions is a great way to send any intensive program into a halt)

I'm so glad you're watching out for this. Performance is a critical accessibility concern.

The good news is that this performance concern is completely solved by how standard broadcasting is implemented. Efficient broadcasting implementations never actually create larger, temporary arrays. The idea of "expanding" a vector is just a simple conceptual model to help users predict the results. The underlying code works efficiently on the original data, so there is no performance penalty or memory allocation cost. This means we get the benefit of a simple mental model without any of the performance drawbacks.

Plus, there's the fact that throwing a warning (which I think that we should do over throwing an error by default in order to correspond with Javascript's philosophy...) requires checking for mismatches, an operation that can be expensive...

This is a great topic for discussion, and it touches on the core philosophy of the library. Here’s how I see it:

1. The p5.js precedent: While JavaScript as a general language is permissive, p5's philosophy is tuned to its precise audience and realized through its Friendly Error System (FES). The goal of FES isn't to avoid errors, but to make them as helpful as possible. Your suggestion of a warning, and @davepagurek's idea of a "repair toolkit" in the error message, are perfect extensions of the FES philosophy. A clear error that tells a user how to fix their code is the most user-friendly approach.
2. The JS ecosystem precedent: For this specific domain (scientific computing in JS), a library like TensorFlow.js is a very strong precedent. It throws clear errors on shape mismatches.
3. The performance consideration: The performance cost of checking for a mismatch is identical for both errors and warnings. In either case, the code must perform an if (dimensions_do_not_match) check. Throwing an error is actually faster because the program stops, whereas a warning would require both the check and the overhead of logging a message while the program continues.

...it seems the clear choice is to not choose one, but to give the users everything needed to cover all use cases... "Why choose one? Choose both."

I appreciate this perspective, but I believe offering multiple modes would introduce more problems than it solves. The numpy.seterr example is interesting, but it's for numeric errors, and even NumPy doesn't offer a custom "permissive" mode for broadcasting shape errors. Offering a custom mode would increase the maintenance burden for p5 developers and the cognitive load for users, in exchange for a set of features with limited uses.

Fortunately, the standard, error-throwing approach is consistent, performant, debuggable, and extensible. It provides a solid foundation that we can build upon with the excellent FES and "repair kit" ideas that have come up in this conversation.