Metadata-Version: 2.4
Name: kaksturbo
Version: 1.1.0rc10
Summary: Codon model averaging with CPU/GPU execution and numerical diagnostics
Requires-Python: >=3.11
Maintainer: Taishan Li
Maintainer-email: litaishan@caf.ac.cn
License-Expression: GPL-3.0-only
License-File: LICENSE
License-File: licenses/KaKs_Calculator_2_LICENSE
License-File: licenses/OpenBLAS-bundle/LICENSE.txt
License-File: licenses/OpenBLAS-bundle/numpy/_core/include/numpy/libdivide/LICENSE.txt
License-File: licenses/OpenBLAS-bundle/numpy/_core/src/common/pythoncapi-compat/COPYING
License-File: licenses/OpenBLAS-bundle/numpy/_core/src/highway/LICENSE
License-File: licenses/OpenBLAS-bundle/numpy/_core/src/multiarray/dragon4_LICENSE.txt
License-File: licenses/OpenBLAS-bundle/numpy/_core/src/npysort/x86-simd-sort/LICENSE.md
License-File: licenses/OpenBLAS-bundle/numpy/_core/src/umath/svml/LICENSE
License-File: licenses/OpenBLAS-bundle/numpy/fft/pocketfft/LICENSE.md
License-File: licenses/OpenBLAS-bundle/numpy/linalg/lapack_lite/LICENSE.txt
License-File: licenses/OpenBLAS-bundle/numpy/ma/LICENSE
License-File: licenses/OpenBLAS-bundle/numpy/random/LICENSE.md
License-File: licenses/OpenBLAS-bundle/numpy/random/src/distributions/LICENSE.md
License-File: licenses/OpenBLAS-bundle/numpy/random/src/mt19937/LICENSE.md
License-File: licenses/OpenBLAS-bundle/numpy/random/src/pcg64/LICENSE.md
License-File: licenses/OpenBLAS-bundle/numpy/random/src/philox/LICENSE.md
License-File: licenses/OpenBLAS-bundle/numpy/random/src/sfc64/LICENSE.md
License-File: licenses/OpenBLAS-bundle/numpy/random/src/splitmix64/LICENSE.md
License-File: licenses/Windows-OpenBLAS-bundle/LICENSE.txt
License-File: licenses/Windows-OpenBLAS-bundle/numpy/_core/include/numpy/libdivide/LICENSE.txt
License-File: licenses/Windows-OpenBLAS-bundle/numpy/_core/src/common/pythoncapi-compat/COPYING
License-File: licenses/Windows-OpenBLAS-bundle/numpy/_core/src/highway/LICENSE
License-File: licenses/Windows-OpenBLAS-bundle/numpy/_core/src/multiarray/dragon4_LICENSE.txt
License-File: licenses/Windows-OpenBLAS-bundle/numpy/_core/src/npysort/x86-simd-sort/LICENSE.md
License-File: licenses/Windows-OpenBLAS-bundle/numpy/_core/src/umath/svml/LICENSE
License-File: licenses/Windows-OpenBLAS-bundle/numpy/fft/pocketfft/LICENSE.md
License-File: licenses/Windows-OpenBLAS-bundle/numpy/linalg/lapack_lite/LICENSE.txt
License-File: licenses/Windows-OpenBLAS-bundle/numpy/ma/LICENSE
License-File: licenses/Windows-OpenBLAS-bundle/numpy/random/LICENSE.md
License-File: licenses/Windows-OpenBLAS-bundle/numpy/random/src/distributions/LICENSE.md
License-File: licenses/Windows-OpenBLAS-bundle/numpy/random/src/mt19937/LICENSE.md
License-File: licenses/Windows-OpenBLAS-bundle/numpy/random/src/pcg64/LICENSE.md
License-File: licenses/Windows-OpenBLAS-bundle/numpy/random/src/philox/LICENSE.md
License-File: licenses/Windows-OpenBLAS-bundle/numpy/random/src/sfc64/LICENSE.md
License-File: licenses/Windows-OpenBLAS-bundle/numpy/random/src/splitmix64/LICENSE.md
License-File: licenses/intel-openmp-2025.0.0-haa95532_1165.json
License-File: licenses/mkl-2023.1.0-h6a75c08_48682.json
License-File: licenses/recovered-v1/README.txt
License-File: licenses/recovered-v1/bzip2-1.0.8/installed-header-copyright.txt
License-File: licenses/recovered-v1/expat/COPYING
License-File: licenses/recovered-v1/expat/conda-package.json
License-File: licenses/recovered-v1/gcc-runtime/RUNTIME.LIBRARY.EXCEPTION
License-File: licenses/recovered-v1/installed-package-metadata/bzip2-1.0.8-h2bbff1b_6.json
License-File: licenses/recovered-v1/installed-package-metadata/cuda-cupti-12.4.127-0.json
License-File: licenses/recovered-v1/installed-package-metadata/cuda-nvtx-12.4.127-0.json
License-File: licenses/recovered-v1/installed-package-metadata/intel-openmp-2025.0.0-haa95532_1165.json
License-File: licenses/recovered-v1/installed-package-metadata/libexpat-2.8.4-hd7fb8db_0.json
License-File: licenses/recovered-v1/installed-package-metadata/libffi-3.4.8-h42d73b9_3.json
License-File: licenses/recovered-v1/installed-package-metadata/libwinpthread-12.0.0.r4.gg4f2fc60ca-h57928b3_10.json
License-File: licenses/recovered-v1/installed-package-metadata/libzlib-1.3.2-h1c6eee0_0.json
License-File: licenses/recovered-v1/installed-package-metadata/mingw-headers-installed.json
License-File: licenses/recovered-v1/installed-package-metadata/mkl-2023.1.0-h6a75c08_48682.json
License-File: licenses/recovered-v1/installed-package-metadata/openssl-3.5.8-hbb43b14_0.json
License-File: licenses/recovered-v1/installed-package-metadata/python-3.11.16-hb00fc5c_0.json
License-File: licenses/recovered-v1/installed-package-metadata/sqlite-3.53.4-hee5a0db_0.json
License-File: licenses/recovered-v1/installed-package-metadata/tbb-2021.8.0-h59b6b97_0.json
License-File: licenses/recovered-v1/installed-package-metadata/ucrt-10.0.22621.0-haa95532_0.json
License-File: licenses/recovered-v1/installed-package-metadata/vc-14.3-h2df5915_12.json
License-File: licenses/recovered-v1/installed-package-metadata/vc14_runtime-14.44.35208-h4927774_12.json
License-File: licenses/recovered-v1/installed-package-metadata/vs2015_runtime-14.44.35208-ha6b5a95_12.json
License-File: licenses/recovered-v1/installed-package-metadata/xz-5.8.2-h53af0af_0.json
License-File: licenses/recovered-v1/installed-package-metadata/zlib-1.3.2-h1c6eee0_0.json
License-File: licenses/recovered-v1/intel-openmp-2025.0.0/license.txt
License-File: licenses/recovered-v1/intel-openmp-2025.0.0/third-party-programs.txt
License-File: licenses/recovered-v1/intel-openmp-2025.0.0/tpp.txt
License-File: licenses/recovered-v1/inventory.json
License-File: licenses/recovered-v1/kaks-calculator-2.0.1/LICENSE
License-File: licenses/recovered-v1/libexpat-2.8.4/COPYING
License-File: licenses/recovered-v1/libffi-3.4.8/installed-header-license.txt
License-File: licenses/recovered-v1/libwinpthread-12.0.0/installed-header-notices.txt
License-File: licenses/recovered-v1/nvidia-cuda-12.4.127/EULA.txt
License-File: licenses/recovered-v1/openssl-3.5.8/LICENSE.txt
License-File: licenses/recovered-v1/provenance/bzip2-1.0.8-h2bbff1b_6.json
License-File: licenses/recovered-v1/provenance/intel-openmp-2025.0.0-upstream-v1.json
License-File: licenses/recovered-v1/provenance/libffi-3.4.8-h42d73b9_3.json
License-File: licenses/recovered-v1/provenance/mkl-2023.1.0-h6a75c08_48682.json
License-File: licenses/recovered-v1/provenance/mkl-2023.1.0-upstream-v1.json
License-File: licenses/recovered-v1/provenance/openssl-3.5.8-hbb43b14_0.json
License-File: licenses/recovered-v1/provenance/python-3.11.16-hb00fc5c_0.json
License-File: licenses/recovered-v1/provenance/sqlite-3.53.4-hee5a0db_0.json
License-File: licenses/recovered-v1/provenance/tbb-2021.8.0-upstream-v1.json
License-File: licenses/recovered-v1/provenance/torch-2.5.1-LICENSE-v1.json
License-File: licenses/recovered-v1/provenance/ucrt-10.0.22621.0-haa95532_0.json
License-File: licenses/recovered-v1/provenance/vc-14.3-h2df5915_12.json
License-File: licenses/recovered-v1/provenance/vc14_runtime-14.44.35208-h4927774_12.json
License-File: licenses/recovered-v1/provenance/vs2015_runtime-14.44.35208-ha6b5a95_12.json
License-File: licenses/recovered-v1/provenance/xz-5.8.2-h53af0af_0.json
License-File: licenses/recovered-v1/python-3.11.16/LICENSE_PYTHON.txt
License-File: licenses/recovered-v1/pytorch-2.5.1/LICENSE.txt
License-File: licenses/recovered-v1/sqlite-3.53.4/LICENSE.md
License-File: licenses/recovered-v1/tbb-2021.8.0/LICENSE.txt
License-File: licenses/recovered-v1/tbb-2021.8.0/notices_and_disclaimers.rst
License-File: licenses/recovered-v1/tbb-2021.8.0/third-party-programs.txt
License-File: licenses/recovered-v1/ucrt-10.0.22621.0/LICENSE.txt
License-File: licenses/recovered-v1/vc-14.3/LICENSE.TXT
License-File: licenses/recovered-v1/vc14_runtime-14.44.35208/LICENSE.RTF
License-File: licenses/recovered-v1/vc14_runtime-14.44.35208/LICENSE.TXT
License-File: licenses/recovered-v1/vs2015_runtime-14.44.35208/LICENSE.TXT
License-File: licenses/recovered-v1/xz-5.8.2/COPYING
License-File: licenses/recovered-v1/xz-5.8.2/COPYING.0BSD
License-File: licenses/recovered-v1/xz-5.8.2/COPYING.GPLv2
License-File: licenses/recovered-v1/zlib-1.3.2/LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3
Project-URL: Source, https://github.com/707728642li/KaKsTurbo
Project-URL: Issues, https://github.com/707728642li/KaKsTurbo/issues
Description-Content-Type: text/markdown

