[release] Merge pre-0.5 branch to main branch for release (#197)

Merge pre-0.5 branch to main branch for release of V0.5.

See `docs/changelog.md` for differences.

Author: forfudan

.gitattributes

@@ -0,0 +1,4 @@
+docs/readthedocs/docs.json -diff -merge -text
+docs/readthedocs/docs.json linguist-generated=true
+docs/readthedocs/docs/autodocs/*.md -diff -merge -text
+docs/readthedocs/docs/autodocs/*.md linguist-generated=true

.github/workflows/run_tests.yaml

@@ -13,7 +13,8 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        os: ["ubuntu-22.04", "macos-14"]
+        # os: ["ubuntu-22.04", "macos-14"]
+        os: ["ubuntu-22.04"]
 
     runs-on: ${{ matrix.os }}
     timeout-minutes: 30

.gitignore

@@ -2,13 +2,13 @@
 /build
 /dist
 /local
-/.vscode
-.DS_Store
-*.html
-*.css
-*.py
 *.egg-info
-*.pyc
+
+# VSCode files
+/.vscode
+
+# MacOs Desktop Service file
+*.DS_Store
 
 # magic environments
 .magic
@@ -17,10 +17,20 @@
 .pixi
 /venv
 
+
+# Irrelevant files
+*.html
+*.css
+*.py
+*.pyc
+
 # Miscellaneous files
 mojo
 numojo.mojopkg
 bench.mojo
 test_ndarray.ipynb
 test.mojo
-tempCodeRunnerFile.mojo
+tempCodeRunnerFile.mojo
+
+# Auto docs
+docs/readthedocs/docs.json

.pre-commit-config.yaml

@@ -6,4 +6,10 @@ repos:
         entry: magic run mojo format
         language: system
         files: '\.(mojo|🔥|py)$'
-        stages: [pre-commit]
+        stages: [pre-commit]
+      # - id: autodoc
+      #   name: mautodoc
+      #   entry: magic run doc_pages
+      #   language: system
+      #   files: '\.(mojo|🔥|py)$'
+      #   stages: [pre-commit]

.readthedocs.yaml

@@ -0,0 +1,26 @@
+
+
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version, and other tools you might need
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+# Build documentation with Mkdocs
+mkdocs:
+   configuration: docs/readthedocs/mkdocs.yml
+
+# Optionally, but recommended,
+# declare the Python requirements required to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+   - requirements: docs/readthedocs/.requirements.txt
+        
+

README.MD

@@ -4,9 +4,7 @@
 
 NuMojo is a library for numerical computing in Mojo 🔥 similar to NumPy, SciPy in Python.
 
-**[Explore the docs»](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo-Examples-and-Benchmarks/blob/main/docs/README.md)**   **[Changelog»](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/blob/main/docs/changelog.md)**   **[Check out our Discord»](https://discord.com/channels/1149778565756366939/1149778566603620455)**
-
-**[中文·简»](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/blob/main/docs/readme_zhs.md)**   **[中文·繁»](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/blob/main/docs/readme_zht.md)**   **[日本語»](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/blob/main/docs/readme_jp.md)**
+**[Explore the docs»](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo-Examples-and-Benchmarks/blob/main/docs/README.md)**  |  **[Changelog»](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/blob/main/docs/changelog.md)**  |  **[Check out our Discord»](https://discord.gg/NcnSH5n26F)**
 
 **Table of Contents**
 
@@ -22,65 +20,47 @@ NuMojo is a library for numerical computing in Mojo 🔥 similar to NumPy, SciPy
 
 ## About the project
 
-***What NuMojo is***
+NuMojo aims to encompass the extensive numerics capabilities found in Python packages such as NumPy, SciPy, and Scikit-learn.
 
-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.
+***What NuMojo is***
 
-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
+We seek to harness the full potential of Mojo, including vectorization, parallelization, and GPU acceleration (when available). Currently, NuMojo extends most (if not all) standard library math functions to support array inputs.
 
-***What NuMojo is not***
+Our vision for NuMojo is to serve as an essential building block for other Mojo packages needing fast math operations, without the additional weight of a machine learning back-propagation system.
 
-NuMojo is not a machine learning library, it will never include back-propagation in the base library.
+***What NuMojo is not***
 
-## Goals and features
+NuMojo is not a machine learning library and will never include back-propagation as part of the base library.
 
-Our main goal is to implement a fast, comprehensive numerics library in Mojo.
+## Features and goals
 
-Following are some brief long-term goals. Some of them have already been implemented or partially implemented.
+Our primary objective is to develop a fast, comprehensive numerics library in Mojo. Below are some features and long-term goals. Some have already been implemented, either fully or partially.
 
 Core data types:
 
 - Native n-dimensional array (`numojo.core.ndarray.NDArray`).
-- Native 2-dimensional array, i.e., matrix (`numojo.mat.matrix.Matrix`).
+- Native 2-dimensional array, i.e., matrix (`numojo.core.matrix.Matrix`).
+- Native n-dimensional complex array (`numojo.core.complex_ndarray.ComplexNDArray`)
 - 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
+- etc...
 
 Please find all the available functions and objects [here](docs/features.md).
 
@@ -97,8 +77,8 @@ from numojo.prelude import *
 
 fn main() raises:
     # Generate two 1000x1000 matrices with random float64 values
-    var A = nm.random.randn(shape=Shape(1000, 1000))
-    var B = nm.random.randn(shape=Shape(1000, 1000))
+    var A = nm.random.randn(Shape(1000, 1000))
+    var B = nm.random.randn(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]]")
@@ -116,26 +96,27 @@ fn main() raises:
     var A_slice = A[1:3, 4:19]
 
     # Get scalar from array
-    var A_item = A[Idx(291, 141)]
+    var A_item = A[item(291, 141)]
+    var A_item_2 = A.item(291, 141)
 ```
 
 An example of matrix (`Matrix` type) goes as follows.
 
 ```mojo
-from numojo import mat
+from numojo import Matrix
 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))
+    var A = Matrix.rand(shape=(1000, 1000))
+    var B = Matrix.rand(shape=(1000, 1000))
 
     # Generate 1000x1 matrix (column vector) with random float64 values
-    var C = mat.rand(shape=(1000, 1))
+    var C = Matrix.rand(shape=(1000, 1))
 
     # Generate a 4x3 matrix from string representation
-    var F = mat.fromstring[i8](
+    var F = Matrix.fromstring[i8](
         "[[12,11,10],[9,8,7],[6,5,4],[3,2,1]]", shape=(4, 3)
     )
 
@@ -150,12 +131,12 @@ fn main() raises:
     print(C[::-1, :])
 
     # Sort and argsort along axis
-    print(mat.sort(A, axis=1))
-    print(mat.argsort(A, axis=0))
+    print(nm.sort(A, axis=1))
+    print(nm.argsort(A, axis=0))
 
     # Sum the matrix
-    print(mat.sum(B))
-    print(mat.sum(B, axis=1))
+    print(nm.sum(B))
+    print(nm.sum(B, axis=1))
 
     # Matrix multiplication
     print(A @ B)
@@ -164,27 +145,74 @@ fn main() raises:
     print(A.inv())
 
     # Solve linear algebra
-    print(mat.solve(A, B))
+    print(nm.solve(A, B))
 
     # Least square
-    print(mat.lstsq(A, C))
+    print(nm.lstsq(A, C))
+```
+
+An example of ComplexNDArray is as follows,
+
+```mojo
+import numojo as nm
+from numojo.prelude import *
+
+
+fn main() raises:
+    # Create a complexscalar 5 + 5j
+    var complexscalar = ComplexSIMD[cf32](re=5, im=5) 
+    # Create complex array filled with (5 + 5j)
+    var A = nm.full[cf32](Shape(1000, 1000), fill_value=complexscalar)
+    # Create complex array filled with (1 + 1j)
+    var B = nm.ones[cf32](Shape(1000, 1000))
+
+    # Print array
+    print(A)
+
+    # Array slicing
+    var A_slice = A[1:3, 4:19]
+
+    # Array multiplication
+    var C = A * B
+
+    # Get scalar from array
+    var A_item = A[item(291, 141)]
+    # Set an element of the array
+    A[item(291, 141)] = complexscalar
 ```
 
 ## How to install
 
-There are two approach to install and use the Numojo package.
+There are three approach to install and use the Numojo package.
+
+### Use magic CLI
+
+You can use the following command in the terminal to install `numojo`.
+
+```console
+magic add numojo 
+```
+
+### Add in toml file
+
+You can add `numojo` in the dependencies section of your toml file.
+
+```toml
+[dependencies]
+numojo = "==0.5"
+```
 
 ### Build package
 
-This approach invovles building a standalone package file `mojopkg`.
+This approach involves building a standalone package file `mojopkg`.
 
 1. Clone the repository.
-2. Build the package using `mojo package numojo`
-3. Move the numojo.mojopkg into the directory containing the your code.
+2. Build the package using `magic run package`.
+3. Move the `numojo.mojopkg` into the directory containing the your code.
 
 ### 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:
+This approach does not require building a package file. Instead, when you compile your code, you can include the path of NuMojo repository with the following command:
 
 ```console
 mojo run -I "../NuMojo" example.mojo
@@ -213,6 +241,8 @@ This library is still very much a work in progress and may change at any time.
 
 Distributed under the Apache 2.0 License with LLVM Exceptions. See [LICENSE](https://github.com/Mojo-Numerics-and-Algorithms-group/NuMojo/blob/main/LICENSE) and the LLVM [License](https://llvm.org/LICENSE.txt) for more information.
 
+This project includes code from [Mojo Standard Library](https://github.com/modularml/mojo), licensed under the Apache License v2.0 with LLVM Exceptions (see the LLVM [License](https://llvm.org/LICENSE.txt)). MAX and Mojo usage and distribution are licensed under the [MAX & Mojo Community License](https://www.modular.com/legal/max-mojo-license).
+
 ## Acknowledgements
 
 Built in native [Mojo](https://github.com/modularml/mojo) which was created by [Modular](https://github.com/modularml).