[PROPOSAL] Creation of NDArray, Matrix views

[shivasankarka]

Summary

This proposal introduces a lightweight and extensible mechanism to create views of NDArray and Matrix objects in NuMojo, similar to the approach discussed in #169 , but without requiring Mojo support for trait parameters.

The goal is to enable array views as a first-class feature in NuMojo, allowing data sharing and view-based operations while minimizing unnecessary array copies. This lays the groundwork for improved memory efficiency as we continue to rework getter/setter methods and optimize internal data handling.

Motivation

In libraries like NumPy, array slicing and subsetting operations often return views instead of copies, enabling efficient reuse of existing memory. This significantly reduces overhead for large numerical computations.
With Mojo’s strong copy semantics now in place, NuMojo is well-positioned to adopt a similar design. Introducing views represents a key step toward zero-copy operations, allowing users to manipulate subarrays that share the same underlying data buffer.

notes

• The example above illustrates one possible approach for constructing views of Matrix and NDArray. The specific names of the trait and struct types are open for discussion, they can be refined to better convey intent and improve clarity for future users and contributors.

• Because this approach is non-intrusive and integrates cleanly with the current data model, it can be gradually incorporated into the existing NDArray and Matrix implementations in subsequent pull requests. Future updates to __getitem__ and __setitem__ will align these behaviors more closely with NumPy’s view semantics, ensuring consistency and intuitive usage.

Detailed Explanation

The proposed design adds a simple abstraction layer around view handling through a new Viewable trait and two supporting structs: ViewData and NonViewData that represent arrays views and original arrays. You can find the full example code here.

Trait definition

trait Viewable(ImplicitlyCopyable, Movable):
    fn __init__(out self):
        ...

    fn get(self) -> Bool:
        ...

ViewData and NonViewData

struct NonViewData(Viewable, ImplicitlyCopyable, Movable):
    alias view: Bool = False
    fn __init__(out self):
        pass

    fn get(self) -> Bool:
        return self.view


