Merge pull request #45 from Mojo-Numerics-and-Algorithms-group/ndarray

[lib+doc+test] Implement NDArray, basic functions and routines

Author: MadAlex1997

.gitignore

@@ -0,0 +1,4 @@
+# Build directory
+/build
+/dist
+/local

CONTRIBUTING.md

@@ -5,13 +5,15 @@ Thank you for your interest in contributing to NuMojo! We appreciate your effort
 ## Style Guide
 
 Please follow the Mojo standard library style guide for all contributions. Consistency in code style helps maintain readability and ease of collaboration. Key points include:
+
 - Use clear, descriptive names for variables and functions.
 - Write concise, well-documented code.
 - Adhere to formatting conventions for indentation, spacing, and line breaks.
 
 ## Pull Requests
 
 When submitting pull requests:
+
 - Ensure they are small but complete. A pull request should introduce at least a minimally viable version of the feature you are adding.
 - Include tests for your contributions where applicable.
 - Provide a clear and concise description of what your pull request accomplishes.
@@ -23,31 +25,39 @@ If you have an idea or want to work on something, go ahead and do it! You don’
 ## Directory Structure
 
 Organize your additions into the appropriate submodule or file, if one does not exist feel free to make it and we can figure out where it goes during the pull request checks. This helps keep the project structured and maintainable. For example:
+
 - If you’re adding a statistics function, place it in the `stats` submodule.
-   - If a stats module does not yet exist put the code in a directory called stats in a file with a name that describes the sub disipline of statistics the code enables, along with a `__init__.mojo`
-   - For a kernel density estimation function, add it to the `kde.mojo` file within the `stats` directory.
+  - If a stats module does not yet exist put the code in a directory called stats in a file with a name that describes the sub disipline of statistics the code enables, along with a `__init__.mojo`
+  - For a kernel density estimation function, add it to the `kde.mojo` file within the `stats` directory.
 
 Following this structure ensures that similar functionalities are grouped together, making the codebase easier to navigate.
 
 ## Contribution Process
 
 1. **Fork the Repository**: Create a personal fork of the repository on GitHub.
 2. **Clone Your Fork**: Clone your forked repository to your local machine.
+
    ```sh
    git clone https://github.com/your-username/numojo.git
    ```
+
 3. **Create a Branch**: Create a new branch for your feature or bugfix.
+
    ```sh
    git checkout -b feature-name
    ```
+
 4. **Make Your Changes**: Implement your changes in your branch.
 5. **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.
+
    ```sh
    git push origin feature-name
    ```
-7. **Submit a Pull Request**: Open a pull request to the `main` branch of the original repository.
 
+7. **Submit a Pull Request**: Open a pull request to the `main` branch of the original repository.

README.MD

@@ -1,65 +1,119 @@
-<br/>
-<p align="center">
-<!-- If we add a logo in future -->
-  <!-- <a href=""> 
-    <img src="" alt="Logo" width="200" height="200">
-  </a> -->
-
-  <h1 align="center">NuMojo</h1>
+<a name="readme-top"></a>
+<!-- add these later -->
+<!-- [![MIT License][license-shield]][] -->
+
+<div align="center">
+  <a href="">
+    <img src="./assets/numojo_logo.png" alt="Logo" width="350" height="350">
+  </a>
+
+  <h1 align="center" style="font-size: 3em; color: white; font-family: 'Avenir'; text-shadow: 1px 1px orange;">NuMojo</h1>
+
   <p align="center">
-    NuMojo is a library for numerical computing in Mojo 🔥 similar to numpy in Python.
+    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 />
+    <!-- <br /> -->
+    <!-- <a href="">View Demo</a>
+    ·
+    <a href="">Report Bug</a>
+    ·
+    <a href="">Request Feature</a> -->
   </p>
