Pre-release

This release is a pre-release and may not be stable for production use.

TICO

TICO (Torch IR to Circle ONE) is a python library for converting Pytorch modules into a circle model that is a lightweight and efficient representation in ONE designed for optimized on-device neural network inference.

For Developers

Testing & Code Formatting
Testing
Code Formatting

For Users

Installation

Prerequisites

Python 3.10
(Optional) one-compiler 1.30.0
- It is only required if you intend to run inference with the converted Circle model. If you are only converting models without running them, this dependency is not needed.

We highly recommend to use a virtual env, e.g., conda.

Clone this repo
Build python package

./ccex build

This will generate build and dist directories in the root directory.

Install generated package

./ccex install

Available options

--dist To install the package from .whl (without this option, TICO is installed in an editable mode)
--torch_ver <torch version> To install a specific torch version (default: 2.6).
- Available : 2.5, 2.6, 2.7, 2.8, nightly

Now you can convert a torch module to a .circle.

Getting started

This tutorial explains how you can use TICO to generate a circle model from a torch module.

Let's assume we have a torch module.

import tico
import torch

class AddModule(torch.nn.Module):
    def __init__(self):
        super().__init__()

    def forward(self, x, y):
        return x + y

NOTE TICO internally uses torch.export. Therefore, the torch module must be 'export'able. Please see this document if you have any trouble to export.

From torch module

You can convert a torch module to a circle model with these steps.

torch_module = AddModule()
example_inputs = (torch.ones(4), torch.ones(4))

circle_model = tico.convert(torch_module.eval(), example_inputs)
circle_model.save('add.circle')

NOTE Please make sure to call eval() on the PyTorch module before passing it to our API. This ensures the model runs in inference mode, disabling layers like dropout and batch normalization updates.

Compile with configuration

from test.modules.op.add import AddWithCausalMaskFolded

torch_module = AddWithCausalMaskFolded()
example_inputs = torch_module.get_example_inputs()

config = tico.CompileConfigV1()
config.legalize_causal_mask_value = True
circle_model = tico.convert(torch_module, example_inputs, config = config)
circle_model.save('add_causal_mask_m120.circle')

With legalize_causal_mask_value option on, causal mask value is converted from -inf to -120, creating a more quantization-friendly circle model with the cost of slight accuracy drop.

From .pt2

The torch module can be exported and saved as .pt2 file (from PyTorch 2.1).

module = AddModule()
example_inputs = (torch.ones(4), torch.ones(4))

exported_program = torch.export.export(module, example_inputs)
torch.export.save(exported_program, 'add.pt2')

There are two ways to convert .pt2 file: python api, command line tool.

Python API

circle_model = tico.convert_from_pt2('add.pt2')
circle_model.save('add.circle')

Command Line Tool

pt2-to-circle -i add.pt2 -o add.circle

Command Line Tool with configuration

pt2-to-circle -i add.pt2 -o add.circle -c config.yaml

# config.yaml

version: '1.0' # You must specify the config version. 
legalize_causal_mask_value: True

Running circle models directly in Python

After circle export, you can run the model directly in Python.

Note that you should install one-compiler package first.

The output types are numpy.ndarray.

torch_module = AddModule()
example_inputs = (torch.ones(4), torch.ones(4))

circle_model = tico.convert(torch_module, example_inputs)
circle_model(*example_inputs)
# numpy.ndarray([2., 2., 2., 2.], dtype=float32)

Quantization

The tico.quantization module provides a unified and modular interface for quantizing large language models (LLMs) and other neural networks.

It introduces a simple two-step workflow — prepare and convert — that abstracts the details of different quantization algorithms.

Basic Usage

from tico.quantization import prepare, convert
from tico.quantization.config.gptq import GPTQConfig
import torch
import torch.nn as nn

class LinearModel(nn.Module):
    def __init__(self):
        super().__init__()
        self.linear = nn.Linear(8, 8)

    def forward(self, x):
        return self.linear(x)

model = LinearModel().eval()

# 1. Prepare for quantization
quant_config = GPTQConfig()
prepared_model = prepare(model, quant_config)

# 2. Calibration
for d in dataset:
    prepared_model(d)

# 3. Apply GPTQ
quantized_model = convert(prepared_model, quant_config)

For detailed documentation, design notes, and contributing guidelines, see tico/quantization/README.md.

For Developers

Testing & Code Formatting

Run below commands to configure testing or formatting environment.

Refer to the dedicated section to have more fine-grained control.

$ ./ccex configure                          # to set up testing & formatting environment
$ ./ccex configure format                   # to set up only formatting environment
$ ./ccex configure test                     # to set up only testing environment

Available options

--torch_ver <torch version> To install a specific torch family package(ex. torchvision) version (default: 2.6)
- Available : '2.5', '2.6', 'nightly'

$ ./ccex configure                          # to set up testing & formatting environment with stable2.6.x version
$ ./ccex configure test                     # to set up only testing environment with stable 2.6.x version
$ ./ccex configure test --torch_ver 2.5     # to set up only testing environment with stable 2.5.x version
$ ./ccex configure test --torch_ver nightly     # to set up only testing environment with nightly version

Testing

Test congifure

Run below commands to install requirements for testing.

NOTE TICO will be installed in an editable mode.

