Metadata-Version: 2.3
Name: torch-rbln
Version: 0.1.3
Summary: Rebellions Extension for PyTorch
Author: Daekyeong Kim
Author-email: daekyeong.kim@rebellions.ai
Requires-Python: >=3.10,<3.14
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Dist: PyYAML (>=6,<7)
Requires-Dist: libcst (>=1.2.0)
Requires-Dist: pybind11 (>=2.13.6,<3.0.0)
Requires-Dist: rebel-compiler (>=0.9.2,<0.10.0)
Requires-Dist: scipy (>=1.14.0)
Requires-Dist: torch (==2.8.0+cpu)
Description-Content-Type: text/markdown

# PyTorch for Rebellions' NPU

This package provides PyTorch integration for Rebellions' NPU.

## Getting Started (`torch`: Python package, `rebel-compiler`: Python package)

### Prerequisites

- Python 3.9 or later
- Git
- CMake 3.18 or later
- Ninja build system
- LDAP credentials for Rebellions' package repository

### Update Git submodules

Clone submodules recursively. This will download required third-party libraries
such as Rebel Compiler headers from `third_party/rebel_compiler`.

    git submodule update --init ./

### Create Python Virtual Environment

Create Python virtual environment. This will create a directory named `.venv` in
the current directory.

    python3 -m venv ./.venv && source ./.venv/bin/activate

### Install Dependencies

Install Python package manager `poetry`. This will manage dependencies,
building, packaging and installing.

    pip3 install poetry==2.0.1

Save credentials for `https://gate-keeper.rebellions.in`. Authorization for
`https://pypi.rbln.in` is required. But, this is not safe way to save
credentials. See `~/.config/pypoetry/auth.toml`.

    export LDAP_USERNAME=daekyeong.kim     # Put your username
    export LDAP_PASSWORD=mysecretpassword  # Put your password
    poetry config keyring.enabled false    # Optional, if building freezes while auth
    poetry config http-basic.rbln-internal $LDAP_USERNAME $LDAP_PASSWORD

**NOTE** During development we have to use rbln-internal instead of rbln. If you
want to download rebel compiler from rbln (external pypi server of rebellions), do
the following.

    poetry config http-basic.rbln <rbln username> <rbln password>

Install dependencies written in `poetry.lock` using `poetry`, except the root
package `torch-rbln`. Be careful, below command uninstall packages which is not
on `poetry.lock`.

    poetry sync --no-root

### Choose Build Type (Optional)

Choose build type like below. Default is `Release`.

    export RBLN_BUILD_TYPE=Debug

### Install Editable Package

Build C++ project and install editable `torch-rbln` package.

    poetry install --only-root


### Control RBLN Log Verbosity

To control the verbosity of logs emitted by torch_rbln, including detailed debug information such as CPU fallback operations, you can set the following environment variable:

```bash
export TORCH_RBLN_LOG_LEVEL=DEBUG
```

Available log levels (from most to least verbose):
- DEBUG – Show all debug messages, including CPU fallbacks and trace markers.
- INFO – General runtime information without detailed debug context.
- WARNING – Only show important warnings.
- ERROR – Only show errors and critical failures.

The default level is WARNING.
Setting DEBUG is especially useful during development or when troubleshooting execution issues on RBLN devices.

### Performance Optimization Flag (Optional)

To reduce runtime overhead (e.g., skipping unnecessary NaN/Inf checks), set the following environment variable:

```bash
export TORCH_RBLN_DEPLOY=ON
```
This enables lightweight execution for deployment scenarios.

### Dynamo Cache Disable (Optional)

By default, kernel caching(from dynamo) are enabled during execution.
If you wish to disable for debugging or development purposes, set the following environment variables:

```bash
export TORCH_RBLN_CACHE=OFF
```

### Install Wheel Package (Optional)

If you want to make `*.whl` and install that, run below command.

    poetry build
    pip install ./dist/torch_rbln*.whl

When you change C++ or Python source code, you just run
`Install Editable Package` or `Install Wheel Package` again.


## Apply Custom `rebel-compiler`

You have 2 choices:
- Use built-in one
- Use external one

### Use `torch-rbln` built-in `rebel-compiler` (`torch`: Python package, `rebel-compiler`: `third_party/rebel_compiler`)

This way is strongly recommended. Those are same with `Getting Started`.

    git submodule update --init ./
    python3 -m venv ./.venv && source ./.venv/bin/activate
    pip3 install poetry==2.0.1
    export LDAP_USERNAME=daekyeong.kim     # Put your username
    export LDAP_PASSWORD=mysecretpassword  # Put your password
    poetry config http-basic.rbln $LDAP_USERNAME $LDAP_PASSWORD

Without `poetry sync`, checkout `rebel-compiler` where
`./third_party/rebel_compiler` to your custom branch.

    pushd ./third_party/rebel_compiler
      git checkout my_custom_branch
    popd

It will make a package and install into your environment with syncing.

    ./tools/apply-custom-rebel.sh

Above script edits `pyproject.toml` and `poetry.lock` files. If you want to
apply custom `rebel-compiler` temporarily, keep your eyes on those files.

(Optional) You can choose build type like below.

    RBLN_BUILD_TYPE=Debug ./tools/apply-custom-rebel.sh

Then, you can build or install `torch-rbln` package on the custom
`rebel-compiler` package.

    poetry install --only-root

### Use external `rebel-compiler` (for rebel-compiler developers)

**Prereqs**
* You’ve already built `rebel-compiler`.
* `${REBEL_HOME}` points to the `rebel-compiler` repo root.

#### 1) Create and activate a virtualenv

```bash
python3 -m venv .venv
source .venv/bin/activate
```

#### 2) Add your local `rebel-compiler` in editable mode

```bash
poetry add --editable "${REBEL_HOME}/python"
```

#### 3) Install this project, using the external compiler

```bash
RBLN_USE_EXTERNAL_REBEL_COMPILER=1 poetry install --only-root
```


## Create Git Commit

Git `pre-commit` hook is working. So, when you create Git commit, linting
would be triggered. For prepare linting, you MUST initialize `lintrunner`.

    source ./.venv/bin/activate

    lintrunner init

Once `lintrunner` initalized, no need to initialize again. You can commit now.

    git commit

Some failures can be fixed automatically. Run below command for auto fixing.

    lintrunner -m main -a


## Run Tests

Assume that you are in Python virtual environment, and install `torch-rbln`
package successfully.

### C++ Tests

Making package runs in new isolated environment. Although you build your C++
project using `poetry install --only-root`, can't find that directory.
So, for `CTest` you MUST build C++ project manually.

    ./tools/build-libtorch-rbln.sh

    ctest --test-dir ./build


### Python Tests

    pytest ./test
--------------------------------------------------------------------------------

