Pre-release

This release is a pre-release and may not be stable for production use.

Proxide

Alpha — experimental, no API stability guarantees. This crate is part of an active research project; APIs may change without notice between versions. Not recommended for production use.

Proxide is a high-performance library for Protein I/O and Physics bridging in JAX. It combines a flexible Python/JAX frontend with a highly optimized Rust backend (_proxider) to provide fast structure parsing, force field parameterization, and seamless integration with JAX MD.

NOTE: This is a research library in active development.

🚀 Features

  • Hybrid Architecture:
    • Rust Backend: 25x faster parsing (PDB/mmCIF), 50x faster topology generation, and robust force field parameterization.
    • JAX Frontend: Differentiable physics, geometric deep learning utilities, and seamless GPU integration.
  • Robust I/O: Load PDB, mmCIF, and PQR files with automatic error handling and corrections.
  • Molecular Dynamics: Parse OpenMM XML force fields, assign GAFF parameters, and generate fully parameterized AtomicSystem objects for JAX MD.
  • Trajectory Support: High-performance parsing of XTC, DCD, and TRR trajectories.

📦 Installation

Proxide requires a Rust toolchain to build the backend extension.

Prerequisites

  • Python: 3.11+
  • Rust: 1.75+ (Install via rustup.rs)
  • C++ Compiler: For compiling HDF5/chemfiles dependencies if needed.

From Source

# Clone the repository
git clone https://github.com/maraxen/proxide.git
cd proxide

# Install with uv (recommended) or pip
uv pip install .

# For development (includes test dependencies)
uv pip install -e ".[dev]"

The installation process will automatically compile the Rust _proxider extension using maturin.

Optional: Espaloma Charge (ML partial charges)

Inference uses the JAX/Equinox port expaloma (bundled weights; no PyTorch/DGL at runtime). The [espaloma] extra pulls expaloma from PyPI (and rdkit).

uv pip install -e ".[espaloma]"

For local development against an editable expaloma checkout, use a path override (e.g. uv.sources in your workspace) or:

uv pip install -e ../expaloma
uv pip install -e ".[dev]"

OpenFF toolkit wrapper (legacy upstream espaloma_charge): uv pip install -e ".[espaloma-openff]".

API: proxide.chem.partial_charges (assign_espaloma_charges_rdkit, etc.). Validation uses golden vectors under tests/data/espaloma_golden/; refresh those files when bumping expaloma.

pytest -m espaloma

🛠️ Usage

Loading a Structure

Use the high-level parse_structure function for fast, robust parsing:

from proxide import parse_structure

# Load a PDB file to a unified Protein object
protein = parse_structure("path/to/structure.pdb")

# Access data as JAX arrays
print(protein.coordinates.shape)  # (N_residues, 37, 3)

Force Field Parameterization

Proxide can automatically assign force field parameters (charges, radii, etc.) via the Rust backend:

from proxide import parse_structure, OutputSpec

# Configure parsing options
spec = OutputSpec(
    add_hydrogens=True,             # Add missing geometric hydrogens
    infer_bonds=True,               # Infer connectivity if missing
    parameterize_md=True,           # Compute MD parameters
    force_field="protein.ff14SB.xml" # Use standard AMBER force field
)

# Parse and parameterize in one step
protein = parse_structure("path/to/structure.pdb", spec)

# Access MD parameters
print(protein.charges)  # Partial charges
print(protein.sigma)    # Lennard-Jones sigma

Trajectory Parsing

from proxide import parse_xtc

# Fast Rust-based XTC parsing
traj_data = parse_xtc("path/to/trajectory.xtc")
coords = traj_data["coordinates"]  # (N_frames, N_atoms, 3)

Fast Partial Charges (Espaloma)

Proxide provides access to high-performance Expaloma graph-neural-network inference for charge assignment using native Rust embedded weights:

# Assign charges with the fast Rust backend
proxide charges molecule.sdf --backend rust

⚡ Performance

The migration to a Rust backend has yielded significant performance improvements compared to the pure Python implementation:

Operation Speedup Example Metric
PDB Parsing 25x -
mmCIF Parsing 25x -
Topology Generation 50x -
Force Field Loading 10x -
Espaloma Inference 7.5x 13.6ms (JAX) ➔ 1.8ms (Rust)

🚀 Deployment & CI/CD

Proxide uses Maturin to seamlessly build Python wheels and publish them to PyPI. To publish proxide releases securely without secrets, we utilize PyPI Trusted Publishing (OIDC). Do not configure a PYPI_API_TOKEN GitHub Secret. Instead, create a Trusted Publisher in the PyPI dashboard bound to this repository to allow .github/workflows/publish.yml to authenticate.

⚠️ Migration Notes

If you are migrating from older versions of Proxide:

  1. Biotite Removal: Direct dependency on biotite for parsing has been removed. All parsing is now handled by _proxider.
  2. API Changes:
    • proxide.io.parsing.biotite -> proxide.parse_structure
    • proxide.physics.force_fields -> proxide.load_forcefield
  3. JAX by Default: Most I/O functions now return JAX arrays by default. Use use_jax=False if you specifically need NumPy arrays.

🔧 Development

Running Tests

# Run all tests
uv run pytest

# Run fast smoke tests
uv run pytest -m smoke

Building Wheels Locally

Before pushing a release to GitHub, test the wheel build locally to catch platform-specific issues early:

