Merge pull request #155 from Mojo-Numerics-and-Algorithms-group/pre-0.4

NuMojo V0.4 Update

Author: shivasankarka

.github/workflows/run_tests.yaml

@@ -51,4 +51,4 @@ jobs:
       - name: Run tests
         run: |
           magic install
-          magic run mojo test tests -I .
+          magic run mojo test tests -I .

.github/workflows/test_pre_commit.yaml

@@ -24,20 +24,28 @@ jobs:
       - name: Checkout repo
         uses: actions/checkout@v4
 
-      - name: Download Modular installer
+      - name: Install magic
         run: |
-          curl -s https://get.modular.com | sh -
+          curl -ssL https://magic.modular.com/ff414efd-16ac-4bf3-8efc-50b059272ab6 | bash
+    
+      - name: Add path
+        run: |
+          echo "MODULAR_HOME=$HOME/.modular" >> $GITHUB_ENV
+          echo "$HOME/.modular/bin"  >> $GITHUB_PATH
+          echo "$HOME/.modular/pkg/packages.modular.com_mojo/bin"  >> $GITHUB_PATH
 
-      - name: Set path Mojo
+      - name: Activate virtualenv
         run: |
-          modular install mojo
-          echo "MODULAR_HOME=/home/runner/.modular" >> $GITHUB_ENV
-          echo "/home/runner/.modular/pkg/packages.modular.com_mojo/bin"  >> $GITHUB_PATH
+          python3 -m venv $HOME/venv/
+          . $HOME/venv/bin/activate
+          echo PATH=$PATH >> $GITHUB_ENV
 
       - name: Install pre-commit
         run: |
           pip install pre-commit
           pre-commit install
       
       - name: Run pre-commit
-        run: pre-commit run --all-files
+        run: | 
+          magic install
+          pre-commit run --all-files

.gitignore

@@ -7,17 +7,20 @@
 *.html
 *.css
 *.py
-mojo
-numojo.mojopkg
-bench.mojo
-test_ndarray.ipynb
-/venv# pixi environments
-.pixi
 *.egg-info
 *.pyc
 
 # magic environments
 .magic
 
-.gitattributes
-.gitignore
+# pixi environments
+.pixi
+/venv
+
+# Miscellaneous files
+mojo
+numojo.mojopkg
+bench.mojo
+test_ndarray.ipynb
+test.mojo
+tempCodeRunnerFile.mojo

.pre-commit-config.yaml

@@ -3,7 +3,7 @@ repos:
     hooks:
       - id: mojo-format
         name: mojo-format
-        entry: mojo format
+        entry: magic run mojo format
         language: system
         files: '\.(mojo|🔥|py)$'
-        stages: [commit]
+        stages: [pre-commit]

README.MD

@@ -45,63 +45,96 @@
         <li><a href="#what-numojo-is-not">What NuMojo is not</a></li>
       </ul>
     </li>
-    <a href="#goals-roadmap">Goals/Roadmap</a>
-      <ul>
-        <li><a href="#long-term-goals">Long term goals</a></li>
-      </ul>
+    <li><a href="#goals">Goals</a></li>
     <li><a href="#usage">Usage</a></li>
     <li><a href="#how-to-install">How to install</a></li>
     <li><a href="#contributing">Contributing</a></li>
     <li><a href="#warnings">Warnings</a></li>
     <li><a href="#license">License</a></li>
     <li><a href="#acknowledgments">Acknowledgments</a></li>
+    <li><a href="#Contributors">Contributors</a></li>
   </ol>
 </details>
 
 ## About the project
 
 ### What NuMojo is
 
-NuMojo intends to capture a wide swath of numerics capability present in the Python packages NumPy, SciPy and Scikit.
+NuMojo intends to capture a wide swath of numerics capability present in the Python packages NumPy, SciPy, and Scikit.
 
-NuMojo intends to try and get the most out of the capabilities of Mojo including vectorization, parallelization, and GPU acceleration(once available). Currently, NuMojo extends (most of) the standard library math functions to work on array inputs.
+NuMojo intends to try and get the most out of the capabilities of Mojo including vectorization, parallelization, and GPU acceleration (once available). Currently, NuMojo extends (most of) the standard library math functions to work on array inputs.
 
 We intend NuMojo to be a building block for other Mojo packages that need fast math under the hood without the added weight of a ML back and forward propagation system
 
 ### What NuMojo is not
 
 NuMojo is not a machine learning library, it will never include back-propagation in the base library.
 
