deep-atomic 0.1.0__tar.gz

deep_atomic-0.1.0/.github/workflows/publish-pypi.yml

@@ -0,0 +1,43 @@
+name: Publish to PyPI
+on: [release]
+jobs:
+  pypi-publish:
+    name: upload release to PyPI
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      # IMPORTANT: this permission is mandatory for Trusted Publishing
+      id-token: write
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v4
+        with:
+          python-version: "3.11"
+      - name: deps
+        run: curl -LsSf https://astral.sh/uv/install.sh | sh # install uv
+      - name: build
+        run: uv build
+      # refer to https://docs.pypi.org/trusted-publishers/using-a-publisher/
+      - name: mint API token
+        id: mint-token
+        run: |
+          # retrieve the ambient OIDC token
+          resp=$(curl -H "Authorization: bearer $ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
+            "$ACTIONS_ID_TOKEN_REQUEST_URL&audience=pypi")
+          oidc_token=$(jq -r '.value' <<< "${resp}")
+
+          # exchange the OIDC token for an API token
+          resp=$(curl -X POST https://pypi.org/_/oidc/mint-token -d "{\"token\": \"${oidc_token}\"}")
+          api_token=$(jq -r '.token' <<< "${resp}")
+
+          # mask the newly minted API token, so that we don't accidentally leak it
+          echo "::add-mask::${api_token}"
+
+          # see the next step in the workflow for an example of using this step output
+          echo "api-token=${api_token}" >> "${GITHUB_OUTPUT}"
+
+      - name: publish
+        # gh-action-pypi-publish uses TWINE_PASSWORD automatically
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ steps.mint-token.outputs.api-token }}

deep_atomic-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.Python
+env/
+venv/
+.venv/
+ENV/
+dist/
+build/
+*.egg-info/
+*.egg
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.mypy_cache/
+.ruff_cache/
+.DS_Store

deep_atomic-0.1.0/.vscode/settings.json

