NDArray.cs

/*
 * NumSharp
 * Copyright (C) 2018 Haiping Chen
 * 
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the Apache License 2.0 as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 * 
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * 
 * You should have received a copy of the Apache License 2.0
 * along with this program.  If not, see <http://www.apache.org/licenses/LICENSE-2.0/>.
 */

//TODO! Complete all TODOs return(?:.*;|;)[\n\r]{1,2}[\t\s]+//

using System;
using System.Collections;
using System.Diagnostics;
using System.Diagnostics.CodeAnalysis;
using System.Runtime.CompilerServices;
using System.Threading;
using NumSharp.Backends;
using NumSharp.Backends.Unmanaged;
using NumSharp.Generic;
using NumSharp.Utilities;

namespace NumSharp
{
    /// <summary>
    ///     An array object represents a multidimensional, homogeneous array of fixed-size items.<br></br>
    ///     An associated data-type object describes the format of each element in the array (its byte-order,<br></br>
    ///     how many bytes it occupies in memory, whether it is an integer, a floating point number, or something else, etc.)
    /// </summary>
    /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.html</remarks>
    [DebuggerTypeProxy(nameof(NDArrayDebuggerProxy))]
    [SuppressMessage("ReSharper", "ParameterHidesMember")]
    [ModuleName("ndarray")]
    public partial class NDArray : IIndex, ICloneable, IEnumerable, IDisposable
    {
        protected TensorEngine tensorEngine;

        // ---------------------------------------------------------------
        // Atomic Reference Counting (ARC) lifecycle
        //
        // Every NDArray ctor holds exactly one logical reference on the
        // underlying MemoryBlock (taken in InitializeArc, called from
        // every concrete ctor). Dispose drops it. Multiple Disposes are
        // idempotent. A finalizer is the safety net for the "user forgot"
        // case — same effect as Dispose, just non-deterministic timing.
        //
        // _disposed is int (not byte) because Interlocked.Exchange's
        // narrowest overload is int. Disposal is gated by a single CAS
        // so concurrent Dispose calls don't double-Release.
        // ---------------------------------------------------------------
        private int _disposed;

        // Ambient-scope back-pointer: the NDScope currently responsible for reclaiming this
        // array (null when untracked or yielded to the caller). Written by NDScope.Track /
        // Returns / Detach on the constructing thread only; makes Returns O(1) and makes
        // yielding an untracked array (an input passthrough, a caller's @out) a provable no-op.
        // Borrowed: the scope owns (tracks) this array, not the other way round.
        [NDBorrowed] internal NDScope TrackingScope;
        internal int TrackingIndex;

        /// <summary>
        ///     <c>true</c> if <see cref="Dispose"/> has been called on this
        ///     <see cref="NDArray"/>. Views and shared storage may still be
        ///     alive; this flag only reflects the local instance.
        /// </summary>
        public bool IsDisposed => Volatile.Read(ref _disposed) != 0;

        /// <summary>
        ///     Called from every concrete ctor after <see cref="Storage"/>
        ///     is assigned. Bumps the refcount on the underlying buffer so
        ///     this NDArray's reference is tracked.
        /// </summary>
        /// <remarks>
        ///     Returns silently when <see cref="Storage"/> or its inner
        ///     <c>IArraySlice</c> is null — that state belongs to
        ///     mid-construction NDArrays which finish wiring up via
        ///     <see cref="UnmanagedStorage.Allocate(Shape, Type)"/> shortly
        ///     after; the eventual TryAddRef call from that path completes
        ///     the bookkeeping.
        /// </remarks>
        private void InitializeArc()
        {
            NDScope.Track(this);   // ambient-scope registration (a thread-static read when no scope is open)
            var arr = Storage?.InternalArray;
            if (arr is null) return;
            arr.TryAddRef();
        }

        /// <summary>
        ///     Releases this <see cref="NDArray"/>'s reference to the
        ///     underlying unmanaged buffer. When the last reference is
        ///     released the buffer is freed synchronously on the calling
        ///     thread; views that still hold references keep working.
        ///
        ///     Safe to call multiple times — second and subsequent calls
        ///     are no-ops.
        /// </summary>
        public void Dispose()
        {
            // Idempotent: only the first call performs the Release.
            if (Interlocked.Exchange(ref _disposed, 1) != 0) return;
            Storage?.InternalArray?.Release();
            GC.SuppressFinalize(this);
        }

        /// <summary>
        ///     Finalizer safety net: runs only when the user never called
        ///     <see cref="Dispose"/>. Drops this NDArray's reference via
        ///     <see cref="IArraySlice.Abandon"/> — decrement WITHOUT the eager
        ///     free-at-zero that <see cref="Dispose"/> performs. This NDArray
        ///     being unreachable proves nothing about OTHER reachable aliases
        ///     of the same buffer (a bare <see cref="UnmanagedStorage"/> /
        ///     <see cref="IArraySlice"/> obtained via <see cref="GetData()"/>
        ///     holds no counted reference), so freeing here read as a
        ///     use-after-free through such aliases. The memory block's own
        ///     finalizer frees (and pools) the buffer in the GC cycle after
        ///     the last alias dies.
        /// </summary>
        ~NDArray()
        {
            if (Volatile.Read(ref _disposed) == 0)
                Storage?.InternalArray?.Abandon();
        }

        /// <summary>
        /// Gets the array owning the memory, or <c>null</c> if this array owns its data.
        /// </summary>
        /// <value>
        /// An <see cref="NDArray"/> wrapping the base storage for views, or <c>null</c> for arrays
        /// that own their data (e.g., created via <c>np.arange</c>, <c>np.zeros</c>, or <c>copy()</c>).
        /// </value>
        /// <remarks>
        /// <para>
        /// <b>NumPy Compatibility:</b> This property mirrors NumPy's <c>ndarray.base</c> attribute.
        /// All views chain to the ultimate owner (not intermediate views).
        /// </para>
        /// <para>
        /// <b>Example:</b>
        /// <code>
        /// var a = np.arange(10);    // a.@base == null (owns data)
        /// var b = a["2:5"];         // b.@base.Storage == a.Storage (view)
        /// var c = b["1:2"];         // c.@base.Storage == a.Storage (chains to original!)
        /// var d = a.copy();         // d.@base == null (copy owns data)
        /// var e = a.reshape(2, 5);  // e.@base.Storage == a.Storage (view)
        /// </code>
        /// </para>
        /// <para>
        /// <b>View Detection:</b> Use <c>arr.@base != null</c> or <c>arr.Storage.IsView</c> to
        /// detect if an array is a view. Note that <c>arr.@base != null</c> may trigger NDArray's
        /// operator overloading for element-wise comparison. Prefer <c>arr.Storage.IsView</c> for
        /// simple boolean checks.
        /// </para>
        /// <para>
        /// <b>Semantic Difference from NumPy:</b> In NumPy, <c>c.base is a</c> returns <c>True</c>
        /// (object identity). In NumSharp, <c>c.@base</c> creates a new wrapper each call, so
        /// <c>ReferenceEquals(c.@base, a)</c> is <c>false</c>. However, the underlying storage
        /// is the same: <c>c.@base.Storage == a.Storage</c> is <c>true</c>.
        /// </para>
        /// <para>
        /// <b>Memory Safety:</b> The underlying memory is kept alive by the shared Disposer
        /// in the MemoryBlock, not by this property. Views remain valid even if the original
        /// array reference is garbage collected.
        /// </para>
        /// </remarks>
        /// <seealso href="https://numpy.org/doc/stable/reference/generated/numpy.ndarray.base.html"/>
        /// <seealso cref="UnmanagedStorage.BaseStorage"/>
        /// <seealso cref="UnmanagedStorage.IsView"/>
        public NDArray? @base => Storage._baseStorage is { } bs ? new NDArray(bs) : null;

        #region Constructors

        /// <summary>
        ///     Creates a new <see cref="NDArray"/> with this storage.
        /// </summary>
        /// <param name="storage"></param>
        public NDArray(UnmanagedStorage storage)
        {
            Storage = storage;
            tensorEngine = storage.Engine ?? BackendFactory.GetEngine();
            Storage.Engine = tensorEngine;
            InitializeArc();
        }

