# Quickstart

```{important}
The following section assumes you are familiar with IREE. To get started with IREE you can follow the [IREE TensorFlowLite Guide](https://iree.dev/guides/ml-frameworks/tflite/)
and the [IREE CPU Deployment Guide](https://iree.dev/guides/deployment-configurations/cpu/).
```
## Setup

- Install compiler and simulator in **one of the following** two ways.

(release-package-ubuntu-24-04)=
### Release Package Ubuntu 24.04

- Download the [release.tar.gz](https://github.com/synaptics-torq/torq-compiler/releases) from the **Assets** section and uncompress it.
- There are some prerequisite system packages that need to be installed.
Please refer to apt-packages.txt for the list.
- In the root directory of the uncompressed package, run:
    ```bash
    $ ./setup.sh <venv-directory>
    ```
    This will:
    - Create a Python virtual environment at `<venv-directory>`.
    - Install all required Python dependencies, including IREE compiler and runtime.
    - Set up import tools and other necessary components.
    > **Note:** The setup process may take some time as it installs all dependencies and tools.

- Once setup is complete, activate the Python environment:
    ```bash
    $ source <venv-directory>/bin/activate
    ```
    You can now use the compiler and runtime tools from this environment.

(docker-image)=
### Docker Image

You can use **either** of the following approaches:

**A. Use the prebuilt image:**
- Log-in to the GitHub docker registry

   ```{code} shell
   docker login ghcr.io
   ```

   Use your Github username and a Github personal access token as password.
   Please refer to [Github documentation for the creation and usage of a
   personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic).

- Create an ephemeral Docker container that uses the prebuilt image:
    ```bash
    $ docker run --rm -it -v $(pwd):$(pwd) -w $(pwd) -u $(id -u):$(id -g) ghcr.io/synaptics-torq/torq-compiler/compiler:main
    ```
    The container will have access to the contents of your current directory.

**B. Build your own image (if you don't have access to the Synaptics GitHub repo):**
- Uncompress the [Release Package Ubuntu 24.04](#release-package-ubuntu-24-04).
- In the root directory of the uncompressed package, build the Docker image using the provided Dockerfile:
    ```bash
    $ docker build -t <image-name> .
    ```
- Run the Docker container:
    ```bash
    $ docker run --rm -it -v $(pwd):$(pwd) -w $(pwd) -u $(id -u):$(id -g) <image-name>
    ```
### Python Wheel (pip)

```{note}
The `torq-compiler` wheel is available from GitHub releases version 2.0.0 and above. It provides a minimal compiler-only installation without example models, tests, or the runtime simulator.
```

The `torq-compiler` package is included in the GitHub release. Install the compiler wheel directly from any release snapshot.

To enable ONNX model importing, install with the `onnx` extra:

```bash
$ pip install "torq_compiler-<version>-<platform>.whl[onnx]"
```

To enable TFLite model conversion, install with the `tflite` extra:

```bash
$ pip install "torq_compiler-<version>-<platform>.whl[tflite]"
```

To enable TensorFlow SavedModel importing, install the `tf` extra:

```bash
$ pip install "torq_compiler-<version>-<platform>.whl[tf]"
```

Multiple extras can be combined:

```bash
$ pip install "torq_compiler-<version>-<platform>.whl[onnx,tflite]"
```

For ONNX importing via Python:

```bash
$ python -m iree.compiler.tools.import_onnx model.onnx -o model.mlir
```

For TFLite conversion:

```bash
$ tosa-converter-for-tflite model.tflite --bytecode -o model.mlirbc
```

## Compile and Run the Model

- Example MLIR models are provided in the `tests/` directory in the package.

    - **[Release Package](#release-package-ubuntu-24-04):**  
    Navigate to the `tests/` directory is located in the root of the uncompressed package.

    - **[Docker Image](#docker-image):**  
    The `tests/` directory is located in the `/opt/release` directory.
    You can navigate there with:
        ```
        $ cd /opt/release
        ```

- Compile an input MLIR file ``tests/testdata/tosa_ops/add.mlir`` to a compiled model ``model.vmfb``:
    ```bash
    $ torq-compile tests/testdata/tosa_ops/add.mlir -o model.vmfb
    ```

- Run the generated model with the Torq simulator:
    ```bash
    $ torq-run-module --module=model.vmfb --input="1x56x56x24xi8=1"
    ```