scisharp / numsharp

High Performance Computation for N-D Tensors in .NET, similar API to NumPy.

NumSharp (NS) is a NumPy port to C# targetting .NET Standard.
NumSharp is the fundamental package needed for scientific computing with C# and F#.

Is it difficult to translate python machine learning code into .NET? Because too many functions can’t be found in the corresponding code in the .NET SDK. NumSharp is the C# version of NumPy, which is as consistent as possible with the NumPy programming interface, including function names and parameter locations. By introducing the NumSharp tool library, you can easily convert from python code to C# or F# code. Here is a comparison code between NumSharp and NumPy (left is python, right is C#):

Bold Features

• Use of Unmanaged Memory and fast unsafe algorithms.
• Broadcasting n-d shapes against each other. (intro)
• NDArray Slicing and nested/recusive slicing (nd["-1, ::2"]["1::3, :, 0"])
• Axis iteration and support in all of our implemented functions.
• Full and precise (to numpy) automatic type resolving and conversion (upcasting, downcasting and other cases)
• Non-copy - most cases, similarly to numpy, does not perform copying but returns a view instead.
• Almost non-effort copy-pasting numpy code from python to C#.
• Wide support for System.Drawing.Bitmap. (read more)

Implemented APIs

The NumPy class is a high-level abstraction of NDArray that allows NumSharp to be used in the same way as Python's NumPy, minimizing API differences caused by programming language features, allowing .NET developers to maximize Utilize a wide range of NumPy code resources to seamlessly translate python code into .NET code.

Install NumSharp in NuGet

PM> Install-Package NumSharp

How to use

using NumSharp;

var nd = np.full(5, 12); //[5, 5, 5 .. 5]
nd = np.zeros(12); //[0, 0, 0 .. 0]
nd = np.arange(12); //[0, 1, 2 .. 11]

// create a matrix
nd = np.zeros((3, 4)); //[0, 0, 0 .. 0]
nd = np.arange(12).reshape(3, 4);

// access data by index
var data = nd[1, 1];

// create a tensor
nd = np.arange(12);

// reshaping
data = nd.reshape(2, -1); //returning ndarray shaped (2, 6)

Shape shape = (2, 3, 2);
data = nd.reshape(shape); //Tuple implicitly casted to Shape
    //or:
nd =   nd.reshape(2, 3, 2);

// slicing tensor
data = nd[":, 0, :"]; //returning ndarray shaped (2, 1, 2)
data = nd[Slice.All, 0, Slice.All]; //equivalent to the line above.

// nd is currently shaped (2, 3, 2)
// get the 2nd vector in the 1st dimension
data = nd[1]; //returning ndarray shaped (3, 2)

// get the 3rd vector in the (axis 1, axis 2) dimension
data = nd[1, 2]; //returning ndarray shaped (2, )

// get flat representation of nd
data = nd.flat; //or nd.flatten() for a copy

// interate ndarray
foreach (object val in nd)
{
    // val can be either boxed value-type or a NDArray.
}

var iter = nd.AsIterator<int>(); //a different T can be used to automatically perform cast behind the scenes.
while (iter.HasNext())
{
    //read
    int val = iter.MoveNext();

    //write
    iter.MoveNextReference() = 123; //set value to the next val
    //note that setting is not supported when calling AsIterator<T>() where T is not the dtype of the ndarray.
}

How to run benchmark

C: \> dotnet NumSharp.Benchmark.dll nparange

NumSharp is referenced by

• dotnet/ML.NET
• ScipSharp/TensorFlow.NET
• ScipSharp/Gym.NET
• ScipSharp/Pandas.NET
• Oceania2018/Bigtree.MachineLearning
• Oceania2018/CherubNLP
• SciSharp/BotSharp

You might also be interested in NumSharp's sister project Numpy.NET which provides a more whole implementation of numpy by using pythonnet and behind-the-scenes deployment of python (read more).