        /// <summary>
        ///     Creates a new <see cref="NDArray"/> with this storage.
        /// </summary>
        /// <param name="shape">The shape to set for this NDArray, does not perform checks.</param>
        /// <remarks>Doesn't copy. Does not perform checks for <paramref name="shape"/>.</remarks>
        protected internal NDArray(UnmanagedStorage storage, Shape shape)
        {
            Storage = storage.Alias(ref shape);
            tensorEngine = storage.Engine ?? BackendFactory.GetEngine();
            Storage.Engine = tensorEngine;
            InitializeArc();
        }

        /// <summary>
        ///     Creates a new <see cref="NDArray"/> with this storage.
        /// </summary>
        /// <param name="shape">The shape to set for this NDArray, does not perform checks.</param>
        /// <remarks>Doesn't copy. Does not perform checks for <paramref name="shape"/>.</remarks>
        protected internal NDArray(UnmanagedStorage storage, ref Shape shape)
        {
            Storage = storage.Alias(ref shape);
            tensorEngine = storage.Engine ?? BackendFactory.GetEngine();
            Storage.Engine = tensorEngine;
            InitializeArc();
        }

        /// <summary>
        ///     Hot-path view ctor: wraps an already-aliased storage whose Engine
        ///     field is known to be set. Skips the standard ctor's
        ///     <c>storage.Engine ?? BackendFactory.GetEngine()</c> guard and the
        ///     <c>Storage.Engine = tensorEngine</c> writeback (it's already there).
        ///     Used by <c>np.split</c> sub-array construction where we already own
        ///     the parent's resolved engine.
        /// </summary>
        internal NDArray(UnmanagedStorage aliasedStorage, TensorEngine engine, bool skipEngineResolve)
        {
            Storage = aliasedStorage;
            tensorEngine = engine;
            InitializeArc();
        }

        /// <summary>
        /// Constructor for init data type
        /// internal storage is 1D with 1 element
        /// </summary>
        /// <param name="dtype">
        ///     The dtype DESCRIPTOR of the elements (NumPy's <c>PyArray_NewFromDescr</c>). A C# <see cref="Type"/>,
        ///     an <see cref="NPTypeCode"/> or a NumPy dtype string convert implicitly.
        /// </param>
        /// <param name="engine">The engine of this <see cref="NDArray"/></param>
        /// <remarks>This constructor does not call allocation/></remarks>
        protected internal NDArray(DType dtype, TensorEngine engine)
        {
            tensorEngine = engine;
            Storage = TensorEngine.GetStorage(dtype);
        }

        /// <summary>
        /// Constructor for init data type
        /// internal storage is 1D with 1 element
        /// </summary>
        /// <param name="dtype">
        ///     The dtype DESCRIPTOR of the elements. A C# <see cref="Type"/> (<c>typeof(double)</c>), an
        ///     <see cref="NPTypeCode"/> or a NumPy dtype string (<c>"f8"</c>) convert implicitly — this is the ONE
        ///     dtype-taking constructor family (the former <see cref="NPTypeCode"/> twins were folded into it).
        /// </param>
        /// <remarks>This constructor does not call allocation/></remarks>
        public NDArray(DType dtype) : this(dtype, BackendFactory.GetEngine()) { }

        /// <summary>
        /// Constructor which takes .NET array
        /// dtype and shape is determined from array
        /// </summary>
        /// <param name="values"></param>
        /// <param name="shape"></param>
        /// <param name="order"></param>
        /// <returns>Array with values</returns>
        /// <remarks>This constructor calls <see cref="IStorage.Allocate(NumSharp.Shape,System.Type)"/></remarks>
        public NDArray(Array values, Shape shape = default, char order = 'C') : this(values.GetType().GetElementType())
        {
            if (shape.IsEmpty)
                shape = Shape.ExtractShape(values);

            // Honor an explicit 'F' request: the (row-major) values buffer is reinterpreted as
            // column-major by rebuilding the shape with F-contiguous strides — mirroring NumPy's
            // ndarray(buffer=..., order='F'). 'C' (the default) keeps the extracted C-order layout.
            if (order == 'F' && shape.NDim > 1)
                shape = new Shape(shape.dimensions, 'F');

            Storage.Allocate(values.ResolveRank() != 1 ? ArraySlice.FromArray(Arrays.Flatten(values), false) : ArraySlice.FromArray(values, false), shape);
            InitializeArc();
        }

        /// <summary>
        /// Constructor which takes .NET array
        /// dtype and shape is determined from array
        /// </summary>
        /// <param name="values"></param>
        /// <param name="shape"></param>
        /// <param name="order"></param>
        /// <returns>Array with values</returns>
        /// <remarks>This constructor calls <see cref="IStorage.Allocate(NumSharp.Shape,System.Type)"/></remarks>
        public NDArray(IArraySlice values, Shape shape = default, char order = 'C') : this(values.TypeCode)
        {
            if (shape.IsEmpty)
                shape = Shape.Vector(values.Count);

            // Honor an explicit 'F' request: reinterpret the buffer as column-major by rebuilding
            // the shape with F-contiguous strides (NumPy's ndarray(buffer=..., order='F')).
            if (order == 'F' && shape.NDim > 1)
                shape = new Shape(shape.dimensions, 'F');

            Storage.Allocate(values, shape);
            InitializeArc();
        }

        /// <summary>
        /// Constructor which initialize elements with 0
        /// type and shape are given.
        /// </summary>
        /// <param name="dtype">The dtype descriptor (a <see cref="Type"/>, <see cref="NPTypeCode"/> or NumPy dtype string converts implicitly)</param>
        /// <param name="shape">Shape of NDArray</param>
        /// <remarks>This constructor calls <see cref="UnmanagedStorage.Allocate(NumSharp.Shape,NumSharp.DType,bool)"/></remarks>
        public NDArray(DType dtype, Shape shape) : this(dtype, shape, true) { }

        /// <summary>
        /// Constructor which initialize elements with 0
        /// type, shape, and order are given.
        /// </summary>
        /// <param name="dtype">internal data type</param>
        /// <param name="shape">Shape of NDArray</param>
        /// <param name="order">Memory order. Note: Only C-order is supported, F-order parameter is accepted but ignored.</param>
        /// <remarks>This constructor calls <see cref="UnmanagedStorage.Allocate(NumSharp.Shape,NumSharp.DType,bool)"/></remarks>
        public NDArray(DType dtype, Shape shape, char order) : this(dtype, shape, true) { }

        /// <summary>
        ///     Constructor which initialize elements with length of <paramref name="size"/>
        /// </summary>
        /// <param name="dtype">Internal data type</param>
        /// <param name="size">The size as a single dimension shape</param>
        /// <remarks>This constructor calls <see cref="UnmanagedStorage.Allocate(NumSharp.Shape,NumSharp.DType,bool)"/></remarks>
        public NDArray(DType dtype, int size) : this(dtype, Shape.Vector(size), true) { }

        /// <summary>
        ///     Constructor which initialize elements with length of <paramref name="size"/>
        /// </summary>
        /// <param name="dtype">Internal data type</param>
        /// <param name="size">The size as a single dimension shape</param>
        /// <param name="fillZeros">Should set the values of the new allocation to default(dtype)? otherwise - old memory noise</param>
        /// <remarks>This constructor calls <see cref="UnmanagedStorage.Allocate(NumSharp.Shape,NumSharp.DType,bool)"/></remarks>
        public NDArray(DType dtype, int size, bool fillZeros) : this(dtype, Shape.Vector(size), fillZeros) { }

        /// <summary>
        ///     Constructor which initialize elements with length of <paramref name="size"/> (long for >2GB arrays)
        /// </summary>
        /// <param name="dtype">Internal data type</param>
        /// <param name="size">The size as a single dimension shape</param>
        /// <remarks>This constructor calls <see cref="UnmanagedStorage.Allocate(NumSharp.Shape,NumSharp.DType,bool)"/></remarks>
        public NDArray(DType dtype, long size) : this(dtype, Shape.Vector(size), true) { }