struct ViewData[is_mutable: Bool, //, origin: Origin[is_mutable]](Viewable, ImplicitlyCopyable, Movable):
    alias view: Bool = True
    fn __init__(out self):
        pass


    fn get(self) -> Bool:
        return self.view

Matrix

The Matrix type is extended with a View parameter that defaults to NonViewData.

struct Matrix[dtype: DType = DType.float64, View: Viewable = NonViewData](
    Copyable, Movable, Sized, Stringable, Writable
):
    alias width: Int = simd_width_of[dtype]()  #
    """Vector size of the data type."""

    var _buf: OwnData[dtype]
    """Data buffer of the items in the NDArray."""

    var view: View
    """View information of the NDArray."""

    var shape: Tuple[Int, Int]
    """Shape of Tensor."""

    var size: Int
    """Size of Tensor."""

    var strides: Tuple[Int, Int]
    """Strides of Tensor."""

    var flags: Flags
    "Information about the memory layout of the array."

This design enables both standard (owning) matrices and non-owning view matrices to coexist cleanly, distinguished by their View type parameter.

Constructing a View
A specialized constructor initializes a non-owning Matrix that references data from another array.

    @always_inline("nodebug")
    fn __init__(
        out self,
        shape: Tuple[Int, Int],
        strides: Tuple[Int, Int],
        offset: Int,
        ptr: UnsafePointer[Scalar[dtype]],
    ):
        self.shape = shape
        self.strides = strides
        self.size = shape[0] * shape[1]
        self._buf = OwnData(ptr=ptr.offset(offset))
        self.view = View()
        self.flags = Flags(
            self.shape, self.strides, owndata=False, writeable=False
        )

Example usage

from numojo.core.matrix_view import Matrix

fn main() raises:
    var a = Tensor(Tuple[Int, Int](2, 2))
    for i in range(4):
        a._store(i, val=i)
    print("a: ", a) 
    var b = a[1] # a[1] returns the view of row of array `a`. 
    print("b :", b)
    b._store(0, val=42) # modifies the data of array `a`
    print("b_modified: ", b)
    print("a_modified: ", a)

Possible naming conventions:

trait: Viewable, StorageKind, OwnerShip.
structs: Owning/NonOwning, Owning/View.
field: var ownership, var view.

Impact

Who benefits:

1. Library users: Gain the ability to slice, reshape, and manipulate subarrays without memory duplication.
2. NuMojo developers: Gain a clear and type-safe foundation for future view-based optimizations (e.g., lazy evaluation, broadcasting).
3. Performance-critical applications: Reduced memory footprint and improved computational efficiency.

What changes:

• Addition of Viewable, ViewData, and NonViewData types.
• Extension of Matrix to support a generic view parameter.
• New constructors for creating non-owning view matrices.

References

• Derived and simplified from the earlier [proposal][core] an approach to construct views of array #169
• Inspired by NumPy’s view semantics for arrays and subarray slicing.

[forfudan]

Related issue: #169

[shivasankarka]

As I have added above, some of the other possible naming conventions are,

trait: Viewable, StorageKind, OwnerShip.
structs: Owning/NonOwning, Owning/View.
field: var ownership, var view.

[forfudan]

@shivasankarka Thanks for the proposal. I agree with this approach and it can be implemented immediately with the current Mojo version.

The only part I want to discuss is about the naming of the tracker type. I found ViewData and NonViewData a little bit confusing (it is verb+noun) and not very self-explanatory. I would propose OwnedData and RefData (BorrowedData) which may better reflect the nature of the data buffer and the relationship between the owner and the borrower(s).

Here is my proposal of the names:

1. The trait Viewable -> Buffered: this reflects the nature that the data of the array is buffered. The type NonViewData can never be a instance of the trait Viewable, semantically :D.
2. The parameter view -> buffer_type: this indicates directly the type of the buffer, whether it is an owner or a borrower.
3. The type ViewData -> RefData.
4. The type NonViewData -> OwnedData.
5. The method get() -> is_owned_data(): it returns a boolean value whether the data buffer is owned or not. We can also add another method is_ref_data() to return a bool.

This results in the following signatures.

trait Buffered(ImplicitlyCopyable, Movable):
    fn __init__(out self):
        ...

    fn is_owned_data(self) -> Bool:
        ...

struct OwnedData(Buffered, ImplicitlyCopyable, Movable):
    fn __init__(out self):
        pass

    fn is_owned_data(self) -> Bool:
        return True


struct RefData[is_mutable: Bool, //, origin: Origin[is_mutable]](Viewable, ImplicitlyCopyable, Movable):
    fn __init__(out self):
        pass

    fn is_owned_data(self) -> Bool:
        return False

struct Matrix[dtype: DType = DType.float64, buffer_type: Buffered = OwnedData](
    Copyable, Movable, Sized, Stringable, Writable
):
    alias width: Int = simd_width_of[dtype]()  #
    """Vector size of the data type."""

    var _buf: OwnData[dtype]
    """Data buffer of the items in the NDArray."""

    var buffer_type: Buffered
    """Whether the data buffer is owned or borrowed."""

    var shape: Tuple[Int, Int]
    """Shape of Tensor."""

    var size: Int
    """Size of Tensor."""

    var strides: Tuple[Int, Int]
    """Strides of Tensor."""

    var flags: Flags
    "Information about the memory layout of the array."

[shivasankarka]

@forfudan I agree with all your naming suggestions, that’s a better way to move forward. One suggestion is that having an OwnedData variant for Buffered may be confusing because we already use OwnData for _buf and OwnedData doesn't semantically convey the meaning, something like OwnData might be better and in line with RefData.

How about we rename var _buf: OwnData[dtype] to something more explicit, for example var _buf: DataStorage[dtype] or var _buf: DataContainer[dtype]? and make the struct OwnedData(Buffered) to be struct OwnData. Those names make the distinction between the marker type and the actual data buffer clearer.

[forfudan]

Could we rename var _buf: OwnData[dtype] to something more explicit, for example var _buf: DataStorage[dtype] or var _buf: DataContainer[dtype]

@shivasankarka, Yes, I fully agree. We just need to rename the data buffer and the move the names one layer up. How about we take the following steps?

1. Rename the current type _buf: OwnData[dtype] to _buf: DataContainer[dtype]. The DataContainer type is a dedicated wrapper for the unsafe pointer to avoid user unintentially accessing the pointer.
2. Remove the trait Bufferable and the type RefData[dtype] from everywhere in the NDAarray` type because they are no longer needed. The Mojo files can be, however, kept because we will re-using the names.
3. Apply your approach described above (the file owned_data.mojo and ref_data.mojo will be completely re-written, the file bufferable.mojo will be renamed as buffered.mojo).
4. In future, maybe we can deprecate the data container type _buf: DataContainer[dtype], but maybe it can still be useful.

In this sense, we only need only extra file data_container.mojo. The files bufferable.mojo, onw_data.mojo, and ref_data.mojo will stay but re-written and re-named.

• bufferable.mojo -> buffered.mojo
• own_data.mojo -> owned_data.mojo
• ref_data.mojo -> ref_data.mojo (unchanged)

For safety consideration, maybe you can make a PR for the first two items. And then a PR for the Step 3?

[shivasankarka]

I have made the changes corresponding to step 1, 2 in #281 . One small difference is,

• They are OwnData and RefData since it makes more sense semantically as we are using this dummy variable to denote whether the array owns the data or references it. We could even make it OwnsData and RefsData.

Regarding deprecating the DataContainer. I think it'll be useful when we transition to GPU backend, we need to differentiate HostStorage and DeviceStorage which can be moved into DataContainer as shown in #276

[forfudan]

They are OwnData and RefData since it makes more sense semantically as we are using this dummy variable to denote whether the array owns the data or references it. We could even make it OwnsData and RefsData.

OwnData and RefData is okay for me. But OwnsData and RefsData sounds a little bit strange. For a type name, it should be "adjective + noun". "Verb + noun" is not a Pythonic naming approach.

[shivasankarka]

Update [2025/11/22]

With the release of Mojo 25.7, a number of changes were introduced, most notably around UnsafePointer and explicit origins. These updates allow us to simplify the previously proposed design.

Updated Model

DataContainer remains unchanged and continues to take a MutOrigin parameter. We now introduce a new MatrixImpl struct, parameterized by:

• dtype: DType
• own_data: Bool, this let's us prevent a lot of potential errors using the where clause in Mojo. Although where is still WIP and can't be used extensively yet.
• origin: MutOrigin, this origin parameter ties up the origin of Matrix instance and that of the DataContainer making sure that compiler can track the origin of owned instances and views correctly.

struct MatrixImpl[
    dtype: DType = DType.float64,
    *,
    own_data: Bool,
    origin: MutOrigin,
](Copyable, Movable, Sized, Stringable, Writable):

    comptime IteratorType[
        is_mutable: Bool, //,
        matrix_origin: MutOrigin,
        iterator_origin: Origin[is_mutable],
        forward: Bool,
    ] = _MatrixIter[dtype, matrix_origin, iterator_origin, forward]
    alias width: Int = simd_width_of[dtype]() 
    var _buf: DataContainer[dtype, origin]
    var shape: Tuple[Int, Int]
    var size: Int
    var strides: Tuple[Int, Int]
    var flags: Flags

Type Aliases

We define the following aliases for convenience:

alias Matrix = MatrixImpl[_, own_data=True, origin = MutOrigin.external

alias MatrixView[dtype: DType, origin: MutOrigin] = MatrixImpl[
    dtype, own_data=False, origin=origin
]

• Matrix: Owns its data and is the primary type exposed to users.
• MatrixView: References the data of a parent Matrix and is parameterized by that matrix’s origin.
• All newly created Matrix instances use MutOrigin.external.

Example: Row View Method

A method returning a view of a matrix row in this model looks like:

    fn get[
        is_mutable: Bool, //, view_origin: Origin[is_mutable]
    ](ref [view_origin]self, x: Int) raises -> MatrixView[
        dtype, MutOrigin.cast_from[view_origin]
    ] where Self.own_data == True:
        if x >= self.shape[0] or x < -self.shape[0]:
            raise Error(
                String("Index {} exceed the row number {}").format(
                    x, self.shape[0]
                )
            )

        var x_norm = self.normalize(x, self.shape[0])
        var new_data = DataContainer[dtype, MutOrigin.cast_from[view_origin]](
            ptr=self._buf.get_ptr().unsafe_origin_cast[
                MutOrigin.cast_from[view_origin]
            ]()
            + x_norm * self.strides[0]
        )
        var row_view = MatrixView[dtype, MutOrigin.cast_from[view_origin]](
            shape=(1, self.shape[1]),
            strides=(self.strides[0], self.strides[1]),
            data=new_data,
        )
        return row_view^

Function signature

To accept either owned or view types in some function, we can use

fn function[dtype: DType](x: MatrixImpl[dtype, **_]):
    pass

To accept only owned matrices:

fn function[dtype: DType](x: Matrix[dtype]):
    pass

and to accept only matrix views:

fn function[dtype: DType](x: MatrixView[dtype, **_]):
    pass

This ensures that functions cannot accidentally mix owned Matrix instances with non-owned MatrixView instances.