mtl-oxide 0.1.0__tar.gz

mtl_oxide-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jasononono
+
+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.

mtl_oxide-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: mtl-oxide
+Version: 0.1.0
+Summary: An array computing library optimized natively with the MacOS GPU.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Oxide
+
+My attempt at building a **GPU-accelerated array computing library** to learn many things in the process.
+
+**Oxide** functions similarly to [Numpy](https://numpy.org/), built exclusively to compute efficiently on the **macOS GPU** using [Metal](https://developer.apple.com/metal/).
+
+The backend of Oxide is written entirely in **C/C++**, linked to Python interface via [nanobind](https://github.com/wjakob/nanobind/).
+
+# Usage
+
+Oxide currently supports multiple data types, basic arithmetic, and shape manipulation, all optimized with array views and batch processing.
+
+[Documentation](https://github.com/jasononono/oxide/tree/main/docs)\
+[Code Explanation & Notes](https://github.com/jasononono/oxide/blob/main/docs/DEV.md)
+
+# Platform & Installation
+
+Oxide is a **macOS-exclusive library** (your device must also have a gpu because I haven't implement a cpu fallback yet)
+
+Run this command to install the latest [PyPI](https://pypi.org/project/mtl-oxide) distribution:
+
+```
+pip install mtl-oxide
+```
+
+# Features
+
+- GPU accelerated *Tensor* class using MTL::ResourceStorageModeShared
+- automatic Tensor memory management (alloc, free, and optimization)
+- memory safe c++ backend (no leaks detected)
+- GPU pseudo-random generator (xorshift currently a little scuffed, ill replace it soon)
+
+# Inspirations
+Parsing through these awesome libraries helped me setup Metal, design the file system, and understand the complicated shader syntax!
+
+- [numpy](https://numpy.org/): most oxide function names corresponds to numpy
+- [torch](https://pytorch.org/): benchmarking alongside numpy
+- [forge](https://github.com/kellen-sun/Forge/): Metal library setup reference
+
+# Contributing
+Oxide is my personal learning project, but feel free to open an issue if you have any suggestions!

mtl_oxide-0.1.0/README.md

@@ -0,0 +1,41 @@
+# Oxide
+
+My attempt at building a **GPU-accelerated array computing library** to learn many things in the process.
+
+**Oxide** functions similarly to [Numpy](https://numpy.org/), built exclusively to compute efficiently on the **macOS GPU** using [Metal](https://developer.apple.com/metal/).
+
+The backend of Oxide is written entirely in **C/C++**, linked to Python interface via [nanobind](https://github.com/wjakob/nanobind/).
+
+# Usage
+
+Oxide currently supports multiple data types, basic arithmetic, and shape manipulation, all optimized with array views and batch processing.
+
+[Documentation](https://github.com/jasononono/oxide/tree/main/docs)\
+[Code Explanation & Notes](https://github.com/jasononono/oxide/blob/main/docs/DEV.md)
+
+# Platform & Installation
+
+Oxide is a **macOS-exclusive library** (your device must also have a gpu because I haven't implement a cpu fallback yet)
+
+Run this command to install the latest [PyPI](https://pypi.org/project/mtl-oxide) distribution:
+
+```
+pip install mtl-oxide
+```
+
+# Features
+
+- GPU accelerated *Tensor* class using MTL::ResourceStorageModeShared
+- automatic Tensor memory management (alloc, free, and optimization)
+- memory safe c++ backend (no leaks detected)
+- GPU pseudo-random generator (xorshift currently a little scuffed, ill replace it soon)
+
+# Inspirations
+Parsing through these awesome libraries helped me setup Metal, design the file system, and understand the complicated shader syntax!
+
+- [numpy](https://numpy.org/): most oxide function names corresponds to numpy
+- [torch](https://pytorch.org/): benchmarking alongside numpy
+- [forge](https://github.com/kellen-sun/Forge/): Metal library setup reference
+
+# Contributing
+Oxide is my personal learning project, but feel free to open an issue if you have any suggestions!

mtl_oxide-0.1.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["setuptools>=82", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mtl-oxide"
+version = "0.1.0"
+description = "An array computing library optimized natively with the MacOS GPU."
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = [
+    
+]
+
+[tool.setuptools]
+package-dir = {"" = "python"}
+packages = ["oxide"]
+
+[tool.setuptools.package-data]
+"oxide" = ["*.so"]

mtl_oxide-0.1.0/python/mtl_oxide.egg-info/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: mtl-oxide
+Version: 0.1.0
+Summary: An array computing library optimized natively with the MacOS GPU.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Oxide
+
+My attempt at building a **GPU-accelerated array computing library** to learn many things in the process.
+
+**Oxide** functions similarly to [Numpy](https://numpy.org/), built exclusively to compute efficiently on the **macOS GPU** using [Metal](https://developer.apple.com/metal/).
+
+The backend of Oxide is written entirely in **C/C++**, linked to Python interface via [nanobind](https://github.com/wjakob/nanobind/).
+
+# Usage
+
+Oxide currently supports multiple data types, basic arithmetic, and shape manipulation, all optimized with array views and batch processing.
+
+[Documentation](https://github.com/jasononono/oxide/tree/main/docs)\
+[Code Explanation & Notes](https://github.com/jasononono/oxide/blob/main/docs/DEV.md)
+
+# Platform & Installation
+
+Oxide is a **macOS-exclusive library** (your device must also have a gpu because I haven't implement a cpu fallback yet)
+
+Run this command to install the latest [PyPI](https://pypi.org/project/mtl-oxide) distribution:
+
+```
+pip install mtl-oxide
+```
+
+# Features
+
+- GPU accelerated *Tensor* class using MTL::ResourceStorageModeShared
+- automatic Tensor memory management (alloc, free, and optimization)
+- memory safe c++ backend (no leaks detected)
+- GPU pseudo-random generator (xorshift currently a little scuffed, ill replace it soon)
+
+# Inspirations
+Parsing through these awesome libraries helped me setup Metal, design the file system, and understand the complicated shader syntax!
+
+- [numpy](https://numpy.org/): most oxide function names corresponds to numpy
+- [torch](https://pytorch.org/): benchmarking alongside numpy
+- [forge](https://github.com/kellen-sun/Forge/): Metal library setup reference
+
+# Contributing
+Oxide is my personal learning project, but feel free to open an issue if you have any suggestions!

mtl_oxide-0.1.0/python/mtl_oxide.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+python/mtl_oxide.egg-info/PKG-INFO
+python/mtl_oxide.egg-info/SOURCES.txt
+python/mtl_oxide.egg-info/dependency_links.txt
+python/mtl_oxide.egg-info/top_level.txt
+python/oxide/__init__.py
+python/oxide/arithmetic.py
+python/oxide/common.py
+python/oxide/core.cpython-313-darwin.so
+python/oxide/create.py
+python/oxide/system.py
+python/oxide/tensorclass.py
+python/oxide/util.py

mtl_oxide-0.1.0/python/mtl_oxide.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mtl_oxide-0.1.0/python/mtl_oxide.egg-info/top_level.txt

@@ -0,0 +1 @@
+oxide

mtl_oxide-0.1.0/python/oxide/__init__.py

@@ -0,0 +1,18 @@
+"""
+__INIT__.PY
+
+module init
+"""
+
+
+from .common import *
+from . import system
+from . import util
+from .tensorclass import *
+from .arithmetic import *
+from .create import *
+from . import core
+
+
+# these module references are stored at runtime to avoid circular import
+system.operand_module = arithmetic

mtl_oxide-0.1.0/python/oxide/arithmetic.py

@@ -0,0 +1,49 @@
+"""
+ARITHMETIC.PY
+
+tensor arithmetic functions
+"""
+
+
+from .common import *
+from . import system
+from . import util
+from .tensorclass import *
+
+
+# binary operations (e.g. out = a + b)
+
+def add(a, b):
+    dtype = util.check_tensors(a, b)
+    return Tensor(system.run(with_type(dtype, "add"), system.dispatcher, a.ctensor, b.ctensor))
+
+def sub(a, b):
+    dtype = util.check_tensors(a, b)
+    return Tensor(system.run(with_type(dtype, "sub"), system.dispatcher, a.ctensor, b.ctensor))
+
+def mul(a, b):
+    dtype = util.check_tensors(a, b)
+    return Tensor(system.run(with_type(dtype, "mul"), system.dispatcher, a.ctensor, b.ctensor))
+
+def div(a, b):
+    dtype = util.check_tensors(a, b)
+    return Tensor(system.run(with_type(dtype, "div"), system.dispatcher, a.ctensor, b.ctensor))
+
+
+# inplace unary operations (e.g. a += b)
+
+def uadd(a, b):
+    dtype = util.check_tensors(a, b)
+    return Tensor(system.run(with_type(dtype, "uadd"), system.dispatcher, a.ctensor, b.ctensor))
+
+def usub(a, b):
+    dtype = util.check_tensors(a, b)
+    return Tensor(system.run(with_type(dtype, "usub"), system.dispatcher, a.ctensor, b.ctensor))
+
+def umul(a, b):
+    dtype = util.check_tensors(a, b)
+    return Tensor(system.run(with_type(dtype, "umul"), system.dispatcher, a.ctensor, b.ctensor))
+
+def udiv(a, b):
+    dtype = util.check_tensors(a, b)
+    return Tensor(system.run(with_type(dtype, "udiv"), system.dispatcher, a.ctensor, b.ctensor))

mtl_oxide-0.1.0/python/oxide/common.py

@@ -0,0 +1,44 @@
+"""
+COMMON.PY
+
+misc inline functions, constants, and types (parallel to common.hpp)
+"""
+
+
+class OxideError(BaseException): pass
+
+# a clearer inheritance hierarchy is used here to make type checking & python type conversion easier
+class oxide_t: pass
+class numeric_t(oxide_t): pass
+class int_t(numeric_t): pass
+class float_t(numeric_t): pass
+class int32(int_t): pass
+class float32(float_t): pass
+
+
+MAXDIMS = 16
+MAXSEEDF = float(4294967295.0)
+CACHETHRESHOLD = 1024 * 16
+
+
+def with_type(dtype, name):
+    return name + "_" + dtype.__name__
+
+# convert oxide data into python type
+def pycast(dtype, data):
+    if isinstance(OX_T[dtype], type):
+        return OX_T[dtype](data)
+    return OX_T[dtype][0](data)
+
+def ansi(code, str):
+    return f"\x1b[{code}m{str}\x1b[0m"
+
+
+PY_T = { # corresponding oxide dtype of python types
+    int: int32,
+    float: float32
+}
+OX_T = { # corresponding python type of oxide dtypes (if a tuple is provided, dtype conversion will prefer the first element)
+    int32: int,
+    float32: (float, int)
+}

mtl_oxide-0.1.0/python/oxide/create.py

@@ -0,0 +1,53 @@
+"""
+ARITHMETIC.PY
+
+tensor initialization, creation, and randomize functions
+"""
+
+
+from .common import *
+from . import system
+from . import util
+from .tensorclass import *
+
+
+# generate float32 tensor randomly filled with elements from range [0, 1)
+def rand(shape):
+    shape = util.check_shape(shape)
+    return Tensor(system.run("rand", system.dispatcher, shape))
+
+# generate tensor randomly filled with elements from range [a, b]
+def random(shape, a = 0, b = 1, dtype = float32):
+    shape = util.check_shape(shape)
+    util.check_dtype(dtype, numeric_t)
+    util.check_args(dtype, a, b)
+
+    return Tensor(system.run(with_type(dtype, "random"), system.dispatcher, shape, a, b))
+
+# generate tensor filled with value
+def filled(shape, value, dtype = float32):
+    shape = util.check_shape(shape)
+    util.check_dtype(dtype, oxide_t)
+    util.check_args(dtype, value)
+
+    return Tensor(system.run(with_type(dtype, "filled"), system.backend, shape, value))
+
+# generate tensor filled with 0s
+def zeros(shape, dtype = float32):
+    shape = util.check_shape(shape)
+    util.check_dtype(dtype, numeric_t)
+
+    return Tensor(system.run(with_type(dtype, "zeros"), system.backend, shape))
+
+# generate tensor filled with 1s
+def ones(shape, dtype = float32):
+    shape = util.check_shape(shape)
+    util.check_dtype(dtype, numeric_t)
+
+    return Tensor(system.run(with_type(dtype, "ones"), system.backend, shape))
+
+
+# move this to viewmanip.py when implemented
+
+    # def transpose(view, order):
+    #     return Tensor(system.run(core.transpose, view.ctensor, order))

mtl_oxide-0.1.0/python/oxide/system.py

@@ -0,0 +1,35 @@
+"""
+SYSTEM.PY
+
+contains module references, cpp backend (core) call mechanics
+"""
+
+
+from .common import *
+from . import core
+import atexit
+
+
+backend = core.Backend()
+dispatcher = core.Dispatcher(backend)
+
+operand_module = None # reference assigned at runtime to avoid circular import
+
+
+# run cpp function by name
+def run(function, *args, **kwargs):
+    core.mem_optimize(backend)
+    try:
+        return getattr(core, function)(*args, **kwargs)
+    except core.oxide_error as e:
+        throw(str(e)) # convert core.oxide_error into the equivalent python class
+    except BaseException as e:
+        raise e
+
+def throw(msg):
+    raise OxideError(msg)
+    
+
+@atexit.register # free backend upon program exit
+def free():
+    core.free_backend(backend)

mtl_oxide-0.1.0/python/oxide/tensorclass.py

@@ -0,0 +1,165 @@
+"""
+TENSORCLASS.PY
+
+tensor class definition and conversion functions
+"""
+
+
+from .common import *
+from . import system
+from . import core
+import typing
+
+
+class Tensor:
+
+    def __init__(self, ctensor):
+        super().__setattr__("ctensor", ctensor)
+        # match class name with dtype
+        for t in OX_T:
+            ct =  with_type(t, "TensorView")
+            if ct == type(ctensor).__name__:
+                super().__setattr__("dtype", t)
+                break
+        else:
+            system.throw("ctensor type invalid")
+
+    def __getitem__(self, key):
+        if isinstance(key, int):
+            return self.ctensor.get_element([key])
+        elif isinstance(key, typing.Iterable):
+            return self.ctensor.get_element(list(key))
+        else:
+            system.throw(f"tensor cannot be indexed with '{type(key).__name__}'")
+
+    def __setitem__(self, key, value):
+        if isinstance(key, int):
+            self.ctensor.set_element([key], value)
+        elif isinstance(key, typing.Iterable):
+            self.ctensor.set_element(list(key), value)
+        else:
+            system.throw(f"tensor cannot be indexed with '{type(key).__name__}'")
+
+    def __getattr__(self, key):
+        if key == "ndim":
+            return self.ctensor.get_ndim()
+        if key == "size":
+            return self.ctensor.get_size()
+        if key == "offset":
+            return self.ctensor.get_offset()
+        if key == "shape":
+            return self.ctensor.get_shape().copy()
+        if key == "strides":
+            return self.ctensor.get_strides().copy()
+        if key == "dtype":
+            return self.dtype
+        
+        system.throw(f"tensor attribute '{key}' does not exist")
+        
+    def __setattr__(self, key, value):
+        system.throw("tensor attributes are immutable")
+    
+    def __str__(self):
+        return self.ctensor.get_string()
+
+    def __add__(self, other):
+        return system.operand_module.add(self, other)
+
+    def __sub__(self, other):
+        return system.operand_module.sub(self, other)
+
+    def __mul__(self, other):
+        return system.operand_module.mul(self, other)
+
+    def __truediv__(self, other):
+        return system.operand_module.div(self, other)
+
+
+# convert oxide tensor into python list
+def topy(tensor):
+
+    def generate(depth = 0): # generate an empty list with the tensor's shape
+        if depth == tensor.ndim:
+            return 0
+        arr = [generate(depth + 1) for _ in range(tensor.shape[depth])]
+        return arr
+    
+    arr = generate()
+
+    arr_tree = [] # current dfs stack of list references
+    ref = arr
+    while ref != 0:
+        arr_tree.append(ref)
+        ref = ref[0]
+
+    indices = [0] * tensor.ndim
+
+    # dfs traversal, similar implementation to get_string() function in tensor.cpp
+    while len(indices) > 0:
+        arr_tree[-1][indices[-1]] = pycast(tensor.dtype, tensor[indices])
+
+        while len(indices) > 0 and indices[-1] == tensor.shape[len(indices) - 1] - 1:
+            indices.pop(-1)
+            arr_tree.pop(-1)
+
+        if len(indices) == 0:
+            break
+
+        indices[-1] += 1
+        if len(indices) != tensor.ndim:
+            # append new ref and recursively append its children
+            arr_tree.append(arr_tree[-1][indices[-1]])
+            indices.append(0)
+            while len(indices) < tensor.ndim:
+                arr_tree.append(arr_tree[-1][0])
+                indices.append(0)
+
+    return arr
+    
+
+############# OUTDATED FUNCTION(s)
+
+# dfs helper function
+def parse_iterable(depth, first, shape, stack, iterable, result):
+    if not isinstance(iterable, typing.Iterable):
+        # constant must be able to be convert into a valid oxide dtype
+        for t in PY_T.keys():
+            if isinstance(iterable, t):
+                result.append(iterable)
+                return PY_T[t]
+        system.throw(f"item of type '{type(iterable).__name__}' cannot be stored in a tensor")
+
+    t = None
+    if len(iterable) == 0:
+        system.throw("empty iterable cannot be a part of tensor")
+
+    for i in iterable:
+        stack.append(len(iterable))
+        if len(stack) > len(shape):
+            if first: # shape is invalid if the maximum encountered depth increases at a position other than the first
+                shape.append(stack[depth])
+            else:
+                system.throw("depth within iterable does not match")
+        elif stack[depth] != shape[depth]:
+            system.throw("dimensions do not match")
+
+        # types must be univariant
+        t_new = parse_iterable(depth + 1, first, shape, stack, i, result)
+        if t and t_new is not t:
+            system.throw("tensor can only store items of similar types")
+        t = t_new
+
+        stack.pop()
+        first = False
+
+    return t
+
+# create an oxide tensor from python iterable
+def tensor(iterable):
+    data = [] # accumulate linear buffer from iterable
+    shape = []
+    t = parse_iterable(0, True, shape, [], iterable, data)
+    ctensor = system.run(with_type(t, "make_view"), system.backend, shape, data)
+    return Tensor(ctensor)
+
+#############

mtl_oxide-0.1.0/python/oxide/util.py

@@ -0,0 +1,49 @@
+"""
+UTIL.PY
+
+utility functions (type & input checkers)
+"""
+
+
+from .common import *
+from . import system
+from .tensorclass import *
+
+
+# ensure that tensor types are univariant
+def check_tensors(*tensors):
+    dtypes = set()
+    for t in tensors:
+        if not isinstance(t, Tensor):
+            system.throw(f"argument should be tensor, not '{type(t).__name__}'")
+        dtypes.add(t.dtype)
+
+    if len(dtypes) > 1:
+        system.throw("tensors should be of the same type")
+    return list(dtypes)[0]
+
+# ensure that tensor shape is valid
+def check_shape(shape):
+    if isinstance(shape, int):
+        shape = [shape]
+    if len(shape) > MAXDIMS:
+        system.throw("shape exceeds maximum dimensions")
+    for i in shape:
+        if not (isinstance(i, int) and i > 0):
+            system.throw("shape is invalid")
+    return shape
+
+# ensure that dtype is an oxide dtype
+# optionally stricter restrictions
+def check_dtype(dtype, tclass = None):
+    if tclass is None:
+        if not issubclass(dtype, oxide_t):
+            system.throw("dtype is invalid")
+    else:
+        if not issubclass(dtype, tclass):
+            system.throw("dtype is invalid")
+
+def check_args(dtype, *args):
+    for a in args:
+        if not isinstance(a, OX_T[dtype]):
+            system.throw("argument type is invalid")

mtl_oxide-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+