        /// <summary>
        ///     Constructor which initialize elements with length of <paramref name="size"/> (long for >2GB arrays)
        /// </summary>
        /// <param name="dtype">Internal data type</param>
        /// <param name="size">The size as a single dimension shape</param>
        /// <param name="fillZeros">Should set the values of the new allocation to default(dtype)? otherwise - old memory noise</param>
        /// <remarks>This constructor calls <see cref="UnmanagedStorage.Allocate(NumSharp.Shape,NumSharp.DType,bool)"/></remarks>
        public NDArray(DType dtype, long size, bool fillZeros) : this(dtype, Shape.Vector(size), fillZeros) { }

        /// <summary>
        /// Constructor which initialize elements with 0
        /// type and shape are given.
        /// </summary>
        /// <param name="dtype">The dtype descriptor (a <see cref="Type"/>, <see cref="NPTypeCode"/> or NumPy dtype string converts implicitly)</param>
        /// <param name="shape">Shape of NDArray</param>
        /// <param name="fillZeros">Should set the values of the new allocation to default(dtype)? otherwise - old memory noise</param>
        /// <remarks>This constructor calls <see cref="UnmanagedStorage.Allocate(NumSharp.Shape,NumSharp.DType,bool)"/></remarks>
        public NDArray(DType dtype, Shape shape, bool fillZeros) : this(dtype)
        {
            Storage.Allocate(shape, dtype, fillZeros);
            InitializeArc();
        }

        private NDArray(IArraySlice array, Shape shape) : this(array.TypeCode)
        {
            Storage.Allocate(array, shape);
            InitializeArc();
        }

        #endregion

        /// <summary>
        ///     The dtype of this array — the dtype DESCRIPTOR (NumPy's <c>ndarray.dtype</c>, a <see cref="DType"/>): the
        ///     canonical instance of the array's dtype class (<c>np.float64</c> for a double array — the same object every
        ///     time, so <c>a.dtype == b.dtype</c> and <c>a.dtype == np.float64</c> are cheap structural compares), or the
        ///     parametric instance an array was created with. It converts implicitly to the CLR element
        ///     <see cref="System.Type"/> (<c>Type t = a.dtype;</c>) and to <see cref="NPTypeCode"/>, and compares equal to a
        ///     <see cref="Type"/> / <see cref="NPTypeCode"/> / dtype string the way NumPy's <c>dtype.__eq__</c> coerces
        ///     (<c>a.dtype == typeof(double)</c>, <c>a.dtype.Equals("f8")</c>). Use <see cref="typecode"/> for the kernel
        ///     discriminator and <c>dtype.type</c> for the element type when a <see cref="System.Type"/> is required by name.
        /// </summary>
        public DType dtype => Storage.Descr;

        /// <summary>
        ///     The <see cref="NPTypeCode"/> of this array.
        /// </summary>
        public NPTypeCode typecode => Storage.TypeCode;

        /// <summary>
        ///     Gets the precomputed <see cref="NPTypeCode"/> of <see cref="dtype"/>.
        /// </summary>
        internal NPTypeCode GetTypeCode
        {
            [MethodImpl(Inline)]
            get => Storage.TypeCode;
        }

        /// <summary>
        ///     Gets the address that this NDArray starts from.
        /// </summary>
        protected internal unsafe void* Address
        {
            [MethodImpl(Inline)]
            get => Storage.Address;
        }

        /// <summary>
        ///     Data length of every dimension
        /// </summary>
        public long[] shape
        {
            get => Storage.Shape.Dimensions;
            set => Storage.Reshape(value);
        }

        /// <summary>
        ///     Dimension count
        /// </summary>
        public int ndim => Storage.Shape.NDim;

        /// <summary>
        ///     Total of elements
        /// </summary>
        public long size => Storage.Shape.Size;

        public int dtypesize => Storage.DTypeSize;

        /// <summary>
        ///     Length of one array element in bytes — NumPy's <c>ndarray.itemsize</c>. This is a pure
        ///     property of the <see cref="dtype"/> and is independent of shape, strides, offset or layout,
        ///     so every view of a given dtype (C/F-contiguous, sliced, strided, transposed, negative-stride,
        ///     broadcast, 0-d or empty) reports the same value. Byte-identical to NumPy for the 13 dtypes
        ///     with a NumPy analog (e.g. float64→8, complex128→16, int8/bool→1); the two NumSharp-only
        ///     dtypes report their in-memory element size (Char→2, Decimal→16). Alias of the legacy
        ///     <see cref="dtypesize"/>; the product <see cref="size"/> * <c>itemsize</c> is <see cref="nbytes"/>.
        /// </summary>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.itemsize.html</remarks>
        public int itemsize => Storage.DTypeSize;

        /// <summary>
        ///     Total bytes consumed by the elements of the array — the LOGICAL element count
        ///     (<see cref="size"/>) times the itemsize (<see cref="dtypesize"/>), matching NumPy's
        ///     <c>PyArray_NBYTES = PyArray_ITEMSIZE * PyArray_SIZE</c>. Because it uses the logical size,
        ///     a broadcast view reports its logical byte size (e.g. a <c>(1000,1000)</c> stride-0 view of
        ///     one int32 reports <c>4000000</c>), not its one-element backing buffer; a 0-d array reports
        ///     one itemsize and an empty array reports 0. Does not include the array object's own overhead.
        /// </summary>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.nbytes.html</remarks>
        public long nbytes => Storage.Shape.Size * (long)Storage.DTypeSize;

        public char order => Storage.Shape.Order;

        /// <summary>
        ///     The strides of the array, in BYTES per axis — matching NumPy's <c>ndarray.strides</c>
        ///     (<c>PyArray_STRIDES</c>): the number of bytes to step in memory to advance one element
        ///     along each dimension. Equal to the element strides times the <see cref="dtypesize"/>
        ///     (itemsize), so a stride-0 broadcast axis stays 0 and a negative-stride (reversed) view
        ///     stays negative. A 0-d array reports an empty array. A fresh array is returned on each
        ///     access. Internal kernels that need ELEMENT strides must read
        ///     <see cref="Shape"/>.<see cref="View.Shape.Strides"/> instead.
        /// </summary>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.strides.html</remarks>
        public long[] strides
        {
            get
            {
                long[] elementStrides = Storage.Shape.Strides;
                int itemsize = Storage.DTypeSize;
                var byteStrides = new long[elementStrides.Length];
                for (int i = 0; i < elementStrides.Length; i++)
                    byteStrides[i] = elementStrides[i] * itemsize;
                return byteStrides;
            }
        }

        /// <summary>
        ///     A 1-D iterator over the array.
        /// </summary>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.flat.html</remarks>
        public NDArray flat
        {
            get
            {
                if (ndim == 1 || Shape.IsScalar) //because it is already flat, there is no need to clone even if it is already sliced.
                    return new NDArray(Storage);
                // flat's documented contract is the raveled C-order IMAGE — a materialized copy
                // for ANY non-contiguous layout (its ~15 internal consumers walk the buffer
                // linearly). reshape must NOT be used here: it now returns nocopy strided VIEWS
                // for combinable layouts (NumPy reshape parity), which would both write through
                // and break the linear walks.
                if (!Shape.IsContiguous)
                    return new NDArray(new UnmanagedStorage(Storage.CloneData(), Shape.Vector(size))) { TensorEngine = TensorEngine };
                return this.reshape(new Shape(size));
            }
        }

        /// <summary>
        ///     A write-through, C-order flat iterator over the array — the NumSharp analog of NumPy's
        ///     <c>flatiter</c> (the type of NumPy's <c>ndarray.flat</c>). Unlike <see cref="flat"/> (a
        ///     raveled <see cref="NDArray"/> that COPIES for a non-contiguous layout, dropping writes),
        ///     this reads and writes through to the base in logical C-order for every memory layout.
        ///     A fresh iterator is returned on each access (its cursor starts at 0).
        /// </summary>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.flatiter.html</remarks>
        public np.FlatIterator flatiter => new np.FlatIterator(this);

        /// <summary>
        ///     The transposed array. <br></br>
        ///     Same as self.transpose().
        /// </summary>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.T.html</remarks>
        public NDArray T
        {
            get
            {
                return transpose();
            }
        }

