{"id":29190024,"url":"https://github.com/samsung/tico","last_synced_at":"2025-07-01T23:33:02.141Z","repository":{"id":285680598,"uuid":"955738226","full_name":"Samsung/TICO","owner":"Samsung","description":"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.","archived":false,"fork":false,"pushed_at":"2025-06-26T08:23:40.000Z","size":412,"stargazers_count":15,"open_issues_count":37,"forks_count":18,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-06-26T09:31:13.260Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Samsung.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-27T05:46:38.000Z","updated_at":"2025-06-26T08:23:44.000Z","dependencies_parsed_at":"2025-04-17T09:18:15.462Z","dependency_job_id":"347f3f2b-0e6f-4f8e-82a7-f8f9376c4793","html_url":"https://github.com/Samsung/TICO","commit_stats":null,"previous_names":["samsung/tico"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Samsung/TICO","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2FTICO","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2FTICO/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2FTICO/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2FTICO/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Samsung","download_url":"https://codeload.github.com/Samsung/TICO/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Samsung%2FTICO/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263049877,"owners_count":23405723,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-07-01T23:31:16.446Z","updated_at":"2025-07-01T23:33:02.115Z","avatar_url":"https://github.com/Samsung.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# TICO\n\n_TICO_ (Torch IR to Circle [ONE](https://github.com/Samsung/ONE)) is a python library for converting \n Pytorch modules into a circle model that is a lightweight and efficient representation in ONE \ndesigned for optimized on-device neural network inference.\n\n## Table of Contents\n\n### For Users\n\n- [Installation](#installation)\n- [Getting Started](#getting-started)\n  - [From torch module](#from-torch-module)\n  - [From .pt2](#from-pt2)\n  - [Running circle models directly in Python](#running-circle-models-directly-in-python)\n\n### For Developers\n\n- [Testing \u0026 Code Formatting](#testing--code-formatting)\n- [Testing](#testing)\n- [Code Formatting](#code-formatting)\n\n## For Users\n\n### Installation\n\n0. Prerequisites\n\n- Python 3.10\n- [one-compiler nightly](https://github.com/Samsung/TICO/issues/2)\n  - This project depends on [ONE](https://github.com/Samsung/ONE) Compiler, and it uses \n  nightly features that are not yet available in the official release. Until one-compiler 1.30.0\n  is released, you must use a prebuilt nighlty version of ONE Compiler.\n\nWe highly recommend to use a virtual env, e.g., conda.\n\n1. Clone this repo\n\n2. Build python package\n\n```bash\n./ccex build\n```\n\nThis will generate `build` and `dist` directories in the root directory.\n\n3. Install generated package\n\n```bash\n./ccex install\n```\n\n**Available options**\n- `--dist` To install the package from .whl (without this option, _TICO_ is installed in an editable mode)\n- `--torch_ver \u003ctorch version\u003e` To install a specific torch version (default: 2.6).\n  - Available \u003ctorch version\u003e: 2.5, 2.6, nightly\n\n4. Now you can convert a torch module to a `.circle`.\n\n### Getting started\n\nThis tutorial explains how you can use _TICO_ to generate a circle model from a torch module. \n\nLet's assume we have a torch module.\n\n```python\nimport tico\nimport torch\n\nclass AddModule(torch.nn.Module):\n    def __init__(self):\n        super().__init__()\n\n    def forward(self, x, y):\n        return x + y\n```\n\n**NOTE**\n_TICO_ internally uses [torch.export](https://pytorch.org/docs/stable/export.html#torch-export).\nTherefore, the torch module must be 'export'able. Please see \n[this document](https://pytorch.org/docs/stable/export.html#limitations-of-torch-export) \nif you have any trouble to export.\n\n#### From torch module\n\nYou can convert a torch module to a circle model with these steps.\n\n```python\ntorch_module = AddModule()\nexample_inputs = (torch.ones(4), torch.ones(4))\n\ncircle_model = tico.convert(torch_module.eval(), example_inputs)\ncircle_model.save('add.circle')\n```\n\n**NOTE**\nPlease make sure to call `eval()` on the PyTorch module before passing it to our API.\nThis ensures the model runs in inference mode, disabling layers like dropout and\nbatch normalization updates.\n\n**Compile with configuration**\n\n```python\nfrom test.modules.op.add import AddWithCausalMaskFolded\n\ntorch_module = AddWithCausalMaskFolded()\nexample_inputs = torch_module.get_example_inputs()\n\nconfig = tico.CompileConfigV1()\nconfig.legalize_causal_mask_value = True\ncircle_model = tico.convert(torch_module, example_inputs, config = config)\ncircle_model.save('add_causal_mask_m120.circle')\n```\n\nWith `legalize_causal_mask_value` option on, causal mask value is converted from \n -inf to -120, creating a more quantization-friendly circle model with the cost of \nslight accuracy drop.\n\n#### From .pt2\n\nThe torch module can be exported and saved as `.pt2` file (from PyTorch 2.1).\n\n```python\nmodule = AddModule()\nexample_inputs = (torch.ones(4), torch.ones(4))\n\nexported_program = torch.export.export(module, example_inputs)\ntorch.export.save(exported_program, 'add.pt2')\n```\n\nThere are two ways to convert `.pt2` file: python api, command line tool.\n\n- Python API\n\n```python\ncircle_model = tico.convert_from_pt2('add.pt2')\ncircle_model.save('add.circle')\n```\n\n- Command Line Tool\n\n```bash\npt2-to-circle -i add.pt2 -o add.circle\n```\n\n- Command Line Tool with configuration\n\n```bash\npt2-to-circle -i add.pt2 -o add.circle -c config.yaml\n```\n\n```yaml\n# config.yaml\n\nversion: '1.0' # You must specify the config version. \nlegalize_causal_mask_value: True\n```\n\n#### Running circle models directly in Python\n\nAfter circle export, you can run the model directly in Python.\n\nNote that you should install one-compiler package first.\n\nThe output types are numpy.ndarray.\n\n```python\ntorch_module = AddModule()\nexample_inputs = (torch.ones(4), torch.ones(4))\n\ncircle_model = tico.convert(torch_module, example_inputs)\ncircle_model(*example_inputs)\n# numpy.ndarray([2., 2., 2., 2.], dtype=float32)\n```\n\n## For Developers\n\n### Testing \u0026 Code Formatting\n\nRun below commands to configure testing or formatting environment.\n\nRefer to the dedicated section to have more fine-grained control.\n\n```bash\n$ ./ccex configure                          # to set up testing \u0026 formatting environment\n$ ./ccex configure format                   # to set up only formatting environment\n$ ./ccex configure test                     # to set up only testing environment\n```\n\n**Available options**\n- `--torch_ver \u003ctorch version\u003e` To install a specific torch family package(ex. torchvision) version (default: 2.6)\n  - Available \u003ctorch version\u003e: '2.5', '2.6', 'nightly'\n\n```bash\n$ ./ccex configure                          # to set up testing \u0026 formatting environment with stable2.6.x version\n$ ./ccex configure test                     # to set up only testing environment with stable 2.6.x version\n$ ./ccex configure test --torch_ver 2.5     # to set up only testing environment with stable 2.5.x version\n$ ./ccex configure test --torch_ver nightly     # to set up only testing environment with nightly version\n```\n\n### Testing\n\n#### Test congifure\n\nRun below commands to install requirements for testing.\n\n**NOTE** `TICO` will be installed in an editable mode.\n\n```bash\n./ccex configure test\n\n# without editable install\n./ccex configure test --dist\n```\n\n#### Test All\n\nRun below commands to run the all unit tests.\n\n**NOTE** Unit tests don't include model test.\n\n```bash\n./ccex test\n# OR\n./ccex test run-all-tests\n```\n\n#### Test Subset\n\nTo run subset of `test.modules.*`,\nRun `./ccex test -k \u003ckeyword\u003e`\n\n\nFor example, to run tests in specific sub-directory (op, net, ..)\n```bash\n# To run tests in specific sub-directory (op/, net/ ..)\n./ccex test -k op\n./ccex test -k net\n\n# To run tests in one file (single/op/add, single/op/sub, ...)\n./ccex test -k add\n./ccex test -k sub\n\n# To run SimpleAdd test in test/modules/single/op/add.py\n./ccex test -k SimpleAdd\n```\n\nTo see the full debug log, add `-v` or `TICO_LOG=4`.\n\n```bash\nTICO_LOG=4 ./ccex test -k add\n# OR\n./ccex test -v -k add\n```\n\n#### Test Model\n\nIf you want to test them locally, you can do so by navigating to each model directory, \n installing the dependencies listed in its `requirements.txt`, and running the tests one by one.\n```bash\n$ pip install -r test/modules/model/\u003cmodel_name\u003e/requirements.txt\n# Run test for a single model\n$ ./ccex test -m \u003cmodel_name\u003e\n```\n\nFor example, to run a single model\n```\n./ccex test -m InceptionV3\n```\n\n#### Runtime Options\n\nBy default, `./ccex test` runs all modules with the `circle-interpreter` engine.\n You can override this and run tests using the `onert` runtime instead.\n\n\n##### 0. Installing ONERT Nightly\n\nSome ONERT features are only available in the nightly build until the next official release.\n To install the ONERT wheel from the issue comment:\n\n1. Download the `.whl` file linked \nin [the relevant Github issue comment](https://github.com/Samsung/TICO/issues/2#issuecomment-2841487306).\n2. Install it with pip, for example:\n\n```bash\npip install /path/to/onert_nightly.whl\n```\n\n##### 1. Command-Line Flag\n\nUse the `--runtime` (or `-r`) flag to select a runtime:\n\n```bash\n# Run with the default circle-interpreter\n./ccex test\n\n# Run all tests with onert\n./ccex test --runtime onert\n# or\n./ccex test -r onert\n```\n\n##### 2. Environment Variable\n\nYou can also set the `CCEX_RUNTIME` environment variable:\n\n```bash\n# Temporarily override for one command\nCCEX_RUNTIME=onert ./ccex test\n\n# Persist in your shell session\nexport CCEX_RUNTIME=onert\n./ccex test\n```\n\n##### Supported Runtimes\n\n- circle-interpreter (default): uses the Circle interpreter for inference.\n- onert: uses the ONERT package for inference, useful when the Circle interpreter\n cannot run a given module.\n\n### Code Formatting\n\n#### Format configure\n\nRun below commands to install requirements for formatting.\n\n```bash\n./ccex configure format\n```\n\n#### Format run\n\n```bash\n./ccex format\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamsung%2Ftico","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamsung%2Ftico","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamsung%2Ftico/lists"}