./ccex configure test

# without editable install
./ccex configure test --dist

Test All

Run below commands to run the all unit tests.

NOTE Unit tests don't include model test.

./ccex test
# OR
./ccex test run-all-tests

Test Subset

To run subset of test.modules.*, Run ./ccex test -k <keyword>

For example, to run tests in specific sub-directory (op, net, ..)

# To run tests in specific sub-directory (op/, net/ ..)
./ccex test -k op
./ccex test -k net

# To run tests in one file (single/op/add, single/op/sub, ...)
./ccex test -k add
./ccex test -k sub

# To run SimpleAdd test in test/modules/single/op/add.py
./ccex test -k SimpleAdd

To see the full debug log, add -v or TICO_LOG=4.

TICO_LOG=4 ./ccex test -k add
# OR
./ccex test -v -k add

To dump intermediate torch graph ir as .png, add TICO_GRAPH_DUMP=1

TICO_GRAPH_DUMP=1 ./ccex test -k add
# Images are dumped into `$(pwd)/.tico_temp`

Test Model

If you want to test them locally, you can do so by navigating to each model directory, installing the dependencies listed in its requirements.txt, and running the tests one by one.

$ pip install -r test/modules/model/<model_name>/requirements.txt
# Run test for a single model
$ ./ccex test -m <model_name>
# Run models whose names contain "Llama" (e.g., Llama, LlamaDecoderLayer, LlamaWithGQA, etc.)
# Note that you should use quotes for the wildcard(*) pattern
$ ./ccex test -m "Llama*"

For example, to run a single model

./ccex test -m InceptionV3

Runtime Options

By default, ./ccex test runs all modules with the circle-interpreter engine. You can override this and run tests using the onert runtime instead.

0. Install ONERT

pip install onert

1. Command-Line Flag

Use the --runtime (or -r) flag to select a runtime:

# Run with the default circle-interpreter
./ccex test

# Run all tests with onert
./ccex test --runtime onert
# or
./ccex test -r onert

2. Environment Variable

You can also set the CCEX_RUNTIME environment variable:

# Temporarily override for one command
CCEX_RUNTIME=onert ./ccex test

# Persist in your shell session
export CCEX_RUNTIME=onert
./ccex test

Supported Runtimes

circle-interpreter (default): uses the Circle interpreter for inference.
onert: uses the ONERT package for inference, useful when the Circle interpreter cannot run a given module.

Code Formatting

Format configure

Run below commands to install requirements for formatting.

./ccex configure format

Format run

./ccex format

Release files for tico 0.2.0.dev260629

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tico 0.2.0.dev260629
File	Size	Uploaded
tico-0.2.0.dev260629.tar.gz	556.9 kB	Jun 29, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for tico 0.2.0.dev260629
File	Interpreter	ABI	Platform	Reset
tico-0.2.0.dev260629-py3-none-any.whl 937.2 kB Jun 29, 2026	Python 3	none	any	Details

Total release size: 1.5 MB

Release files / tico-0.2.0.dev260629.tar.gz

Download URL	tico-0.2.0.dev260629.tar.gz
Size	556.9 kB
Tags	Source
SHA-256 checksum How to use checksums	`8efcda0a73fb08ad8bfeb1f7f18f9aebe6471ff601d537913acc1410d2d70c04`
BLAKE2b-256 checksum How to use checksums	`980ebd059c8853a092931a27dd975406c2917f899a54c26d67f2d48e77a4aea1`
Upload date	Jun 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Samsung/TICO
Publishing commit: github.com/Samsung/TICO/tree/67f979d428f00a79a593d13f514aa34376bd06a9

Workflow

Publishing configuration: github.com/Samsung/TICO/blob/67f979d428f00a79a593d13f514aa34376bd06a9/.github/workflows/publish-nightly-package.yaml
Publishing logs: github.com/Samsung/TICO/actions/runs/28401235729/attempts/1

Artifact

Subject: tico-0.2.0.dev260629.tar.gz
SHA-256 checksum: 8efcda0a73fb08ad8bfeb1f7f18f9aebe6471ff601d537913acc1410d2d70c04 Verifying attestations

Release files / tico-0.2.0.dev260629-py3-none-any.whl

Download URL	tico-0.2.0.dev260629-py3-none-any.whl
Size	937.2 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`98ee8314c02db9906429d3f4b49addce0d5dda93a60d14eddb81915bf99e2b59`
BLAKE2b-256 checksum How to use checksums	`98357f1626dddfc24c35ee6a66d2717cb3ca4c6da32eb6407b864e054b7b605e`
Upload date	Jun 29, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.12`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/Samsung/TICO
Publishing commit: github.com/Samsung/TICO/tree/67f979d428f00a79a593d13f514aa34376bd06a9

Workflow

Publishing configuration: github.com/Samsung/TICO/blob/67f979d428f00a79a593d13f514aa34376bd06a9/.github/workflows/publish-nightly-package.yaml
Publishing logs: github.com/Samsung/TICO/actions/runs/28401235729/attempts/1

Artifact

Subject: tico-0.2.0.dev260629-py3-none-any.whl
SHA-256 checksum: 98ee8314c02db9906429d3f4b49addce0d5dda93a60d14eddb81915bf99e2b59 Verifying attestations