        /// <summary>
        ///     View of the matrix transposed array. <br></br>
        ///     Swaps the two innermost dimensions, i.e. an array of shape <c>(..., M, N)</c> becomes <c>(..., N, M)</c>.<br></br>
        ///     Same as <c>np.matrix_transpose(self)</c> / <c>self.swapaxes(-1, -2)</c>. Requires at least 2 dimensions.
        /// </summary>
        /// <exception cref="System.ArgumentException">If this array has fewer than 2 dimensions.</exception>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.mT.html</remarks>
        public NDArray mT
        {
            get
            {
                if (ndim < 2)
                    throw new System.ArgumentException("matrix transpose with ndim < 2 is undefined");
                return TensorEngine.SwapAxes(this, -1, -2);
            }
        }

        /// <summary>
        ///     The device on which this array lives. NumSharp — like NumPy — is single-device and always
        ///     CPU-resident, so this is always the string <c>"cpu"</c>. Exposed for Array-API conformance,
        ///     so code such as <c>xp.zeros(shape, device: x.device)</c> ports from NumPy unchanged.
        /// </summary>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.device.html</remarks>
        public string device => "cpu";

        /// <summary>
        ///     Array-API device transfer. NumSharp has only the CPU device, so the sole accepted target is
        ///     <c>"cpu"</c>, for which the SAME array is returned with no copy — matching NumPy, which returns
        ///     <c>self</c>. Any other device raises.
        /// </summary>
        /// <param name="device">Target device. Must be <c>"cpu"</c>.</param>
        /// <param name="stream">Accepted for Array-API signature parity; must be <c>null</c> (NumSharp models no streams).</param>
        /// <returns>This array, unchanged.</returns>
        /// <exception cref="ArgumentNullException">If <paramref name="device"/> is <c>null</c> (NumPy raises <c>TypeError</c>).</exception>
        /// <exception cref="ArgumentException">If <paramref name="device"/> is not <c>"cpu"</c>, or <paramref name="stream"/> is non-null.</exception>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.to_device.html</remarks>
        public NDArray to_device(string device, object stream = null)
        {
            // NumPy parses `device` as a required str first, so a null device is a TypeError before the
            // stream check; then stream, then the device value (conversion_utils.c / array_api_standard.c).
            if (device is null)
                throw new ArgumentNullException(nameof(device), "to_device() argument 1 must be str, not None");
            if (stream != null)
                throw new ArgumentException("The stream argument in to_device() is not supported");
            // Single quotes around 'cpu' here — the creation-path device= message uses double quotes.
            // The asymmetry is deliberate and matches NumPy 2.x verbatim.
            if (!string.Equals(device, "cpu", StringComparison.Ordinal))
                throw new ArgumentException($"Unsupported device: {device}. Only 'cpu' is accepted.");
            return this;
        }

        /// <summary>
        ///     The shape representing this <see cref="NDArray"/>.
        /// </summary>
        public Shape Shape
        {
            [MethodImpl(Inline)]
            get => Storage.Shape;
            [MethodImpl(Inline)]
            set => Storage.Reshape(value);
        }

        /// <summary>
        /// The internal storage that stores data for this <see cref="NDArray"/>.
        /// </summary>
        protected internal UnmanagedStorage Storage;

        /// <summary>
        ///     The tensor engine that handles this <see cref="NDArray"/>.
        /// </summary>
        public TensorEngine TensorEngine
        {
            [DebuggerStepThrough] get => tensorEngine ?? Storage.Engine ?? BackendFactory.GetEngine();
            set
            {
                tensorEngine = value ?? Storage.Engine ?? BackendFactory.GetEngine();
                Storage.Engine = tensorEngine;
            }
        }

        /// <summary>
        /// Shortcut for access internal elements
        /// </summary>
        /// <typeparam name="T"></typeparam>
        /// <returns></returns>
        public ArraySlice<T> Data<T>() where T : unmanaged
        {
            return Storage.GetData<T>();
        }

        /// <summary>
        ///     Get: Gets internal storage array by calling <see cref="IStorage.GetData"/><br></br>
        ///     Set: Replace internal storage by calling <see cref="IStorage.ReplaceData(System.Array)"/>
        /// </summary>
        /// <remarks>Setting does not replace internal storage array.</remarks>
        protected internal IArraySlice Array
        {
            [MethodImpl(Inline)]
            get => Storage.InternalArray;
        }

        public ArraySlice<T> CloneData<T>() where T : unmanaged => Storage.CloneData<T>();

        public IArraySlice CloneData() => Storage.CloneData();

        /// <summary>
        ///     Copy of the array, cast to a specified type.
        /// </summary>
        /// <param name="dtype">
        ///     The dtype to cast this array to — one descriptor parameter, like NumPy's <c>dtype</c>: a C# <see cref="Type"/>
        ///     (<c>typeof(float)</c>), an <see cref="NPTypeCode"/>, a NumPy dtype string (<c>"f4"</c>, <c>"float32"</c>) or a
        ///     <see cref="DType"/> (<c>np.float32</c>, <c>other.dtype</c>) all convert implicitly.
        /// </param>
        /// <param name="copy">By default, astype always returns a newly allocated array. If this is set to false and the dtype requirement is already satisfied, the input array itself is returned instead of a copy; when a conversion is needed a new array is still allocated and the input is never modified (NumPy semantics).</param>
        /// <returns>An <see cref="NDArray"/> of given <paramref name="dtype"/>.</returns>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.astype.html</remarks>
        [SuppressMessage("ReSharper", "ParameterHidesMember")]
        public NDArray astype(DType dtype, bool copy = true) => astype(dtype, copy, 'K');

        /// <summary>
        ///     Copy of the array, cast to a specified type and memory layout.
        /// </summary>
        /// <param name="dtype">
        ///     The dtype to cast this array to — one descriptor parameter, like NumPy's <c>dtype</c>: a C# <see cref="Type"/>,
        ///     an <see cref="NPTypeCode"/>, a NumPy dtype string or a <see cref="DType"/> all convert implicitly.
        /// </param>
        /// <param name="copy">By default, astype always returns a newly allocated array. If this is set to false and the dtype requirement is already satisfied, the input array itself is returned instead of a copy; when a conversion is needed a new array is still allocated and the input is never modified (NumPy semantics).</param>
        /// <param name="order">
        ///     Controls the memory layout: 'C' (row-major), 'F' (column-major),
        ///     'A' - 'F' if source is F-contiguous (and not C-contiguous) else 'C',
        ///     'K' (default) - preserve the source layout.
        /// </param>
        /// <param name="casting">
        ///     NumPy's cast-rule gate ('no' / 'equiv' / 'safe' / 'same_kind' / 'unsafe').
        ///     Default 'unsafe' (matches NumPy's astype default) — any conversion is permitted.
        ///     A stricter rule raises <see cref="InvalidCastException"/> (NumPy's TypeError analogue)
        ///     when the source dtype cannot cast to <paramref name="dtype"/> under that rule.
        /// </param>
        /// <returns>An <see cref="NDArray"/> of given <paramref name="dtype"/> with the requested layout.</returns>
        /// <exception cref="ArgumentNullException"><paramref name="dtype"/> is null.</exception>
        /// <exception cref="NotSupportedException">The descriptor's class has no storage lane yet (a datetime64/timedelta64 descriptor before Stage C).</exception>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.astype.html</remarks>
        [SuppressMessage("ReSharper", "ParameterHidesMember")]
        public NDArray astype(DType dtype, bool copy, char order, string casting = "unsafe")
        {
            if (dtype is null)
                throw new ArgumentNullException(nameof(dtype));
            var typeCode = dtype.GetTypeCode(); // a descriptor-only class raises its own descriptive "no storage yet"
            ValidateAstypeCasting(typeCode, casting);
            var casted = TensorEngine.Cast(this, dtype.type, copy);
            // 'K' (astype's default) is fully handled by Cast's KEEPORDER allocation — including
            // the neither-contiguous sorted-stride-perm layouts (3-D transpose, broadcast) that a
            // binary C/F resolve cannot express; re-imposing the collapsed order here would both
            // undo that layout and force a copy out of a satisfied `copy: false` call.
            if (order == 'K' || order == 'k')
                return casted;
            char physical = OrderResolver.Resolve(order, this.Shape);
            return RelayoutAstype(casted, physical);
        }

