Rebuilding NumPy to understand it

How writing a simplified NumPy in pure-Python taught me more about numerical computing than using the real thing.

I'm a wee bit fuzzy on the exact timelines, but it all started around mid-November of 2024. I was still at the uni and in my second-to-last quarter. I was working on an assignment that required me to use NumPy.

I multiplied some matrices; NumPy did its thing, as it always does and made all the computations look super easy. But, under this "simplicity", a few questions began to gnaw at me.

So, I thought of experimenting with a simple code, nothing fancy:

1a = np.array([[1, 2], [3, 4]])
2b = np.array([[5, 6], [7, 8]])
3np.dot(a, b)

The result popped out instantly. But this time, instead of just accepting the answer, I asked myself a bunch of questions. Like, why was I even using np.dot(a, b) when I could've used np.matmul(a, b), which feels more appropriate?

And if np.dot(a, b) indeed performs matrix multiplication, then what's the deal with the a @ b (@ operator)? Why are there three different ways to perform matrix multiplication, and if so, which one's the best?

Building with a purpose.

With all these questions in mind, I was motivated enough to learn the actual implementation details of NumPy. I was ready to build my own scrappy version. I didn't set out to create something that'd rival NumPy; I mean, NumPy's a bloody powerhouse, built over decades of work by incredibly talented minds in maths and science, plus loads of optimisations.

I couldn't possibly compete with that.

I wanted to stop treating these libraries (starting with NumPy) as black boxes and truly understand the "whys" and "hows". This realisation hit me so hard, I challenged myself.

Could I build a dinky version of NumPy from scratch? Because if I'm going to teach these concepts one day, I have to go deeper. If I were going to learn this properly, I needed discipline and some rules to follow.

Rules of engagement

  • No use of LLMs or any AI usage of anything.

  • Every line of code and every solution had to come from my own understanding and experimentation.

  • Pure Python only. No external dependencies, just the standard library.

  • It should be clean, maintainable, statically typed and well-documented code that mirrors NumPy's public APIs, aiming to be a drop-in replacement where sensible.

Writing my first array.

Now that I have set my rules, I started experimenting with NumPy's core APIs, trying to understand their core behaviours and functionality. As I read through more and more documentation and Stack Overflow answers, it quickly became clear that most of NumPy's APIs are heavily relying on a single core construct, the np.array function.

It's also worth noting that this function is a cheeky little wrapper for the np.ndarray class. That's where I decided to start, implementing my own ndarray data structure.

Quick analogy

If you're new to arrays, think of them as egg cartons, each slot holds an egg and the shape of the carton tells you how many eggs you've got.

Where your hand moves from one slot to the next are the strides; the type of eggs is the dtype; the carton itself is the buffer or the actual storage.

Now, by this point in time, I had a basic understanding of arrays and how they worked. But, as I looked deeper and deeper, I discovered heaps of concepts, including memory allocation, shape calculations, strides and various optimisation techniques for data storage.

It felt like opening Pandora's box; I wasn't ready. After a few days of head-scratching, I managed to create a primitive, albeit minimal, working version using Python's built-in ctypes module.

It worked poorly. But it worked!

Looking back, that was the easy bit. A constructor that takes five things, shape, dtype, buffer, offset and strides, looks harmless until you realise each of them is a small rabbit hole and they all have to agree with one another.

What finally helped was a change in how I pictured the thing. I'd been thinking of an array as its data. It isn't. The data is just a strip of memory, numbers sitting back to back with no idea they're supposed to be a grid. The array is a way of looking at that strip and the shape, the dtype and the strides are the pair of glasses you read it through. Swap the glasses and the very same memory becomes a different array.

That sounds a bit grand for a few dozen lines of Python, so let's watch it happen instead.

Making sense of shapes.

A shape of an array is a tuple of integers that represents the number of elements along each dimension (axis) of the array.

I'll build a 3x4 array of floats in front of you, a line at a time, so just keep scrolling. One warning first. I've intentionally removed loads of details to keep things simple, like the check for unsupported memory orders and a fair bit of type juggling. If you'd rather read the lot in one go, the complete implementation of ndarray is on GitHub.

See full implementation