NumSharp is a member project of SciSharp.org which is the .NET based ecosystem of open-source software for mathematics, science, and engineering.

Regen Templating

Our library contains over 150,000 lines of repetitive generated code, mostly for handling different data types without hurting performance.
The templates can be recognized with #if _REGEN blocks and are powered by Regen Templating Engine.
Regen is a powerful external tool (Visual studio extension, download here) that generates on demand based on a C#-like regen-lang.

numsharp's Issues

Implement numpy.amin

Return the minimum of an array or minimum along an axis.
https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.amin.html#numpy.amin

Need to refactor current Min(this NDArray<double> np).

Project structure with "src" & "test" folder

Sorry again to disturb ^^'

since C# is compiler and not interpreter project - shouldn't we make the structure :

• "/src/NumSharp" instead of NumSharp
• "/test/NumSharp.Test" instead of NumSharp.UnitTest

and for future (maybe one day ^^ ) have even "/src/SciSharp" and "/src/PandasSharp" ;)

implement numpy.vstack

Stack arrays in sequence vertically (row wise).
https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.vstack.html#numpy.vstack

Unique() and Random() methods do not resolve

Have they not been implemented yet?

Rewrite operations with switch pattern matching

I just found out that the modern c# language 7.x supports pattern matching in combination with switch.

Since numerical types like double complex, quaternion,... Do not have a common interface or numerical parent class and most numerical operations require operations like +, -, /, * it is necessary to have a switch case inside which check the generic type of ndarray.

At moment I wrote it quite ugly and lot of casting. Just want to rewrite it like this pattern matching

https://docs.microsoft.com/de-de/dotnet/csharp/pattern-matching

Which interfaces a NArray shall implement?

Hello NumSharp fans,

Since all great collections of numeric values implement some interfaces, I was thinking which we shall target?

It is not a critical question but it come to my mind and want to ask the others of you

• IEnumerable< T > --> would be fine since we store all numerics in one 1D array (so should be not to hard to implement)
• IList< T > --> because indexing but as far as I was reading IList< T > forces you to implement indexing with one int (which bring me to the question "ok what about matrix or Tensor? if we use a single int shall it be splitted / sliced? from tensor to matrix or matrix to vector?" if we think it could be beneficial why not? --> but here we should first implement the slicing which should using the Span< T > stuff.
• ICollection< T > --> ok here we have the problem that a collection can add elements. sounds easy but .... here my question "do we allow heterogeneous tensors? which is actual possible with jagged arrays but never with multidimensional? Something like ok 3 rows but 1st row has 2 columns, 2nd has 3 columns and 3rd das 4?"

Thanks for your though and I again say it "it is not functional important but i just want to start an issue t collect thoughts about this topic". ;)

Refactor shape property in NDArray

Since the dimension offset is depended on shapes, they should be binding together. We want to encapsulate these two properties into one class named Shape. Only way to modify shape property is to new it, after that, it becomes read only. That prevents some operations that change shape without modifying dimension offsets.

Looking Good!

Are you planning on porting all functionality or just a subset?

implement numpy.random.shuffle

Modify a sequence in-place by shuffling its contents.
https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.random.shuffle.html

Is there a reason to implement methods as extended methods?

Hello again,

just a question - no complain. :)
Is there a reason to implement methods as extension methods for NumSharp?

My consideration is just the following :

• extensions methods is sth. C# connected
• extensions methods are hard to use in other languages (e.g. powershell, F#. python.NET, ...)
• NumSharp could be used by many other languages if they are normal methods ;)

thanks again for your time. ;)

Set CI for NumSharp

Set up a Continuous integration tool for project.

Implement numpy.linspace

Return evenly spaced numbers over a specified interval.
https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.linspace.html

Implement numpy.asarray

Convert the input to an array.
https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.asarray.html

implement eye

implementing numpys eye method following https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.eye.html?highlight=eye#numpy.eye

Implement numpy.exp