        /// <summary>
        ///     Force the cast result into the astype-requested physical layout. NumPy's
        ///     <c>astype(order=…)</c> ALWAYS honours the order — <c>order='C'</c> on an F-contiguous
        ///     source produces a C-contiguous result, and <c>order='F'</c> on a C-contiguous source an
        ///     F-contiguous one (probed on 2.4.2). <see cref="Backends.TensorEngine.Cast"/> preserves the
        ///     source layout (a same-dtype copy of an F array stays F), so the requested order must be
        ///     re-imposed here — previously only the 'F' half existed, so <c>F.astype(t, order:'C')</c>
        ///     silently kept F. Both orders coincide for ndim ≤ 1, so no re-layout is needed there.
        /// </summary>
        private static NDArray RelayoutAstype(NDArray casted, char physical)
        {
            // Guard the empty sentinel (`new NDArray(typecode)`, null dimensions) and 0-/1-D shapes
            // by reading the raw dimensions field — Shape.NDim/IsContiguous NRE on a null-dims shape,
            // and both C and F coincide for ndim ≤ 1, so no re-layout is possible or needed there.
            var dims = casted.Shape.dimensions;
            if (dims is null || dims.Length <= 1)
                return casted;
            if (physical == 'F' && !casted.Shape.IsFContiguous)
                return casted.copy('F');
            if (physical == 'C' && !casted.Shape.IsContiguous)
                return casted.copy('C');
            return casted;
        }

        /// <summary>
        ///     NumPy astype casting gate: default 'unsafe' allows any conversion; a stricter rule
        ///     raises <see cref="InvalidCastException"/> (NumPy's TypeError analogue) when the cast
        ///     is not permitted. Same exception type and message shape as <see cref="np.copyto"/>.
        /// </summary>
        [SuppressMessage("ReSharper", "ParameterHidesMember")]
        private void ValidateAstypeCasting(NPTypeCode toType, string casting)
        {
            // 'unsafe' (astype's default) short-circuits — every conversion is allowed, no work.
            if (string.IsNullOrEmpty(casting) || casting == "unsafe")
                return;
            NPTypeCode fromType = this.GetTypeCode;
            if (fromType == toType)
                return;
            // np.can_cast validates the rule name (ArgumentException on an unknown rule) and
            // encodes NumPy's cast table (bit-exact vs 2.4.2, verified across all 15 dtypes).
            if (!np.can_cast(fromType, toType, casting))
                throw new InvalidCastException(
                    $"Cannot cast array data from dtype('{fromType.AsNumpyDtypeName()}') " +
                    $"to dtype('{toType.AsNumpyDtypeName()}') according to the rule '{casting}'");
        }

        /// <summary>
        /// Clone the whole NDArray
        /// internal storage is also cloned into 2nd memory area
        /// </summary>
        /// <returns>Cloned NDArray</returns>
        object ICloneable.Clone() => Clone();

        /// <summary>
        /// Clone the whole NDArray
        /// internal storage is also cloned into 2nd memory area
        /// </summary>
        /// <returns>Cloned NDArray</returns>
        public virtual NDArray Clone() => new NDArray(this.Storage.Clone()) { TensorEngine = TensorEngine };

        /// <summary>
        /// Returns an enumerator that iterates along the first axis.
        /// </summary>
        /// <remarks>
        /// NumPy-compatible iteration behavior:
        /// - 0-D arrays (scalars): throws TypeError
        /// - 1-D arrays: yields scalar elements
        /// - N-D arrays (N > 1): yields (N-1)-D NDArray slices along first axis
        /// </remarks>
        public IEnumerator GetEnumerator()
        {
            // Empty array: no iterations
            if (Array == null || Shape.IsEmpty || Shape.size == 0)
                return _empty().GetEnumerator();

            // 0-D scalar: not iterable (matches NumPy)
            if (ndim == 0)
                throw new TypeError("iteration over a 0-d array");

            // N-D arrays (N > 1): iterate over slices along first axis
            if (ndim > 1)
                return _iterSlices().GetEnumerator();

            // 1-D arrays: iterate over scalar elements.
            // Materialize via Storage.ToArray<T>() which already handles contig,
            // sliced, and strided layouts (Buffer.MemoryCopy fast path or
            // coordinate walk as appropriate). Foreach over a flat T[] avoids
            // per-element iterator/delegate overhead and lets the JIT inline.
            switch (GetTypeCode)
            {
                case NPTypeCode.Boolean: return _iter1D<bool>().GetEnumerator();
                case NPTypeCode.Byte: return _iter1D<byte>().GetEnumerator();
                case NPTypeCode.SByte: return _iter1D<sbyte>().GetEnumerator();
                case NPTypeCode.Int16: return _iter1D<short>().GetEnumerator();
                case NPTypeCode.UInt16: return _iter1D<ushort>().GetEnumerator();
                case NPTypeCode.Int32: return _iter1D<int>().GetEnumerator();
                case NPTypeCode.UInt32: return _iter1D<uint>().GetEnumerator();
                case NPTypeCode.Int64: return _iter1D<long>().GetEnumerator();
                case NPTypeCode.UInt64: return _iter1D<ulong>().GetEnumerator();
                case NPTypeCode.Char: return _iter1D<char>().GetEnumerator();
                case NPTypeCode.Half: return _iter1D<Half>().GetEnumerator();
                case NPTypeCode.Double: return _iter1D<double>().GetEnumerator();
                case NPTypeCode.Single: return _iter1D<float>().GetEnumerator();
                case NPTypeCode.Decimal: return _iter1D<decimal>().GetEnumerator();
                case NPTypeCode.Complex: return _iter1D<System.Numerics.Complex>().GetEnumerator();
                default:
                    throw new NotSupportedException();
            }

            IEnumerable _empty()
            {
                yield break;
            }

            IEnumerable _iterSlices()
            {
                // Iterate over slices along first axis
                // For a (3, 4, 5) array, yields 3 slices of shape (4, 5)
                var len = shape[0];
                for (int i = 0; i < len; i++)
                {
                    yield return this[i];
                }
            }

            System.Collections.Generic.IEnumerable<T> _iter1D<T>() where T : unmanaged
            {
                var flat = Storage.ToArray<T>();
                foreach (var v in flat)
                    yield return v;
            }
        }

        /// <summary>
        ///     New view of array with the same data.
        /// </summary>
        /// <param name="dtype">
        ///     Data-type descriptor of the returned view, e.g., float32 or int16. The default, None, results in the view having the same data-type as a.
        ///     This argument can also be specified as an ndarray sub-class, which then specifies the type of the returned object (this is equivalent to setting the type parameter).
        /// </param>
        /// <returns></returns>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.view.html</remarks>
        public NDArray view(DType dtype = null)
        {
            if (dtype is null || dtype.GetTypeCode() == Storage.TypeCode)
            {
                return new NDArray(Storage.Alias()) { TensorEngine = TensorEngine };
            }
            // AliasAs reinterprets bytes without conversion (like NumPy's view)
            return new NDArray(Storage.AliasAs(dtype.GetTypeCode())) { TensorEngine = TensorEngine };
        }

        /// <summary>
        ///     New view of array with the same data.
        /// </summary>
        /// <param name="dtype">
        ///     Data-type descriptor of the returned view, e.g., float32 or int16. The default, None, results in the view having the same data-type as a.
        ///     This argument can also be specified as an ndarray sub-class, which then specifies the type of the returned object (this is equivalent to setting the type parameter).
        /// </param>
        /// <returns></returns>
        /// <remarks>https://numpy.org/doc/stable/reference/generated/numpy.ndarray.view.html</remarks>
        public NDArray<T> view<T>() where T : unmanaged 
            => view(typeof(T)).AsGeneric<T>();

        #region Getters