-## Goals / Roadmap
-
-For a detailed roadmap, please refer to the [Roadmap.md](Roadmap.md) file.
-
-Our main goal is to implement a fast, comprehensive numerics library in Mojo. Following are some brief long-term goals,
-
-### Long term goals
-
-* Linear Algebra
-  * Native n-dimensional array types
-  * Vectorized, Parallelized math operations
-  * Array manipulation - vstack, slicing, concat etc.
-* Calculus
-  * Integration & Derivatives etc
-* Optimizers
-* Function approximators
-* Sorting
+## Goals and features
+
+Our main goal is to implement a fast, comprehensive numerics library in Mojo.
+
+Following are some brief long-term goals. Some of them have already been implemented or partially implemented.
+
+Core data types:
+
+- Native n-dimensional array (`numojo.core.ndarray.NDArray`).
+- Native 2-dimensional array, i.e., matrix (`numojo.mat.matrix.Matrix`).
+- Native fixed-dimension array (to be implemented when trait parameterization is available).
+
+Routines and objects:
+
+- Array creation routines (`numojo.routines.creation`)
+- Array manipulation routines (`numojo.routines.manipulation`)
+- Bit-wise operations (`numojo.routines.bitwise`)
+- Constants (`numojo.routines.constants`)
+- Input and output (`numojo.routines.io`)
+- Text files (`numojo.routines.files`)
+- Text formatting options (`numojo.routines.formatting`)
+- Linear algebra (`numojo.routines.linalg`)
+- Decompositions (`numojo.routines.decompositions`)
+- Products of matrices and vectors (`numojo.routines.products`)
+- Solving (`numojo.routines.solving`)
+- Logic functions (`numojo.routines.logic`)
+- Comparison (`numojo.routines.comparison`)
+- Array contents (`numojo.routines.contents`)
+- Truth value testing (`numojo.routines.truth`)
+- Mathematical functions (`numojo.routines.math`)
+- Arithmetic operations (`numojo.routines.arithmetic`)
+- Exponents and logarithms (`numojo.routines.exponents`)
+- Extrema finding (`numojo.routines.extrema`)
+- Floating point routines (`numojo.routines.floating`)
+- Hyperbolic functions (`numojo.routines.hyper`)
+- Indexing (`numojo.routines.indexing`)
+- Miscellaneous (`numojo.routines.misc`)
+- Rounding (`numojo.routines.rounding`)
+- Sums, products, differences (`numojo.routines.sums`, `numojo.routines.products`, `numojo.routines.differences`)
+- Trigonometric functions (`numojo.routines.trig`)
+- Random sampling (`numojo.routines.random`)
+- Sorting, searching, and counting (`numojo.routines.sorting`, `numojo.routines.searching`)
+- Statistics (`numojo.routines.statistics`)
+- Averages and variances (`numojo.routines.averages`)
+- Calculus, Integration & Derivatives etc
+- Optimizers
+- Function approximators
+
+Please find all the available functions and objects [here](docs/features.md).
+
+For a detailed roadmap, please refer to the [docs/roadmap.md](docs/roadmap.md) file.
 
 ## Usage
 
-An example goes as follows.
+An example of n-dimensional array (`NDArray` type) goes as follows.
 
 ```mojo
 import numojo as nm
 from numojo.prelude import *
 
+
 fn main() raises:
     # Generate two 1000x1000 matrices with random float64 values
-    var A = nm.random.randn[f64](shape=List[Int](1000, 1000))
-    var B = nm.random.randn[f64](shape=List[Int](1000, 1000))
+    var A = nm.random.randn(shape=Shape(1000, 1000))
+    var B = nm.random.randn(shape=Shape(1000, 1000))
 
     # Generate a 3x2 matrix from string representation
     var X = nm.fromstring[f32]("[[1.1, -0.32, 1], [0.1, -3, 2.124]]")
@@ -119,10 +152,59 @@ fn main() raises:
     var A_slice = A[1:3, 4:19]
 
     # Get scalar from array
-    var A_item = A.item(291, 141)
+    var A_item = A[Idx(291, 141)]
 ```
 
-Please find all the available functions [here](features.md)
+An example of matrix (`Matrix` type) goes as follows.
+
+```mojo
+from numojo import mat
+from numojo.prelude import *
+
+
+fn main() raises:
+    # Generate two 1000x1000 matrices with random float64 values
+    var A = mat.rand(shape=(1000, 1000))
+    var B = mat.rand(shape=(1000, 1000))
+
+    # Generate 1000x1 matrix (column vector) with random float64 values
+    var C = mat.rand(shape=(1000, 1))
+
+    # Generate a 4x3 matrix from string representation
+    var F = mat.fromstring[i8](
+        "[[12,11,10],[9,8,7],[6,5,4],[3,2,1]]", shape=(4, 3)
+    )
+
+    # Matrix slicing
+    var A_slice = A[1:3, 4:19]
+    var B_slice = B[255, 103:241:2]
+
+    # Get scalar from matrix
+    var A_item = A[291, 141]
+
+    # Flip the column vector
+    print(C[::-1, :])
+
+    # Sort and argsort along axis
+    print(mat.sort(A, axis=1))
+    print(mat.argsort(A, axis=0))
+
+    # Sum the matrix
+    print(mat.sum(B))
+    print(mat.sum(B, axis=1))
+
+    # Matrix multiplication
+    print(A @ B)
+
+    # Matrix inversion
+    print(A.inv())
+
+    # Solve linear algebra
+    print(mat.solve(A, B))
+
+    # Least square
+    print(mat.lstsq(A, C))
+```
 
 ## How to install
 