Calculate the exponential of all elements in the input array.
https://docs.scipy.org/doc/numpy-1.15.1/reference/generated/numpy.exp.html

Implement NDArray.ToString()

Create this issue to keep improving string formatting for multiple dimension array.

@dotChris90 I really like this format. Appreciate.

How to internal storage the array

This issue come up because of discussion in other issue.

We should clear how to internal storage the NDArray data.
Until now we discussed 2 strategies. And I want to use this issue to discuss pro and cons.

Option 1 ) NDArray as an adapter
This means we have a generic NDArray class< T > where T can be any array or jagged array. The storage is 100% the same like the generic T. So accessing an object arr[idx][jdx] would lead to the same like arr.Data[idx][jdx] and the methods would just extend existing .NET classes.

Option 2 ) NDArray as a total new Array type
This means we have for all types e.g. matrix, tensor etc. always just one 1D array. The NDArray must offer methods for indexing and so on by itself and every type is always a NDArray< T >.

implement numpy.stack

Join a sequence of arrays along a new axis.
https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.stack.html#numpy.stack

Implement numpy.absolute

Calculate the absolute value element-wise.
https://docs.scipy.org/doc/numpy-1.15.1/reference/generated/numpy.absolute.html

Is NumSharp valuable to move forward?

partial class NDArray<T>

@dotChris90 Don't know why we need this. Could you give me the use case?

public partial class NDArray<T>
{
    public NDArray<T> reshape(params int[] shape)
    {
        return NumSharp.Extensions.NDArrayExtensions.reshape(this, shape);
    }
}

Reshape with -1

I'm sure this can be optimized. I couldn't really find how numpy actually does this so I guessed and rewrote the reshape routines. It currently only handles two dimensional reshape.

public static NDArray<T> ReShape<T>(this NDArray<T> np, params int[] shape)
{
    var count = shape.Length;
    var idx = FindNegativeIndex(shape);
    if (idx == -1)
        np.Shape = shape;
    else
        np.Shape = CalculateNegativeShape(idx, np.Shape, shape);

    //np.Shape = newShape;

    return np;
}

private static int FindNegativeIndex(params int[] shape)
{
    var count = shape.Length;
    var negOne = false;
    var indexOfNegOne = -1;
    for (int i = 0; i < count; i++)
    {
        if (shape[i] == -1)
        {
            if (negOne)
                throw new ArgumentException("Only allowed to pass one shape dimension as -1");

            negOne = true;
            indexOfNegOne = i;
        }
    }

    return indexOfNegOne;
}

private static IList<int> CalculateNegativeShape(int negativeIndex, IList<int> currentShape, params int[] shapeParams)
{
    var currentShapeCount = currentShape.Count;
    var shapeParamCount = shapeParams.Length;
    var newShape = new List<int>();
    var curShapeVolume = currentShape.Aggregate((x, y) => x * y);
    if (negativeIndex > -1)
    {
        int x = shapeParams[0];
        int y = 0;
        if (shapeParamCount >= 1)
            y = shapeParams[1];
        if (shapeParamCount > 2)
            throw new ArgumentException("We cannot currently handle reshapes of more than 2 dimensions");

        if (negativeIndex == 0 && shapeParamCount == 2)
        {
            var mod = curShapeVolume % y == 0;
            if (!mod)
                throw new ArgumentException($"Wrong Reshape. {curShapeVolume} is not evenly divisible by {y}");
            else
            {
                var a = curShapeVolume / y;
                var b = y;
                newShape.Add(a);
                newShape.Add(b);
            }
        }
        else if (negativeIndex == 1 && shapeParamCount == 2)
        {
            var mod = curShapeVolume % x == 0;
            if (!mod)
                throw new ArgumentException($"Wrong Reshape. {curShapeVolume} is not evenly divisible by {x}");
            else
            {
                var a = x;
                var b = curShapeVolume / x;
                newShape.Add(a);
                newShape.Add(b);
            }
        }
    }
    else
        return currentShape;

    return newShape;
}