        /// <summary>
        ///     Get all NDArray slices at that specific dimension.
        /// </summary>
        /// <param name="axis">Zero-based dimension index on which axis and forward of it to select data., e.g. dimensions=1, shape is (2,2,3,3), returned shape = 4 times of (3,3)</param>
        /// <remarks>Does not perform copy.</remarks>
        /// <example>
        /// <code>
        ///     var nd = np.arange(27).reshape(3,1,3,3);<br></br>
        ///     var ret = nd.GetNDArrays(1);<br></br>
        ///     Assert.IsTrue(ret.All(n=>n.Shape == new Shape(3,3));<br></br>
        ///     Assert.IsTrue(ret.Length == 3);<br></br><br></br>
        ///     var nd = np.arange(27).reshape(3,1,3,3);<br></br>
        ///     
        ///     var ret = nd.GetNDArrays(0);<br></br>
        ///     Assert.IsTrue(ret.All(n=>n.Shape == new Shape(1,3,3));<br></br>
        ///     Assert.IsTrue(ret.Length == 3);<br></br>
        /// </code>
        /// </example>
        [SuppressMessage("ReSharper", "LoopCanBeConvertedToQuery")]
        public NDArray[] GetNDArrays(int axis = 0)
        {
            axis += 1; //axis is 0-based, we need 1 based (aka count)
            if (axis <= 0 || axis > Shape.dimensions.Length)
                throw new ArgumentOutOfRangeException(nameof(axis));

            //get all the dimensions involved till the axis
            var dims = Storage.Shape.dimensions;
            long[] selectDimensions = new long[axis];
            for (int i = 0; i < axis; i++)
                selectDimensions[i] = dims[i];

            //compute len
            long len = 1;
            foreach (var i in selectDimensions)
                len = len * i;

            var ret = new NDArray[len];
            var iter = new ValueCoordinatesIncrementor(selectDimensions);
            var index = iter.Index; //heap the pointer to that array.
            for (long i = 0; i < ret.Length; i++)
            {
                ret[i] = new NDArray(Storage.GetData(index)) { TensorEngine = TensorEngine };
                iter.Next();
            }

            return ret;
        }

        /// <summary>
        ///     Gets the internal storage and converts it to <typeparamref name="T"/> if necessary.
        /// </summary>
        /// <typeparam name="T">The returned type.</typeparam>
        /// <returns>An array of type <typeparamref name="T"/></returns>
        public ArraySlice<T> GetData<T>() where T : unmanaged => Storage.GetData<T>();

        /// <summary>
        ///     Get reference to internal data storage
        /// </summary>
        /// <returns>reference to internal storage as System.Array</returns>
        public IArraySlice GetData() => Storage.GetData();

        /// <summary>
        ///     Gets a NDArray at the single element addressed by the coordinate
        ///     <paramref name="indices"/> (one index per axis).
        /// </summary>
        /// <param name="indices">The coordinates to the wanted value</param>
        /// <remarks>
        ///     Does not copy, returns a memory slice. This is the COORDINATE-ACCESS
        ///     replacement for the old <c>nd[new int[]{…}]</c> behavior: a raw
        ///     <c>int[]</c> as an index is now FANCY indexing (NumPy parity, selects
        ///     rows), so use <c>nd.GetData(coords)</c> for the former element access.
        /// </remarks>
        public NDArray GetData(int[] indices) => new NDArray(Storage.GetData(indices)) { TensorEngine = TensorEngine };

        /// <summary>
        ///     Gets a NDArray at the single element addressed by the coordinate
        ///     <paramref name="indices"/> (one index per axis).
        /// </summary>
        /// <param name="indices">The coordinates to the wanted value</param>
        /// <remarks>
        ///     Does not copy, returns a memory slice. This is the COORDINATE-ACCESS
        ///     replacement for the old <c>nd[new long[]{…}]</c> behavior: a raw
        ///     <c>long[]</c> as an index is now FANCY indexing (NumPy parity, selects
        ///     rows), so use <c>nd.GetData(coords)</c> for the former element access.
        /// </remarks>
        public NDArray GetData(long[] indices) => new NDArray(Storage.GetData(indices)) { TensorEngine = TensorEngine };

        /// <summary>
        ///     Retrieves value of type <see cref="bool"/>.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="bool"/></exception>
        [MethodImpl(Inline)]
        public bool GetBoolean(int[] indices) => Storage.GetBoolean(indices);

        /// <summary>
        ///     Retrieves value of type <see cref="byte"/>.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="byte"/></exception>
        [MethodImpl(Inline)]
        public byte GetByte(int[] indices) => Storage.GetByte(indices);

        /// <summary>
        ///     Retrieves value of type <see cref="char"/>.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="char"/></exception>
        [MethodImpl(Inline)]
        public char GetChar(int[] indices) => Storage.GetChar(indices);

        /// <summary>
        ///     Retrieves value of type <see cref="decimal"/>.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="decimal"/></exception>
        [MethodImpl(Inline)]
        public decimal GetDecimal(int[] indices) => Storage.GetDecimal(indices);

        /// <summary>
        ///     Retrieves value of type <see cref="double"/>.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="double"/></exception>
        [MethodImpl(Inline)]
        public double GetDouble(int[] indices) => Storage.GetDouble(indices);

        /// <summary>
        ///     Retrieves value of type <see cref="short"/>.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="short"/></exception>
        [MethodImpl(Inline)]
        public short GetInt16(int[] indices) => Storage.GetInt16(indices);

        /// <summary>
        ///     Retrieves value of type <see cref="int"/>.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="int"/></exception>
        [MethodImpl(Inline)]
        public int GetInt32(int[] indices) => Storage.GetInt32(indices);

        /// <summary>
        ///     Retrieves value of type <see cref="long"/>.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="long"/></exception>
        [MethodImpl(Inline)]
        public long GetInt64(int[] indices) => Storage.GetInt64(indices);

        /// <summary>
        ///     Retrieves value of type <see cref="float"/>.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="float"/></exception>
        [MethodImpl(Inline)]
        public float GetSingle(int[] indices) => Storage.GetSingle(indices);

        /// <summary>
        ///     Retrieves value of type <see cref="ushort"/>.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="ushort"/></exception>
        [MethodImpl(Inline)]
        public ushort GetUInt16(int[] indices) => Storage.GetUInt16(indices);

        /// <summary>
        ///     Retrieves value of type <see cref="uint"/>.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="uint"/></exception>
        [MethodImpl(Inline)]
        public uint GetUInt32(int[] indices) => Storage.GetUInt32(indices);

        /// <summary>
        ///     Retrieves value of type <see cref="ulong"/>.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="ulong"/></exception>
        [MethodImpl(Inline)]
        public ulong GetUInt64(int[] indices) => Storage.GetUInt64(indices);

        [MethodImpl(Inline)]
        public sbyte GetSByte(int[] indices) => Storage.GetSByte(indices);

        [MethodImpl(Inline)]
        public Half GetHalf(int[] indices) => Storage.GetHalf(indices);

        [MethodImpl(Inline)]
        public System.Numerics.Complex GetComplex(int[] indices) => Storage.GetComplex(indices);

        #region Typed Getters (long[] overloads for int64 indexing)

        [MethodImpl(Inline)]
        public bool GetBoolean(params long[] indices) => Storage.GetBoolean(indices);

        [MethodImpl(Inline)]
        public byte GetByte(params long[] indices) => Storage.GetByte(indices);

        [MethodImpl(Inline)]
        public char GetChar(params long[] indices) => Storage.GetChar(indices);

        [MethodImpl(Inline)]
        public decimal GetDecimal(params long[] indices) => Storage.GetDecimal(indices);

        [MethodImpl(Inline)]
        public double GetDouble(params long[] indices) => Storage.GetDouble(indices);

        [MethodImpl(Inline)]
        public short GetInt16(params long[] indices) => Storage.GetInt16(indices);

        [MethodImpl(Inline)]
        public int GetInt32(params long[] indices) => Storage.GetInt32(indices);

        [MethodImpl(Inline)]
        public long GetInt64(params long[] indices) => Storage.GetInt64(indices);

        [MethodImpl(Inline)]
        public float GetSingle(params long[] indices) => Storage.GetSingle(indices);