class ndarray:
 
    def __init__(
        self,
        shape,
        dtype=float64,
        buffer=None,
        offset=0,
        strides=None,
    ):
        if not isinstance(shape, Iterable):
            shape = (shape,)
        shape = tuple(int(dim) for dim in shape)
        if dtype is None:
            dtype = float64
        elif isinstance(dtype, type):
            dtype = globals()[f"{dtype.__name__}32"]
        else:
            dtype = globals()[dtype]
        itemsize = int(_convert_dtype(dtype, "short")[-1])
        if buffer is None:
            if offset != 0:
                raise ValueError(
                    "Offset must be 0 when buffer is None"
                )
            if strides is not None:
                raise ValueError(
                    "Strides must be None when buffer is None"
                )
            strides = calc_strides(shape, itemsize)
        else:
            if (
                isinstance(buffer, ndarray)
                and buffer.base is not None
            ):
                buffer = buffer.base
            if isinstance(buffer, ndarray):
                buffer = buffer.data
            if strides is None:
                strides = calc_strides(shape, itemsize)
        buffersize = strides[0] * shape[0] // itemsize
        buffersize += offset
        Buffer = _convert_dtype(dtype, "ctypes") * buffersize
        if buffer is None:
            data = Buffer()
        elif isinstance(buffer, ctypes.Array):
            data = Buffer.from_address(ctypes.addressof(buffer))
        else:
            data = Buffer.from_buffer(buffer)
        self._shape, self._dtype = shape, dtype
        self._strides, self._data = strides, data
 
ndarray((3, 4), dtype=float)

I started by checking if the provided shape can be iterated. If it wasn't, I wrapped it in a tuple, so 5 becomes (5,). Ours already is one.

Then, I converted the shape into a tuple of integers, because you can't have non-integer dimensions in an array.

Next up, the dtype (short for data type). If you didn't provide one, the constructor falls back to float64. If you hand it a float or an int, it looks the appropriate data type up in the globals() namespace.

This nifty trick meant I could dynamically fetch whatever data type I fancied. We passed float, so dtype lands on float32.

Every data type knows how wide it is. float32's short code is f4, whose last character is the number of bytes, so that's our itemsize, 4.

Right, on to the buffer. If none was provided, the array is initialised without an external memory buffer. In this case, the offset must be zero and the strides must be None, which is all these two checks are for. Nothing gets raised this time.

The constructor then calculates the strides, which, put simply, are just the number of bytes between consecutive elements in memory.

I've tucked calc_strides out of sight. It walks the shape backwards, multiplying up by each dimension as it goes, because the last axis is the one that's contiguous in memory. Step along a row and you move 4 bytes, step down a column and you move 16.

Finally, calculating the total buffer size. This is worked out using the strides, shape and the size. 16 * 3 // 4 is 12 items, plus whatever offset there is, which is none.

The buffer itself is a type derived from the data type and its size. A float32 is a ctypes.c_float, so this is twelve of those, back to back. It's only the type so far. Nothing has been allocated.

Depending on whether a buffer was passed or not, the constructor handles the data accordingly, either creating a new buffer or using the existing one. We passed none, so Buffer() allocates a fresh one, zeroed.

Store the lot and that's an array.

Have a look at what that actually made. Forty-eight bytes of zeros, a shape, a dtype and a pair of strides. Nothing in those bytes knows it's a grid. That's the glasses again and it's why I stopped finding reshaping and transposing so mysterious a while later. They don't touch the bytes at all. They just hand you a different pair of glasses.

But that was the easy case, the one where the array makes its own memory. What if the memory is already there?

That's the other half of the if and it's the half I understood last. Every time you slice an array, you don't want a copy, you want to look at the same memory again through new glasses. So a slice calls the constructor and hands it the original array's memory as the buffer. Here's the very same constructor again, this time handed some memory that somebody else already allocated.

