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 Aug 27, 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:
Latest release

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 Aug 27, 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.0a16.tar.gz (7.5 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.0a16-cp311-abi3-win_amd64.whl (14.1 MB view details)

Uploaded CPython 3.11+Windows x86-64

proxide-0.1.0a16-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (13.8 MB view details)

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

proxide-0.1.0a16-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (13.6 MB view details)

Uploaded CPython 3.11+manylinux: glibc 2.17+ ARM64

proxide-0.1.0a16-cp311-abi3-macosx_11_0_arm64.whl (12.6 MB view details)

Uploaded CPython 3.11+macOS 11.0+ ARM64

proxide-0.1.0a16-cp311-abi3-macosx_10_12_x86_64.whl (13.0 MB view details)

Uploaded CPython 3.11+macOS 10.12+ x86-64

File details

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

File metadata

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

File hashes

Hashes for proxide-0.1.0a16.tar.gz
Algorithm Hash digest
SHA256 92fcbdd92d35ff04a42605cd6f205c4ac5ad9f14d7a82cbce980880cfc5ae2cc
MD5 0a264a317060318e78d87fbd37490e62
BLAKE2b-256 f9ff41309fa77332524ceed70f07e47b8b82ce638e9430c43a1b839f3e06c722

See more details on using hashes here.

Provenance

The following attestation bundles were made for proxide-0.1.0a16.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.0a16-cp311-abi3-win_amd64.whl.

File metadata

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

File hashes

Hashes for proxide-0.1.0a16-cp311-abi3-win_amd64.whl
Algorithm Hash digest
SHA256 c54c98163f5f034aa7f05ea2189c4e15e9bd5bde76a9f0cc99263ea80e6cc149
MD5 a22b3119d2930693d84230a5811f30ee
BLAKE2b-256 f2195f50b1f38204765c02cfd993c94edb7666e1f89b9226bc47b6222ffc8d5f

See more details on using hashes here.

Provenance

The following attestation bundles were made for proxide-0.1.0a16-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.0a16-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl.

File metadata

File hashes

Hashes for proxide-0.1.0a16-cp311-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm Hash digest
SHA256 a9c24b0835c6ea1a7a99991c164be5a92bd825e9ec36c975a55e6851218cec94
MD5 997ffd7cc04e47a9f3629d8c174d5729
BLAKE2b-256 e89d0d2603f85d52477592ac123eeee3f4848d9f098b46ec2d8cdce2d1d02552

See more details on using hashes here.

Provenance

The following attestation bundles were made for proxide-0.1.0a16-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.0a16-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl.

File metadata

File hashes

Hashes for proxide-0.1.0a16-cp311-abi3-manylinux_2_17_aarch64.manylinux2014_aarch64.whl
Algorithm Hash digest
SHA256 3f9464cb30a90942fe82fb9ed10a7c58b76d371a4323a217469f30bc885d39e6
MD5 c8f6f37afe066bd165f6454672013219
BLAKE2b-256 2fa761b90da7def10852c32fb46cc3a3ae9b8b09228b12432b0409c2c6a05329

See more details on using hashes here.

Provenance

The following attestation bundles were made for proxide-0.1.0a16-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.0a16-cp311-abi3-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for proxide-0.1.0a16-cp311-abi3-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 62a9ce8eb447618b1b67196103b698f343e5ce2052e1b616feac28b0ada6229e
MD5 51f0f51c74a0e9cc37aaa70c3fafb9b7
BLAKE2b-256 568940255f220825b3a36e73a1c1d2bb7f7c65366ebe90dfc3cbf57b28fd8429

See more details on using hashes here.

Provenance

The following attestation bundles were made for proxide-0.1.0a16-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.0a16-cp311-abi3-macosx_10_12_x86_64.whl.

File metadata

File hashes

Hashes for proxide-0.1.0a16-cp311-abi3-macosx_10_12_x86_64.whl
Algorithm Hash digest
SHA256 4388955df85027338f9767340776a8ab805378b8cc277ab78bb52c9141d698c8
MD5 b3f8f586cbebbe764aa4e8ae027661cf
BLAKE2b-256 18e58549b01e1ef07e7dda516cc50bd22c5e26361abc6a5225efba7d9779f84f

See more details on using hashes here.

Provenance

The following attestation bundles were made for proxide-0.1.0a16-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