        [MethodImpl(Inline)]
        public ushort GetUInt16(params long[] indices) => Storage.GetUInt16(indices);

        [MethodImpl(Inline)]
        public uint GetUInt32(params long[] indices) => Storage.GetUInt32(indices);

        [MethodImpl(Inline)]
        public ulong GetUInt64(params long[] indices) => Storage.GetUInt64(indices);

        [MethodImpl(Inline)]
        public sbyte GetSByte(params long[] indices) => Storage.GetSByte(indices);

        [MethodImpl(Inline)]
        public Half GetHalf(params long[] indices) => Storage.GetHalf(indices);

        [MethodImpl(Inline)]
        public System.Numerics.Complex GetComplex(params long[] indices) => Storage.GetComplex(indices);

        #endregion

        /// <summary>
        ///     Retrieves value of unspecified type (will figure using <see cref="DType"/>).
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="object"/></exception>
        [MethodImpl(Inline)]
        public object GetValue(int[] indices) => Storage.GetValue(indices);

        /// <summary>
        ///     Retrieves value of unspecified type (will figure using <see cref="DType"/>).
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="object"/></exception>
        [MethodImpl(Inline)]
        public object GetValue(params long[] indices) => Storage.GetValue(indices);

        /// <summary>
        ///     Retrieves value of unspecified type (will figure using <see cref="DType"/>).
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="object"/></exception>
        [MethodImpl(Inline)]
        public T GetValue<T>(int[] indices) where T : unmanaged => Storage.GetValue<T>(indices);

        /// <summary>
        ///     Get a single value from NDArray as type T.
        /// </summary>
        /// <param name="indices">The shape's indices to get.</param>
        /// <returns></returns>
        /// <exception cref="NullReferenceException">When <see cref="DType"/> is not <see cref="object"/></exception>
        [MethodImpl(Inline)]
        public T GetValue<T>(params long[] indices) where T : unmanaged => Storage.GetValue<T>(indices);

        /// <summary>
        ///     Retrieves value of
        /// </summary>
        /// <param name="index"></param>
        /// <returns></returns>
        [MethodImpl(Inline)]
        public object GetAtIndex(long index) => Storage.GetAtIndex(index);

        /// <summary>
        ///     Retrieves value of
        /// </summary>
        /// <param name="index"></param>
        /// <returns></returns>
        [MethodImpl(Inline)]
        public T GetAtIndex<T>(long index) where T : unmanaged => Storage.GetAtIndex<T>(index);

        #endregion

        #region Setters

        /// <summary>
        ///     Set a <see cref="IArraySlice"/> at given <see cref="indices"/>.
        /// </summary>
        /// <param name="value">The value to set</param>
        /// <param name="indices">The </param>
        /// <remarks>
        ///     Does not change internal storage data type.<br></br>
        ///     If <paramref name="value"/> does not match <see cref="DType"/>, <paramref name="value"/> will be converted.
        /// </remarks>
        public void SetData(IArraySlice value, int[] indices)
        {
            Storage.SetData(value, indices);
        }

        /// <summary>
        ///     Set a <see cref="IArraySlice"/> at given <see cref="indices"/> (long version).
        /// </summary>
        /// <param name="value">The value to set</param>
        /// <param name="indices">The indices (long version)</param>
        /// <remarks>
        ///     Does not change internal storage data type.<br></br>
        ///     If <paramref name="value"/> does not match <see cref="DType"/>, <paramref name="value"/> will be converted.
        /// </remarks>
        public void SetData(IArraySlice value, params long[] indices)
        {
            Storage.SetData(value, indices);
        }

        /// <summary>
        ///     Set a <see cref="NDArray"/> at given <see cref="indices"/>.
        /// </summary>
        /// <param name="value">The value to set</param>
        /// <param name="indices">The </param>
        /// <remarks>
        ///     Does not change internal storage data type.<br></br>
        ///     If <paramref name="value"/> does not match <see cref="DType"/>, <paramref name="value"/> will be converted.
        /// </remarks>
        public void SetData(NDArray value, int[] indices)
        {
            Storage.SetData(value, indices);
        }

        /// <summary>
        ///     Set a <see cref="NDArray"/> at given <see cref="indices"/> (long version).
        /// </summary>
        /// <param name="value">The value to set</param>
        /// <param name="indices">The indices (long version)</param>
        /// <remarks>
        ///     Does not change internal storage data type.<br></br>
        ///     If <paramref name="value"/> does not match <see cref="DType"/>, <paramref name="value"/> will be converted.
        /// </remarks>
        public void SetData(NDArray value, params long[] indices)
        {
            Storage.SetData(value, indices);
        }

        /// <summary>
        ///      Set a <see cref="NDArray"/>, <see cref="IArraySlice"/>, <see cref="Array"/> or a scalar value at given <see cref="indices"/>.
        /// </summary>
        /// <param name="value">The value to set</param>
        /// <param name="indices">The </param>
        /// <remarks>
        ///     Does not change internal storage data type.<br></br>
        ///     If <paramref name="value"/> does not match <see cref="DType"/>, <paramref name="value"/> will be converted.
        /// </remarks>
        public void SetData(object value, int[] indices)
        {
            Storage.SetData(value, indices);
        }

        /// <summary>
        ///     Set a single value at given <see cref="indices"/>.
        /// </summary>
        /// <param name="value">The value to set</param>
        /// <param name="indices">The </param>
        /// <remarks>
        ///     Does not change internal storage data type.<br></br>
        ///     If <paramref name="value"/> does not match <see cref="DType"/>, <paramref name="value"/> will be converted.
        /// </remarks>
        public void SetValue(object value, int[] indices)
        {
            Storage.SetValue(value, indices);
        }

        /// <summary>
        ///     Set a single value at given <see cref="indices"/>.
        /// </summary>
        /// <param name="value">The value to set</param>
        /// <param name="indices">The </param>
        /// <remarks>
        ///     Does not change internal storage data type.<br></br>
        ///     If <paramref name="value"/> does not match <see cref="DType"/>, <paramref name="value"/> will be converted.
        /// </remarks>
        public void SetValue<T>(T value, int[] indices) where T : unmanaged
        {
            Storage.SetValue<T>(value, indices);
        }

        /// <summary>
        ///     Set a single value at given <see cref="indices"/>.
        /// </summary>
        /// <param name="value">The value to set</param>
        /// <param name="indices">The coordinates (long version).</param>
        /// <remarks>
        ///     Does not change internal storage data type.<br></br>
        ///     If <paramref name="value"/> does not match <see cref="DType"/>, <paramref name="value"/> will be converted.
        /// </remarks>
        public void SetValue<T>(T value, params long[] indices) where T : unmanaged
        {
            Storage.SetValue<T>(value, indices);
        }

        /// <summary>
        ///     Set a single value at given <see cref="indices"/>.
        /// </summary>
        /// <param name="value">The value to set</param>
        /// <param name="indices">The coordinates (long version).</param>
        /// <remarks>
        ///     Does not change internal storage data type.<br></br>
        ///     If <paramref name="value"/> does not match <see cref="DType"/>, <paramref name="value"/> will be converted.
        /// </remarks>
        public void SetValue(object value, params long[] indices)
        {
            Storage.SetValue(value, indices);
        }

        /// <summary>
        ///     Sets <see cref="values"/> as the internal data storage and changes the internal storage data type to <see cref="dtype"/> and casts <see cref="values"/> if necessary.
        /// </summary>
        /// <param name="values">The values to set as internal data soruce</param>
        /// <param name="dtype">The type to change this storage to and the type to cast <see cref="values"/> if necessary.</param>
        /// <remarks>Does not copy values unless cast is necessary.</remarks>
        // ReSharper disable once ParameterHidesMember
        public void ReplaceData(Array values, Type dtype)
        {
            Storage.ReplaceData(values, dtype);
        }

        /// <summary>
        ///     Sets <see cref="values"/> as the internal data storage and changes the internal storage data type to <see cref="values"/> type.
        /// </summary>
        /// <param name="values"></param>
        /// <remarks>Does not copy values.</remarks>
        public void ReplaceData(Array values)
        {
            Storage.ReplaceData(values);
        }

