cdef public class usm_ndarray [object PyUSMArrayObject, type PyUSMArrayType]:
    cdef int nd               # number of indexes needed to reference an element
    cdef char* data           # usm pointer representing location of element 
                              # with zero multi-index
    cdef Py_ssize_t *shape    # ranges of indexes, e.g. (2, 5, 1)
    cdef Py_ssize_t *strides  # Number of elements to jump with unit increase
                              # of each index value
    cdef int typenum          # enum representing array element data type 
    cdef int flags            # flags representing cached property of array
                              # USM_ARRAY_C_CONTIGUOUS, USM_ARRAY_F_CONTIGUOUS,
                              # USM_ARRAY_WRITEABLE
    cdef object base          # reference to object that owns the memory, the object 
                              # must be dpctl.memory.MemoryUSM*, ample enough 
                              # to accomodate all elements of the array

usm_ndarray(
    shape,                       # shape: tuple of integer
    dtype="|f8",                 # type_str for array element
                                 # np.dtype(type_str) must be 
                                 # subdtype of either integer or inexact 
    buffer='device',             # 'shared', 'host', 'device' to allocate new memory,
                                 # or existing _Memory object, or usm_ndarray object
    strides=None,                # layout info: None of tuple of integers of 
                                 # same size of shape
    offset=0,                    # position of zero-multi-index in buffer
    order='C',                   # how to interpret strides=None
    buffer_ctor_kwargs = dict()  # additional keywords to pass to new memory constructor
                                 # supported keywords of `dpctl.memory.MemoryUSM*`
                                 # constructors: 'queue', 'alignment', 'copy'
)

usm_ndarray((2,3), dtype='u2', buffer='device')
      # allocates 12 bytes of USM device memory for (2,3) array of 
      # unsigned shorts, C-contiguous
      # buffer has 6 elements
      # buf_flat = {a[0,0], a[0,1], a[0,2], a[1,0], a[1, 1], a[1,2]}

usm_ndarray((2,3), dtype='i8', buffer='shared', strides=(6, 1))
      # allocates 9*8 bytes of USM-shared memory for (2, 3) array of 
      # int64, strided
      # buffer has 9 elements
      # buf_flat = {a[0,0], a[0, 1], a[0, 2], __, __, __, a[1, 0], a[1, 1], a[1, 2]}

usm_ndarray((2, 2), dtype='u1', buffer='host', strides=(2, -1))
      # allocates 4 bytes of USM-host memory for (2,2) array of unsigned char
      # buffer has 4 elements
      # buf_flat = {a[0, 1],     a[0,0], a[1,1],     a[1,0]}
      #  addr:     { offset - 1, offset, offset + 1, offset + 2}
      # offset was auto-computed to be 1

# object mem is MemoryUSMShared of 64 bytes
usm_ndarray((4,), dtype='f8', buffer=mem, strides=(-2,), offset = 7)
     # map 4-elements of doubles to the buffer
     # buf_flat = {__, a[3], __, a[2], __, a[1], __, a[0]} 
     #   addr:    {    offset-6, offset-4, offset-2, offset }

# passing usm_ndarray in place of the buffer is equivalent to passing usm_ndarray's usm_data
W = usm_array.usm_ndarray((4, 2), dtype='i4', buffer='device', strides=(-5, -2))
Wiface = W.__sycl_usm_array_interface__
W2 = dpctl.tensor.usm_ndarray(
         Wiface['shape'],           # same shape
         dtype=Wiface['typestr'],   # same type
         buffer=W,                  # reuse the USM-memory buffer underlying usm_ndarray
         strides=Wiface['strides'], # use same strides
         offset=Wiface['offset']    # 
)
W2iface = W2.__sycl_usm_array_interface__
print(Wiface == W2iface) # prints True