This release is a pre-release and may not be stable for production use.
TICO (Torch IR to Circle ONE) is a Python library that converts PyTorch modules into Circle models — a lightweight and efficient representation in ONE designed for optimized on-device neural network inference.
Highlights
- One-call conversion —
tico.convert()turns annn.Moduleinto a ready-to-deploy.circlebinary. .pt2support — convert savedtorch.exportprograms via the Python API or thept2-to-circlecommand-line tool.- Run Circle models in Python — execute converted models directly for quick parity checks against PyTorch.
- Circle artifact tools — inspect, verify, extract, optimize, and clean up exported
.circlegraphs with thetico.circleAPI ortico-circleCLI. - Quantization toolkit — a unified
prepare/convertAPI with GPTQ, PTQ (WrapQ), SmoothQuant, SpinQuant, and CLE, plus config-driven CLI recipes for LLMs and VLMs.
Installation
Prerequisites
- Python 3.10+
- (Optional) one-compiler — only required to run inference with converted Circle models. Conversion itself does not need it.
We highly recommend using a virtual environment (e.g., conda, venv).
From PyPI
pip install tico
From source
git clone https://github.com/Samsung/TICO.git
cd TICO
./ccex build # generates build/ and dist/
./ccex install # installs the package
./ccex install options
| Option | Description |
|---|---|
--dist |
Install from the built wheel (default is editable mode) |
--torch_ver <ver> |
Torch version to install: a configured family (2.5 ~ 2.13; 2.5 ~ 2.9 are legacy best-effort and 2.13 is a candidate), an exact version (e.g. 2.13.0+cu132), nightly (repository-pinned), or nightly-latest (moving Torch/TorchVision pair). Default: 2.12 |
--cuda_ver <maj.min> |
Override the detected CUDA version (e.g. 12.1) |
--cpu_only |
Force a CPU-only Torch installation |
./ccex install pins the newest qualified stable family for a reproducible source
setup. Older configured families remain explicitly installable, while pyproject.toml
keeps an unbounded torch dependency so pip install does not reject a user-managed
Torch version. See the PyTorch version policy for the
installer, support, and CI tiers.
Quick start
import tico
import torch
class AddModule(torch.nn.Module):
def forward(self, x, y):
return x + y
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')
Converting a saved .pt2 file from the command line:
pt2-to-circle -i add.pt2 -o add.circle
See the Getting Started guide for compile configurations,
.pt2 conversion, and running Circle models directly in Python.
Circle artifact tools
tico.circle provides Python APIs and the tico-circle CLI for inspecting and
transforming exported .circle files.
tico-circle inspect model.circle --tensors --operators
tico-circle verify model.circle
tico-circle extract model.circle --ops 20-64 -o region.circle
tico-circle optimize model.circle --preset o1 -o model.o1.circle
verify performs a static internal-consistency check of the Circle artifact itself, including
indices, graph connections, buffers, signatures, and subgraph references. It does not
run inference or validate numerical accuracy or backend compatibility.
See the Circle artifact tools guide for the Python API, exact verification rules, extraction semantics, semantic optimization and cleanup passes, O1 scheduling, multi-subgraph and signature behavior, and stream pipelines.
Quantization
The tico.quantization module provides a unified,
modular interface for quantizing neural networks — including large language models —
through a simple two-step prepare → convert workflow:
from tico.quantization import prepare, convert
from tico.quantization.config.gptq import GPTQConfig
prepared_model = prepare(model.eval(), GPTQConfig())
for d in dataset: # calibration
prepared_model(d)
quantized_model = convert(prepared_model, GPTQConfig())
- Quantization overview — API, architecture, and how to add a new algorithm
- Quantization algorithms — GPTQ, SmoothQuant, SpinQuant, CLE, …
- Config-driven CLI examples — quantize, evaluate, and inspect LLM/VLM recipes from the command line
Documentation
For users
| Document | Description |
|---|---|
| Getting Started | Converting modules and .pt2 files, compile configuration, running Circle models directly in Python |
| Circle artifact tools | Inspecting, verifying, extracting, optimizing, and cleaning up exported Circle models |
| Quantization | The prepare/convert quantization API and toolkit |
| Quantization examples | Command-line quantization, evaluation, and debugging workflows |
For developers
| Document | Description |
|---|---|
| Development guide | Environment setup, testing, and code formatting with ./ccex |
| System design | Architecture, pass pipeline, invariants, and behavior design |
| Circle artifact tools | Circle pass contracts, index rewriting, verification, and test expectations |
| Requirements | Functional and non-functional requirements |
| System tests | System-level test coverage |
Contributing
Contributions are welcome! For quantization algorithms, start with the quantization contribution guide and the recipes developer guide. Before submitting a PR, set up the development environment and run the tests and formatter as described in the development guide.
License
Licensed under the Apache License 2.0 — see LICENSE.
1 maintainer
Release files for tico 0.2.0.dev260924
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| tico-0.2.0.dev260924.tar.gz | 1.0 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| tico-0.2.0.dev260924-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 2.5 MB
Release files / tico-0.2.0.dev260924.tar.gz
| Download URL | tico-0.2.0.dev260924.tar.gz |
|---|---|
| Size | 1.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5e9ed668a019f7d4283c75f1dce9f60b0f77407e14cbb9e99e47d707bdd0bab7
|
|
BLAKE2b-256 checksum How to use checksums |
0152f960da10a8a15aadad46c6d51407f056062f6a9c0600467274985aebdc60
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency logRelease files / tico-0.2.0.dev260924-py3-none-any.whl
| Download URL | tico-0.2.0.dev260924-py3-none-any.whl |
|---|---|
| Size | 1.5 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
de672b74c1fe54f043e600739181866c6d17a6340b2b396c322d42ff041fcafc
|
|
BLAKE2b-256 checksum How to use checksums |
e0359f761e62870af619660c6538e2a2fbd54df87c9735b5daf14d33a7a3026b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 24, 2026.
Transparency log