-</p>
+</div>
+
+<details>
+  <summary>Table of Contents</summary>
+  <ol>
+    <li>
+      <a href="#about-the-project">About The Project</a>
+      <ul>
+        <li><a href="#what-numojo-is"> What NuMojo is </a></li>
+        <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="#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>
+  </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 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 tensor 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 tensor 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
 
-## What NuMojo is not
+### 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 check [here](Roadmap.md)
+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/Tensor Algebra
-    * Native array types
-    * Vectorized, Parallelized math operations
-    * Array manipulation - vstack, slicing, concat etc. 
+
+* Linear Algebra
+  * Native n-dimensional array types
+  * Vectorized, Parallelized math operations
+  * Array manipulation - vstack, slicing, concat etc.
 * Calculus
-    * Integration
-    * Derivates
+  * Integration & Derivatives etc
 * Optimizers
 * Function approximators
+* Sorting
 
 ## Usage
 
-For now
+An example goes as follows.
 
 ```mojo
-import numojo
-from tensor import Tensor
-def main():
-    var tens = Tensor[DType.float32](10,10)
-    tens=tens+numojo.pi/2
-    print(numojo.sin[DType.float32](tens))
+import numojo as nm
+
+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)
+
+    # Print AB
+    print(nm.linalg.matmul_parallelized(A, B))
 ```
 
-Please find all the available functions [here](Features.md)
+Please find all the available functions [here](features.md)
 
 ## How to install
 
 Clone the repository and build
 
+## Contributing
+
+Any contributions you make are **greatly appreciated**. For more details and guidelines on contributions, please check [here](CONTRIBUTING.md)
+
 ## Warnings
 
 This library is still very much a work in progress and may change at any time. Also, the standard tensor has many rough edges.
 
+## License
+
+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.
+
 ## Acknowledgements
 
-* Built in native [Mojo](https://github.com/modularml/mojo) 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)

Roadmap.md

@@ -4,24 +4,27 @@ Overall the goal is to make a powerful and broad featured library for numerical
 
 With that in mind NuMojo as a project is in an early stage of development. If you notice a missing feature either build it and make a pull request or make a feature request.
 
-### TASKS
+## TASKS
+
 * Implement tensor version all SIMDable standard library math functions (mostly done waiting on std lib [issue 2492](https://github.com/modularml/mojo/issues/2492))
 * Build statistics functions
 * Build optimizers (newton raphson, bisection,etc)
 * Build function approximators
 
-## N Dimensional Arrays
+## N-dimensional Arrays
+
 Now that Modular has decided to no longer support Tensor and to open source and deprecate it NuMojo intends to take Tensor and Make it our own Once they do.
 
 Which means that we will be trying to add many of the features from numpy.array that tensor currently lacks, while not sacrificing performance.
 
 ## Notional organization of functions and features
+
 * Most common functions at top level like in numpy (trig, basic stats, masking, querying, and mapping)
 * Other features should be organized either by type of math or intended utilization
-    * Statistics probably merits its own sub module
-    * Regression could either be a submodule of statistics or its own module
-    * kernel density estimators almost certainly should be part of the statistics sub module
-    * It is tempting to make a algebra, calculus and trig submodules however that may end up being confusing as those topics include so many things, it may be better to organize what would be there into functional applications instead
-    * An Ordinary differential equations submodule would include solvers and utilities
-    * The optimizer sub module could mirror scipy.optimize but minimally should include all of those functions
+  * Statistics probably merits its own sub module
+  * Regression could either be a submodule of statistics or its own module
+  * kernel density estimators almost certainly should be part of the statistics sub module
+  * It is tempting to make a algebra, calculus and trig submodules however that may end up being confusing as those topics include so many things, it may be better to organize what would be there into functional applications instead
+  * An Ordinary differential equations submodule would include solvers and utilities
+  * The optimizer sub module could mirror scipy.optimize but minimally should include all of those functions
 * There will need to be discussions and bike shedding about both organization of the library and what does and doesn't belong.