Merge pull request #125 from Mojo-Numerics-and-Algorithms-group/exper…

…imental

V0.3 Update

.github/workflows/run_tests.yaml

@@ -13,7 +13,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: ["ubuntu-latest", "macos-14"]
+        os: ["ubuntu-22.04", "macos-14"]
 
     runs-on: ${{ matrix.os }}
     timeout-minutes: 30
@@ -28,26 +28,27 @@ 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: Activate virtualenv
         run: |
           python3 -m venv $HOME/venv/
           . $HOME/venv/bin/activate
           echo PATH=$PATH >> $GITHUB_ENV
 
-      - name: Install Mojo
+      - name: Install packages
         run: |
-          modular install mojo
-
-      - name: Set path Mojo
-        run: |
-          echo "MODULAR_HOME=$HOME/.modular" >> $GITHUB_ENV
-          echo "$HOME/.modular/pkg/packages.modular.com_mojo/bin"  >> $GITHUB_PATH
+          pip install "numpy"
 
       - name: Run tests
         run: |
-          pip install "numpy<2.0"
-          mojo test tests -I .
+          magic install
+          magic run mojo test tests -I .

.github/workflows/test_pre_commit.yaml

@@ -11,7 +11,7 @@ permissions:
 
 jobs:
   lint:
-    runs-on: "ubuntu-latest"
+    runs-on: "ubuntu-22.04"
     timeout-minutes: 30
 
     defaults:

.gitignore

@@ -9,7 +9,15 @@
 *.py
 mojo
 numojo.mojopkg
-.gitignore
 bench.mojo
 test_ndarray.ipynb
-/venv
+/venv# pixi environments
+.pixi
+*.egg-info
+*.pyc
+
+# magic environments
+.magic
+
+.gitattributes
+.gitignore

CONTRIBUTING.md

@@ -10,7 +10,7 @@ Please follow the Mojo standard library style guide for all contributions. Consi
 - Write concise, well-documented code.
 - Adhere to formatting conventions for indentation, spacing, and line breaks.
 
-Additionally refer to `style guide.md` for docstring and nameing conventions.
+Additionally refer to `style guide.md` for docstring and naming conventions.
 
 ## Pull Requests
 
@@ -50,16 +50,20 @@ Following this structure ensures that similar functionalities are grouped togeth
    ```
 
 4. **Make Your Changes**: Implement your changes in your branch.
-5. **Commit Your Changes**: Commit your changes with a clear and descriptive commit message.
+5. **Run Tests**: NuMojo now uses the `Magic` package manager by Modular. To ensure that all unit tests pass, the NuMojo module packages correctly, and the .mojo files are properly formatted, run the following command:
+   ```sh
+   magic run final
+   ```
+6. **Commit Your Changes**: Commit your changes with a clear and descriptive commit message.
 
    ```sh
    git commit -m "Add feature XYZ"
    ```
 
-6. **Push Your Changes**: Push your branch to your fork on GitHub.
+7. **Push Your Changes**: Push your branch to your fork on GitHub.
 
    ```sh
    git push origin feature-name
    ```
 
-7. **Submit a Pull Request**: Open a pull request to the `main` branch of the original repository.
+8. **Submit a Pull Request**: Open a pull request to the `main` branch of the original repository.

README.MD

@@ -13,10 +13,19 @@
     NuMojo is a library for numerical computing in Mojo 🔥 similar to NumPy, SciPy in Python.
     <br />
     <!-- when we create docs -->
-    <a href="https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo-Examples-and-Benchmarks/blob/main/docs/README.md"><strong>Explore the docs» </strong></a>
-    <br>
-    <a href="https://discord.com/channels/1149778565756366939/1149778566603620455"><strong>Check out our Discord» </strong></a>
+    <div style="font-family: 'Arial'; border: 1px solid black; padding: 5px;">
+        <a href="https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo-Examples-and-Benchmarks/blob/main/docs/README.md"><strong>Explore the docs» </strong></a> &nbsp; &nbsp;
+        <a href="./docs/changelog.md"><strong>Changelog» </strong></a> &nbsp; &nbsp;
+        <a href="https://discord.com/channels/1149778565756366939/1149778566603620455" ><strong>Check out our Discord» </strong></a>
+    </div>
     <br />
+    <div style="font-family: 'Arial'; border: 1px solid black; padding: 5px;">
+        <a href="./docs/readme_zhs.md"><strong>中文·简» </strong></a> &nbsp; 
+        <a href="./docs/readme_zht.md"><strong>中文·繁» </strong></a> &nbsp;
+        <a href="./docs/readme_jp.md"><strong>日本語» </strong></a>
+    </div>
+    <!-- <a href="./docs/readme_kr.md"><strong>한국어 문서» </strong></a> -->
+    <!-- <br /> -->
     <!-- <br /> -->
     <!-- <a href="">View Demo</a>
     ·
@@ -55,10 +64,9 @@
 
 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.
 
-NuMojo intends 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
+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
 
@@ -88,14 +96,30 @@ An example 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.NDArray[nm.f64](shape=List[Int](1000,1000), random=True)
-    var B = nm.NDArray[nm.f64](1000,1000, random=True)
+    var A = nm.random.randn[f64](shape=List[Int](1000, 1000))
+    var B = nm.random.randn[f64](shape=List[Int](1000, 1000))
+
+    # Generate a 3x2 matrix from string representation
+    var X = nm.fromstring[f32]("[[1.1, -0.32, 1], [0.1, -3, 2.124]]")
+
+    # Print array
+    print(A)
+
+    # Array multiplication
+    var C = A @ B
+
+    # Array inversion
+    var I = nm.inv(A)
+
+    # Array slicing
+    var A_slice = A[1:3, 4:19]
 
-    # Print AB
-    print(nm.linalg.matmul_parallelized(A, B))
+    # Get scalar from array
+    var A_item = A.item(291, 141)
 ```
 
 Please find all the available functions [here](features.md)
