Reference for shape manipulation, stacking, splitting, and array transformation operations.
Reshape the array to a new shape.
public function reshape(array $newShape, string $order = 'C'): NDArrayReturns a new array with the specified shape. Supports both C-order (row-major, order='C') and F-order (column-major, order='F').
One dimension in $newShape may be -1. When present, that dimension is inferred from the array size and the remaining dimensions. The total number of elements must stay the same.
| Name | Type | Description |
|---|---|---|
$newShape |
array<int> |
New shape. At most one dimension may be -1 to infer that dimension automatically. |
$order |
string |
Memory layout: 'C' for row-major, 'F' for column-major. Default: 'C' |
NDArray- Reshaped array. This will be a new view object if the array is contiguous; otherwise, it will be a copy. Note there is no guarantee of the memory layout (C- or Fortran- contiguous) of the returned array.
ShapeException- If the requested shape does not contain the same number of elements as the original array.ShapeException- If more than one dimension is-1.ShapeException- If a dimension is less than-1.ShapeException- If the inferred-1dimension would not be an integer.ShapeException- If the inferred dimension is ambiguous because the product of the known dimensions is zero.
$arr = NDArray::arange(12);
// Reshape to 2D
$matrix = $arr->reshape([3, 4]);
print_r($matrix->shape());
// Output: [3, 4]
// Infer one dimension from the array size
$matrix = $arr->reshape([3, -1]);
print_r($matrix->shape());
// Output: [3, 4]
$rows = $arr->reshape([-1, 6]);
print_r($rows->shape());
// Output: [2, 6]
// Reshape to 3D
$tensor = $arr->reshape([2, 2, 3]);
print_r($tensor->shape());
// Output: [2, 2, 3]Only one dimension can be inferred:
$arr->reshape([-1, -1]); // ShapeException
$arr->reshape([5, -1]); // ShapeException: 12 cannot be divided into rows of 5
$arr->reshape([2, -2]); // ShapeException: -2 is not a valid dimensionTranspose the array.
public function transpose(): NDArrayFor 2D arrays, swaps rows and columns. For nD arrays, reverses the order of all axes.
None.
NDArray- A view of the array with its axes permuted. A view is returned whenever the array is contiguous; otherwise a copy is made.
$matrix = NDArray::array([
[1, 2, 3],
[4, 5, 6]
]);
$transposed = $matrix->transpose();
print_r($transposed->shape());
// Output: [3, 2]
print_r($transposed->toArray());
// Output: [[1, 4], [2, 5], [3, 6]]Flatten the array to 1D.
public function flatten(): NDArrayAlways returns a copy in C-order (row-major).
None.
NDArray- Flattened 1D array (copy).
$matrix = NDArray::array([[1, 2], [3, 4]]);
$flat = $matrix->flatten();
print_r($flat->toArray());
// Output: [1, 2, 3, 4]Ravel the array to 1D.
public function ravel(string $order = 'C'): NDArraySimilar to flatten() but may return a view if the array is contiguous.
| Name | Type | Description |
|---|---|---|
$order |
string |
Memory layout: 'C' for row-major, 'F' for column-major. Default: 'C' |
NDArray- A 1D view of the array if it is contiguous; otherwise, a contiguous 1D copy.
$matrix = NDArray::array([[1, 2], [3, 4]]);
$raveled = $matrix->ravel();
print_r($raveled->toArray());
// Output: [1, 2, 3, 4]When you need a one-dimensional representation of an array, you have three options:
| Method | Returns | When to Use |
|---|---|---|
flatten() |
1D NDArray (copy) | When you need a real array and want to ensure no shared memory |
ravel() |
1D NDArray (view or copy) | When you need a real array and want zero-copy when possible |
flat() |
FlatIterator | When you just need to iterate or index elements, not a full array |
Key Differences:
flatten() always creates a new contiguous copy. Changes to the result don't affect the original, and vice versa. This is safest when you need independence.
ravel() returns a view if the array is already contiguous, avoiding a copy. For non-contiguous arrays (like slices or transposed arrays), it falls back to copying. Use this when performance matters and you can handle either views or copies.
flat() returns an iterator, not an array. It provides element-by-element access without copying any data, working efficiently even on complex views. However, you get an iterator object, not an NDArray, so you can't use array methods like mean() or sum() on it directly.
$matrix = NDArray::array([[1, 2], [3, 4]]);
// Get a 1D array (copy)
$copy = $matrix->flatten();
echo $copy->sum(); // Works: 10
// Get a 1D array (view if contiguous)
$view = $matrix->ravel();
echo $view->mean(); // Works: 2.5
// Iterate without copying
foreach ($matrix->flat() as $value) {
echo $value . " ";
}
// Output: 1 2 3 4Swap two axes of the array.
public function swapaxes(int $axis1, int $axis2): NDArray| Name | Type | Description |
|---|---|---|
$axis1 |
int |
First axis to swap |
$axis2 |
int |
Second axis to swap |
NDArray- Array with swapped axes (view).
$tensor = NDArray::arange(24)->reshape([2, 3, 4]);
$result = $tensor->swapaxes(0, 2);
print_r($result->shape());
// Output: [4, 3, 2]Permute axes of the array.
public function permute(int ...$axes): NDArrayReorders the axes according to the given permutation. For example, permute(1, 0) on a 2D array is equivalent to transpose().
| Name | Type | Description |
|---|---|---|
$axes |
int... |
New order of axes (variadic) |
NDArray- Array with permuted axes (view).
$tensor = NDArray::ones([2, 3, 4, 5]);
$permuted = $tensor->permute(2, 0, 3, 1);
print_r($permuted->shape());
// Output: [4, 2, 5, 3]Merge axes by combining one axis into another.
public function mergeaxes(int $take, int $into): NDArrayMerges the axis take into axis into by combining their dimensions. The take axis is removed and its size is multiplied into the into axis.
| Name | Type | Description |
|---|---|---|
$take |
int |
Axis to merge from (will be removed) |
$into |
int |
Axis to merge into (size will be multiplied) |
NDArray- A view of the array with merged axes. This is always a view into the original array with updated shape and strides.
$tensor = NDArray::arange(24)->reshape([2, 3, 4]);
$result = $tensor->mergeaxes(1, 0);
print_r($result->shape());
// Output: [6, 4]Reverse the order of elements in an array along the given axis or axes.
public function flip(array|int|null $axes = null): NDArray| Name | Type | Description |
|---|---|---|
$axes |
array<int>|int|null |
Axis or axes to flip. If null, flip over all axes. |
NDArray- Array with reversed elements.
$arr = NDArray::array([[1, 2, 3], [4, 5, 6]]);
// Flip single axis
$result = $arr->flip(0);
print_r($result->toArray());
// Output: [[4, 5, 6], [1, 2, 3]]
// Flip with negative index
$result = $arr->flip(-1);
print_r($result->toArray());
// Output: [[3, 2, 1], [6, 5, 4]]
// Flip multiple axes
$result = $arr->flip([0, 1]);
print_r($result->toArray());
// Output: [[6, 5, 4], [3, 2, 1]]
// Flip all axes
$result = $arr->flip();
print_r($result->toArray());
// Output: [[6, 5, 4], [3, 2, 1]]Insert a new axis at the specified position.
public function insertaxis(int $axis): NDArrayThe new axis always has length 1.
| Name | Type | Description |
|---|---|---|
$axis |
int |
Position where new axis is inserted |
NDArray- Array with new axis (view).
$arr = NDArray::array([1, 2, 3]);
$expanded = $arr->insertaxis(0);
print_r($expanded->shape());
// Output: [1, 3]
$expanded = $arr->insertaxis(1);
print_r($expanded->shape());
// Output: [3, 1]Expand dimensions by inserting a new axis.
public function expandDims(int $axis): NDArrayAlias for insertaxis().
| Name | Type | Description |
|---|---|---|
$axis |
int |
Position where new axis is inserted |
NDArray- A view of the array with the number of dimensions increased by inserting a new axis of length 1. This is always a view into the original array.
$arr = NDArray::array([1, 2, 3]);
$expanded = $arr->expandDims(0);
print_r($expanded->shape());
// Output: [1, 3]Remove axes of length 1 from the array.
public function squeeze(?array $axes = null): NDArrayIf no axes are specified, removes all length-1 axes.
| Name | Type | Description |
|---|---|---|
$axes |
array<int>|null |
Specific axes to squeeze (null for all). Default: null |
NDArray- The input array, but with all or a subset of the dimensions of length 1 removed. This is always a view into the original array. Note that if all axes are squeezed, the result is a 0D array and not a scalar.
$arr = NDArray::ones([1, 3, 1, 4, 1]);
// Remove all single dimensions
$squeezed = $arr->squeeze();
print_r($squeezed->shape());
// Output: [3, 4]
// Remove specific axis
$squeezed = $arr->squeeze([0]);
print_r($squeezed->shape());
// Output: [3, 1, 4, 1]Pad an array.
public function pad(
array|int $padWidth,
PadMode $mode = PadMode::Constant,
array|bool|float|int $constantValues = 0
): NDArray| Name | Type | Description |
|---|---|---|
$padWidth |
array|int |
Number of elements to pad on each side of each axis. int: same on all sides of every axis; array{int,int}: [before, after] for all axes; array per-axis: int or [before, after] per axis |
$mode |
PadMode |
Padding mode. Default: PadMode::Constant |
$constantValues |
array|bool|float|int |
Constant value for PadMode::Constant. Default: 0 |
NDArray- Padded array.
$arr = NDArray::array([[1, 2], [3, 4]]);
// Pad with zeros (1 element on each side)
$padded = $arr->pad(1);
print_r($padded->shape());
// Output: [4, 4]
// With constant value
$padded = $arr->pad(1, constantValues: 9);Construct an array by repeating this array the number of times given by reps.
public function tile(array|int|NDArray $reps): NDArray| Name | Type | Description |
|---|---|---|
$reps |
array|int|NDArray |
Number of repetitions along each axis |
NDArray- Tiled output array.
$arr = NDArray::array([[1, 2], [3, 4]]);
// Tile 2 times along axis 0 and 3 times along axis 1
$result = $arr->tile([2, 3]);
print_r($result->shape());
// Output: [4, 6]
// Tile with integer (applies to first axis only)
$result = $arr->tile(2);
print_r($result->shape());
// Output: [4, 2]Repeat elements of an array.
public function repeat(array|int|NDArray $repeats, ?int $axis = null): NDArray| Name | Type | Description |
|---|---|---|
$repeats |
array|int|NDArray |
Number of repetitions for each element |
$axis |
int|null |
Axis along which to repeat. Default: flattened input. Default: null |
NDArray- Output array (same shape except along the given axis).
$arr = NDArray::array([1, 2, 3]);
// Repeat each element twice
$result = $arr->repeat(2);
print_r($result->toArray());
// Output: [1, 1, 2, 2, 3, 3]
// Repeat along axis
$matrix = NDArray::array([[1, 2], [3, 4]]);
$result = $matrix->repeat(2, axis: 1);
print_r($result->toArray());
// Output: [[1, 1, 2, 2], [3, 3, 4, 4]]Join arrays along an existing axis.
public static function concatenate(array $arrays, int $axis = 0): NDArrayAll arrays must have the same shape except for the dimension along the axis.
| Name | Type | Description |
|---|---|---|
$arrays |
array<NDArray> |
Arrays to concatenate |
$axis |
int |
Axis along which to join. Default: 0 |
NDArray- Concatenated array.
$a = NDArray::array([[1, 2], [3, 4]]);
$b = NDArray::array([[5, 6], [7, 8]]);
$out = NDArray::concatenate([$a, $b], axis: 0);
print_r($out->shape());
// Output: [4, 2]
$out = NDArray::concatenate([$a, $b], axis: 1);
print_r($out->shape());
// Output: [2, 4]Stack arrays along a new axis.
public static function stack(array $arrays, int $axis = 0): NDArrayAll arrays must have identical shapes.
| Name | Type | Description |
|---|---|---|
$arrays |
array<NDArray> |
Arrays to stack |
$axis |
int |
Axis in the result at which the arrays are stacked. Default: 0 |
NDArray- Stacked array.
$a = NDArray::array([1, 2, 3]);
$b = NDArray::array([4, 5, 6]);
$out = NDArray::stack([$a, $b]);
print_r($out->shape());
// Output: [2, 3]Stack arrays vertically (along axis 0).
public static function vstack(array $arrays): NDArrayEquivalent to concatenate(arrays, axis=0).
| Name | Type | Description |
|---|---|---|
$arrays |
array<NDArray> |
Arrays to stack |
NDArray- Vertically stacked array.
$a = NDArray::array([[1, 2], [3, 4]]);
$b = NDArray::array([[5, 6]]);
$out = NDArray::vstack([$a, $b]);
print_r($out->shape());
// Output: [3, 2]Stack arrays horizontally (along axis 1).
public static function hstack(array $arrays): NDArrayEquivalent to concatenate(arrays, axis=1).
| Name | Type | Description |
|---|---|---|
$arrays |
array<NDArray> |
Arrays to stack |
NDArray- Horizontally stacked array.
$a = NDArray::array([[1, 2], [3, 4]]);
$b = NDArray::array([[5], [6]]);
$out = NDArray::hstack([$a, $b]);
print_r($out->shape());
// Output: [2, 3]Split array along an axis.
public function split(array|int $indicesOrSections, int $axis = 0): arrayIf $indicesOrSections is an integer N, split into N equal parts (axis length must be divisible by N). If it is an array of indices, split at those positions.
| Name | Type | Description |
|---|---|---|
$indicesOrSections |
array<int>|int |
Number of equal parts, or array of split indices |
$axis |
int |
Axis along which to split. Default: 0 |
array<NDArray>- List of sub-arrays (views).
$arr = NDArray::arange(12)->reshape([3, 4]);
// Split into 3 equal parts along axis 0
$parts = $arr->split(3, axis: 0);
// 3 arrays of shape [1, 4]
// Split at indices
$parts = $arr->split([1, 2], axis: 1);
// 3 arrays of shape [3, 1], [3, 1], [3, 2]Split array vertically (along axis 0).
public function vsplit(array|int $indicesOrSections): array| Name | Type | Description |
|---|---|---|
$indicesOrSections |
array<int>|int |
Number of equal parts or split indices |
array<NDArray>- List of sub-arrays.
$arr = NDArray::arange(12)->reshape([4, 3]);
$parts = $arr->vsplit(2);
// 2 arrays of shape [2, 3]Split array horizontally (along axis 1).
public function hsplit(array|int $indicesOrSections): array| Name | Type | Description |
|---|---|---|
$indicesOrSections |
array<int>|int |
Number of equal parts or split indices |
array<NDArray>- List of sub-arrays.
$arr = NDArray::arange(12)->reshape([3, 4]);
$parts = $arr->hsplit(2);
// 2 arrays of shape [3, 2]| Method | Description | Returns View? |
|---|---|---|
reshape() |
Change array shape | Sometimes |
transpose() |
Reverse axes | Yes |
flatten() |
Flatten to 1D (copy) | No |
ravel() |
Flatten to 1D (view if possible) | Sometimes |
swapaxes() |
Swap two axes | Yes |
permute() |
Reorder axes | Yes |
merge() |
Merge two axes | Yes |
flip() |
Reverse elements | No |
insertaxis() / expandDims() |
Add dimension | Yes |
squeeze() |
Remove length-1 dimensions | Yes |
pad() |
Pad with values | No |
tile() |
Repeat array | No |
repeat() |
Repeat elements | No |
| Method | Description |
|---|---|
concatenate() |
Join along existing axis |
stack() |
Join along new axis |
vstack() |
Stack vertically (axis 0) |
hstack() |
Stack horizontally (axis 1) |
split() |
Split along axis |
vsplit() |
Split vertically (axis 0) |
hsplit() |
Split horizontally (axis 1) |