{"id":15704398,"url":"https://github.com/siddeshsambasivam/matterix","last_synced_at":"2025-07-11T17:43:31.124Z","repository":{"id":37671629,"uuid":"282178209","full_name":"SiddeshSambasivam/MatterIx","owner":"SiddeshSambasivam","description":"A deep learning framework built to understand the fundamental concepts such as autodiff, optimizers, loss functions from a first principle basis.","archived":false,"fork":false,"pushed_at":"2023-02-08T01:23:35.000Z","size":183,"stargazers_count":9,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-05-06T16:48:03.481Z","etag":null,"topics":["deep-learning-framework"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/MatterIx/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SiddeshSambasivam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-07-24T09:29:15.000Z","updated_at":"2022-07-19T06:39:05.000Z","dependencies_parsed_at":"2024-10-23T02:15:18.656Z","dependency_job_id":null,"html_url":"https://github.com/SiddeshSambasivam/MatterIx","commit_stats":{"total_commits":144,"total_committers":3,"mean_commits":48.0,"dds":0.02083333333333337,"last_synced_commit":"d4b65a34cc786330cfc5e91abca0e9f0aae099c3"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiddeshSambasivam%2FMatterIx","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiddeshSambasivam%2FMatterIx/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiddeshSambasivam%2FMatterIx/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SiddeshSambasivam%2FMatterIx/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SiddeshSambasivam","download_url":"https://codeload.github.com/SiddeshSambasivam/MatterIx/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253750337,"owners_count":21958285,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["deep-learning-framework"],"created_at":"2024-10-03T20:11:43.428Z","updated_at":"2025-05-12T13:46:56.517Z","avatar_url":"https://github.com/SiddeshSambasivam.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/SiddeshSambasivam/MatterIx/master/assets/Logo.png?token=AKHFPP5DPO3RQLN3NBTHJGDA4DBL6\" /\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003cimg alt=\"PyPI\" src=\"https://img.shields.io/pypi/v/Matterix\"\u003e\n    \u003cimg alt=\"PyPI - License\" src=\"https://img.shields.io/pypi/l/Matterix\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca style=\"padding: 0 10px;\" target=\"#\" href=\"#ins\"\u003eInstallation\u003c/a\u003e • \n  \u003ca style=\"padding: 0 10px;\" target=\"#\" href=\"#releases\"\u003eReleases\u003c/a\u003e • \n  \u003ca style=\"padding: 0 10px;\" href=\"#contributing\"\u003eContributing\u003c/a\u003e • \n  \u003ca style=\"padding: 0 10px;\" href=\"#features\"\u003eFeatures\u003c/a\u003e\n\u003c/p\u003e\n\nMatterIx is a simple deep learning framework built to understand the fundamental concepts of \u003cb\u003eautodiff\u003c/b\u003e, \u003cb\u003eoptimizers\u003c/b\u003e and \u003cb\u003eloss functions\u003c/b\u003e from a first principle basis. It provide features such as automatic differentiation (autodiff), optimizers, loss functions and basic modules to create your own neural networks.\n\n\u003ctable align=\"center\" width=\"600px\"\u003e\n \u003ctr\u003e\n    \u003cth\u003eFeature\u003c/th\u003e\n    \u003cth\u003eDescription\u003c/th\u003e\n    \u003cth\u003eFunction/Specs\u003c/th\u003e\n \u003c/tr\u003e\n \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"#autodiff\"\u003eAutodiff\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eAllows to compute gradients for tensors.\u003c/td\u003e\n    \u003ctd\u003eFirst-order derivative\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"#loss\"\u003eLoss functions\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eProvides a metric to evaluate the model or function\u003c/td\u003e\n    \u003ctd\u003eMean squared error (MSE), Root mean squared error (RMSE)\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"#opt\"\u003eOptimizers\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eUpdates the parameters of a model for a specific optimization problem\u003c/td\u003e\n    \u003ctd\u003eStochastic gradient descent (SGD)\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"#act\"\u003eActivation functions\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eIt basically decides whether a neuron should be activated or not. Activation function is a non-linear transformation which applied to the output before passing it to the next layer\u003c/td\u003e\n    \u003ctd\u003eSigmoid, tanh, ReLU\u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\u003ca href=\"#mod\"\u003eModule\u003c/a\u003e\u003c/td\u003e\n    \u003ctd\u003eServes as a base class to design your own neural networks\u003c/td\u003e\n    \u003ctd\u003eNIL\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n\u003cbr/\u003e\n\nThe \u003cb\u003ecore value of matterix\u003c/b\u003e is that it is a distilled version of pytorch so it is easier to understand what is happening under the hood.\n\n\u003ch3 style=\"font-weight:bold\" id=\"#ins\"\u003eInstallation\u003c/h3\u003e\na. Install it from github\n\n```bash\n# Install either with option-1 or option-2\n\n# Option-1 (Preferred)\npip install git+https://github.com/SiddeshSambasivam/MatterIx.git#egg=MatterIx\n\n# Option-2\ngit clone https://github.com/SiddeshSambasivam/MatterIx.git\n\npython setup.py install\n\n```\n\n(or)\n\nb. Install from PyPI\n\n```bash\n# Install directly from PyPI repository\npip install --upgrade matterix\n```\n\n\u003ch2 style=\"font-weight:bold\" id=\"features\"\u003eFeatures\u003c/h2\u003e\n\n\u003ch3 style=\"font-weight:bold\" id=\"autodiff\"\u003e1. Autodiff\u003c/h3\u003e\n\nGradients are computed using reverse-mode autodiff. All computations are representated as a graph of tensors with each tensor holding a reference to a function which can compute the local gradient of that tensor. The calculation of the partial derivative for each tensor is completed when the entire graph is traversed.\n\nThe fundamental idea behind **`autodiff`** is that it calculates the local derivative for each variable rather than its partial derivative. This way traversing through the computational graph is simple and modular, i.e we could calculate the partial derivative of any variable with respect to the output with just one traversal, with a complexity of `O(n)`.\n\nThe difference between **partial** and **local derivative** is the way each variable is treated in each equation. When calculating the partial derivative of a function, the expression is broken down into variables, for example `c= a* b` and `d=a+b+c`, instead of using `c`, we say `a*b` in the `d= a+b+(a*b)`. On the other hand, when calculating the local derivative of a function, each element in the expression is considered a variable. I understand this might not be clear, so refer to the following \u003ca href=\"https://github.com/SiddeshSambasivam/MatterIx/wiki/Understanding-reverse-mode-automatic-differentiation\"\u003eexplanation\u003c/a\u003e.\n\n\u003ch3 style=\"font-weight:bold\" id=\"loss\"\u003e2. Loss functions\u003c/h3\u003e\n\n2.1 Mean squared error. Example\n\n```python\nfrom matterix.functions import MSE\n\ny_train = ... # Actual/true value\ny_pred = ... # model prediction\n\nloss = MSE(y_train, y_pred)\n\n```\n\n2.2 Root Mean squared error\n\n```python\nfrom matterix.functions import RMSE\n\ny_train = ... # Actual/true value\ny_pred = ... # model prediction\n\nloss = RMSE(y_train, y_pred)\n\n```\n\n\u003ch3 style=\"font-weight:bold\" id=\"opt\"\u003e3. Optimizers\u003c/h3\u003e\n\n3.1 **Stochastic gradient descent**\n\n```python\nfrom matterix.optimizer import SGD\n\noptimizer = SGD(model, model.parameters(), lr=0.001) # model, parameters to optimize, learning rate\n\n# To set the gradient of the parameters to zero\noptimizer.zero_grad()\n\n# To update the parameters\noptimizer.step()\n\n```\n\n\u003ch3 style=\"font-weight:bold\" id=\"act\"\u003e4. Activation functions\u003c/h3\u003e\n\n**Functions:** sigmoid, tanh, relu.\n\nAll the activation functions are available from `matterix.functions`. Example,\n\n```python\nfrom matterix.functions import sigmoid\n```\n\n\u003ch3 style=\"font-weight:bold\" id=\"mod\"\u003e5. Module\u003c/h3\u003e\n\nModule provides the necessary functions to design your own neural network. It has methods to set all the gradients of the parameters to zero, get all the parameters of the network.\n\n1. Create a class which inherits from `nn.Module` to define for network\n2. Initiate your parameters\n3. Write a forward function\n\nSee the example below.\n\n```python\nfrom matterix import Tensor\nimport matterix.nn as nn\n\n# To define a neural network, just inherit `Module` from `nn`\nclass SampleModel(nn.Module):\n\n    def __init__(self) -\u003e None:\n        # Initilalize your parameters\n        self.w1 = Tensor.randn(5, requires_grad=True)\n        self.w2 = Tensor.randn(14, requires_grad=True)\n        ...\n\n    def forward(self, x) -\u003e Tensor:\n\n        out_1 = x @ self.w1\n        ...\n\n        return output\n\nmodel = SampleModel()\n\nmodel.zero_grad() # Sets the gradient of all the parameters to zero\nmodel.parameters() # Gets all the parameters\n```\n\n\u003ch2 style=\"font-weight:bold\"\u003eExample\u003c/h2\u003e\n\nThe following is a simple example\n\n```python\n# MNIST classifier\n\nimport numpy as np\nfrom matterix import Tensor, datasets\nimport matterix.nn as nn\nimport matterix.functions as F\nfrom matterix.optim import SGD\n\nfrom tqdm import trange\n\n# Get the MNIST dataset\nx_train, y_train, x_test, y_test = datasets.getMNIST()\n\n\nclass MnistModel(nn.Module):\n    def __init__(self) -\u003e None:\n\n        self.l1 = nn.Linear(28 * 28, 128, bias=False)\n        self.l2 = nn.Linear(128, 10, bias=False)\n\n    def forward(self, x) -\u003e Tensor:\n\n        o1 = self.l1(x)\n        o2 = self.l2(o1)\n        out = F.softmax(o2)\n\n        return out\n\n\nmodel = MnistModel()\nEPOCHS = 1000\nbatch_size = 1000\nlr = 0.01\n\noptimizer = SGD(parameters=model.parameters(), lr=lr, momentum=0.9)\n\nt_bar = trange(EPOCHS)\n\nlosses = []\n\nfor epoch in t_bar:\n\n    optimizer.zero_grad()\n\n    # Batching\n    ids = np.random.choice(60000, batch_size)\n    x = Tensor(x_train[ids])\n    y = Tensor(y_train[ids])\n\n    y_pred = model(x)\n    diff = y - y_pred\n    loss = (diff ** 2).sum() * (1.0 / diff.shape[0])\n\n    loss.backward()\n\n    optimizer.step()\n    losses.append(loss.data)\n\n    t_bar.set_description(\"Epoch: %.0f Loss: %.8f\" % (epoch, loss.data))\n\ny_pred = model(Tensor(x_test))\n\nacc = np.array(np.argmax(y_pred.data, axis=1) == np.argmax(y_test, axis=1)).sum()\nprint(\"Accuracy: \", acc / len(x_test))\n\n```\n\n\u003ch2 style=\"font-weight:bold\"\u003eDevelopment setup\u003c/h2\u003e\n\nInstall the necessary dependecies in a seperate virtual environment\n\n```bash\n# Create a virtual environment during development to avoid dependency issues\npip install -r requirements.txt\n\n# Before submitting a PR, run the unittests locally\npytest -v\n```\n\n\u003ch2 style=\"font-weight:bold\" id=\"releases\"\u003eRelease history\u003c/h2\u003e\n\n-   **1.1.1**\n\n    -   **ADD:** Linear layer: Provides an abstraction to a linear model\n    -   **ADD:** Log, exp and softmax functions\n    -   **ADD:** Momentum to SGD\n    -   **ADD:** Uniform weight initialization to linear layer\n    -   **FIX:** Softmax underflow issue, Tanh bug,\n\n-   **1.0.1**\n\n    -   Used 1.0.0 for testing\n    -   **ADD:** Tanh function, RMSE loss, randn and randint\n\n-   **0.1.1**\n\n    -   **ADD:** Optimizer: SGD\n    -   **ADD:** Functions: Relu\n    -   **ADD:** Loss functions: RMSE, MSETensor\n    -   **ADD:** Module: For defining neural networks\n    -   **FIX:** Floating point precision issue when calculating gradient\n\n-   **0.1.0**\n\n    -   First stable release\n    -   **ADD:** Tensor, tensor operations, sigmoid functions\n    -   **FIX:** Inaccuracies with gradient computation\n\n\u003ch2 style=\"font-weight:bold\" id=\"contributing\"\u003eContributing\u003c/h2\u003e\n\n1. Fork it\n\n2. Create your feature branch\n\n    ```bash\n    git checkout -b feature/new_feature\n    ```\n\n3. Commit your changes\n\n    ```\n    git commit -m 'add new feature'\n    ```\n\n4. Push to the branch\n\n    ```\n    git push origin feature/new_feature\n    ```\n\n5. Create a new pull request (PR)\n\n---\n\nSiddesh Sambasivam Suseela - [@ssiddesh45](https://twitter.com/ssiddesh45) - plutocrat45@gmail.com\n\nDistributed under the MIT license. See `LICENSE` for more information.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiddeshsambasivam%2Fmatterix","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsiddeshsambasivam%2Fmatterix","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsiddeshsambasivam%2Fmatterix/lists"}