class ndarray:
 
    def __init__(
        self,
        shape,
        dtype=float64,
        buffer=None,
        offset=0,
        strides=None,
    ):
        if not isinstance(shape, Iterable):
            shape = (shape,)
        shape = tuple(int(dim) for dim in shape)
        if dtype is None:
            dtype = float64
        elif isinstance(dtype, type):
            dtype = globals()[f"{dtype.__name__}32"]
        else:
            dtype = globals()[dtype]
        itemsize = int(_convert_dtype(dtype, "short")[-1])
        if buffer is None:
            if offset != 0:
                raise ValueError(
                    "Offset must be 0 when buffer is None"
                )
            if strides is not None:
                raise ValueError(
                    "Strides must be None when buffer is None"
                )
            strides = calc_strides(shape, itemsize)
        else:
            if (
                isinstance(buffer, ndarray)
                and buffer.base is not None
            ):
                buffer = buffer.base
            if isinstance(buffer, ndarray):
                buffer = buffer.data
            if strides is None:
                strides = calc_strides(shape, itemsize)
        buffersize = strides[0] * shape[0] // itemsize
        buffersize += offset
        Buffer = _convert_dtype(dtype, "ctypes") * buffersize
        if buffer is None:
            data = Buffer()
        elif isinstance(buffer, ctypes.Array):
            data = Buffer.from_address(ctypes.addressof(buffer))
        else:
            data = Buffer.from_buffer(buffer)
        self._shape, self._dtype = shape, dtype
        self._strides, self._data = strides, data
 
raw = (ctypes.c_float * 12)()
ndarray((3, 4), dtype=float, buffer=raw)

The very same constructor, not a character changed. The only difference is the last two lines.

Twelve floats' worth of memory that already exists, made with plain ctypes and not by me.

And now an ndarray that's handed it as the buffer. Everything up to the if runs exactly as before, so I'll skip along.

This time buffer isn't None, so the other branch runs. If the buffer is itself an ndarray, I swap it for the memory it looks at, so a slice of a slice still points at the original. Ours is a plain ctypes array, so both of those checks wave it through.

Then the strides are either given, which a slice would do, or calculated the usual way, which is what happens here.

The same sum as before, 12 items, and the same type to hold them.

And here's what the three-way if was for. No buffer, allocate a fresh one. Already a ctypes array, point from_address straight at it. Anything else that supports the buffer protocol goes through from_buffer.

Store it. self._data is raw's very own memory, not a copy of it.

That's why slicing in NumPy is so cheap and why it is in xsNumPy as well. a[1:] copies nothing. It makes another ndarray that looks at the same memory, which is also why writing into a slice writes into the original.

That's a lot of work, innit?

Illusion of simplicity.

After all that hard work, I thought of giving myself a break. I remembered telling myself

Let's start with something dead easy... perhaps just display the array. That couldn't be hard, right? All I've to do is print the content of my array in a readable format, just like NumPy does

—silly me, 2025

Little did I know, I was shooting myself in the foot. At its core, a __repr__ is an object's internal data representation. Here's every version I wrote on the way there, one after another and what each one printed when I tried it.

def __repr__(self):
    return f"array({self._data}, dtype={str(self.dtype)})"
def __repr__(self):
    return f"array({self._data}, dtype={str(self.dtype)})"
Broke: >>> xp.array([[1, 2], [3, 4]])
array([1, 2, 3, 4], dtype=int64)

I started with something simple and it worked for scalars and 1D arrays. Feeling quite pleased and a bit cocky, I tried a 2D array, but it unexpectedly printed everything as a flat list. I hadn't accounted for the rows and columns.

def __repr__(self):
    if self.ndim == 1:
        return f"array({self._data}, dtype={str(self.dtype)})"
    elif self.ndim > 1:
        rows = ",\n       ".join(
            [f"[{', '.join(map(str, row))}]" for row in self._data]
        )
        return f"array([{rows}], dtype={str(self.dtype)})"
Broke: >>> xp.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])
array([[[1, 2], [3, 4]],
       [[5, 6], [7, 8]]], dtype=int64)

No problem, I updated the code and it worked.

A 1D array keeps what already worked.

Anything bigger gets its rows joined with a newline and seven spaces, so each one lines up under array([.

Then the 3D arrays... It broke again.

def __repr__(self):
    def _extended_repr(s, axis, offset):
        indent = min(2, max(0, (self.ndim - axis - 1)))
        if axis < len(self.shape):
            step = self.strides[axis] // self.itemsize
            s += "["
            for idx in range(self.shape[axis]):
                if idx > 0:
                    s += ("\n       " + " " * axis) * indent
                _oset = offset + idx * step
                s = _extended_repr(s, axis + 1, _oset)
                if idx < self.shape[axis] - 1:
                    s += ", "
            s += "]"
        else:
            s += repr(self.data[offset])
        return s
 
    s = _extended_repr("", 0, self._offset)
    if self.dtype not in (float64, int64, bool):
        return f"array({s}, dtype={self.dtype})"
    return f"array({s})"
Worked: >>> xp.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])
array([[[1, 2],
        [3, 4]],

       [[5, 6],
        [7, 8]]])