# Test the build locally (validates HDF5 static compilation and workflow config)
bash scripts/test-wheel-build.sh

# This will:
# 1. Check build prerequisites (cargo, rustc, python3)
# 2. Build the Rust extension with static HDF5 compilation
# 3. Verify the GitHub workflow is correctly configured

Note: The Rust extension uses static HDF5 compilation via the hdf5-metno crate with the static feature enabled. This means HDF5 is compiled from source during the build and included in the binary, eliminating platform-specific library dependencies.

Linting and Typing

# Linting
uv run ruff check src/proxide/ --fix

# Type Checking
uv run ty check

Project links

Data verified by PyPI on Jul 22, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (0.1.0a16)

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for maraxen from gravatar.com maraxen

Credits

Author: Marielle Russo

GitHub Statistics

Data verified by PyPI on Jul 22, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License expression

MIT
View SPDX License List

Requires

Python >=3.11

Provides Extra

cpu cuda dev espaloma espaloma-openff foldcomp ml molecules openmm tpu trajectories

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

proxide-0.1.0a14.tar.gz (7.3 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

proxide-0.1.0a14-cp311-abi3-win_amd64.whl (13.8 MB view details)

Uploaded CPython 3.11+Windows x86-64

proxide-0.1.0a14-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (13.6 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ x86-64

proxide-0.1.0a14-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (13.3 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

proxide-0.1.0a14-cp311-abi3-macosx_11_0_arm64.whl (12.3 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

proxide-0.1.0a14-cp311-abi3-macosx_10_12_x86_64.whl (12.7 MB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

Details for the file proxide-0.1.0a14.tar.gz.

File metadata

  • Download URL: proxide-0.1.0a14.tar.gz
  • Upload date:
  • Size: 7.3 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for proxide-0.1.0a14.tar.gz
Algorithm Hash digest
SHA256 534a77cd6e78e69579948ec76648227c44ed5944e9310d2e02d8156fd0cd0ac9
MD5 d5b57818547dd173ba19584435e3dc56
BLAKE2b-256 5c75c37e6203ab77cadcc2cc1ef264885ace64e578366e1e037dff1926638d30

See more details on using hashes here.

Provenance

The following attestation bundles were made for proxide-0.1.0a14.tar.gz:

Publisher: publish.yml on maraxen/proxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file proxide-0.1.0a14-cp311-abi3-win_amd64.whl.

File metadata

  • Download URL: proxide-0.1.0a14-cp311-abi3-win_amd64.whl
  • Upload date:
  • Size: 13.8 MB
  • Tags: CPython 3.11+, Windows x86-64
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for proxide-0.1.0a14-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 2913b42585d0245c4208e655b3f99ce3435019843e60efe96e6d1d532f846fa4
MD5 2c5d5bdd0a1dd22493208663f1e4b021
BLAKE2b-256 8216e08219b182176461c1b8b2c513726bae1e25fe2b8fd8261ea2ea9576bec5

See more details on using hashes here.

Provenance

The following attestation bundles were made for proxide-0.1.0a14-cp311-abi3-win_amd64.whl:

Publisher: publish.yml on maraxen/proxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file proxide-0.1.0a14-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for proxide-0.1.0a14-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 55e324d7e83aa2f1c77e7e1eb86e76caad746bebab0ca17737d8339ccd5d8b79
MD5 70faa6346381637d76d173fa165283e9
BLAKE2b-256 c9790f0ee8d99bda0f6e212bd0641af48892d159e85f69f62baad328d79518aa

See more details on using hashes here.

Provenance

The following attestation bundles were made for proxide-0.1.0a14-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl:

Publisher: publish.yml on maraxen/proxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file proxide-0.1.0a14-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for proxide-0.1.0a14-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 45ae6c92f4458707029543992d3fe572db3b67d99a279b53af12eca299e98db4
MD5 229d4fedc33bb71864d99b6313cd17f5
BLAKE2b-256 52d0cf59e3eb45ebd634e94a87e7f16cdb518c5a939e5fe456eb727cc4d11c4f

See more details on using hashes here.

Provenance

The following attestation bundles were made for proxide-0.1.0a14-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl:

Publisher: publish.yml on maraxen/proxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file proxide-0.1.0a14-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for proxide-0.1.0a14-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 c4105d1c94e8f1125cbe62605972b6d0af49f3e453a57427842a356f59b69ab0
MD5 a36a8a866a78345094fa7141df37ecd9
BLAKE2b-256 392ca1dec33a660de79d6acd1f630f5a4d53d96e310d3461d761c9015f70cba1

See more details on using hashes here.

Provenance

The following attestation bundles were made for proxide-0.1.0a14-cp311-abi3-macosx_11_0_arm64.whl:

Publisher: publish.yml on maraxen/proxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file proxide-0.1.0a14-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for proxide-0.1.0a14-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 559886456919cbc329937eb5133097c876e8c4054fd10bd15017f260c4405d2b
MD5 4cf41f9cbf2ce61e5a1d5ce1b300d171
BLAKE2b-256 dc95fe57e6c39865ec59a9303a6adeb24b056e7294648ef0f38a9a346efcd011

See more details on using hashes here.

Provenance

The following attestation bundles were made for proxide-0.1.0a14-cp311-abi3-macosx_10_12_x86_64.whl:

Publisher: publish.yml on maraxen/proxide

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page