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: thirdparty/01176a7d09b76db1.json
License-File: thirdparty/05f3b88351988ecf
License-File: thirdparty/08fc458c51d99453.json
License-File: thirdparty/0b01625d853911cd.0BSD
License-File: thirdparty/0e111337b25494a7.md
License-File: thirdparty/0fcc0510a8ace3c5.json
License-File: thirdparty/103166b62b80443a.md
License-File: thirdparty/1180dc3ee90e3bd4.json
License-File: thirdparty/12dde7e20fd8439d.txt
License-File: thirdparty/183565b004626bff.json
License-File: thirdparty/19027ec4b3aa6714.json
License-File: thirdparty/19060ef465e1797d.txt
License-File: thirdparty/19434516dc96e26d.json
License-File: thirdparty/19cac2ec18885369.txt
License-File: thirdparty/1b0bb34c79c52427.json
License-File: thirdparty/211e7d737d6179a0.md
License-File: thirdparty/2169a9a139c5c16e.txt
License-File: thirdparty/268b0ca06759d31e.md
License-File: thirdparty/28cad82ce1379dc5.md
License-File: thirdparty/2b3ded22d47b83c3.json
License-File: thirdparty/30740199a52e0a26.json
License-File: thirdparty/31b15de82aa19a84
License-File: thirdparty/322ac46d870c8aee.md
License-File: thirdparty/327bef51b43a475a.json
License-File: thirdparty/3972dc9744f6499f
License-File: thirdparty/3b2f81fe21d181c4.txt
License-File: thirdparty/3f2c1ffa76383a55
License-File: thirdparty/41190663b77bee53.md
License-File: thirdparty/454ec7350e478e03.md
License-File: thirdparty/469778be8f33d54e.md
License-File: thirdparty/47a26beb94e3f6b3.txt
License-File: thirdparty/4860083caa0de2ac.txt
License-File: thirdparty/49819ba57b9ccb00.json
License-File: thirdparty/4bbee99b11596ddb.json
License-File: thirdparty/55ab95cb90bd87e0.json
License-File: thirdparty/585483905b13d4b4
License-File: thirdparty/5c4d492c08f9d5ba.json
License-File: thirdparty/6142778c8df76772.json
License-File: thirdparty/616a3ad264ce29b8
License-File: thirdparty/67acf90238aab8a8.json
License-File: thirdparty/6f5828a57223d4cc.md
License-File: thirdparty/733ea42a2891faeb.json
License-File: thirdparty/74463029bca1d31f.json
License-File: thirdparty/748d20161ddef944.json
License-File: thirdparty/767dd09158f31439.txt
License-File: thirdparty/7774012637c13155.json
License-File: thirdparty/7b8fb5b24bc75b86.txt
License-File: thirdparty/7d5450cb2d142651.txt
License-File: thirdparty/8099dc3cf9502c33.RTF
License-File: thirdparty/84ec75f30bc8f8b9.json
License-File: thirdparty/871e77ae5c7e3d14.json
License-File: thirdparty/8db000e158c162e7.md
License-File: thirdparty/92c10699884321f1.md
License-File: thirdparty/956a106e0f4e2f83.txt
License-File: thirdparty/99002541c19c3ebb.json
License-File: thirdparty/9d4098846018319c.md
License-File: thirdparty/9d6b43ce4d8de0c8.EXCEPTION
License-File: thirdparty/a14cc25e10d40a3a.txt
License-File: thirdparty/a732977853530066.md
License-File: thirdparty/a804dff0ead9fadc.txt
License-File: thirdparty/a81491a0243fa1d0.txt
License-File: thirdparty/a85ca13fdf90160b.md
License-File: thirdparty/aea41976c720f91b
License-File: thirdparty/afd6f4096d20050f.json
License-File: thirdparty/b0fd592d4ead5631.txt
License-File: thirdparty/b151ebf76a637986.json
License-File: thirdparty/b4bc2f4fa1c95778.md
License-File: thirdparty/b68cf849de1222ef.json
License-File: thirdparty/b7675b75b3bbcfd2.json
License-File: thirdparty/b9b15704e1772f86.json
License-File: thirdparty/c17011467b4fe6e2
License-File: thirdparty/c364f9e15c3d7408.json
License-File: thirdparty/c6e0d0f8df7ed01f.md
License-File: thirdparty/c71d239df91726fc.txt
License-File: thirdparty/ca7f6ce097b96fd8.json
License-File: thirdparty/cbc31d023acca2e3.rst
License-File: thirdparty/cf5619f25b112d5c.md
License-File: thirdparty/cf89b37107c22cf8.TXT
License-File: thirdparty/d208152e2777ffd0
License-File: thirdparty/d497029cb6e8e33b.json
License-File: thirdparty/d544761558b51086.txt
License-File: thirdparty/d6ce4743ce845c1d.json
License-File: thirdparty/d78dbb208b80d92b
License-File: thirdparty/e2c71babfd18a8e6.txt
License-File: thirdparty/e32ff4e00d9d9493
License-File: thirdparty/e340270d4f643845
License-File: thirdparty/e7d4f4fb20358f31.md
License-File: thirdparty/edaef632cbb643e4.GPLv2
License-File: thirdparty/f2e91b3a61f93f5d.json
License-File: thirdparty/f5c0360461bcefdb.json
License-File: thirdparty/f684083aca0dc1bb.json
License-File: thirdparty/f6d63ba851f70ab0.json
License-File: thirdparty/f7b14309e5f54e50.txt
License-File: thirdparty/f8b7b26ccec430af.json
License-File: thirdparty/f8ce918fe7311ce2.txt
License-File: thirdparty/f90f507defe1986d.json
License-File: thirdparty/fbc539f47d0cf83b.txt
License-File: thirdparty/febfb69a5b058f55.txt
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.