That's when it hit me, this wasn't just about formatting strings. I needed a general solution that would work with any number of dimensions. A few days later, I found myself neck-deep in recursive logic and multidimensional indexing, all for what I believed was an "easy" print function.

This is where the strides finally pay off. step is how many items one step along this axis moves through the flat buffer.

Between the items of an axis goes a newline and seven spaces, so each one lines up under array([, and one more space for every level of nesting. The outer levels of a bigger array get a blank line as well.

Then do the very same thing one axis down, from wherever this item starts in the buffer.

At the bottom there are no axes left, only a number, so print it.

The dtype only gets a mention when it isn't one of the usual suspects, just like NumPy.

What started as a chilled attempt to rework __repr__ turned out to be a masterclass in designing for generality. This struggle taught me something fundamental. What seemingly appears simple on the surface often hides massive complexity underneath.

And so, I realised, printing a NumPy array from scratch was a rabbit hole.

See also

Complete implementation of __repr__ with helper functions.

More than meets the eye.

After wrestling with the "simple" things, I naively believed the hardest part was behind me. I was excited for the fun stuff: element-wise arithmetic, broadcasting, transposing and other random functions. However, I didn't realise my journey was about to get even more challenging.

Basic arithmetic operations like addition, subtraction and scalar multiplication seemed straightforward. I figured I could just iterate through my flattened data and perform operations element-wise.

And it worked for the first few test cases. But, as always, the test cases failed almost immediately for higher-dimensional vectors. Here's __add__, before and after.

def __add__(self, other):
    arr = ndarray(self.shape, self.dtype)
    if isinstance(other, (int, float)):
        arr[:] = [x + other for x in self._data]
    elif isinstance(other, ndarray):
        if self.shape != other.shape:
            raise ValueError(
                "Operands couldn't broadcast together with shapes "
                f"{self.shape} {other.shape}"
            )
        arr[:] = [x + y for x, y in zip(self.flat, other.flat)]
    else:
        raise TypeError(
            "Unsupported operand type(s) for +: "
            f"{type(self).__name__!r} and "
            f"{type(other).__name__!r}"
        )
    return arr
def __add__(self, other):
    arr = ndarray(self.shape, self.dtype)
    if isinstance(other, (int, float)):
        arr[:] = [x + other for x in self._data]
    elif isinstance(other, ndarray):
        if self.shape != other.shape:
            raise ValueError(
                "Operands couldn't broadcast together with shapes "
                f"{self.shape} {other.shape}"
            )
        arr[:] = [x + y for x, y in zip(self.flat, other.flat)]
    else:
        raise TypeError(
            "Unsupported operand type(s) for +: "
            f"{type(self).__name__!r} and "
            f"{type(other).__name__!r}"
        )
    return arr
Broke: >>> matrix = xp.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
>>> vector = xp.array([1, 2, 3])
>>> matrix + vector
Traceback (most recent call last):
  ...
ValueError: Operands couldn't broadcast together with shapes (3, 3) (3,)

A number gets added to every element of the flat data.

Another array has to be the very same shape, otherwise I turn it away. If it is, the two get added element by element.

Anything else is turned away at the door.

Looks sensible, doesn't it? But what about a (3,) array and a (3, 3) matrix?

NumPy adds those two without blinking.

def __add__(self, other):
    if isinstance(other, (int, float)):
        out = ndarray(self.shape, self.dtype)
        out[:] = [data + other for data in self._data]
    elif isinstance(other, ndarray):
        shape = broadcast_shape(self.shape, other.shape)
        self = self.broadcast_to(shape)
        other = other.broadcast_to(shape)
        out = ndarray(shape, self.dtype)
        out[:] = [x + y for x, y in zip(self.flat, other.flat)]
    else:
        raise TypeError(
            "Unsupported operand type(s) for +: "
            f"{type(self).__name__!r} and "
            f"{type(other).__name__!r}"
        )
    return out
Worked: >>> matrix + vector
array([[ 2,  4,  6],
       [ 5,  7,  9],
       [ 8, 10, 12]])
>>> matrix + 10
array([[11, 12, 13],
       [14, 15, 16],
       [17, 18, 19]])

So I stopped turning shapes away and started working out what they could become.

Work out the shape both sides agree on first. That's the resolver in the next bit and it took me longer than the rest of this put together.

Then stretch each side out to that shape, so the two line up number for number.

And from there it's the same element-by-element sum as before.

What if I added a scalar to a matrix or a (3,) array to a (3, 3) matrix? Could I add a float to an int? Each of those experiments brought new challenges and I was absolutely frustrated!

That's when I realised I wasn't just adding or multiplying numbers, but learning and simultaneously recreating NumPy's broadcasting rules.

The shape both sides agree on.

Here's the resolver, running. This one's worth watching the values on rather than the code.

def broadcast_shape(input, other):
    buffer = []
    r_input = list(reversed(input))
    r_other = list(reversed(other))
    maximum = max(len(r_input), len(r_other))
    r_input.extend([1] * (maximum - len(r_input)))
    r_other.extend([1] * (maximum - len(r_other)))
    for idx, jdx in zip(r_input, r_other):
        if idx == jdx or idx == 1 or jdx == 1:
            buffer.append(max(idx, jdx))
        else:
            raise ValueError(
                "Operands couldn't broadcast together with shapes "
                f"{input} and {other}"
            )
    return tuple(reversed(buffer))
 
broadcast_shape((3, 3), (3,))

The shape resolver on its own, with nothing else in the way.

A (3, 3) matrix and a bare (3,) vector. NumPy does this without blinking. I very much did blink.

buffer is where the answer gets built. Both shapes are turned back to front first, because broadcasting lines the shapes up from the right. The last dimensions meet first.

The thing that finally made it click, the shorter shape gets padded out with ones. That's it. That's the rule I'd been dancing around for days. (3,) quietly becomes (3, 1) back to front, which is (1, 3) the right way round, and suddenly both shapes are the same length.

Now walk them in step, one pair of dimensions at a time.

If the two dimensions match or either one is a 1, take the bigger of the two and move on. A 1 stretches to meet the other side. Nothing is actually copied, mind, that's the whole point of it, but the shape maths behaves as though it were.

The else is the branch we never get to here. If neither side is a 1 and they don't match, the shapes are genuinely incompatible and there's nothing clever to be done about it.

(3, 3), once it's turned back the right way round. Which is obvious in hindsight and obvious things in hindsight are the entire reason I built this library.

NumPy raises on that last branch too. It took me an unreasonable amount of time to accept that "just error" was the correct answer.

Final boss, Matrix Multiplication.

Matrix multiplication was another beast entirely.

I thought it would be just a matter of looping through rows and columns, summing them element-wise, high school maths, if you ask me. Here's roughly that, on the very same matrices from the start of this story.

def matmul(a, b):
    out = [[0] * len(b[0]) for _ in range(len(a))]
    for idx in range(len(a)):
        for jdx in range(len(b[0])):
            out[idx][jdx] = sum(
                a[idx][kdx] * b[kdx][jdx] for kdx in range(len(b))
            )
    return out
 
matmul([[1, 2], [3, 4]], [[5, 6], [7, 8]])

A plain function on plain nested lists. No NumPy, no ndarray, just what I'd have written in the first week of any programming course.

The matrices from the very first snippet. NumPy handed the answer back in a blink. Let's see how long it takes me.

The answer has as many rows as a and as many columns as b. It starts out as nothing but zeros.

One row of the answer at a time and one cell of it at a time.

Each cell is a row of a against a column of b, multiplied pair by pair and added up, so the first is 1 * 5 + 2 * 7, which is 19.

[[19, 22], [43, 50]]. The very matrix that popped out of np.dot(a, b) at the start.

And it worked as well until I tried with higher-dimensional arrays.

This is where I realised that matrix multiplication isn't just about rows and columns, but about correctly handling batch dimensions for higher-order tensors.

I found myself diving into NVIDIA's documentation, reading about the Generalised Matrix Multiplication (GEMM) routines and how broadcasting affects the output shapes.

See also

Complete implementation of arithmetic operations on GitHub.

Which, finally, answered the question that started all of this. For two dimensions, np.dot(a, b), np.matmul(a, b) and a @ b give the very same answer, which is exactly why it took me so long to spot that there was a difference. The @ operator is just matmul in a nicer coat.

Above two dimensions, they part ways. matmul treats the leading axes as a stack of matrices and multiplies them pair by pair, while dot multiplies every matrix in the first against every matrix in the second.

>>> a = np.ones((2, 2, 2))
>>> (a @ a).shape
(2, 2, 2)
>>> np.dot(a, a).shape
(2, 2, 2, 2)

So, which one's the best? For matrices, @, every time. It says what it means.

Small victories, big lessons.

Here comes December. By now, I wasn't just rebuilding a scrappy numerical computing doppelganger like I thought I was.

I was on my winter break. I was fully committed to this project because I didn't have to attend uni or work on any assignments. After days of debugging, I realised that my vector operations weren't just about getting the "maths" right.

They were about thinking like NumPy:

  • How can I minimise unnecessary data duplication?

  • How can I broadcast arrays?

  • How can I infer the correct output shape?

I was creating a flexible and extensible system that could handle both intuitive and weird edge cases. With each iteration, every commit I made, I explored even more ways to optimise it, reducing redundant calculations.

Every bug, every unexpected result, every failure, every new piece of answer and advice that I received on Stack Overflow and every small achievement taught me something new about NumPy. As time passed, xsNumPy evolved into more than just a project and a scrappy experiment.

It became a weird, obsessive mentality. A belief that the best way to learn is by rolling up your sleeves, taking things apart, trying to understand the problem and putting it back together, piece by piece.

So, what can xsNumPy do?

Like I said, xsNumPy started off as a learning exercise and has since grown into a small but cheeky, reliable companion that I can use to demonstrate the underlying mechanics of some of the implementations of NumPy.

It was not about speed but about clarity. Below are some things that xsNumPy does quite well.

xsNumPy provides familiar ways to create arrays. These creation routines are consistent, predictable and designed to slot neatly into later operations.

  • array()

    Like NumPy, the array function is the bread and butter of xsNumPy as well. It's the most flexible way to create arrays from Python lists or tuples with sensible dtype inference and the option to set one explicitly.

    >>> import xsnumpy as xp
    >>> xp.array([[[1, 2], [3, 4]], [[5, 6], [7, 8]]])
    array([[[1, 2],
            [3, 4]],
    
           [[5, 6],
            [7, 8]]])
    >>> xp.array([1, 0, 2], dtype=xp.bool)
    array([True, False, True])
    
  • zeros(), ones() and full()

    xsNumPy support zeros, ones and full functions for repeatable initialisation of arrays filled with, zeros, ones and any fill_value respectively.

    >>> xp.zeros(3)
    array([0. , 0. , 0. ])
    >>> xp.ones([3, 2], dtype=xp.int32)
    array([[1, 1],
           [1, 1],
           [1, 1]])
    >>> xp.full(2, 3, fill_value=3.14159)
    array([[3.14159, 3.14159, 3.14159],
           [3.14159, 3.14159, 3.14159]])
    
  • arange()

    Inspired by Python's range, arange generates arrays with evenly spaced values.

    >>> xp.arange(0, 5, 0.5)
    array([0. , 0.5, 1. , 1.5, 2. , 2.5, 3. , 3.5, 4. , 4.5])
    

See also

Check out all of array creation methods supported by xsNumPy on GitHub.

xsNumPy provides a range of arithmetic operations, carefully adhering to NumPy's rules for broadcasting and type coercion. The emphasis is on correctness and clear behaviour across dimensions.

  • Element-wise arithmetic

    xsNumPy supports element-wise addition, subtraction, multiplication, and division along with other basic arithmetics.

    >>> a = xp.array([[1, 0], [0, 1]])
    >>> b = xp.array([[4, 1], [2, 2]])
    >>> a + b
    array([[5, 1],
           [2, 3]])
    
  • Broadcasting arithmetic

    xsNumPy matches shapes, stretches smaller arrays and makes sure the output shape followed NumPy's exact logic. Just like NumPy, these operations are broadcasted.

    >>> matrix = xp.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
    >>> vector = xp.array([[1], [2], [3]])
    >>> matrix + vector
    array([[ 2,  4,  6],
           [ 5,  7,  9],
           [ 8, 10, 12]])
    
  • Linear algebraic helper functions

    To mirror NumPy's API, xsNumPy supports explicit arithmetic functions. These are useful when you want to be very clear about the operation being performed or when you need more control over the parameters.

    >>> a = xp.array([[1, 0], [0, 1]])
    >>> b = xp.array([[4, 1], [2, 2]])
    >>> xp.dot(a, b)
    array([[4, 1],
           [2, 2]])
    
  • Scalar operations

    xsNumPy supports scalar operations as well so you're not just limited to array-to-array operations.

    >>> xp.array([3, 4]) + 10
    array([13, 14])
    

See also

Check out examples of the arithmetic operations supported by xsNumPy on GitHub.

xsNumPy provides essential shape manipulation APIs that are predictable and memory-aware. The emphasis is on clarity of intent and avoiding unnecessary data duplication. Think of this as learning to fold and unfold the same fabric without tearing it.

Tip

Read more about NumPy internals here.

  • .reshape()

    The reshape method changes the view of data when possible, preserving the total element count.

    >>> a = xp.array([1, 2, 3, 4, 5, 6])
    >>> a.reshape((2, 3))
    array([[1, 2, 3],
           [4, 5, 6]])
    
  • .transpose()

    Transposing is more than just flipping rows and columns; for higher-dimensional arrays, it's about permuting the axes. The transpose method does just that.

    >>> a = xp.array([[1, 2, 3], [4, 5, 6]])
    >>> a.transpose()
    array([[1, 4],
           [2, 5],
           [3, 6]])
    
  • .flatten()

    The flatten method returns a tidy 1D copy.

    >>> a = xp.array([[1, 2, 3], [4, 5, 6]])
    >>> a.flatten()
    array([1, 2, 3, 4, 5, 6])
    

Indexing is expressive and disciplined in xsNumPy, just like NumPy. The goal is to provide intuitive access to elements and subarrays while maintaining clarity about the underlying data structure.

Attention

Indexing and slicing were implemented by overridding the standard __getitem__ and __setitem__ protocols.

  • Basic indexing

    At its core, basic indexing in xsNumPy works similarly to NumPy, using zero-based indices to access elements. You can fetch single elements or entire subarrays. You can also use negative indices to count from the end of an array.

    >>> a = xp.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
    >>> a[1, 2]
    6
    >>> a[-1, -2]
    8
    
  • Slicing

    Slicing allows you to extract subarrays using a a[start:stop:step] format. Just like NumPy, xsNumPy supports almost all the classic slicing mechanics.

    >>> a = xp.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]])
    >>> a[::2]
    array([[1, 2, 3],
           [7, 8, 9]])
    >>> a[:2, 1:]
    array([[2, 3],
           [5, 6]])
    
  • Boolean masking

    Boolean masking lets you select elements based on a condition.

    >>> a[a % 2 == 0]
    array([2, 4, 6, 8])
    