And the tests.

[TestMethod]
public void ReshapeNegative()
{
    var np = new NDArray<int>();
    np.ARange(12);
    np.ReShape(-1, 2);
    Assert.IsTrue(np.Shape[0] == 6);
    Assert.IsTrue(np.Shape[1] == 2);

    np.ARange(12);
    np.ReShape(2, -1);
    Assert.IsTrue(np.Shape[0] == 2);
    Assert.IsTrue(np.Shape[1] == 6);

    np.ARange(12);
    np.ReShape(1, 3, 4);
    np.ReShape(-1, 3);
    Assert.IsTrue(np.Shape[0] == 4);
    Assert.IsTrue(np.Shape[1] == 3);

    np.ARange(12);
    np.ReShape(1, 3, 4);
    np.ReShape(3, -1);
    Assert.IsTrue(np.Shape[0] == 3);
    Assert.IsTrue(np.Shape[1] == 4);

    np.ARange(100 * 100 * 3);
    np.ReShape(100, 100, 3);
    np.ReShape(-1, 3);
    Assert.IsTrue(np.Shape[0] == 10000);
    Assert.IsTrue(np.Shape[1] == 3);

    np.ARange(15801033);
    np.ReShape(2531, 2081, 3);
    np.ReShape(-1, 3);
    Assert.IsTrue(np.Shape[0] == 5267011);
    Assert.IsTrue(np.Shape[1] == 3);
}

Implement numpy.where

Return elements, either from x or y, depending on condition.
https://docs.scipy.org/doc/numpy-1.13.0/reference/generated/numpy.where.html

Target Multiple Frameworks

Are there any objections to changing the csproj from this:

<TargetFramework>netstandard2.0</TargetFramework>

To this?

<TargetFrameworks>netstandard2.0;net472</TargetFrameworks>

This just allows one to test with the normal dotnet framework as well as dotnet standard.

Does mean Test fail on your local system?

• for my local the first (simplest) test fail
• debugging show all fine
• but when running without debugging fail because the mean is inf?
• have no idea why
• please some people can check your local system and let me know result ? :D

Let more people know about NumSharp

I've written an article here which introduce NumSharp.

@dotChris90 Can you start with the docs.

implement numpy.dot

Dot product of two arrays. Specifically,
https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.dot.html

implement numpy.convolve

Returns the discrete, linear convolution of two one-dimensional sequences. https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.convolve.html

Bitmaps?

I'm interested in loading a bitmap in to a NumSharp array. I realize that isn't written yet but I'm concerned that if I write and contribute that method it will be way too slow to do anything with. What are your thoughts on speed?

Thanks,
Darren

---

EDIT:
System.Drawing.Bitmap are now supported by a separate package, read more.

Import benchmark tool

Performance is critical for numerical computation. Import the benchmark tool BenchmarkDotNet to measure and visualize the performance.

Question : can a package be published to ~/.nuget on local machine?

Very stupid question.

Is it possible in msbuild to pack NumSharp after build automaticly and move to ~/.nuget?

I come up with this question because if there are other projects like pandas.net or I can image SciSharp and they are in different repos, we can not reference them in csproj. Because everybody of us has a different folder structure.

To avoid bad style or complains I think we have now 2 possible options.

No 1) one repo with one solution and all projects so we can reference them in csproj. And we all have same fder structure

No 2) we reference them as nuget package. Usual nuget search first local so if msbuild copy NumSharp nuget package automatically to local cache we are fine. :)

Maybe we have other options?

Support axis in min method

Add axis parameter to min method. Default is NULL.

Better Encapsulating for high level API

We're going to add a new entry class named NumSharp. NumSharp will have our API more stable for high level usage. Just change NDArray implementation, better encapsulation of OOP, and more readable function names, trying to be as same as possible for NumPy.