@@ -109,10 +133,10 @@ There are two approach to install and use the Numojo package.
 This approach invovles building a standalone package file `mojopkg`.
 
 1. Clone the repository.
-1. Build the package using `mojo pacakge numojo`
-1. Move the numojo.mojopkg into the directory containing the your code.
+2. Build the package using `mojo package numojo`
+3. Move the numojo.mojopkg into the directory containing the your code.
 
-### Inlcude NuMojo's path for compiler and LSP
+### Include NuMojo's path for compiler and LSP
 
 This approach does not require buiding a package file. Instead, when you compile your code, you can include the path of NuMojo reporsitory with the following command:
 
@@ -125,11 +149,11 @@ This is more flexible as you are able to edit the NuMojo source files when testi
 In order to allow VSCode LSP to resolve the imported `numojo` package, you can:
 
 1. Go to preference page of VSCode.
-1. Got to `Mojo › Lsp: Include Dirs`
-1. Click `add item` and write the path where the Numojo repository is located, e.g. `/Users/Name/Programs/NuMojo`.
-1. Restart the Mojo LSP server.
+2. Go to `Mojo › Lsp: Include Dirs`
+3. Click `add item` and write the path where the Numojo repository is located, e.g. `/Users/Name/Programs/NuMojo`.
+4. Restart the Mojo LSP server.
 
-Now VSCode can show function hints for the Numojo pakcage!
+Now VSCode can show function hints for the Numojo package!
 
 ## Contributing
 

docs/changelog.md

