Metadata-Version: 2.4
Name: synth-afm
Version: 0.1.1
Summary: Synthetic High-Speed AFM image generation with differentiable kernels
Author: George Elkins
License-Expression: MIT
Project-URL: Homepage, https://elkins.github.io/synth-afm
Project-URL: Repository, https://github.com/elkins/synth-afm
Project-URL: Documentation, https://elkins.github.io/synth-afm
Project-URL: Changelog, https://github.com/elkins/synth-afm/blob/master/CHANGELOG.md
Keywords: afm,biophysics,simulation,jax,structural-biology
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: jax
Requires-Dist: jaxlib
Requires-Dist: numpy>=2.0.0
Requires-Dist: biotite>=0.35.0
Requires-Dist: scipy>=1.10.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"

# 🧬 synth-afm: Differentiable HS-AFM Simulation

[![PyPI version](https://img.shields.io/badge/pypi-v0.1.1--dev-blue)](https://github.com/elkins/synth-afm)
[![Supported Python versions](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://github.com/elkins/synth-afm)
[![Tests](https://github.com/elkins/synth-afm/actions/workflows/test.yml/badge.svg)](https://github.com/elkins/synth-afm/actions/workflows/test.yml)
[![Coverage](https://img.shields.io/badge/coverage-100%25-brightgreen)](https://github.com/elkins/synth-afm)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![JAX](https://img.shields.io/badge/Accelerated_by-JAX-blue.svg)](https://github.com/google/jax)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

`synth-afm` is a JAX-powered toolkit for generating synthetic High-Speed Atomic Force Microscopy (HS-AFM) images and movies from atomistic protein structures.

Built with the **differentiable biophysics** philosophy, every step—from coordinate rotation to tip-collision height mapping—is end-to-end differentiable.

---

### 🧪 For Structural Biologists
HS-AFM provides a unique look at "proteins at work," but interpreting noisy movies is challenging. `synth-afm` helps you bridge the resolution gap:
*   **Realistic Tip Physics:** Uses a spherical-tip dilation model to account for the broadening effect of the AFM probe.
*   **Atomic Rigor:** Automatically assigns van der Waals radii based on element (Bondi, 1964) for accurate topography.
*   **Temporal Distortion:** Models **Scanning Lag**, simulating how protein dynamics during a scan cause the "shear" artifacts seen in real HS-AFM movies.
*   **Force Maps:** Go beyond height-maps with experimental support for tip-sample repulsion (deflection) modeling.

### 🤖 For Machine Learning Geeks
`synth-afm` treats the entire AFM scanning process as a differentiable operator $\mathcal{H}: \mathbb{R}^{N \times 3} \rightarrow \mathbb{R}^{H \times W}$:
*   **End-to-End Differentiable:** Built entirely in JAX, allowing you to flow gradients from an experimental AFM image $\mathbf{I}_{exp}$ back to atomic coordinates $\mathbf{X}$.
*   **Flexible Fitting:** Enable gradient-based optimization of molecular structures using experimental AFM data as a loss term: $\mathcal{L} = \|\mathcal{H}(\mathbf{X}) - \mathbf{I}_{exp}\|^2$.
*   **Synthetic Benchmarking:** Generate large-scale, ground-truth datasets of "corrupted" AFM movies (with lag, noise, and dilation) to train denoising or state-detection models.

---

## 🚀 Key Features

*   **Differentiable Height Mapping:** Efficient Log-Sum-Exp collision detection for sub-nanometer topography.
*   **Physical Realism:** Simulate cantilever noise and substrate tilt (linear gradients) to match experimental conditions.
*   **Scanning Lag Simulation:** Models the line-by-line temporal delay inherent in pixel-by-pixel acquisition.
*   **Memory Efficiency:** Uses `jax.lax.scan` for constant-memory simulation of long trajectories.
*   **Flexible Tip Geometries:** Supports spherical tip-shape dilation.
*   **Integration:** Reads PDB/mmCIF files via `biotite` and integrates with `synth-pdb` and `synth-dynamics`.

## 📦 Installation

```bash
pip install synth-afm
```

## 📖 Tutorials

Get started immediately with our interactive Jupyter notebooks:

*   **[Quick Start: Differentiable HS-AFM Simulation](examples/quickstart_afm.ipynb)**: Learn how to generate height maps with tip dilation and scanning lag.
    [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/elkins/synth-afm/blob/master/examples/quickstart_afm.ipynb)

## 🛠 Quick Start

```python
import jax.numpy as jnp
from synth_afm.simulator import AFMSimulator
from synth_afm.io import load_coords_and_radii

# 1. Load your structure (N, 3) and radii (N,)
coords, radii = load_coords_and_radii("molecule.pdb")

# 2. Initialize simulator (1A pixel size, 2nm tip radius, 0.5A noise, slight tilt)
sim = AFMSimulator(
    pixel_size=1.0,
    tip_radius=20.0,
    noise_level=0.5,
    substrate_tilt=(0.01, 0.0)
)

# 3. Generate height map (Differentiable!)
height_map = sim.scan(coords, radii)
```

## 🧪 Scientific Validation

The height-mapping kernels are validated against the standard Villarrubia algorithm and verified to preserve atomic heights within 0.01 Å precision. The temporal lag simulation correctly reproduces the stroboscopic shearing effects documented in high-speed biological AFM (Ando et al., 2011).

## 🔗 Related Projects

`synth-afm` is part of a broader ecosystem for synthetic biophysics data generation:

| Project | Purpose |
|---|---|
| [synth-pdb](https://github.com/elkins/synth-pdb) | Foundation: Realistic protein structure generation and PDB/mmCIF handling |
| [synth-nmr](https://github.com/elkins/synth-nmr) | NMR observables (NOE, RDC, chemical shifts, J-couplings, relaxation) |
| [synth-saxs](https://github.com/elkins/synth-saxs) | SAXS profile simulation via Debye formula |
| [synth-cryo-em](https://github.com/elkins/synth-cryo-em) | Cryo-EM density map generation with CTF/noise modeling |
| [synth-dynamics](https://github.com/georgeelkins/synth-dynamics) | ANM/Langevin dynamics for conformational ensembles |
| [diff-biophys](https://github.com/elkins/diff-biophys) | Differentiable JAX implementations of all biophysics kernels |

## 📜 License

Distributed under the MIT License. See `LICENSE` for more information.

## ✍️ Citation

If you use `synth-afm` in your research, please cite:

```bibtex
@software{synth_afm,
  author = {Elkins, George},
  title = {synth-afm: Differentiable HS-AFM Simulation},
  year = {2026},
  url = {https://github.com/elkins/synth-afm}
}
```
