alp-na 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. alp_na-1.0.0/.gitignore +5 -0
  2. alp_na-1.0.0/CHANGELOG.md +7 -0
  3. alp_na-1.0.0/CMakeLists.txt +64 -0
  4. alp_na-1.0.0/PKG-INFO +149 -0
  5. alp_na-1.0.0/README.md +140 -0
  6. alp_na-1.0.0/alp/__init__.py +23 -0
  7. alp_na-1.0.0/alp/_core.py +519 -0
  8. alp_na-1.0.0/alp/_matrices.py +120 -0
  9. alp_na-1.0.0/lib/alp/LICENSE +20 -0
  10. alp_na-1.0.0/lib/alp/njn_approx.hpp +89 -0
  11. alp_na-1.0.0/lib/alp/njn_doubletype.hpp +64 -0
  12. alp_na-1.0.0/lib/alp/njn_dynprogprob.cpp +295 -0
  13. alp_na-1.0.0/lib/alp/njn_dynprogprob.hpp +236 -0
  14. alp_na-1.0.0/lib/alp/njn_dynprogproblim.cpp +195 -0
  15. alp_na-1.0.0/lib/alp/njn_dynprogproblim.hpp +165 -0
  16. alp_na-1.0.0/lib/alp/njn_dynprogprobproto.cpp +41 -0
  17. alp_na-1.0.0/lib/alp/njn_dynprogprobproto.hpp +84 -0
  18. alp_na-1.0.0/lib/alp/njn_function.hpp +117 -0
  19. alp_na-1.0.0/lib/alp/njn_integer.hpp +228 -0
  20. alp_na-1.0.0/lib/alp/njn_ioutil.cpp +167 -0
  21. alp_na-1.0.0/lib/alp/njn_ioutil.hpp +146 -0
  22. alp_na-1.0.0/lib/alp/njn_localmaxstat.cpp +215 -0
  23. alp_na-1.0.0/lib/alp/njn_localmaxstat.hpp +198 -0
  24. alp_na-1.0.0/lib/alp/njn_localmaxstatmatrix.cpp +157 -0
  25. alp_na-1.0.0/lib/alp/njn_localmaxstatmatrix.hpp +144 -0
  26. alp_na-1.0.0/lib/alp/njn_localmaxstatutil.cpp +533 -0
  27. alp_na-1.0.0/lib/alp/njn_localmaxstatutil.hpp +170 -0
  28. alp_na-1.0.0/lib/alp/njn_matrix.hpp +656 -0
  29. alp_na-1.0.0/lib/alp/njn_memutil.hpp +127 -0
  30. alp_na-1.0.0/lib/alp/njn_random.cpp +102 -0
  31. alp_na-1.0.0/lib/alp/njn_random.hpp +55 -0
  32. alp_na-1.0.0/lib/alp/njn_root.hpp +486 -0
  33. alp_na-1.0.0/lib/alp/njn_uniform.hpp +76 -0
  34. alp_na-1.0.0/lib/alp/njn_vector.hpp +362 -0
  35. alp_na-1.0.0/lib/alp/readme.txt +10 -0
  36. alp_na-1.0.0/lib/alp/sls_alignment_evaluer.cpp +1151 -0
  37. alp_na-1.0.0/lib/alp/sls_alignment_evaluer.hpp +217 -0
  38. alp_na-1.0.0/lib/alp/sls_alp.cpp +2366 -0
  39. alp_na-1.0.0/lib/alp/sls_alp.hpp +364 -0
  40. alp_na-1.0.0/lib/alp/sls_alp_data.cpp +1654 -0
  41. alp_na-1.0.0/lib/alp/sls_alp_data.hpp +937 -0
  42. alp_na-1.0.0/lib/alp/sls_alp_regression.cpp +723 -0
  43. alp_na-1.0.0/lib/alp/sls_alp_regression.hpp +174 -0
  44. alp_na-1.0.0/lib/alp/sls_alp_sim.cpp +4549 -0
  45. alp_na-1.0.0/lib/alp/sls_alp_sim.hpp +579 -0
  46. alp_na-1.0.0/lib/alp/sls_basic.cpp +196 -0
  47. alp_na-1.0.0/lib/alp/sls_basic.hpp +222 -0
  48. alp_na-1.0.0/lib/alp/sls_normal_distr_array.hpp +151 -0
  49. alp_na-1.0.0/lib/alp/sls_pvalues.cpp +1301 -0
  50. alp_na-1.0.0/lib/alp/sls_pvalues.hpp +306 -0
  51. alp_na-1.0.0/pyproject.toml +88 -0
  52. alp_na-1.0.0/src/alp_api.cpp +159 -0
  53. alp_na-1.0.0/src/alp_api.h +125 -0
  54. alp_na-1.0.0/tests/test_alp.py +243 -0
  55. alp_na-1.0.0/uv.lock +1697 -0