# KaKsTurbo

**Model-averaged Ka/Ks estimation with CPU/GPU execution and explicit numerical diagnostics.**

[Source and documentation](https://github.com/707728642li/KaKsTurbo) · [Quick start](https://github.com/707728642li/KaKsTurbo/blob/main/QUICKSTART.md) · [Raw CDS/PEP tutorial](https://github.com/707728642li/KaKsTurbo/blob/main/docs/RAW_CDS_TUTORIAL.md) · [Portable downloads](https://github.com/707728642li/KaKsTurbo/releases/tag/v1.1.0rc10)

KaKsTurbo estimates nonsynonymous and synonymous substitution rates (Ka and Ks), and their ratio, for batches of homologous codon-aligned gene pairs. It combines structured FP64 matrix computation, boundary-constrained optimization and complete fourteen-model averaging. The statistical model families and averaging framework build on established KaKs methods; this is a computational implementation with numerical validation, not a new biological selection test.

![KaKsTurbo workflow](https://raw.githubusercontent.com/707728642li/KaKsTurbo/main/docs/assets/workflow.png)

## Installation

This is a **release candidate**, version **1.1.0rc10**. Use Python **3.11 or later** on **Linux x86-64 (glibc >=2.17)** or **Windows x86-64**. ARM and macOS are not supported by these native wheels.

```bash
python -m pip install --only-binary=:all: kaksturbo==1.1.0rc10
kaksturbo --version
kaksturbo doctor --backend cpu
```

The wheel includes the pinned native CPU/GPU engine. CPU execution needs no CUDA installation. Existing portable GitHub downloads include their own Python runtime and remain available separately; this pip distribution uses the Python environment into which it is installed.

## Analyze aligned pairs

```bash
kaksturbo validate --input aligned_pairs.axt
kaksturbo run --input aligned_pairs.axt --output results_cpu --backend cpu --threads 8
kaksturbo status results_cpu
```

Supply codon-aligned AXT, or aligned FASTA plus an explicit pair manifest. Raw CDS and protein files require alignment first: the [Linux-first batch tutorial](https://github.com/707728642li/KaKsTurbo/blob/main/docs/RAW_CDS_TUTORIAL.md) provides MAFFT/PAL2NAL preparation scripts, examples and validation. Download those companion files from the repository or portable archive; they are not installed as commands by pip.

Use a new output directory. `kaksturbo resume results_cpu` continues a compatible interrupted run. Terminal progress reports committed pairs and processing stages; `--json` provides machine-readable command output and `--quiet` suppresses progress.

## GPU requirements

```bash
nvidia-smi
kaksturbo doctor --backend gpu --probe-gpu
kaksturbo run --input aligned_pairs.axt --output results_gpu --backend gpu --device cuda:0
```

One run uses one NVIDIA GPU. The compiled backend requires compute capability **>=8.6**, driver CUDA compatibility **>=12.9** and **>=8 GiB free memory**, including a 2 GiB reserve. A separate CUDA Toolkit is not needed. `auto` selects CPU. An explicit GPU request reports unavailable devices, incompatible drivers or insufficient memory with corrective guidance; it never silently falls back to CPU. See [device requirements](https://github.com/707728642li/KaKsTurbo/blob/main/docs/DEVICES.md).

## Outputs and interpretation

| Files | Contents |
|---|---|
| `result.tsv`, `results.jsonl` | Ka, Ks, Ka/Ks, pair identifiers and availability |
| `models.tsv`, `models.jsonl` | All fourteen model slots, weights and diagnostics |
| `pair_statistics.jsonl`, `qc.tsv` | Codon statistics and input quality |
| `quality_summary.txt`, `quality_summary.json` | Finite/NA coverage, boundaries, iteration caps and gradient flags |

Missing or unidentifiable estimates remain **NA with reasons**. Finite output and optimizer success are not convergence certificates. The projected-gradient diagnostic threshold remains **1e-8**; unresolved numerical cases are documented. Ka/Ks >1 alone is not a significance test for positive selection. Current scope is **MA under standard genetic code 1**, with FP64 and all fourteen models preserved.

Optional compatibility export writes a KaKs_Calculator-style table without replacing the standard results:

```bash
kaksturbo export results_cpu --format kaks-calculator --output compatible_results
```

Unsupported or unvalidated statistics are NA with explanations. File-format compatibility does not imply estimator equivalence.

## Performance, methods and support

The [performance report](https://github.com/707728642li/KaKsTurbo/blob/main/docs/PERFORMANCE.md) contains measured full-workflow comparisons, replicate counts, physical-core allocations and limitations. Speedups depend on sequence characteristics and estimator policies; no universal acceleration or cross-platform GPU ratio is claimed.

[Methods](https://github.com/707728642li/KaKsTurbo/blob/main/docs/METHODS.md) · [Numerical validation](https://github.com/707728642li/KaKsTurbo/blob/main/docs/NUMERICAL_VALIDATION.md) · [Input/output schema](https://github.com/707728642li/KaKsTurbo/blob/main/docs/INPUT_OUTPUT.md) · [Build and corresponding source](https://github.com/707728642li/KaKsTurbo/blob/main/docs/BUILDING_NATIVE.md)

**GPL-3.0-only**; third-party license notices are included. Maintainer: **Taishan Li**, litaishan@caf.ac.cn. [Report issues](https://github.com/707728642li/KaKsTurbo/issues) using minimal synthetic inputs. Cite the version and release URL; no paper DOI is currently assigned.
