tensora-taco 0.1.2
Python wrapper around the TACO CLI as an alternative kernel generator for Tensora
License: MIT
Requires Python: >=3.10,<4.0

# TACO CLI interface for Tensora

This Python package provides a Python wrapper around the CLI tool of the [Tensor Algebra Compiler](http://tensor-compiler.org/) (TACO). This package exists to support the `tensora[taco]` extra of [Tensora](https://tensora.drhagen.com). The main [`tensora`](https://github.com/drhagen/tensora) package is pure Python, and including TACO by default would complicate its distribution.

The `tensora-taco` Python package contains one function `taco_cli` that takes the `taco` CLI arguments of as a list of strings, and returns a [`Result`](https://returns.readthedocs.io/en/latest/pages/result.html).

```python
from tensora_taco import taco_cli

result = taco_cli(["y(i) = A(i,j) * x(j)", "-print-nocolor", "-print-compute"])

kernel = result.unwrap()
# // Generated by the Tensor Algebra Compiler (tensor-compiler.org)
#
# int compute(taco_tensor_t *y, taco_tensor_t *A, taco_tensor_t *x) {
#   int y1_dimension = (int)(y->dimensions[0]);
#   double* restrict y_vals = (double*)(y->vals);
#   int A1_dimension = (int)(A->dimensions[0]);
#   int A2_dimension = (int)(A->dimensions[1]);
#   double* restrict A_vals = (double*)(A->vals);
#   int x1_dimension = (int)(x->dimensions[0]);
#   double* restrict x_vals = (double*)(x->vals);
#
#   #pragma omp parallel for schedule(runtime)
#   for (int32_t i = 0; i < A1_dimension; i++) {
#     double tjy_val = 0.0;
#     for (int32_t j = 0; j < x1_dimension; j++) {
#       int32_t jA = i * A2_dimension + j;
#       tjy_val += A_vals[jA] * x_vals[j];
#     }
#     y_vals[i] = tjy_val;
#   }
#   return 0;
# }
```

## Contributing

`tensora-taco` is a free and open source project developed under an MIT license. Development occurs at the [GitHub project](https://github.com/drhagen/tensora-taco).

### Cloning the repo

To make a local copy of `tensora-taco`, clone the repository with git. This project depends on TACO at build time as a submodule, so it must be cloned as well in order to build the project:

```shell
git clone --recurse-submodules https://github.com/drhagen/tabeline.git
```

### Installing from source

`tensora-taco` uses Poetry as its packaging and dependency manager. In whatever Python environment you prefer, [install Poetry](https://python-poetry.org/docs/) and then use Poetry to install this package and its dependencies:

```shell
pip install poetry
poetry install
```

### Testing

`tensora-taco` uses pytest to run the tests in the `tests/` directory. The test command is encapsulated with Nox:

```shell
poetry run nox -s test
```

This will try to test with all compatible Python versions that `nox` can find. To run the tests with only a particular version, run something like this:

```shell
poetry run nox -s test-3.11
```

It is good to run the tests locally before making a PR, but it is not necessary to have all Python versions run. It is rare for a failure to appear in a single version, and the CI will catch it anyway.


### Code quality

`tensora-taco` uses Ruff to ensure a minimum standard of code quality. The code quality commands are encapsulated with Nox:

```shell
poetry run nox -s ruff
```

### Making a release

1. Bump
    1. Increment version in `pyproject.toml`
    2. Commit with message "Bump version number to X.Y.Z"
    3. Push commit to GitHub
    4. Check [CI](https://github.com/drhagen/tensora-taco/actions/workflows/ci.yml) to ensure all tests pass
2. Tag
    1. Tag commit with "vX.Y.Z"
    2. Push tag to GitHub
    3. Wait for [build](https://github.com/drhagen/tensora-taco/actions/workflows/release.yml) to finish
    4. Check [PyPI](https://pypi.org/project/tensora-taco/) for good upload
3. Document
    1. Create [GitHub release](https://github.com/drhagen/tensora-taco/releases) with name "Tensora TACO X.Y.Z" and major changes in body