@@ -0,0 +1,7 @@
+{
+    "python.testing.pytestArgs": [
+        "tests"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true
+}

deep_atomic-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Your Name
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

deep_atomic-0.1.0/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: deep_atomic
+Version: 0.1.0
+Summary: A simple deep learning framework built upon numpy only
+Author-email: Elliot Zhang <elliot_zh@proton.me>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Requires-Dist: numpy>=1.24.4
+Requires-Dist: pytest>=8.3.5
+Provides-Extra: dev
+Requires-Dist: black>=23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# deep-atomic
+
+A simple deep learning framework built upon numpy only. Mainly for practice and learning.
+
+## Usage
+
+### Import
+
+```python
+import deep_atomic as da
+import numpy as np   # required for tensor initialization and some operations
+```
+
+### Creating a Tensor
+
+```python
+# Create a tensor from a NumPy array (requires_grad=True by default)
+a = da.Tensor(
+    np.array([1, 2, 3], dtype=np.float64),
+    requires_grad=True
+)
+```
+
+### Supported Operations
+
+Most essential deep‑learning operations are implemented. For those that also exist in NumPy, we follow NumPy's API conventions.
+
+```python
+a, b = da.Tensor(np.random.rand(3, 4)), da.Tensor(np.random.rand(3, 4))
+
+# Arithmetic & math
+c = a + b                     # addition
+c = a - b                     # subtraction
+c = a * b                     # element‑wise multiplication
+c = a / b                     # element‑wise division
+c = a ** b                    # element‑wise power
+c = a @ b                     # matrix multiplication
+c = da.exp(a)
+c = da.log(a)
+
+# Reductions
+c = da.sum(a)                               # shape: (1,)
+c = da.sum(a, axis=1)                       # shape: (3,)
+c = da.sum(a, axis=1, keepdims=True)        # shape: (3, 1)
+# min, max, argmin, argmax follow the same signature
+
+# Softmax
+c = da.softmax(a, axis=-1)
+c = da.log_softmax(a, axis=-1)
+
+# Shape manipulations
+c = a.reshape(2, 6)
+c = a.reshape(1, 12).squeeze(0)               # shape: (12,)
+c = da.expand_dims(a, -1)                   # shape: (3, 4, 1)
+c = a.expand_dims(-1)                         # method‑style alternative
+c = a.repeat(2, axis=1)                       # shape: (3, 8)
+c = da.tile(a, (2, 2))                      # shape: (6, 8)
+c = a.tile(2, 2)                              # method‑style alternative
+```
+
+## Todo
+
+- [ ] more basic operations and their autograd
+    - [ ] convolution and 2d convolution
+    - [ ] topk
+    - [ ] boolean and masked operation
+    - [ ] einsum
+    - [ ] scatter
+- [ ] basic neural network classes
+- [ ] optimizers and loss functions
+- [ ] full training test
+- [ ] benchmark with pytorch on CPU
+- [ ] attention layers and full LLM training
+- [ ] finer type annotations, comments and documentation
+
+## Installation
+
+```bash
+pip install deep_atomic
+
+# or with uv
+uv add deep_atomic
+```
+
+## Development
+
+Install in editable mode with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```

deep_atomic-0.1.0/README.md

@@ -0,0 +1,97 @@
+# deep-atomic
+
+A simple deep learning framework built upon numpy only. Mainly for practice and learning.
+
+## Usage
+
+### Import
+
+```python
+import deep_atomic as da
+import numpy as np   # required for tensor initialization and some operations
+```
+
+### Creating a Tensor
+
+```python
+# Create a tensor from a NumPy array (requires_grad=True by default)
+a = da.Tensor(
+    np.array([1, 2, 3], dtype=np.float64),
+    requires_grad=True
+)
+```
+
+### Supported Operations
+
+Most essential deep‑learning operations are implemented. For those that also exist in NumPy, we follow NumPy's API conventions.
+
+```python
+a, b = da.Tensor(np.random.rand(3, 4)), da.Tensor(np.random.rand(3, 4))
+
+# Arithmetic & math
+c = a + b                     # addition
+c = a - b                     # subtraction
+c = a * b                     # element‑wise multiplication
+c = a / b                     # element‑wise division
+c = a ** b                    # element‑wise power
+c = a @ b                     # matrix multiplication
+c = da.exp(a)
+c = da.log(a)
+
+# Reductions
+c = da.sum(a)                               # shape: (1,)
+c = da.sum(a, axis=1)                       # shape: (3,)
+c = da.sum(a, axis=1, keepdims=True)        # shape: (3, 1)
+# min, max, argmin, argmax follow the same signature
+
+# Softmax
+c = da.softmax(a, axis=-1)
+c = da.log_softmax(a, axis=-1)
+
+# Shape manipulations
+c = a.reshape(2, 6)
+c = a.reshape(1, 12).squeeze(0)               # shape: (12,)
+c = da.expand_dims(a, -1)                   # shape: (3, 4, 1)
+c = a.expand_dims(-1)                         # method‑style alternative
+c = a.repeat(2, axis=1)                       # shape: (3, 8)
+c = da.tile(a, (2, 2))                      # shape: (6, 8)
+c = a.tile(2, 2)                              # method‑style alternative
+```
+
+## Todo
+
+- [ ] more basic operations and their autograd
+    - [ ] convolution and 2d convolution
+    - [ ] topk
+    - [ ] boolean and masked operation
+    - [ ] einsum
+    - [ ] scatter
+- [ ] basic neural network classes
+- [ ] optimizers and loss functions
+- [ ] full training test
+- [ ] benchmark with pytorch on CPU
+- [ ] attention layers and full LLM training
+- [ ] finer type annotations, comments and documentation
+
+## Installation
+
+```bash
+pip install deep_atomic
+
+# or with uv
+uv add deep_atomic
+```
+
+## Development
+
+Install in editable mode with development dependencies:
+
+```bash
+pip install -e ".[dev]"
+```
+
+Run tests:
+
+```bash
+pytest
+```

deep_atomic-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "deep_atomic"
+version = "0.1.0"
+description = "A simple deep learning framework built upon numpy only"
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+authors = [
+    { name = "Elliot Zhang", email = "elliot_zh@proton.me" }
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "numpy>=1.24.4",
+    "pytest>=8.3.5",
+] 
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "black>=23.0",
+    "ruff>=0.1.0",
+]
+
+[tool.black]
+line-length = 88
+target-version = ['py38']
+
+[tool.ruff]
+line-length = 88
+lint.select = ["E", "F", "W", "I"]
+lint.fixable = ["I"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = "*_test.py"

deep_atomic-0.1.0/src/deep_atomic/__init__.py

@@ -0,0 +1,7 @@
+"""deep-atomic - A simple deep learning framework built upon numpy only"""
+
+__version__ = "0.1.0"
+__author__ = "elliot_zh@proton.me"
+
+from .tensor import *
+from .op import *

deep_atomic-0.1.0/src/deep_atomic/graph.py

@@ -0,0 +1,246 @@
+import numpy as np
+from .tensor import Tensor
+from abc import ABC, abstractmethod
+
+from .utils import *
+
+
+class Op(ABC):
+    @abstractmethod
+    def backward(self, grad):
+        pass
+
+
+class SingleOp(Op):
+    def __init__(self, input: Tensor):
+        self.input = input
+        self.input.depended_count += 1
+
+
+class TwoOp(Op):
+    def __init__(self, a1, a2):
+        self.a1_np, self.a2_np = (
+            i.to_np() if isinstance(i, Tensor) else i for i in [a1, a2]
+        )
+        self.a1, self.a2 = (i if isinstance(i, Tensor) else None for i in [a1, a2])
+        if isinstance(self.a1, Tensor):
+            self.a1.depended_count += 1
+        if isinstance(self.a2, Tensor):
+            self.a2.depended_count += 1
+
+
+class Add(TwoOp):
+    def __init__(self, a1, a2, sub=False):
+        super().__init__(a1, a2)
+        self.sub = sub
+
+    def backward(self, grad):
+        if self.a1 is not None:
+            self.a1.backward(grad)
+        if self.a2 is None:
+            return
+        if self.sub:
+            grad = -grad
+        self.a2.backward(grad)
+
+
+class Mul(TwoOp):
+    def __init__(self, a1, a2):
+        super().__init__(a1, a2)
+
+    def backward(self, grad):
+        if self.a1 is not None:
+            self.a1.backward(grad * self.a2_np)
+        if self.a2 is not None:
+            self.a2.backward(self.a1_np * grad)
+
+
+class Div(TwoOp):
+    def __init__(self, a1, a2):
+        super().__init__(a1, a2)
+
+    def backward(self, grad):
+        if self.a1 is not None:
+            self.a1.backward(grad / self.a2_np)
+        if self.a2 is not None:
+            self.a2.backward(-1 * self.a1_np / (self.a2_np**2) * grad)
+
+
+class MatMul(TwoOp):
+    def __init__(self, a1, a2):
+        super().__init__(a1, a2)
+
+    def backward(self, grad):
+        if self.a1 is not None:
+            self.a1.backward(grad @ self.a2_np.swapaxes(-1, -2))
+        if self.a2 is not None:
+            self.a2.backward(self.a1_np.swapaxes(-1, -2) @ grad)
+
+
+class Exp(SingleOp):
+    def __init__(
+        self, input: Tensor
+    ):  # node of exp is introduced only when the input is a Tensor
+        super().__init__(input)
+
+    def backward(self, grad):
+        self.input.backward(np.exp(self.input.to_np()) * grad)
+
+
+class Log(SingleOp):
+    def __init__(
+        self, input: Tensor
+    ):  # node of log is introduced only when the input is a Tensor
+        super().__init__(input)
+
+    def backward(self, grad):
+        self.input.backward(1 / self.input.to_np() * grad)
+
+
+class Pow(TwoOp):
+    def __init__(self, a1, a2):
+        super().__init__(a1, a2)
+
+    def backward(self, grad):
+        if self.a1 is not None:
+            self.a1.backward(self.a2_np * (self.a1_np) ** (self.a2_np - 1) * grad)
+        if self.a2 is not None:
+            self.a2.backward(np.log(self.a1_np) * (self.a1_np) ** (self.a2_np) * grad)
+
+
+class Sum(SingleOp):
+    def __init__(self, input: Tensor, axis, keepdims):
+        super().__init__(input)
+        self.axis = axis
+        self.keepdims = keepdims
+
+    def backward(self, grad):
+        if self.axis is None or self.keepdims:
+            self.input.backward(grad)
+        else:
+            self.input.backward(np.expand_dims(grad, self.axis))
+
+
+class Abs(SingleOp):
+    def __init__(self, input: Tensor):
+        super().__init__(input)
+
+    def backward(self, grad):
+        self.input.backward(np.where(grad < 0, -grad, grad))
+
+
+class MinMax(SingleOp):
+    def __init__(
+        self, input: Tensor, axis, keepdims, indices=None, full_red_value=None
+    ):
+        super().__init__(input)
+        self.indices = indices  # result of argmin / argmax. when axis is not None
+        self.axis, self.keepdims = axis, keepdims
+        self.full_red_value = full_red_value  # for faster compute when axis is None
+        if axis is None:
+            assert full_red_value is not None
+        else:
+            assert indices is not None
+
+    def backward(self, grad):
+        if self.axis is None:
+            if not self.keepdims:
+                grad = np.tile(grad, self.input.shape)
+            mask = self.input.to_np() == self.full_red_value
+            grad /= np.count_nonzero(
+                mask
+            )  # distribute gradient evenly across max values. following pytorch implementation
+        else:
+            if not self.keepdims:
+                tile_reps = [1] * self.input.ndim
+                tile_reps[self.axis] = self.input.shape[self.axis]
+                grad = np.expand_dims(grad, axis=self.axis)
+                grad = np.tile(grad, tile_reps)
+            baseline_expansion_axis = list(range(self.input.ndim))
+            baseline_expansion_axis.pop(self.axis)
+            baseline_indices = np.expand_dims(
+                np.arange(self.input.shape[self.axis]), axis=baseline_expansion_axis
+            )
+            mask = self.indices == baseline_indices
+        self.input.backward(np.where(mask, grad, 0.0))
+
+
+class Reshape(SingleOp):
+    def __init__(self, input: Tensor, from_):
+        super().__init__(input)
+        self.from_ = from_
+
+    def backward(self, grad):
+        self.input.backward(grad.reshape(self.from_))
+
+
+class Squeeze(SingleOp):
+    def __init__(self, input: Tensor, axis):
+        super().__init__(input)
+        self.axis = axis
+
+    def backward(self, grad):
+        self.input.backward(np.expand_dims(grad, self.axis))
+
+
+class ExpandDims(SingleOp):
+    def __init__(self, input: Tensor, axis):
+        super().__init__(input)
+        self.axis = axis
+
+    def backward(self, grad):
+        self.input.backward(grad.squeeze(self.axis))
+
+
+class Repeat(SingleOp):
+    def __init__(self, input: Tensor, repeats, axis=None):
+        super().__init__(input)
+        self.repeats = repeats
+        self.axis = axis
+
+    def backward(self, grad):
+        if isinstance(self.repeats, int):
+            if self.axis is None:
+                grad = grad.reshape(-1, self.repeats).sum(axis=-1)
+            else:
+                shape = list(grad.shape)
+                shape[self.axis] //= self.repeats
+                shape.insert(self.axis + 1, self.repeats)
+                grad = grad.reshape(shape).sum(axis=self.axis + 1)
+            self.input.backward(grad)
+        else:
+            if self.axis is None:
+                grad_ = np.zeros(len(self.repeats), dtype=grad.dtype)
+                start = 0
+                for i, r in enumerate(self.repeats):
+                    if r > 0:
+                        grad_[i] = grad[start : start + r].sum()
+                    start += r
+            else:
+                moved = np.moveaxis(grad, self.axis, 0)
+                grad_ = np.zeros(self.input.shape, dtype=grad.dtype)
+                start = 0
+                for i, r in enumerate(self.repeats):
+                    if r > 0:
+                        idx = [slice(None)] * self.input.ndim
+                        idx[self.axis] = i
+                        grad_[tuple(idx)] = moved[start : start + r].sum(axis=0)
+                    start += r
+            self.input.backward(grad_)
+
+
+class Tile(SingleOp):
+    def __init__(self, input: Tensor, reps):
+        super().__init__(input)
+        self.reps = reps
+
+    def backward(self, grad):
+        start = (grad.ndim - len(self.reps)) if grad.ndim > len(self.reps) else 0
+        for i, r in enumerate(self.reps, start=start):
+            shape = list(grad.shape)
+            shape[i] //= r
+            shape.insert(i + 1, r)
+            grad = grad.reshape(shape, order="F").sum(axis=i + 1)
+        if grad.ndim < len(self.reps):
+            grad = grad.reshape(self.input.shape)
+        self.input.backward(grad)