var np = new NumSharp();
np.arrange(10).reshape(2, 5);

implement numpy.hstack

Stack arrays in sequence horizontally (column wise).
https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.hstack.html

Which APIs and Modules could be implemented?

Hallo,

first of all : awesome work! :D
I just was thinking APIs could be used for numpy (so which classes and methods)?
And I was asking what modules should be also implemented?

• numpy
• scipy
• pandas
• matplotlib

Is there a way to generate a List with APIs on every module?
So could check which APIs exist in python and which should be implemented.

Moreover I think this libs could be used very well in F# and Powershell.
At end : great work for starting ;)

implement numpy asmatrix

following the API doc https://docs.scipy.org/doc/numpy-1.13.0/reference/generated/numpy.asmatrix.html

implement numpy Matrix Class

following the API doc https://docs.scipy.org/doc/numpy-1.15.1/reference/generated/numpy.matrix.html

open a Wiki

just want to ask if it is possible to open a wiki for numpy.
So we could start give examples for using in F#,C#.Powershell :D

Implement numpy.random.randint

Return random integers from low (inclusive) to high (exclusive).
https://docs.scipy.org/doc/numpy-1.15.1/reference/generated/numpy.random.randint.html

Span<T> and Slice?

@Oceania2018, @dotChris90 Have you seen Span? It's as fast as C++ code in dotnet. It may be useful in this assembly.

Docs
https://docs.microsoft.com/en-us/dotnet/api/system.span-1?view=netcore-2.1
https://msdn.microsoft.com/en-us/magazine/mt814808.aspx
https://blogs.msdn.microsoft.com/mazhou/2018/03/25/c-7-series-part-10-spant-and-universal-memory-management/
https://adamsitnik.com/Span/

implement method zeros

implementing zeros following https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.zeros.html

Implement a method which computes .NET tensor from NDArray

I was thinking that it could be very beneficial to create a method "ToDotNetArray" which convert the 1D NDArray to a jagged array in .NET World.

• Name --> ToDotNetArray
• Input --> nothing
• output --> dynamic

The reason for this is "better integration of NumSharp for other .NET packages". So no Numpy based reason for implementation.

Check matrix multiplication again with index check

I think I was wrong about the indexing with matrix multiplication. Will check this tomorrow.

Seems when mapping 1 dimension to 2 dimension the columns are 1st dimension. I did the multiplication with lines first. I need to check this again.

Until now just checked the computed values.

implement numpy.mean

Compute the arithmetic mean along the specified axis.
https://docs.scipy.org/doc/numpy-1.15.1/reference/generated/numpy.mean.html

implement np.std

Compute the standard deviation along the specified axis.
https://docs.scipy.org/doc/numpy-1.15.1/reference/generated/numpy.std.html

Implement numpy.sqrt

Return the non-negative square-root of an array, element-wise.
https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.sqrt.html

Rewrite methods so NDArray_Legacy can be finally removed

• since now we 0.3 I want to start tidy up little bit
• I kick out NDArray_legacy since we finally decided to go with the 1D array storage and I do not want to start a 2nd NDArray version
  ;)
• I will do it

Implement method ones

implement numpys ones method following https://docs.scipy.org/doc/numpy-1.15.0/reference/generated/numpy.ones.html?highlight=ones#numpy.ones

Generic ARange?

Is there a reason why the ARange isn't generic?

public static NDArray<T> ARange<T>(this NDArray<T> np, int stop, int start = 0, int step = 1) where T : IConvertible
{
    int index = 0;

    np.Data = Enumerable.Range(start, stop - start)
                        .Where(x => index++ % step == 0)
                        .Select(x => (T)Convert.ChangeType(x, typeof(T)))
                        .ToArray();
    return np;
}

Release notes and tracking

We have released v0.6.

@dotChris90 , @fdncred , @AoaAquarius and @Esther2013 Thanks all of you. Your excellent job make the NumSharp more and more closer to its goal.