From 2512febf9ccc024d898441b689115793ad3f53f1 Mon Sep 17 00:00:00 2001 From: Jeong Woo-kyung <77jwk0724@gmail.com> Date: Sat, 14 Sep 2024 02:05:47 +0900 Subject: [PATCH] docs: introduce README.md, remove outdated .md files --- Cargo.lock | 4 +- README.md | 85 +++++++++++++++++++++++++++++++++++++++- docs/dev-guide.md | 14 ------- docs/tensor-structure.md | 41 ------------------- poetry.lock | 2 +- pyproject.toml | 4 +- 6 files changed, 89 insertions(+), 61 deletions(-) delete mode 100644 docs/dev-guide.md delete mode 100644 docs/tensor-structure.md diff --git a/Cargo.lock b/Cargo.lock index b6e4cf7..6feb070 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -243,9 +243,9 @@ checksum = "61c41af27dd6d1e27b1b16b489db798443478cef1f06a660c96db617ba5de3b1" [[package]] name = "unicode-ident" -version = "1.0.12" +version = "1.0.13" source = "registry+https://github.com/rust-lang/crates.io-index" -checksum = "3354b9ac3fae1ff6755cb6db53683adb661634f67557942dea4facebec0fee4b" +checksum = "e91b56cd4cadaeb79bbf1a5645f6b4f8dc5bde8834ad5894a8db35fda9efa1fe" [[package]] name = "unindent" diff --git a/README.md b/README.md index fea7509..f5fd804 100644 --- a/README.md +++ b/README.md @@ -1 +1,84 @@ -Documentation is still in progress. If you're interested in Cranberry, feel free to join us and say hi in [our Discord channel](https://discord.gg/DKqZGpPJDV)! +

Cranberry

+ +

+A lightweight deep learning framework in Rust and Python +

+ +

+ + unit tests + + + github repo stars + +

+

+ + discord server + +

+ + +## Overview + +Cranberry is a deep learning framework designed for efficiency and simplicity. It combines the performance of Rust with the flexibility of Python to create a powerful yet concise tool for machine learning practitioners and researchers. + +### Current Status + +Cranberry is in its early stages of development but is already functional for basic deep learning tasks. We are actively working on expanding its capabilities to make it a robust and practical framework for a wide range of applications. + +### Key Features +- Minimal set of kernels implemented in Rust +- Majority of the framework logic implemented in Python for flexibility and ease of development +- Extremely concise codebase, making it easy to understand and extend +- PyTorch-like API for familiar and intuitive usage +- Designed for real-world applications while maintaining simplicity + +## Getting Started + +### Installation + +```bash +git clone https://github.com/manoflearning/cranberry.git +cd cranberry +pip install poetry +poetry install +poetry run maturin develop +``` + +### Usage and Examples + +```python +from cranberry import nn, optim +from cranberry.features.datasets import mnist + +X_train, Y_train, X_test, Y_test = mnist() +X_train, X_test = X_train.flatten(1), X_test.flatten(1) + +model = nn.Sequential(nn.Linear(784, 128), nn.ReLU(), nn.Linear(128, 64), nn.ReLU(), nn.Linear(64, 10)) + +optimizer = optim.SGD(model.parameters(), lr=0.001) + +for i in range(100): + optimizer.zero_grad() + # forward + loss = model(X_train).sparse_categorical_crossentropy(Y_train) + # backward + loss.backward() + # update + optimizer.step() + + print(f"epoch {i}, loss {loss.item():.4f}") +``` + +For more examples, see the [examples](./examples) directory. + +## Contributing and Community + +We welcome contributions to help Cranberry grow into a fully-featured, production-ready deep learning framework. + +Join our [Discord server](https://discord.gg/DKqZGpPJDV) to discuss development, get help, or just hang out with us. + +## License + +Cranberry is released under the MIT License. diff --git a/docs/dev-guide.md b/docs/dev-guide.md deleted file mode 100644 index 04c02cf..0000000 --- a/docs/dev-guide.md +++ /dev/null @@ -1,14 +0,0 @@ -# Cranberry Development Guide - -## PR and Commit Rules - -- PR titles and commit messages must follow [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/). -- Use lowercase letters only. -- Omit articles (e.g., a, the). -- Always use the “squash and merge” option when merging PRs. - -## Code Writing Rules - -- Keep the code short and concise, avoiding boilerplate. -- Format Python code using autopep8. -- Capitalize comments in the code. \ No newline at end of file diff --git a/docs/tensor-structure.md b/docs/tensor-structure.md deleted file mode 100644 index 0bddc4b..0000000 --- a/docs/tensor-structure.md +++ /dev/null @@ -1,41 +0,0 @@ -# Cranberry Tensor Structure Scheme - -## Python Components - -The Python components provide a logical representation of Tensors, including: -- Tensor -- Shape -- Strides -- Offset -- Device -- Dtype - -These components don't handle the actual data; instead, they manage abstract Tensor operations. -Using Shape, Strides, and Offset, we define and slice operations, which are then passed to the kernels in the Rust components. - -### TODO -- Implement an algorithm to access physical addresses using Shape, Strides, and Offset - - Determine the physical index corresponding to a given logical index - - If certain indices are contiguous (i.e., adjacent in the physical layer), identify the range $[l, r]$ - - The task of dividing operations into kernels is handled entirely here. It is not addressed in the Rust Components. -- Resources: - - PyTorch internals: http://blog.ezyang.com/2019/05/pytorch-internals/ - - EurekaLabsAI/tensor: https://github.com/EurekaLabsAI/tensor - -## Rust Components - -The Rust components are responsible for managing the physical aspects of Tensors, specifically: -- Storage -- Kernel code for performing operations on Storage - -### Why Rust? -- Easier memory management compared to C/C++ -- High performance - -### TODO -- Implement CPU, Metal, and CUDA operations for Storage -- Resources: - - A Taste of GPU Compute (by Jane Street): https://youtu.be/eqkAaplKBc4?si=a03WY4QUKlLtOmck - - gpu.cpp: https://github.com/AnswerDotAI/gpu.cpp - - huggingface/candle: https://github.com/huggingface/candle - - cuda-mode/lectures: https://github.com/cuda-mode/lectures \ No newline at end of file diff --git a/poetry.lock b/poetry.lock index 34cbeea..0fe13cd 100644 --- a/poetry.lock +++ b/poetry.lock @@ -729,4 +729,4 @@ files = [ [metadata] lock-version = "2.0" python-versions = "~3.11" -content-hash = "7da498d64fa69d1c0c9ef52ac2ab1ebe6cfc352fc23c89b866c74d06f6a7288d" +content-hash = "fe215b22c62e54a2f283c720a3e4e38f1da07d22a141fc21cdb9a5a3773447bc" diff --git a/pyproject.toml b/pyproject.toml index 5ff4fbc..1a89529 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -17,7 +17,7 @@ pyright = "^1.1.372" ruff = "^0.5.4" pytest = "^8.3.1" torch = "^2.3.1" -maturin = "^1.7.0" +maturin = "^1.7.1" [tool.ruff] line-length = 120 @@ -28,7 +28,7 @@ build-backend = "maturin" [project] name = "cranberry" -version = "0.1.1" +version = "0.1.2" description = "" authors = [ {name = "Wookyung Jeong", email = "77jwk0724@gmail.com"} ] requires-python = "~=3.11"