bundles / numpy latest / numpy / block
_ArrayFunctionDispatcher
numpy:block
source: /dev/numpy/build-install/usr/lib/python3.14/site-packages/numpy/_core/shape_base.py :778
Signature
def block ( arrays ) Summary
Assemble an nd-array from nested lists of blocks.
Extended Summary
Blocks in the innermost lists are concatenated (see concatenate) along the last dimension (-1), then these are concatenated along the second-last dimension (-2), and so on until the outermost list is reached.
Blocks can be of any dimension, but will not be broadcasted using the normal rules. Instead, leading axes of size 1 are inserted, to make block.ndim the same for all blocks. This is primarily useful for working with scalars, and means that code like np.block([v, 1]) is valid, where v.ndim == 1.
When the nested list is two levels deep, this allows block matrices to be constructed from their components.
Parameters
arrays: nested list of array_like or scalars (but not tuples)If passed a single ndarray or scalar (a nested list of depth 0), this is returned unmodified (and not copied).
Elements shapes must match along the appropriate axes (without broadcasting), but leading 1s will be prepended to the shape as necessary to make the dimensions match.
Returns
block_array: ndarrayThe array assembled from the given blocks.
The dimensionality of the output is equal to the greatest of:
the dimensionality of all the inputs
the depth to which the input list is nested
Raises
: ValueErrorIf list depths are mismatched - for instance,
[[a, b], c]is illegal, and should be spelt[[a, b], [c]]If lists are empty - for instance,
[[a, b], []]
Notes
When called with only scalars, np.block is equivalent to an ndarray call. So np.block([[1, 2], [3, 4]]) is equivalent to np.array([[1, 2], [3, 4]]).
This function does not enforce that the blocks lie on a fixed grid. np.block([[a, b], [c, d]]) is not restricted to arrays of the form
AAAbb AAAbb cccDD
But is also allowed to produce, for some a, b, c, d
AAAbb AAAbb cDDDD
Since concatenation happens along the last axis first, block is not capable of producing the following directly
AAAbb cccbb cccDD
Matlab's "square bracket stacking", [A, B, ...; p, q, ...], is equivalent to np.block([[A, B, ...], [p, q, ...]]).
Examples
The most common use of this function is to build a block matrix:import numpy as np A = np.eye(2) * 2 B = np.eye(3) * 3 np.block([ [A, np.zeros((2, 3))], [np.ones((3, 2)), B ] ])✓
np.block([1, 2, 3]) # hstack([1, 2, 3])
✓a = np.array([1, 2, 3]) b = np.array([4, 5, 6]) np.block([a, b, 10]) # hstack([a, b, 10])✓
A = np.ones((2, 2), int) B = 2 * A np.block([A, B]) # hstack([A, B])✓
a = np.array([1, 2, 3]) b = np.array([4, 5, 6]) np.block([[a], [b]]) # vstack([a, b])✓
A = np.ones((2, 2), int) B = 2 * A np.block([[A], [B]]) # vstack([A, B])✓
a = np.array(0) b = np.array([1]) np.block([a]) # atleast_1d(a) np.block([b]) # atleast_1d(b)✓
np.block([[a]]) # atleast_2d(a) np.block([[b]]) # atleast_2d(b)✓
See also
- column_stack
Stack 1-D arrays as columns into a 2-D array.
- concatenate
Join a sequence of arrays along an existing axis.
- dstack
Stack arrays in sequence depth wise (along third axis).
- hstack
Stack arrays in sequence horizontally (column wise).
- stack
Join a sequence of arrays along a new axis.
- unstack
Split an array into a tuple of sub-arrays along an axis.
- vsplit
Split an array into multiple sub-arrays vertically (row-wise).
- vstack
Stack arrays in sequence vertically (row wise).
Aliases
-
numpy.block