You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+42-7Lines changed: 42 additions & 7 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -38,7 +38,16 @@ In my experience, calling `numpy` from C# is about 4 times slower than calling i
38
38
39
39
All of `numpy` is centered around the `ndarray` class which allows you to pass a huge chunk of data into the `C` routines and let them execute all kinds of operations on the elements efficiently without the need for looping over the data. So if you are manipulating arrays or matrices with thousands or hundreds of thousands of elements, the call overhead will be neglegible.
40
40
41
-
The most performance sensitive aspect is creating an `NDarray` from a `C#` array, since the data has to be moved from the `CLR` into the `Python` interpreter. `pythonnet` does not optimize for passing large arrays from `C#` to `Python` but we still found a way to do that very efficiently. When creating an array with `np.array( ... )` we internally use `Marshal.Copy` to copy the entiry `C#`-array's memory into the `numpy`-array's storage. And to efficiently retrieve computation results from `numpy` there is a method called `GetData<T>` which will copy the data back to `C#` in the same way.
41
+
The most performance sensitive aspect is creating an `NDarray` from a `C#` array, since the data has to be moved from the `CLR` into the `Python` interpreter. `pythonnet` does not optimize for passing large arrays from `C#` to `Python` but we still found a way to do that very efficiently. When creating an array with `np.array( ... )` we internally use `Marshal.Copy` to copy the entiry `C#`-array's memory into the `numpy`-array's storage. And to efficiently retrieve computation results from `numpy` there is a method called `GetData<T>` which will copy the data back to `C#` in the same way:
42
+
43
+
```csharp
44
+
// create a 2D-shaped NDarray<int> from an int[]
45
+
varm=np.array(newint[] {1, 2, 3, 4});
46
+
// calculate the cosine of each element
47
+
varresult=np.cos(m);
48
+
// get the floating point data of the result NDarray back to C#
@@ -59,18 +68,44 @@ The SciSharp team is also developing a pure C# port of NumPy called [NumSharp](h
59
68
60
69
The vast majority of Numpy.NET's code is generated using [CodeMinion](https://github.com/SciSharp/CodeMinion) by parsing the documentation at [docs.scipy.org/doc/numpy/](docs.scipy.org/doc/numpy/). This allowed us to wrap most of the `numpy`-API in just two weeks. The rest of the API can be completed in a few more weeks, especially if there is popular demand.
61
70
62
-
TODO: information about completed API categories
71
+
### Competion status
72
+
73
+
TODO: information about completion status API categories
74
+
75
+
### Auto-generated Unit-Tests
76
+
77
+
We even generated hundreds of unit tests from all the examples found on the NumPy documentation. Most of them don't compile without fixing them because we did not go so far as to employ a Python-To-C# converter. Instead, the tests are set up with a commented out Python-console log that shows what the expected results are and a commented out block of somewhat C#-ified Python code that doesn't compile without manual editing.
78
+
79
+
Another reason why this process can not be totally automated is the fact that NumPy obviously changed the way how arrays are printed out on the console after most of the examples where written (they removed extra spaces between the elements). This means that oftentimes the results needs to be reformatted manually for the test to pass.
80
+
81
+
Getting more unit tests to run is very easy though, and a good portion have already been processed to show that Numpy.NET really works. If you are interested in working on the test suite, please join in and help. You'll learn a lot about NumPy on the way.
63
82
64
83
## Documentation
65
84
66
85
Since we have taken great care to make Numpy.NET as similar to NumPy itself, you can, for the most part, rely on the official [NumPy manual](https://docs.scipy.org/doc/numpy/).
67
86
87
+
### Creating multi-dimensional NDarrays from C# arrays
88
+
89
+
Creating an `NDarray` from data is easy. Just pass the C# array into `np.array(...)`. You can pass 1D, 2D and 3D C# arrays into it.
90
+
91
+
```csharp
92
+
// create a 2D NDarray
93
+
varm=np.array(newint[,] {{1, 2}, {3, 4}}); // the NDarray represents a 2 by 2 matrix
94
+
```
95
+
96
+
Another even more efficient way (saves one array copy operation) is to pass the data as a one-dimensional array and just reshape the NDarray.
97
+
98
+
```csharp
99
+
// create a 2D NDarray
100
+
varm=np.array(newint[] {1, 2, 3, 4}).reshape(2,2); // the reshaped NDarray represents a 2 by 2 matrix
101
+
```
102
+
68
103
### Differences between Numpy.NET and NumPy
69
104
70
-
As you have seen in the example above, apart from language syntax and idioms, usage of Numpy.NET is almost identical to Python. However, there are some differences which can not be resolved due to lack of language support in C#.
105
+
As you have seen, apart from language syntax and idioms, usage of Numpy.NET is almost identical to Python. However, due to lack of language support in C#, there are some differences which you should be aware of.
71
106
72
-
#### Slice syntax
73
-
C# doesn't support the colon syntax in indexers i.e. `[:, 1]`. However, by allowing to pass a string with *Python slicing syntax*we circumvented it, i.e. `[":, 1"]`. Only the `...` operator is not yet implemented, as it is not very important.
107
+
#### Array slicing syntax
108
+
You can access parts of an NDarray using [array slicing](https://docs.scipy.org/doc/numpy/reference/arrays.indexing.html#arrays-indexing). C# doesn't support the colon syntax in indexers i.e. `a[:, 1]`. However, by allowing to pass a string we circumvented this limitation, i.e. `a[":, 1"]`. Only the `...` operator is not yet implemented, as it is not very important.
74
109
75
110
#### Variable argument lists
76
111
Some NumPy functions like `reshape` allow variable argument lists at the beginning of the parameter list. This of course is not allowed in C#, which supports a variable argument list only as the last parameter. In case of `reshape` the solution was to replace the variable argument list that specifies the dimensions of the reshaped array by a `Shape` object which takes a variable list of dimensions in its constructor:
Python has native support of complex numbers, something the C# language is lacking as well. Converting complex results to and from NumPy is not implemented at all.
162
+
Python has native support of complex numbers, something the C# language is lacking as well. Converting complex results to and from NumPy is not implemented at all (yet). Please step forward if you want to work on this.
128
163
129
164
## Versions and Compatibility
130
165
131
166
Currently, Numpy.NET is targeting .NET Standard (on Windows) and packages the following binaries:
To make Numpy.NET support Linux a separate version of [Python.Included](https://github.com/henon/Python.Included) packaging linux binaries of Python needs to be made and a version of Numpy.NET that packages a linux-compatible NumPy wheel.
170
+
To make Numpy.NET support Linux a separate version of [Python.Included](https://github.com/henon/Python.Included) packaging linux binaries of Python needs to be made and a version of Numpy.NET that packages a linux-compatible NumPy wheel. If you are interested, you may work on this issue.
0 commit comments