Tensor Broadcasting in Java: Shapes, Rules, and Common Errors

Add a bias vector to a Java tensor, fix an incompatible shape, and catch a valid broadcast that silently calculates the wrong loss.

Javajax4jtensorsbroadcastingnumerical computing
Java notebookJava kernel · starts on first runWebGPU · not requested

Run cells from top to bottom. Typed declarations and imports carry into later cells. Shift + Enter runs a cell. Reloading or leaving this page discards edits and Java state.

Ready to start

You have two examples, three output scores per example, and three biases to add. A six-line loop would do it. With jax4j, scores.add(bias) does it too. Then you add one adjustment per example, and the same operation throws a shape error. Reshape the wrong way and it may run perfectly while answering a different question.

Tensor broadcasting determines how operands with different shapes line up during elementwise arithmetic. The useful question is which values meet at each output position. Java arrays do not provide these rules themselves; here we use jax4j's tensor API.

Our constructed example starts with scores [[1, 2, 3], [4, 5, 6]]. Rows identify examples; columns identify outputs. Adding biases [10, 20, 30] should produce [[11, 22, 33], [14, 25, 36]]. Each bias belongs to a column and applies to both rows.

Solid input cells stretch into dashed repeated positions. A bias row 10,20,30 expands down to two examples; a column of adjustments 100,200 expands across three outputs. Arrows show the expanding axis and the result grids show the corresponding sums.

Run the cells in order, or choose Run all. They use jax4j 0.2.2 on the browser notebook's emulated CPU, with F32 values. No training, dataset, or GPU is involved. The first run includes loading Java. Later cells reuse the imports from the first; each try block closes its own tensors.

Add a bias vector to every row

A tensor's shape lists its axis lengths. Our scores have shape [2, 3]: two rows and three columns. The bias has shape [3], a one-dimensional vector. A one-dimensional tensor has no built-in row or column orientation.

In [ ]:

1. One bias per output

The result has shape [2, 3] and flattened values [11, 22, 33, 14, 25, 36]. toFloatArray() prints values in row order; it does not remove the tensor's shape. For row i and column j, the calculation is shifted[i,j] = scores[i,j] + bias[j].

The addition creates a result tensor and leaves the input scores available. It also requires the operands to share a dtype and device. Compatible shapes alone do not permit mixing unrelated device placements or F32 and F64 tensors.

For one adjustment per example, construct a column directly: Tensors.array(new float[] {100, 200}, 2, 1). The explicit [2, 1] shape places one value on each row, ready to expand across the three outputs. No separate reshape is needed.

In [ ]:

2. Construct a column of row adjustments

The adjustment shape is [2, 1]; the result shape is [2, 3]. Expect [101, 102, 103, 204, 205, 206]: 100 was added to every entry in the first row, and 200 to every entry in the second.

Broadcasting rules: align shapes from the right

jax4j follows NumPy-style broadcasting rules. Compare axes from right to left. An aligned pair is compatible if its lengths are equal or either length is one. Treat a missing leading axis as length one. A singleton axis expands to the matching length; equal lengths stay equal.

For the bias calculation, write the shapes with their right edges aligned:

Shapes align by their final axes. A length-three bias acts as one-by-three: the final threes match and one row expands to two. A length-two vector fails because its final two cannot match three.

The final threes match. The implicit leading one expands to two. This describes which bias value each addition uses; your Java code does not need to construct a second bias row.

These rules concern elementwise operations such as add, sub, mul, and div. Multiplying a [2, 3] tensor by a [3] vector with mul scales each column. Matrix multiplication uses matmul and has a separate contract.

Left shapeRight shapeResultMeaning for our scores
[2, 3][3][2, 3]One value per column
[2, 3][1, 3][2, 3]Explicit version of the same alignment
[2, 3][2, 1][2, 3]One value per row
[2, 3][2]ErrorFinal lengths three and two disagree

Give each example its own adjustment

