Metadata-Version: 2.5
Name: zsasa
Version: 0.11.0
Summary: Fast SASA calculation using Zig
Project-URL: Homepage, https://n283t.github.io/zsasa/
Project-URL: Repository, https://github.com/N283T/zsasa
Project-URL: Documentation, https://n283t.github.io/zsasa/
Project-URL: Issues, https://github.com/N283T/zsasa/issues
Project-URL: Changelog, https://github.com/N283T/zsasa/blob/main/CHANGELOG.md
Author: Tsubasa Nagae
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.11
Requires-Dist: cffi>=1.15
Requires-Dist: numpy>=1.24
Provides-Extra: all
Requires-Dist: biopython>=1.80; extra == 'all'
Requires-Dist: biotite>=1.0.0; extra == 'all'
Requires-Dist: gemmi>=0.6.0; extra == 'all'
Requires-Dist: mdanalysis>=2.0.0; extra == 'all'
Requires-Dist: mdtraj>=1.9.0; extra == 'all'
Provides-Extra: biopython
Requires-Dist: biopython>=1.80; extra == 'biopython'
Provides-Extra: biotite
Requires-Dist: biotite>=1.0.0; extra == 'biotite'
Provides-Extra: dev
Requires-Dist: hatchling; extra == 'dev'
Requires-Dist: pdoc>=14.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: ty>=0.0.1a0; extra == 'dev'
Provides-Extra: gemmi
Requires-Dist: gemmi>=0.6.0; extra == 'gemmi'
Provides-Extra: mdanalysis
Requires-Dist: mdanalysis>=2.0.0; extra == 'mdanalysis'
Provides-Extra: mdtraj
Requires-Dist: mdtraj>=1.9.0; extra == 'mdtraj'
Description-Content-Type: text/markdown

# zsasa Python Bindings

Python bindings for [zsasa](https://github.com/N283T/zsasa) — a high-performance SASA calculator in Zig.

**[Full Documentation](https://n283t.github.io/zsasa/docs/python-api)**

## Installation

```bash
pip install zsasa
# or
uv add zsasa
```

The x86_64 wheels need a CPU with AVX2 and FMA (x86-64-v3, 2013 and later), and the macOS wheels need macOS 11 or later. On an older CPU, install from source with `pip install --no-binary zsasa zsasa` (needs Zig 0.16).

### Optional Dependencies

```bash
pip install zsasa[gemmi]      # Gemmi integration
pip install zsasa[biopython]  # BioPython integration
pip install zsasa[biotite]    # Biotite integration
pip install zsasa[all]        # All integrations
```

### Native Library

A wheel from PyPI bundles the `libzsasa` shared library and the `zsasa` binary. The library is looked for in the file `ZSASA_LIB` names, the package directory (and `zig-out` of a source checkout), the environment of the running interpreter (`<sys.prefix>/lib`, on Windows `<sys.prefix>\Library\bin`), and `/usr/local/lib` and `/usr/lib`, in that order; the current directory is never searched. Packagers that ship the library and the binary separately build a pure-Python wheel with `ZSASA_NO_BUNDLE=1`. See [How the Native Library Is Found](https://n283t.github.io/zsasa/docs/python-api#library-lookup).

## Quick Start

```python
import numpy as np
from zsasa import calculate_sasa

coords = np.array([[0.0, 0.0, 0.0], [3.0, 0.0, 0.0]])
radii = np.array([1.5, 1.5])
result = calculate_sasa(coords, radii)
print(f"Total SASA: {result.total_area:.2f} Å²")
```

```python
# With structure file (gemmi)
from zsasa.integrations.gemmi import calculate_sasa_from_structure
result = calculate_sasa_from_structure("protein.cif")
print(f"Total: {result.total_area:.1f} Å²")
```

## Features

- **Two algorithms**: Shrake-Rupley and Lee-Richards, with bitmask LUT optimization
- **Selectable precision**: `calculate_sasa_batch` takes `precision="f64"` (default) or `"f32"`
- **Multi-threading**: Automatic parallelization
- **Atom classification**: CCD, ProtOr, NACCESS, and OONS classifiers
- **Analysis**: Per-residue aggregation, RSA, polar/nonpolar classification
- **Batch processing**: `process_directory()` for proteome-scale datasets
- **MD trajectory**: [MDTraj](https://github.com/mdtraj/mdtraj) and [MDAnalysis](https://github.com/MDAnalysis/mdanalysis) integrations; use [pyztraj](https://github.com/N283T/ztraj) for direct trajectory-file I/O
- **Integrations**: Gemmi, BioPython, Biotite

See the [full API reference](https://n283t.github.io/zsasa/docs/python-api) for details.

## Development

```bash
cd python
uv run --with pytest pytest tests/ -v    # Tests
ruff format . && ruff check --fix .      # Lint
```

## License

MIT