        /// <summary>
        ///     Sets <see cref="nd"/> as the internal data storage and changes the internal storage data type to <see cref="nd"/> type.
        /// </summary>
        /// <param name="nd"></param>
        /// <remarks>Does not copy values and does change shape and dtype.</remarks>
        public void ReplaceData(NDArray nd)
        {
            Storage.ReplaceData(nd);
        }

        /// <summary>
        ///     Set an Array to internal storage, cast it to new dtype and if necessary change dtype  
        /// </summary>
        /// <param name="values"></param>
        /// <param name="typeCode"></param>
        /// <remarks>Does not copy values unless cast is necessary and doesn't change shape.</remarks>
        public void ReplaceData(Array values, NPTypeCode typeCode)
        {
            Storage.ReplaceData(values, typeCode);
        }

        /// <summary>
        ///     Sets <see cref="values"/> as the internal data source and changes the internal storage data type to <see cref="values"/> type.
        /// </summary>
        /// <param name="values"></param>
        /// <param name="dtype"></param>
        /// <remarks>Does not copy values and doesn't change shape.</remarks>
        public void ReplaceData(IArraySlice values, Type dtype)
        {
            Storage.ReplaceData(values, dtype);
        }

        /// <summary>
        ///     Sets <see cref="values"/> as the internal data source and changes the internal storage data type to <see cref="values"/> type.
        /// </summary>
        /// <param name="values"></param>
        /// <remarks>Does not copy values and doesn't change shape.</remarks>
        public void ReplaceData(IArraySlice values)
        {
            Storage.ReplaceData(values);
        }

        /// <summary>
        ///     Retrieves value at given linear (offset) <paramref name="index"/>.
        /// </summary>
        /// <param name="index"></param>
        /// <returns></returns>
        [MethodImpl(Inline)]
        public void SetAtIndex(object obj, long index) => Storage.SetAtIndex(obj, index);

        /// <summary>
        ///     Retrieves value of
        /// </summary>
        /// <param name="index"></param>
        /// <returns></returns>
        [MethodImpl(Inline)]
        public void SetAtIndex<T>(T value, long index) where T : unmanaged => Storage.SetAtIndex(value, index);

	// %foreach supported_dtypes,supported_dtypes_lowercase%
        // /// <summary>
        // ///     Sets a #2 at specific coordinates.
        // /// </summary>
        // /// <param name="value">The values to assign</param>
        // /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        // [MethodImpl(Inline)]
        // public void Set#1(#2 value, int[] indices) => Storage.Set#1(value, indices);

    // %
        /// <summary>
        ///     Sets a bool at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetBoolean(bool value, int[] indices) => Storage.SetBoolean(value, indices);

        /// <summary>
        ///     Sets a byte at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetByte(byte value, int[] indices) => Storage.SetByte(value, indices);

        /// <summary>
        ///     Sets a short at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetInt16(short value, int[] indices) => Storage.SetInt16(value, indices);

        /// <summary>
        ///     Sets a ushort at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetUInt16(ushort value, int[] indices) => Storage.SetUInt16(value, indices);

        /// <summary>
        ///     Sets a int at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetInt32(int value, int[] indices) => Storage.SetInt32(value, indices);

        /// <summary>
        ///     Sets a int at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at (long version).</param>
        [MethodImpl(Inline)]
        public void SetInt32(int value, params long[] indices) => Storage.SetInt32(value, indices);

        /// <summary>
        ///     Sets a uint at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetUInt32(uint value, int[] indices) => Storage.SetUInt32(value, indices);

        /// <summary>
        ///     Sets a long at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetInt64(long value, int[] indices) => Storage.SetInt64(value, indices);

        /// <summary>
        ///     Sets a long at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at (long version).</param>
        [MethodImpl(Inline)]
        public void SetInt64(long value, params long[] indices) => Storage.SetInt64(value, indices);

        /// <summary>
        ///     Sets a ulong at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetUInt64(ulong value, int[] indices) => Storage.SetUInt64(value, indices);

        /// <summary>
        ///     Sets a char at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetChar(char value, int[] indices) => Storage.SetChar(value, indices);

        /// <summary>
        ///     Sets a double at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetDouble(double value, int[] indices) => Storage.SetDouble(value, indices);

        /// <summary>
        ///     Sets a double at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetDouble(double value, params long[] indices) => Storage.SetDouble(value, indices);

        /// <summary>
        ///     Sets a float at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetSingle(float value, int[] indices) => Storage.SetSingle(value, indices);

        /// <summary>
        ///     Sets a decimal at specific coordinates.
        /// </summary>
        /// <param name="value">The values to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetDecimal(decimal value, int[] indices) => Storage.SetDecimal(value, indices);

        [MethodImpl(Inline)]
        public void SetSByte(sbyte value, int[] indices) => Storage.SetSByte(value, indices);

        [MethodImpl(Inline)]
        public void SetHalf(Half value, int[] indices) => Storage.SetHalf(value, indices);

        [MethodImpl(Inline)]
        public void SetComplex(System.Numerics.Complex value, int[] indices) => Storage.SetComplex(value, indices);

        #region Typed Setters (long[] overloads for int64 indexing)

        /// <summary>
        ///     Sets a bool at specific coordinates.
        /// </summary>
        /// <param name="value">The value to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetBoolean(bool value, params long[] indices) => Storage.SetBoolean(value, indices);

        /// <summary>
        ///     Sets a byte at specific coordinates.
        /// </summary>
        /// <param name="value">The value to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetByte(byte value, params long[] indices) => Storage.SetByte(value, indices);

        /// <summary>
        ///     Sets a short at specific coordinates.
        /// </summary>
        /// <param name="value">The value to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetInt16(short value, params long[] indices) => Storage.SetInt16(value, indices);

        /// <summary>
        ///     Sets a ushort at specific coordinates.
        /// </summary>
        /// <param name="value">The value to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetUInt16(ushort value, params long[] indices) => Storage.SetUInt16(value, indices);

        /// <summary>
        ///     Sets a uint at specific coordinates.
        /// </summary>
        /// <param name="value">The value to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetUInt32(uint value, params long[] indices) => Storage.SetUInt32(value, indices);

        /// <summary>
        ///     Sets a ulong at specific coordinates.
        /// </summary>
        /// <param name="value">The value to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetUInt64(ulong value, params long[] indices) => Storage.SetUInt64(value, indices);

        /// <summary>
        ///     Sets a char at specific coordinates.
        /// </summary>
        /// <param name="value">The value to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetChar(char value, params long[] indices) => Storage.SetChar(value, indices);

        /// <summary>
        ///     Sets a float at specific coordinates.
        /// </summary>
        /// <param name="value">The value to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetSingle(float value, params long[] indices) => Storage.SetSingle(value, indices);

        /// <summary>
        ///     Sets a decimal at specific coordinates.
        /// </summary>
        /// <param name="value">The value to assign</param>
        /// <param name="indices">The coordinates to set <paramref name="value"/> at.</param>
        [MethodImpl(Inline)]
        public void SetDecimal(decimal value, params long[] indices) => Storage.SetDecimal(value, indices);

        [MethodImpl(Inline)]
        public void SetSByte(sbyte value, params long[] indices) => Storage.SetSByte(value, indices);

        [MethodImpl(Inline)]
        public void SetHalf(Half value, params long[] indices) => Storage.SetHalf(value, indices);

        [MethodImpl(Inline)]
        public void SetComplex(System.Numerics.Complex value, params long[] indices) => Storage.SetComplex(value, indices);

        #endregion

        #endregion

        [NDBorrowed] // the debugger's view of an array it does not own
        private class NDArrayDebuggerProxy
        {
            private readonly NDArray NDArray;

            /// <summary>Initializes a new instance of the <see cref="T:System.Object"></see> class.</summary>
            public NDArrayDebuggerProxy(NDArray ndArray)
            {
                NDArray = ndArray;
            }

            /// <summary>Returns a string that represents the current object.</summary>
            /// <returns>A string that represents the current object.</returns>
            public override string ToString()
            {
                //TODO! make a truncuted to string.
                return NDArray.ToString(false);
            }
        }
    }
}