@@ -0,0 +1,5 @@
1
+ build/
2
+ dist/
3
+ *.so
4
+ __pycache__/
5
+ .pytest_cache/
@@ -0,0 +1,7 @@
1
+ # CHANGELOG
2
+
3
+ <!-- version list -->
4
+
5
+ ## v1.0.0 (2026-11-18)
6
+
7
+ - Initial Release
@@ -0,0 +1,64 @@
1
+ cmake_minimum_required(VERSION 3.15)
2
+ project(alp LANGUAGES CXX)
3
+
4
+ set(CMAKE_CXX_STANDARD 17)
5
+ set(CMAKE_CXX_STANDARD_REQUIRED ON)
6
+ set(CMAKE_POSITION_INDEPENDENT_CODE ON)
7
+ # Link the MSVC C++ runtime statically: Python ships vcruntime140.dll but not
8
+ # msvcp140.dll, so a dynamically linked libalp.dll could fail to load.
9
+ set(CMAKE_MSVC_RUNTIME_LIBRARY "MultiThreaded")
10
+
11
+ if(NOT CMAKE_BUILD_TYPE AND NOT CMAKE_CONFIGURATION_TYPES)
12
+ set(CMAKE_BUILD_TYPE Release)
13
+ endif()
14
+
15
+ set(ALP_DIR ${CMAKE_CURRENT_SOURCE_DIR}/lib/alp)
16
+ set(ALP_SRCS
17
+ ${ALP_DIR}/njn_dynprogprob.cpp
18
+ ${ALP_DIR}/njn_dynprogproblim.cpp
19
+ ${ALP_DIR}/njn_dynprogprobproto.cpp
20
+ ${ALP_DIR}/njn_ioutil.cpp
21
+ ${ALP_DIR}/njn_localmaxstat.cpp
22
+ ${ALP_DIR}/njn_localmaxstatmatrix.cpp
23
+ ${ALP_DIR}/njn_localmaxstatutil.cpp
24
+ ${ALP_DIR}/njn_random.cpp
25
+ ${ALP_DIR}/sls_alignment_evaluer.cpp
26
+ ${ALP_DIR}/sls_alp.cpp
27
+ ${ALP_DIR}/sls_alp_data.cpp
28
+ ${ALP_DIR}/sls_alp_regression.cpp
29
+ ${ALP_DIR}/sls_alp_sim.cpp
30
+ ${ALP_DIR}/sls_basic.cpp
31
+ ${ALP_DIR}/sls_pvalues.cpp
32
+ )
33
+ # Third-party public-domain NCBI code: silence its warnings.
34
+ if(MSVC)
35
+ set_source_files_properties(${ALP_SRCS} PROPERTIES COMPILE_OPTIONS "/w")
36
+ else()
37
+ set_source_files_properties(${ALP_SRCS} PROPERTIES COMPILE_OPTIONS "-w")
38
+ endif()
39
+
40
+ add_library(alp SHARED src/alp_api.cpp ${ALP_SRCS})
41
+ target_include_directories(alp PRIVATE ${ALP_DIR} ${CMAKE_CURRENT_SOURCE_DIR}/src)
42
+ # File name is libalp.so / libalp.dylib / libalp.dll. The library is loaded with
43
+ # ctypes, so all symbols are exported on Windows, and the output goes straight
44
+ # into the build dir (the $<0:> genex suppresses per-config subdirectories).
45
+ set_target_properties(alp PROPERTIES
46
+ PREFIX "lib"
47
+ WINDOWS_EXPORT_ALL_SYMBOLS ON
48
+ LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}$<0:>"
49
+ RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}$<0:>"
50
+ )
51
+ if(MSVC)
52
+ target_compile_options(alp PRIVATE /O2)
53
+ else()
54
+ target_compile_options(alp PRIVATE -O2)
55
+ endif()
56
+ if(NOT WIN32)
57
+ target_link_libraries(alp PRIVATE m)
58
+ endif()
59
+
60
+ # Used by scikit-build-core to place the library inside the `alp` package.
61
+ install(TARGETS alp
62
+ LIBRARY DESTINATION alp
63
+ RUNTIME DESTINATION alp
64
+ )
alp_na-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,149 @@
1
+ Metadata-Version: 2.2
2
+ Name: alp-na
3
+ Version: 1.0.0
4
+ Summary: Gumbel (Karlin-Altschul) parameters for local alignment scores via the NCBI ALP library
5
+ Author: NaturalAntibody
6
+ Project-URL: Homepage, https://github.com/NaturalAntibody/alp
7
+ Requires-Python: >=3.9
8
+ Description-Content-Type: text/markdown
9
+
10
+ # alp
11
+
12
+ Standalone Python wrapper over the NCBI **ALP** library ([Sheetlin & Frith, ALP & FALP: C++ libraries for pairwise local alignment E-values](https://academic.oup.com/bioinformatics/article/32/2/304/1744607)) for computing the Gumbel / Karlin–Altschul parameters
13
+ (λ, K and the finite-size corrections a, b, α, β, σ, τ) of local alignment
14
+ scores. Use these parameters to turn raw Smith–Waterman scores into bit-scores
15
+ and E-values.
16
+
17
+ The directory is self-contained: it ships its own copy of ALP (`lib/alp`), a
18
+ small C API (`src/alp_api.{h,cpp}`), a CMake build and a ctypes package
19
+ with **no runtime Python dependencies**.
20
+
21
+ ## Install
22
+
23
+ ```bash
24
+ pip install alp-na # prebuilt wheels for Linux, macOS and Windows
25
+ ```
26
+
27
+ The distribution is named `alp-na` on PyPI (`alp` is taken by an unrelated
28
+ project); the import name is still `alp`.
29
+
30
+ ## Development
31
+
32
+ The project is managed with [uv](https://docs.astral.sh/uv/) and built with
33
+ [scikit-build-core](https://scikit-build-core.readthedocs.io/) (CMake). You need
34
+ a C++17 compiler; CMake is installed into the isolated build environment
35
+ automatically.
36
+
37
+ ```bash
38
+ uv sync # create .venv, build libalp, install dev deps
39
+ uv run pytest # run the tests
40
+ uv build # build the sdist and a wheel for this machine into dist/
41
+ ```
42
+
43
+ `uv sync` rebuilds the library whenever `CMakeLists.txt` or a C++ source
44
+ changes; the CMake build tree is kept in `build/` so rebuilds are incremental.
45
+
46
+ The shared library (`libalp.so` / `libalp.dylib` / `libalp.dll`) is looked up in
47
+ the package directories, then in `./build/` (a plain
48
+ `cmake -B build && cmake --build build`); `ALP_LIB=/path/to/libalp.so`
49
+ overrides both.
50
+
51
+ ## Releasing
52
+
53
+ Every push to `master` runs `.github/workflows/ci.yml`: python-semantic-release
54
+ bumps the version from the conventional commits (and refreshes `uv.lock`),
55
+ cibuildwheel builds one `py3-none` wheel each for Linux (x86_64, aarch64), macOS
56
+ (universal2) and Windows (AMD64), `uv build --sdist` builds the sdist, and
57
+ `uv publish` uploads everything to PyPI with trusted publishing.
58
+
59
+ ## Usage
60
+
61
+ ```python
62
+ from alp import compute_gumbel_params
63
+
64
+ # Built-in BLOSUM (45/50/62/80/90) with Robinson & Robinson background freqs
65
+ p = compute_gumbel_params("blosum62", gap_open=11, gap_extend=1)
66
+ p.lambda_, p.K # (0.2741, 0.0494)
67
+
68
+ # Any dict-of-dicts matrix, e.g. from the `blosum` package
69
+ import blosum
70
+ p = compute_gumbel_params(blosum.BLOSUM(62), gap_open=11, gap_extend=1)
71
+
72
+ # Square integer array (list of lists / numpy) + optional alphabet
73
+ p = compute_gumbel_params(my_matrix, alphabet="ACGT", bg_freqs=[.3, .2, .2, .3],
74
+ gap_open=5, gap_extend=2)
75
+
76
+ # Match / mismatch scoring (default alphabet ACGT, uniform frequencies)
77
+ p = compute_gumbel_params(match=2, mismatch=3, gap_open=5, gap_extend=2)
78
+
79
+ # Omit gap penalties for (exact, analytic) gapless statistics
80
+ p = compute_gumbel_params("blosum62")
81
+
82
+ # Statistics
83
+ p.bit_score(55)
84
+ p.evalue(55, query_length=120, subject_length=1_000_000) # ALP finite-size corrected
85
+ p.pvalue(55, 120, 1_000_000)
86
+ p.to_dict(), p.as_tuple(), p.errors # errors = ALP std. errors
87
+ ```
88
+
89
+ `GumbelParams(*stored_tuple)` rebuilds a parameter set from saved values, so
90
+ the (sub-second to ~1 min) simulation only needs to run once per scoring
91
+ system. Within a process, results are also memoised.
92
+
93
+ ### Options
94
+
95
+ | argument | default | meaning |
96
+ |---|---|---|
97
+ | `alphabet` | auto | symbol order; for dict matrices the 20 standard amino acids are used when present (B/Z/X/\* are dropped) |
98
+ | `bg_freqs`, `bg_freqs2` | Robinson for 20 AA, else uniform | `"uniform"`, `"robinson"`/`"blast"` (BLAST's Robinson & Robinson), `"blosum62"`/`"mmseqs"` (BLOSUM62 background, as in MMseqs2), a mapping, or a sequence; `bg_freqs2` for sequence #2 |
99
+ | `gap_convention` | `"ncbi"` | `"ncbi"`: gap of length k costs `open + k·extend` (ALP, BLAST, MMseqs2). `"open_includes_extend"`: `open + (k−1)·extend` (SSW, parasail); converted before calling ALP |
100
+ | `n_samples` | 20000 | fixed number of simulation samples, so results are bit-identical for given inputs and seed. `None` = ALP's adaptive mode (see below) |
101
+ | `n_preliminary_samples` | 200 | samples per preliminary stage (fixed mode) |
102
+ | `lambda_tolerance`, `k_tolerance` | 0.01, 0.05 | target relative errors (adaptive mode only) |
103
+ | `max_seconds` | `None` | no time limit by default. If set, it is a hard timeout (`ALPError`) in fixed and gapless mode; in adaptive mode it is ALP's planning budget (default 60 s) |
104
+ | `max_mem_mb` | 500 | memory limit |
105
+ | `seed` | 42 | random seed |
106
+
107
+ `ValueError` is raised for invalid input, including scoring systems with no
108
+ valid local statistics (no positive score or non-negative expected score).
109
+ `ALPError` is raised when ALP itself fails.
110
+
111
+ ## Notes
112
+
113
+ * **Reproducibility.** By default ALP chooses its sample sizes adaptively,
114
+ from the tolerances *and* from measured run time. With a binding time
115
+ limit, results then depend on machine speed and load: BLOSUM62 9/1 on a
116
+ loaded machine gave K and α values 3.5% and 10% different. This package
117
+ therefore defaults to a fixed plan (`n_samples=20000`). Results are
118
+ bit-identical across runs, load and `max_seconds`. They depend only on
119
+ the inputs, the seed and the build: across platforms and compilers the
120
+ random sample paths are the same, but floating-point rounding differs in
121
+ the last digits (~1e-14 relative; checked in CI on Linux, macOS and Windows).
122
+ * **Accuracy vs `n_samples`.** Statistical error is roughly ∝ 1/√n and
123
+ runtime is linear in n. At 20000, λ is good to ≤0.5% and K to ≤2%. The
124
+ finite-size α/σ converge more slowly and are biased low at small n for
125
+ low gap costs. Raise `n_samples` (e.g. 100000) when E-values for short
126
+ sequences matter. Runtime at 20000 is ~2.5 s for BLOSUM62 11/1, ~10 s for
127
+ 9/1 and ~36 s for BLOSUM45 16/1.
128
+ * `n_samples=None` (seed 42, tolerances 0.01/0.05, 60 s) reproduces
129
+ MMseqs2's ALP settings.
130
+ * `lib/alp` is vendored NCBI ALP with one patch (`sls_alignment_evaluer.cpp`,
131
+ marked "alp-python patch"). In fixed-plan mode, the gapless pre-step
132
+ originally had a hard-coded 120 s cap; it now honours `max_seconds`, and has
133
+ no limit when that is unset.
134
+ * Gapless parameters are exact. They reproduce BLAST's ungapped rows with
135
+ Robinson frequencies and MMseqs2's gapless BLOSUM62 entry with
136
+ `bg_freqs="mmseqs"`.
137
+ * C API: see `src/alp_api.h` (`gumbel_compute`, `gumbel_evalue`).
138
+
139
+ ## Comparison with BLAST and MMseqs2 tables
140
+
141
+ `scripts/compare_blast.py` recomputes every precomputed row in BLAST's
142
+ `blast_stat.c` (BLOSUM45–90, all blastn reward/penalty tables). It also adds
143
+ MMseqs2's hard-coded entries from `EvalueComputation.h` where they exist:
144
+
145
+ ```bash
146
+ python scripts/compare_blast.py path/to/blast_stat.c \
147
+ --mmseqs path/to/EvalueComputation.h --csv cmp.csv --md cmp.md \
148
+ [--n-samples 100000] # or --n-samples 0 for ALP adaptive mode
149
+ ```
alp_na-1.0.0/README.md ADDED
@@ -0,0 +1,140 @@
1
+ # alp
2
+
3
+ Standalone Python wrapper over the NCBI **ALP** library ([Sheetlin & Frith, ALP & FALP: C++ libraries for pairwise local alignment E-values](https://academic.oup.com/bioinformatics/article/32/2/304/1744607)) for computing the Gumbel / Karlin–Altschul parameters
4
+ (λ, K and the finite-size corrections a, b, α, β, σ, τ) of local alignment
5
+ scores. Use these parameters to turn raw Smith–Waterman scores into bit-scores
6
+ and E-values.
7
+
8
+ The directory is self-contained: it ships its own copy of ALP (`lib/alp`), a
9
+ small C API (`src/alp_api.{h,cpp}`), a CMake build and a ctypes package
10
+ with **no runtime Python dependencies**.
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ pip install alp-na # prebuilt wheels for Linux, macOS and Windows
16
+ ```
17
+
18
+ The distribution is named `alp-na` on PyPI (`alp` is taken by an unrelated
19
+ project); the import name is still `alp`.
20
+
21
+ ## Development
22
+
23
+ The project is managed with [uv](https://docs.astral.sh/uv/) and built with
24
+ [scikit-build-core](https://scikit-build-core.readthedocs.io/) (CMake). You need
25
+ a C++17 compiler; CMake is installed into the isolated build environment
26
+ automatically.
27
+
28
+ ```bash
29
+ uv sync # create .venv, build libalp, install dev deps
30
+ uv run pytest # run the tests
31
+ uv build # build the sdist and a wheel for this machine into dist/
32
+ ```
33
+
34
+ `uv sync` rebuilds the library whenever `CMakeLists.txt` or a C++ source
35
+ changes; the CMake build tree is kept in `build/` so rebuilds are incremental.
36
+
37
+ The shared library (`libalp.so` / `libalp.dylib` / `libalp.dll`) is looked up in
38
+ the package directories, then in `./build/` (a plain
39
+ `cmake -B build && cmake --build build`); `ALP_LIB=/path/to/libalp.so`
40
+ overrides both.
41
+
42
+ ## Releasing
43
+
44
+ Every push to `master` runs `.github/workflows/ci.yml`: python-semantic-release
45
+ bumps the version from the conventional commits (and refreshes `uv.lock`),
46
+ cibuildwheel builds one `py3-none` wheel each for Linux (x86_64, aarch64), macOS
47
+ (universal2) and Windows (AMD64), `uv build --sdist` builds the sdist, and
48
+ `uv publish` uploads everything to PyPI with trusted publishing.
49
+
50
+ ## Usage
51
+
52
+ ```python
53
+ from alp import compute_gumbel_params
54
+
55
+ # Built-in BLOSUM (45/50/62/80/90) with Robinson & Robinson background freqs
56
+ p = compute_gumbel_params("blosum62", gap_open=11, gap_extend=1)
57
+ p.lambda_, p.K # (0.2741, 0.0494)
58
+
59
+ # Any dict-of-dicts matrix, e.g. from the `blosum` package
60
+ import blosum
61
+ p = compute_gumbel_params(blosum.BLOSUM(62), gap_open=11, gap_extend=1)
62
+
63
+ # Square integer array (list of lists / numpy) + optional alphabet
64
+ p = compute_gumbel_params(my_matrix, alphabet="ACGT", bg_freqs=[.3, .2, .2, .3],
65
+ gap_open=5, gap_extend=2)
66
+
67
+ # Match / mismatch scoring (default alphabet ACGT, uniform frequencies)
68
+ p = compute_gumbel_params(match=2, mismatch=3, gap_open=5, gap_extend=2)
69
+
70
+ # Omit gap penalties for (exact, analytic) gapless statistics
71
+ p = compute_gumbel_params("blosum62")
72
+
73
+ # Statistics
74
+ p.bit_score(55)
75
+ p.evalue(55, query_length=120, subject_length=1_000_000) # ALP finite-size corrected
76
+ p.pvalue(55, 120, 1_000_000)
77
+ p.to_dict(), p.as_tuple(), p.errors # errors = ALP std. errors
78
+ ```
79
+
80
+ `GumbelParams(*stored_tuple)` rebuilds a parameter set from saved values, so
81
+ the (sub-second to ~1 min) simulation only needs to run once per scoring
82
+ system. Within a process, results are also memoised.
83
+
84
+ ### Options
85
+
86
+ | argument | default | meaning |
87
+ |---|---|---|
88
+ | `alphabet` | auto | symbol order; for dict matrices the 20 standard amino acids are used when present (B/Z/X/\* are dropped) |
89
+ | `bg_freqs`, `bg_freqs2` | Robinson for 20 AA, else uniform | `"uniform"`, `"robinson"`/`"blast"` (BLAST's Robinson & Robinson), `"blosum62"`/`"mmseqs"` (BLOSUM62 background, as in MMseqs2), a mapping, or a sequence; `bg_freqs2` for sequence #2 |
90
+ | `gap_convention` | `"ncbi"` | `"ncbi"`: gap of length k costs `open + k·extend` (ALP, BLAST, MMseqs2). `"open_includes_extend"`: `open + (k−1)·extend` (SSW, parasail); converted before calling ALP |
91
+ | `n_samples` | 20000 | fixed number of simulation samples, so results are bit-identical for given inputs and seed. `None` = ALP's adaptive mode (see below) |
92
+ | `n_preliminary_samples` | 200 | samples per preliminary stage (fixed mode) |
93
+ | `lambda_tolerance`, `k_tolerance` | 0.01, 0.05 | target relative errors (adaptive mode only) |
94
+ | `max_seconds` | `None` | no time limit by default. If set, it is a hard timeout (`ALPError`) in fixed and gapless mode; in adaptive mode it is ALP's planning budget (default 60 s) |
95
+ | `max_mem_mb` | 500 | memory limit |
96
+ | `seed` | 42 | random seed |
97
+
98
+ `ValueError` is raised for invalid input, including scoring systems with no
99
+ valid local statistics (no positive score or non-negative expected score).
100
+ `ALPError` is raised when ALP itself fails.
101
+
102
+ ## Notes
103
+
104
+ * **Reproducibility.** By default ALP chooses its sample sizes adaptively,
105
+ from the tolerances *and* from measured run time. With a binding time
106
+ limit, results then depend on machine speed and load: BLOSUM62 9/1 on a
107
+ loaded machine gave K and α values 3.5% and 10% different. This package
108
+ therefore defaults to a fixed plan (`n_samples=20000`). Results are
109
+ bit-identical across runs, load and `max_seconds`. They depend only on
110
+ the inputs, the seed and the build: across platforms and compilers the
111
+ random sample paths are the same, but floating-point rounding differs in
112
+ the last digits (~1e-14 relative; checked in CI on Linux, macOS and Windows).
113
+ * **Accuracy vs `n_samples`.** Statistical error is roughly ∝ 1/√n and
114
+ runtime is linear in n. At 20000, λ is good to ≤0.5% and K to ≤2%. The
115
+ finite-size α/σ converge more slowly and are biased low at small n for
116
+ low gap costs. Raise `n_samples` (e.g. 100000) when E-values for short
117
+ sequences matter. Runtime at 20000 is ~2.5 s for BLOSUM62 11/1, ~10 s for
118
+ 9/1 and ~36 s for BLOSUM45 16/1.
119
+ * `n_samples=None` (seed 42, tolerances 0.01/0.05, 60 s) reproduces
120
+ MMseqs2's ALP settings.
121
+ * `lib/alp` is vendored NCBI ALP with one patch (`sls_alignment_evaluer.cpp`,
122
+ marked "alp-python patch"). In fixed-plan mode, the gapless pre-step
123
+ originally had a hard-coded 120 s cap; it now honours `max_seconds`, and has
124
+ no limit when that is unset.
125
+ * Gapless parameters are exact. They reproduce BLAST's ungapped rows with
126
+ Robinson frequencies and MMseqs2's gapless BLOSUM62 entry with
127
+ `bg_freqs="mmseqs"`.
128
+ * C API: see `src/alp_api.h` (`gumbel_compute`, `gumbel_evalue`).
129
+
130
+ ## Comparison with BLAST and MMseqs2 tables
131
+
132
+ `scripts/compare_blast.py` recomputes every precomputed row in BLAST's
133
+ `blast_stat.c` (BLOSUM45–90, all blastn reward/penalty tables). It also adds
134
+ MMseqs2's hard-coded entries from `EvalueComputation.h` where they exist:
135
+
136
+ ```bash
137
+ python scripts/compare_blast.py path/to/blast_stat.c \
138
+ --mmseqs path/to/EvalueComputation.h --csv cmp.csv --md cmp.md \
139
+ [--n-samples 100000] # or --n-samples 0 for ALP adaptive mode
140
+ ```
@@ -0,0 +1,23 @@
1
+ """Gumbel (Karlin-Altschul) parameters for local alignment via NCBI ALP."""
2
+
3
+ from ._core import (
4
+ ALPError,
5
+ GumbelParams,
6
+ BLOSUM62_FREQS,
7
+ ROBINSON_FREQS,
8
+ compute_gumbel_params,
9
+ match_mismatch_matrix,
10
+ )
11
+ from ._matrices import AA_ALPHABET, BLOSUM
12
+
13
+ __all__ = [
14
+ "AA_ALPHABET",
15
+ "ALPError",
16
+ "BLOSUM",
17
+ "GumbelParams",
18
+ "BLOSUM62_FREQS",
19
+ "ROBINSON_FREQS",
20
+ "compute_gumbel_params",
21
+ "match_mismatch_matrix",
22
+ ]
23
+ __version__ = "1.0.0"