aksha 0.2.1__tar.gz

aksha-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Jacob West-Roberts
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aksha-0.2.1/MANIFEST.in

@@ -0,0 +1,6 @@
+recursive-include native *.py *.pyx *.pxd *.h *.hpp *.cc *.cpp *.cu *.patch *.md
+recursive-include release *.py *.json *.md *.txt *.in
+recursive-include tests *.py
+include docs/database-setup.md
+prune docs/development
+global-exclude __pycache__ *.py[cod] *.so *.o *.a

aksha-0.2.1/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: aksha
+Version: 0.2.1
+Summary: Scalable HMM-based sequence search and retrieval
+Author: Jacob West-Roberts
+License-Expression: MIT
+Project-URL: Repository, https://github.com/jwestrob/aksha
+Project-URL: Issues, https://github.com/jwestrob/aksha/issues
+Keywords: hmm,hmmer,pyhmmer,bioinformatics,sequence-search,genomics,metagenomics
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: <3.13,>=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aksha-runtime==0.1.1
+Requires-Dist: pandas>=2.0.0
+Requires-Dist: tqdm>=4.65.0
+Requires-Dist: requests>=2.28.0
+Requires-Dist: platformdirs>=3.0.0
+Provides-Extra: gpu
+Requires-Dist: aksha-cuda12==0.1.1; extra == "gpu"
+Dynamic: license-file
+
+# Aksha
+
+**Fast HMM-based annotation for genomes and metagenomes.**
+
+Aksha accelerates HMM-based sequence searches so you can spend more time on
+biology and less time waiting for annotations. Built on [HMMER](http://hmmer.org/)
+and [PyHMMER](https://pyhmmer.readthedocs.io/), it combines fast CPU searches,
+optional NVIDIA GPU acceleration, database management and sequence retrieval
+in one command-line tool.
+
+Aksha outperformed MetaCerberus 1.4 in our Pfam benchmarks on both CPU and GPU.
+
+<details>
+<summary>Benchmark results and comparison conditions</summary>
+
+The recorded PLM2_5 workload contained 300,186 proteins and 27,481 Pfam models.
+
+| Tool / configuration | Physical CPU cores | Pfam runtime | Speedup over MetaCerberus |
+| --- | ---: | ---: | ---: |
+| MetaCerberus 1.4, CPU | 64 | 11m 34s | — |
+| Aksha, CPU | 64 | 4m 46s | 2.43× |
+| Aksha, 1 H200 GPU + CPU | 64 host cores | 3m 39s | 3.17× |
+
+Aksha's CPU and GPU outputs matched exactly in these runs. Both CPU-only
+runs used 64 physical cores on the same Xeon 6787P machine. The GPU run used
+one H200 plus 64 physical Xeon Platinum 8480+ host cores on a separate node.
+Core counts are allocated physical cores, not CPU sockets or SMT threads.
+MetaCerberus timing covers its HMM search/filter/parse pipeline, not
+additional reporting; its thresholds and output rules differ, so this is a
+workflow comparison, not identical-work benchmarking. Measurements predate
+wheel packaging. [CPU evidence](https://github.com/jwestrob/aksha/blob/main/docs/development/CPU_PRODUCTION_INTEGRATION.md)
+and [GPU evidence](https://github.com/jwestrob/aksha/blob/main/docs/development/GPU_PRODUCTION_INTEGRATION.md).
+
+</details>
+
+## More than a fast search
+
+- Search proteins or nucleotide sequences using supported databases or your own HMMs.
+- Download and manage databases such as Pfam and KOfam from the same tool.
+- Use a database's recommended cutoffs, or choose your own score and E-value thresholds.
+- Export tabular results and optionally retrieve matching sequences for downstream analysis.
+
+## Installation
+
+The PyPI release is being prepared. Once published:
+
+```bash
+python -m pip install aksha
+# With optional GPU support:
+python -m pip install 'aksha[gpu]'
+```
+
+Currently supported: Linux x86-64 with Python 3.12. GPU use requires a
+compatible NVIDIA GPU and driver. ARM, macOS and Windows are not yet supported.
+See the [installation guide](https://github.com/jwestrob/aksha/blob/main/release/INSTALL.md)
+for hardware requirements, local-wheel installation and GPU setup.
+
+## Quick start
+
+Download the Pfam protein-family database, then search your protein sequences:
+
+```bash
+aksha initialize --hmms PFAM
+aksha search --prot_in proteins.faa --installed_hmms PFAM --cut_ga --outdir results
+```
+
+Results are written to `results/`. The example uses Pfam's built-in score
+thresholds. You can also supply your own models with `--hmm_in` instead of
+`--installed_hmms`. Run `aksha --help` or `aksha search --help` for more options.
+
+The [database setup guide](https://github.com/jwestrob/aksha/blob/main/docs/database-setup.md)
+explains available databases, storage locations and reusing existing files.
+For source builds, see the [maintainer guide](https://github.com/jwestrob/aksha/blob/main/release/BUILD.md).
+
+## License
+
+Aksha's original code is MIT-licensed; third-party components retain their own
+licenses. See the [application license](https://github.com/jwestrob/aksha/blob/main/LICENSE),
+[native-code license](https://github.com/jwestrob/aksha/blob/main/native/README.md)
+and [third-party notices](https://github.com/jwestrob/aksha/blob/main/release/THIRD_PARTY_NOTICES.md).

aksha-0.2.1/aksha/__init__.py

@@ -0,0 +1,27 @@
+# aksha/__init__.py
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(description='Aksha: A suite of sequence analysis tools.')
+    parser.add_argument('command', choices=['search', 'initialize', 'nucsearch', 'phmmer', 'jackhmmer'],
+                        help='Subcommand to run')
+
+    # Parse only the first argument to determine the command
+    args, remaining_args = parser.parse_known_args()
+
+    if args.command == 'search':
+        from . import search
+        search.main(remaining_args)
+    elif args.command == 'initialize':
+        from . import initialize
+        initialize.main(remaining_args)
+    elif args.command == 'nucsearch':
+        from . import nucsearch
+        nucsearch.main(remaining_args)
+    elif args.command == 'phmmer':
+        from . import phmmer
+        phmmer.main(remaining_args)
+    elif args.command == 'jackhmmer':
+        from . import jackhmmer
+        jackhmmer.main(remaining_args)

aksha-0.2.1/aksha/_launcher.py

@@ -0,0 +1,143 @@
+"""Minimal console launcher for Aksha's high-thread allocator policy.
+
+This module must remain free of imports from :mod:`aksha.main`, PyHMMER, or
+other allocation-heavy runtime modules.  The console entry point can then set
+the glibc arena limit and replace itself with a fresh interpreter before any
+of those modules are imported.  Programmatic/library entry points bypass this
+module and retain their existing behavior.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+
+
+_GLIBC_ARENA_ENV = "MALLOC_ARENA_MAX"
+_ASTRA_ARENA_ENV = "ASTRA_CPU_MALLOC_ARENA_MAX"
+_REEXEC_SENTINEL_ENV = "_ASTRA_CPU_ALLOCATOR_REEXEC"
+_DEFAULT_ARENA_MAX = 24
+_MINIMUM_AUTO_THREADS = 64
+_MAXIMUM_ARENA_MAX = (1 << 31) - 1
+
+
+def _is_linux_glibc() -> bool:
+    """Return whether the current interpreter uses glibc on Linux."""
+    if not sys.platform.startswith("linux"):
+        return False
+    try:
+        version = os.confstr("CS_GNU_LIBC_VERSION")
+    except (AttributeError, OSError, ValueError):
+        return False
+    return isinstance(version, str) and version.startswith("glibc ")
+
+
+def _requested_threads(arguments: tuple[str, ...]) -> int | None:
+    """Return the CLI worker count, or ``None`` for malformed input.
+
+    Aksha's parser owns diagnostics for malformed ``--threads`` arguments.
+    The launcher simply declines to re-exec in that case so it cannot mask the
+    existing command-line error or alter its ordering.
+    """
+    value = "1"
+    index = 0
+    while index < len(arguments):
+        argument = arguments[index]
+        if argument == "--threads":
+            index += 1
+            if index >= len(arguments):
+                return None
+            value = arguments[index]
+        elif argument.startswith("--threads="):
+            value = argument.partition("=")[2]
+        index += 1
+    try:
+        return int(value)
+    except ValueError:
+        return None
+
+
+def _is_high_thread_search(arguments: tuple[str, ...]) -> bool:
+    """Return whether raw arguments select a search with at least 64 threads.
+
+    The allocator policy applies before Aksha can resolve CPU versus GPU
+    execution. Both routes run high-thread HMMER continuations and have
+    independently retained the 24-arena setting.
+    """
+    if not arguments or arguments[0] != "search":
+        return False
+    threads = _requested_threads(arguments[1:])
+    return threads is not None and threads >= _MINIMUM_AUTO_THREADS
+
+
+def _arena_max(environment: dict[str, str]) -> int | None:
+    """Parse the Aksha-specific arena control.
+
+    Zero is an explicit opt-out.  A standard ``MALLOC_ARENA_MAX`` value is
+    handled by the caller before this parser and always takes precedence.
+    """
+    value = environment.get(_ASTRA_ARENA_ENV)
+    if value is None:
+        return _DEFAULT_ARENA_MAX
+    if value == "0":
+        return None
+    if (
+        not value
+        or not value.isascii()
+        or not value.isdigit()
+        or value[0] == "0"
+    ):
+        raise ValueError(
+            f"{_ASTRA_ARENA_ENV} must be 0 or a canonical positive integer"
+        )
+    parsed = int(value)
+    if parsed > _MAXIMUM_ARENA_MAX:
+        raise ValueError(
+            f"{_ASTRA_ARENA_ENV} must be at most {_MAXIMUM_ARENA_MAX}"
+        )
+    return parsed
+
+
+def _reexec_environment(
+    arguments: tuple[str, ...], environment: dict[str, str]
+) -> dict[str, str] | None:
+    """Return the environment for a required allocator re-exec, if any."""
+    # The standard glibc setting is entirely user-owned, including an empty or
+    # otherwise unusual value.  Never reinterpret or overwrite it.
+    if _GLIBC_ARENA_ENV in environment:
+        return None
+    if _REEXEC_SENTINEL_ENV in environment:
+        return None
+    if not _is_high_thread_search(arguments) or not _is_linux_glibc():
+        return None
+    arena_max = _arena_max(environment)
+    if arena_max is None:
+        return None
+    updated = environment.copy()
+    updated[_GLIBC_ARENA_ENV] = str(arena_max)
+    updated[_REEXEC_SENTINEL_ENV] = "1"
+    return updated
+
+
+def _dispatch() -> object:
+    """Import and run the existing CLI only after allocator routing."""
+    from .main import main as astra_main
+
+    return astra_main()
+
+
+def main() -> object:
+    """Run the Aksha console command with the high-thread arena policy."""
+    arguments = tuple(sys.argv[1:])
+    try:
+        environment = _reexec_environment(arguments, dict(os.environ))
+    except ValueError as error:
+        raise SystemExit(str(error)) from None
+    if environment is not None:
+        os.execvpe(
+            sys.executable,
+            [sys.executable, "-m", "aksha.main", *arguments],
+            environment,
+        )
+        raise RuntimeError("os.execvpe returned unexpectedly")
+    return _dispatch()