Why did we explicitly construct the adjustments with shape [2, 1]? A [2] vector looks tempting: two examples, two adjustments. But broadcasting matches axis positions, not the names in our heads. Its length two would meet the scores' final length three.

The next cell deliberately catches that error, then adds a trailing singleton axis with reshape(2, 1).

In [ ]:

3. Put the adjustment on the row axis

Expect [101, 102, 103, 204, 205, 206]. The trailing one expands across columns; the leading two matches the examples. Reshaping keeps the two adjustment values in their order and changes how their axes align. It cannot turn two values into three independent column biases.

Try changing only the second adjustment to 500. Only the second row should change. This is a useful check because an output with the right shape can still have values assigned to the wrong axis.

On a square [2, 2] matrix, a [2] vector would be compatible and apply by column, even if you intended row adjustments. An exception is helpful here. Equal axis lengths can take that help away.

Keep the axis when reducing a row

Broadcasting also matters after a reduction, an operation that combines values along an axis. Suppose we want to subtract each row's mean. Axis zero identifies examples; axis one identifies the three outputs.

scores.mean(1) reduces the output axis and returns shape [2]. Those are the two correct means, but their shape is unsuitable for subtracting them from [2, 3]. scores.mean(1, true) retains the reduced axis at length one, returning [2, 1].

In [ ]:

4. Center each row with keepDims

The means are [2, 5], with shape [2, 1]. Centered values are [-1, 0, 1, -1, 0, 1]. Each row now sums to zero. Keeping the axis records where the reduced values belong when they meet the original tensor again.

The same pattern appears in stable softmax: retain the class axis when calculating row maxima and sums, then broadcast those quantities back across each row. For a longer practice session, the reshape, slice and reduce lesson lets you work through axis changes in editable cells.

The broadcast that silently changes your loss

An incompatible shape stops the calculation. A compatible mistake can survive much longer.

Suppose a model makes one prediction per example. Predictions have shape [2, 1] and values [[2], [5]]. Targets arrive as a plain [2] vector containing [1, 4]. We want errors [1, 1], so the mean squared error should be one.

Subtract the tensors as supplied, however, and broadcasting creates a [2, 2] result. Each prediction meets every target:

Both loss operands expand: the prediction column 2,5 repeats across columns and the target row 1,4 repeats down rows. The four errors 1,-2,4,1 give MSE 5.5; red off-diagonal cells compare different examples. Reshaping targets to a column gives two paired errors 1,1 and MSE 1.0.

The squared errors sum to 22. Averaging four entries gives 5.5, an entirely finite answer to the wrong question.

In [ ]:

5. Compare paired errors with all-pairs errors

The corrected subtraction uses two [2, 1] tensors and produces [1, 1], with mean squared error 1.0. If a loss requires paired predictions and targets, assert equal shapes at that boundary. Broadcasting is useful elsewhere; this particular calculation needs matching positions.

Check the output size before allocating it

The accidental all-pairs calculation also has a memory consequence. [N, 1] combined with [N] produces [N, N]. At 10,000 examples, that is 100 million F32 entries: 400 MB for one result buffer, before squared errors and any other temporaries. The intended [N, 1] result needs only 40,000 bytes.

Broadcasting avoids writing a repeated Java input array, but does not guarantee zero-copy execution. jax4j's eager binary-operation path can materialize expanded operands and closes its temporary broadcast tensors after the operation. Output storage still scales with the result shape. See the implementation in Tensor.java; these examples make no performance claim.

Before changing a reshape to silence an error, write the axis meanings beside both shapes. Align their right edges, predict the result shape, and check one output by hand. Use unequal axis lengths in a small debugging example so a swapped meaning is more likely to fail visibly. For paired losses, check exact shape equality before subtraction.

The broadcasting lesson offers more experiments with per-sensor gains and offsets. Try changing our batch from two examples to four while keeping three outputs. The column bias should stay [3]; row adjustments must become [4, 1]. Predicting those two shapes before running is a useful check that the axis meanings have stuck.


Questions or corrections? open an issue