Skip to content

Commit dea0778

Browse files
NucsNucs
authored
Readme.md rewrite (SciSharp#352)
1 parent d7235c7 commit dea0778

1 file changed

Lines changed: 68 additions & 46 deletions

File tree

‎README.md‎

Lines changed: 68 additions & 46 deletions
Original file line numberDiff line numberDiff line change
@@ -1,91 +1,113 @@
11
# NumSharp
2-
3-
NumPy port in C# .NET Standard<a href="http://scisharpstack.org"><img src="https://github.com/SciSharp/SciSharp/blob/master/art/scisharp_badge.png" width="200" height="200" align="right" /></a>
4-
2+
[![NuGet](https://img.shields.io/nuget/dt/NumSharp.svg)](https://www.nuget.org/packages/NumSharp)
53
[![Join the chat at https://gitter.im/publiclab/publiclab](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/sci-sharp/community)
64
[![AppVeyor](https://ci.appveyor.com/api/projects/status/bmaauxd9rx5lsq9i?svg=true)](https://ci.appveyor.com/project/Haiping-Chen/numsharp)
75
[![codecov](https://codecov.io/gh/SciSharp/NumSharp/branch/master/graph/badge.svg)](https://codecov.io/gh/SciSharp/NumSharp)
8-
[![NuGet](https://img.shields.io/nuget/dt/NumSharp.svg)](https://www.nuget.org/packages/NumSharp)
96
[![Badge](https://img.shields.io/badge/link-996.icu-red.svg)](https://996.icu/#/en_US)
107

11-
Is it difficult to translate python machine learning code into C#? 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# code. Here is a comparison code between NumSharp and NumPy (left is python, right is C#):
8+
[NumPy](https://github.com/numpy/numpy) port to C# targetting .NET Standard.<a href="http://scisharpstack.org"><img src="https://github.com/SciSharp/SciSharp/blob/master/art/scisharp_badge.png" width="200" height="200" align="right" /></a><br>
9+
NumSharp is the fundamental package needed for scientific computing with C#.<br>
1210

13-
![comparision](docfx_project/images/python-csharp-comparision.png)
11+
Is it difficult to translate python machine learning code into C#? Because too many functions can’t be found in the corresponding code in the .NET SDK.
12+
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# code.
13+
Here is a comparison code between NumSharp and NumPy (left is python, right is C#):
1414

15-
If you want to read some more informations, we start a doc on https://scisharp.github.io/NumSharp/.
15+
![comparision](docfx_project/images/python-csharp-comparision.png)
1616

17-
NumSharp has implemented the arange, array, max, min, reshape, normalize, unique interfaces. More and more interfaces will be added to the library gradually. If you want to use .NET to get started with machine learning, NumSharp will be your best tool library.
17+
### Bold Features
18+
* Use of Unmanaged Memory and fast unsafe algorithms.
19+
* [Broadcasting](https://docs.scipy.org/doc/numpy-1.15.0/user/basics.broadcasting.html) n-d shapes against each other. ([intro](https://machinelearningmastery.com/broadcasting-with-numpy-arrays/))
20+
* [NDArray Slicing](https://docs.scipy.org/doc/numpy/reference/arrays.indexing.html) and nested/recusive slicing (`nd["-1, ::2"]["1::3, :, 0"]`)
21+
* Axis iteration and support in all of our implemented functions.
22+
* Full and precise (to numpy) automatic type resolving and conversion (upcasting, downcasting and other cases)
23+
* Non-copy - most cases, similarly to numpy, do not perform copying but returns a view instead.
24+
* Almost non-effort copy-pasting numpy code from python to C#.
1825

1926
### Implemented APIs
20-
2127
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.
2228

23-
Check the code: [src\NumSharp.Core\APIs](src\NumSharp.Core\APIs)
29+
### Install NumSharp in NuGet
30+
```sh
31+
PM> Install-Package NumSharp
32+
```
2433

2534
### How to use
2635
```cs
2736
using NumSharp;
28-
```
29-
```cs
30-
// create a vector
31-
var nd = np.arange(12)
37+
38+
var nd = np.full(5, 12); //[5, 5, 5 .. 5]
39+
nd = np.zeros(12); //[0, 0, 0 .. 0]
40+
nd = np.arange(12); //[0, 1, 2 .. 11]
3241
3342
// create a matrix
43+
nd = np.zeros((3, 4)); //[0, 0, 0 .. 0]
3444
nd = np.arange(12).reshape(3, 4);
3545

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

3949
// create a tensor
40-
nd = np.arange(12).reshape(2, 3, 2);
50+
nd = np.arange(12);
51+
52+
// reshaping
53+
data = nd.reshape(2, -1); //returning ndarray shaped (2, 6)
54+
55+
Shape shape = (2, 3, 2);
56+
data = nd.reshape(shape); //Tuple implicitly casted to Shape
57+
//or:
58+
nd = nd.reshape(2, 3, 2);
4159

60+
// slicing tensor
61+
data = nd[":, 0, :"]; //returning ndarray shaped (2, 1, 2)
62+
data = nd[Slice.All, 0, Slice.All]; //equivalent to the line above.
63+
64+
// nd is currently shaped (2, 3, 2)
4265
// get the 2nd vector in the 1st dimension
43-
data = n[new Shape(1)];
66+
data = nd[1]; //returning ndarray shaped (3, 2)
4467
4568
// get the 3rd vector in the (axis 1, axis 2) dimension
46-
data = n[new Shape(1, 2)];
69+
data = nd[1, 2]; //returning ndarray shaped (2, )
70+
71+
// get flat representation of nd
72+
data = nd.flat; //or nd.flatten() for a copy
4773
4874
// interate ndarray
49-
foreach (data in nd)
75+
foreach (object val in nd)
5076
{
51-
// data is a ndarray or a value
77+
// val can be either boxed value-type or a NDArray.
5278
}
53-
```
5479

55-
### Install NumSharp in NuGet
56-
```
57-
PM> Install-Package NumSharp
58-
```
80+
var iter = nd.AsIterator<int>(); //a different T can be used to automatically perform cast behind the scenes.
81+
while (iter.HasNext())
82+
{
83+
//read
84+
int val = iter.MoveNext();
5985

60-
### How to make docs
61-
- Download docfx and put on PATH &rarr; https://github.com/dotnet/docfx/releases
62-
- ```docfx ./docfx_project/docfx.json -o ./docs```
86+
//write
87+
iter.MoveNextReference() = 123; //set value to the next val
88+
//note that setting is not supported when calling AsIterator<T>() where T is not the dtype of the ndarray.
89+
}
90+
```
6391

6492
### How to run benchmark
6593
```
6694
C: \> dotnet NumSharp.Benchmark.dll nparange
6795
```
68-
Reference the [documents](https://scisharp.github.io/NumSharp) generated by DocFX.
69-
70-
Reference the [documents](https://numsharp.readthedocs.io) host on readthedocs.io.
7196

72-
NumSharp is referenced by:
73-
* [Pandas.NET](https://github.com/SciSharp/Pandas.NET)
74-
* [SciSharp-Learn](https://github.com/SciSharp/scisharp-learn)
75-
* [TensorFlow.NET](https://github.com/SciSharp/TensorFlow.NET)
76-
* [Bigtree.MachineLearning](https://github.com/Oceania2018/Bigtree.MachineLearning)
77-
* [CherubNLP](https://github.com/Oceania2018/CherubNLP)
78-
* [BotSharp](https://github.com/dotnetcore/BotSharp)
97+
### NumSharp is referenced by
98+
* [dotnet/ML.NET](https://github.com/dotnet/machinelearning)
99+
* [ScipSharp/TensorFlow.NET](https://github.com/SciSharp/TensorFlow.NET)
100+
* [ScipSharp/Gym.NET](https://github.com/SciSharp/Gym.NET)
101+
* [ScipSharp/Pandas.NET](https://github.com/SciSharp/Pandas.NET)
102+
* [Oceania2018/Bigtree.MachineLearning](https://github.com/Oceania2018/Bigtree.MachineLearning)
103+
* [Oceania2018/CherubNLP](https://github.com/Oceania2018/CherubNLP)
104+
* [SciSharp/BotSharp](https://github.com/SciSharp/BotSharp)
79105

80-
You might also be interested in NumSharp's sister project [Numpy.NET](https://github.com/SciSharp/Numpy.NET).
106+
You might also be interested in NumSharp's sister project [Numpy.NET](https://github.com/SciSharp/Numpy.NET) which provides a more whole implementation of numpy by using [pythonnet](https://github.com/pythonnet/pythonnet) and [behind-the-scenes deployment of python](https://github.com/henon/Python.Included) ([read more](https://henon.wordpress.com/2019/06/05/using-python-libraries-in-net-without-a-python-installation/)).
81107

82108
NumSharp is a member project of [SciSharp.org](https://github.com/SciSharp) which is the .NET based ecosystem of open-source software for mathematics, science, and engineering.
83-
Welcome to fork and pull request to add more APIs, and make reference list longer.
84-
85-
<img src="https://avatars3.githubusercontent.com/u/44989469?s=200&v=4" width="80">
86-
87-
Join us on [Gitter](https://gitter.im/sci-sharp/community)
88-
89-
Scan QR code to join TIM group:
90109

91-
![SciSharp STACK](https://raw.githubusercontent.com/SciSharp/TensorFlow.NET/master/docs/TIM.jpg)
110+
### Regen Templating
111+
Our library contains over 150,000 lines of repetitive generated code, mostly for handling different data types without hurting performance.<br>
112+
The templates can be recognized with `#if _REGEN` blocks and are powered by [Regen Templating Engine](https://github.com/Nucs/Regen).<br>
113+
Regen is a powerful external tool (Visual studio extension, [download here](https://github.com/Nucs/Regen/tree/master/releases)) that generates on demand based on a C#-like `regen-lang`.

0 commit comments

Comments
 (0)