@@ -169,4 +251,10 @@ Distributed under the Apache 2.0 License with LLVM Exceptions. See [LICENSE](htt
 
 ## Acknowledgements
 
-* Built in native [Mojo](https://github.com/modularml/mojo) which was created by [Modular](https://github.com/modularml)
+Built in native [Mojo](https://github.com/modularml/mojo) which was created by [Modular](https://github.com/modularml).
+
+## Contributors
+
+<a href="https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=Mojo-Numerics-and-Algorithms-group/NuMojo" />
+</a>

docs/changelog.md

@@ -2,6 +2,58 @@
 
 This is a list of RELEASED changes for the NuMojo Package.
 
+## 22/12/2024 (v0.4)
+
+### ⭐️ New
+
+- Implement a static-sized 2D Array type (`Matrix` type) in `numojo.mat` sub-package. `Matrix` is a special case of `NDArray` but has been optimized since the number of dimensions is known at the compile time. It is useful when users only want to work with 2-dimensional arrays. The indexing and slicing is also more consistent with `numpy` ([PR #138](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/138), [PR #141](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/142), [PR #141](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/142)). It provides:
+  - `Matrix` type (2D array) with basic dunder methods and core methods.
+  - Function to construct `Matrix` from other data objects, e.g., `List`, `NDArray`, `String`, and `numpy` array.
+  - Arithmetic functions for item-wise calculation and broadcasting.
+  - Linear algebra: matrix mutiplication, decomposition, inverse of matrix, solve of linear system, Ordinary Least Square, etc.
+  - Auxilliary types, e.g., `_MatrixIter`.
+- Implement more the array creation routines from numpy and expand the NuMojo array creation functionality ([PR #137](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/137)).
+- Add `convolve2d` and in the `science.signal` module ([PR #135](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/135)).
+- Add more detailed error messages for `NDArray` type ([PR #140](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/140)).
+
+### 🦋 Changed
+
+- Adapt the code to [the latest update of Mojo to V24.6](https://docs.modular.com/mojo/changelog/) ([PR #148](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/148)).
+  - `Slice.step` is now returning `Optional[int]`. Thus, it is fixed by using `Slice.step.else_to(1)`.
+  - `Formattable` is now renamed to `Writable` (same applies to `write_to` and `string.write`).
+  - `width` is now inferred from the SIMD's width. So this parameter must be removed when we call `UnSafePointer`'s `load` and `store` methods. Due to this, the function `fill_pointer`, which fill in a width of array with a scale, no longer work. It is replaced by copying with loop.
+  - `Lifetime` is renamed as `Origin` (same applies to the function `__origin_of`).
+  - `inout` is renamed as `mut`.
+- Rename the data buffer from `data` to `_buf` ([PR #136](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/136), [PR #137](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/137))
+- To make `matmul` flexible for different shapes of input arrays ([PR #137](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/137)).
+- Change the way to get the shape of the array: `array.shape` returns the shape of array as `NDArrayShape` ([PR #137](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/137)).
+- The array creation functions are unified in such a way ([PR #139](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/139)).
+  - `NDAarray.__init__()` reads in shape information and initializes an empty ndarray.
+  - All other creation routines are implemented by the functions in the `array_creation_routine` module. For example, to create an array with filled value, the function `full` should be used. To create an array from a list, the function `array` should be used.
+- Re-organize the functions and modules by topic, so that it is more consistent with `numpy` ([Issue 144](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/issues/144), [PR #146](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/146)).
+- Rename some attributes of `NDArray` and make `size` an attribute instead of a method ([PR #145](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/145)).
+- Completely remove `import *` in __init__ files to fix namespace leak ([PR #151](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/151)).
+- Update function `sum` ([PR #149](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/149)).
+- `transpose` now allows arbitrary dimensions and permutations of axes ([PR #152](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/152)).
+- Change buffer type of `NDArrayShape` and `NDArrayStrides` to `Int` ([PR #153](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/153)).
+- `sort` now allows sorting by any axis for high dimensional arrays ([PR #154](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/154)).
+
+### ❌ Removed
+
+- Temporarily removed negative indexing support in slices since it causes error. Will add just feature in later updates ([PR #133](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/133)).
+- Remove `inout` before `self` for `NDArray.__getitem__` ([PR #137](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/137)).
+
+### 🛠️ Fixed
+
+- Fixed and rewrote the `adjust_slice` function that was causing errors ([PR #133](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/133)).
+- There is an error in fromstring that the negative signs are not read. It is fixed. Now a valid numeric should start with a digit, a dot, or a hyhen ([PR #134](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/134)).
+
+### 📚 Documentary and testing
+
+- Added test for slicing in getters. Complete tests for setters will be added later. This is due to python interop limitation ([PR #133](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/133)).
+- Move documents from root docs. Delete unused files ([PR #147](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/147)).
+- Update the readme.md and features.md to reflect current progress ([PR #150](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/pull/150)).
+
 ## 19/10/2024 (v0.3.1)
 
 ### 🛠️ Fixed