See also

Check out the complete implementation here on GitHub.

Reductions condense information carefully, preserving the essence of the data. xsNumPy provides a few key reduction operations that are predictable and consistent.

  • .sum()

    The sum method computes the sum of elements along a given axis.

    >>> a = xp.array([[1, 2, 3], [4, 5, 6]])
    >>> a.sum()
    21
    >>> a.sum(axis=0)
    array([5, 7, 9])
    
  • .prod()

    The prod (product) method computes the multiplication of elements along a given axis.

    >>> a = xp.array([[1, 2, 3], [4, 5, 6]])
    >>> a.prod()
    720
    >>> a.prod(axis=0)
    array([ 4, 10, 18])
    
  • .any() and .all()

    The all method checks if all elements are True, while any checks if at least one is.

    >>> b = xp.array([[True, False, True], [True, True, False]])
    >>> b.all()
    False
    >>> b.any(axis=1)
    array([True, True])
    

Sharing notes with the community.

I gave a talk at ChiPy titled "xsNumPy: Curiosity to Code", walking through the decisions, the missteps and the insights that stayed with me.

The presentation covered the technical challenges, mathematical discoveries and most importantly, the mindset shift from viewing libraries as opaque entities to understanding them as collections of elegant algorithms waiting to be explored.

Looking back, moving forward.

xsNumPy didn't aim for performance; that wasn't the plan anyway. It was to learn and understand, build intuition. It taught me to replace awe with attention, trusting libraries while still learning and understanding their core concepts with care.

Most importantly, it reminded me that doing something by yourself is perhaps the best teaching and learning experience.

I intend to work on this project in small, respectful steps whenever I get time. However, the larger work is already done. I re-learnt the essentials by making them and that learning will travel with me far beyond this code.