@@ -0,0 +1,81 @@
+# NuMojo released changelog
+
+This is a list of RELEASED changes for the NuMojo Package.
+
+## 14/10/2024 (v0.3)
+
+### ⭐️ New
+
+- Add support for `magic` system and MAX 24.5 (PR #91 #109 by @shivasankarka).
+- Add some basic functions, e.g., `diagflat`, `tri`, `trace`, `T` (PR #91 by @shivasankarka).
+- Add a constructor which reads arrays from numpy arrays (PR #91 by @shivasankarka).
+- Add functions `solve` and `inv` for solving linear algebra `AX = Y` for `X`, finding inverse of a matrix, and conducting LU decomposition (PR #101 #104 #105 by @forFudan).
+- Add `itemset` method to fill a scalar into an `NDArray` (PR #102 by @forFudan).
+- Add `Idx` struct to represent the index of an `NDArray` (PR #118 by @shivasankarka).
+- Add NDArray initialization from numpy arrays (PR #118 by @shivasankarka).
+- Created a new `io` module with some basic functions, e.g., `format_float_scientific`, `loadtxt`, `savetxt` (PR #118 by @shivasankarka).
+
+### 🦋 Changed
+
+- Make some methods, e.g., `sort`, `flatten`, `inplace` (Issue #87 by @mmenendezg, PR #91 by @shivasankarka).
+- Modify initialization of NDArray (PR #97 by @MadAlex1997)
+- Added `Formattable` trait and fixed the `print` function (PR #108 by @shivasankarka)
+- Refine the `NDArray` initializers and array creation routines (Discussion #90, Issue #110).
+  - Remove `random` argument from `NDArray` constructors. Make random initializer a standalone functions (Issue #96 by @MadAlex1997, PR #97 by @MadAlex1997, PR #98 by @shivasankarka).
+  - Remove initializers from `String`. Make `fromstring` a standalone function (#113 by @forFudan).
+  - Add several `array` overloads for initializing `NDArray` (PR #118 by @shivasankarka).
+- Modify the behavior of `__get__` and `__set__`. Passing in a sequence of `Int` or `Slice` returns an `NDArray`. Passing in an `Idx` returns a scalar. Allow users to set a multiple items in one `NDArray` with another `NDArray`, using `__set__` (PR #118 by @shivasankarka, Discussion #70).
+
+### ❌ Removed
+
+- Removed all instances of getters and setters with `List[Int]`, `VariadicList[Int]` (PR #118 by @shivasankarka).
+
+### 🛠️ Fixed
+
+- Fix the issues in parallelization (due to Max 24.5) for some linear algebra functions, e.g, `matmul`, `solve`, `inv`, etc (PR #115 #117 by @forFudan).
+
+### 📚 Documentary and testing
+
+- Add workflows with unit tests and linting (PR #95 by @sandstromviktor).
+- Add multi-lingual support (Chinese, Japanese) for the readme file (PR #99 #120 by @forFudan, PR #100 by @shivasankarka).
+- Update the test flow file to accommodate MAX 24.5 and the `magic` system (PR #116 by @forFudan).
+
+## 17/08/2024 (V0.2)
+
+### ⭐️ New
+
+Array operations:
+
+- Introduced `diagflat()` method for creating diagonal arrays
+- Implemented most basic array creation routines
+- Implemented initializer from string `numojo.NDArray("[[1,2,3],[4,5,6]]")`
+- Enhanced `NDArray` constructor methods
+- Added boolean masking for NDArrays
+- Introduced new mathematical methods: `floordiv`, `mod`, and more
+- `__getitem__` and `__setitem__` now fully compatible with NumPy behavior
+
+Others:
+
+- Introduced Rust-like data type aliases (e.g., `DType.float64` → `f64`)
+- Implemented function overloading for core mathematical operations (add, sub, etc.)
+- Added a new differentiation module
+
+### 🦋 Changed
+
+- Improved slicing functionality to match NumPy behavior
+
+### ❌ Removed
+
+- Removed `in_dtype` and `out_dtype` parameters for simplified type handling
+
+### 📚 Documentatory and testing
+
+Documentation updates:
+
+- Expanded and updated README
+- Improved docstrings for functions
+- Added style guide and examples
+
+Testing updates:
+
+- Introduced new test files that are compatible with `mojo test`.

docs/changelog_unreleased.md

@@ -0,0 +1,17 @@
+# NuMojo UNRELEASED changelog
+
+This is a list of UNRELEASED changes (not yet merged to the nightly branch) for the NuMojo Package.
+
+When a PR is merged to the nightly branch, the items in this file will be moved to `changelog.md`.
+
+## dd/mm/yyyy (v0.3)
+
+### ⭐️ New
+
+### 🦋 Changed
+
+### ❌ Removed
+
+### 🛠️ Fixed
+
+### 📚 Documentary and testing