RayMol
RayMol is a native macOS · iPad · iPhone reimagining of the PyMOL molecular visualization system. Built with SwiftUI and Metal, it pairs a modern touch- and pointer-native user interface with the real PyMOL C++ chemistry and graphics core and an embedded CPython 3.13 runtime, running the full pymol Python API on-device. RayMol is an open-source fork of pymol-open-source.
Highlights
- Metal renderer & hardware ray tracing — Real-time ray-cast spheres and cylinders, smooth spline cartoons, order-independent transparency, and hardware-accelerated ambient occlusion and shadows on Apple Silicon (
metal_raytrace, on by default where supported).
- Studio lights & atmosphere (beta, not yet released) — Up to six spot lights per scene with customizable beam widths, warmth, and colored shadows, plus volumetric haze and floating dust drift (
lights and atmosphere).
- Materials & Looks — Per-object materials (matte, plastic, metallic, glass, frosted glass, jelly, marble, clay, rubber) with realistic refraction and reflections, plus one-click Looks (gold, copper, statuary marble, terracotta).
- Camera lens & depth of field — True focal length and dolly-zoom camera controls (wide-angle to telephoto) and scatter-based bokeh depth of field with autofocus on active selections.
- Timeline movie studio — Docked multi-track timeline editor for animating camera keyframes, scene cuts, and multi-state (NMR/MD) ensemble playback.
- Structure prediction — On-device structure prediction with Boltz-2 (all platforms) and Protenix (AlphaFold3-class, macOS only) via Tools ▸ Enter Predict Mode (
⌃P) or cmd.predict, with remote MSA search and live progress reporting. Prediction on iPad and iPhone requires iOS/iPadOS 18.
- Sequence design — On-device ProteinMPNN sequence design in Design mode via Tools ▸ Enter Design Mode (
⌃D) with live rescoring and sidechain repacking, plus experimental, macOS-only RFdiffusion3 backbone generation (binder_design; generates a backbone, not a confirmed binder). Design mode on iPad and iPhone requires iOS/iPadOS 18.
- Metrics — Per-residue and whole-structure prediction and design confidence scores (pLDDT, PAE, certainty, native fit) attached directly to molecular objects (
metrics_get, metrics_color).
- Analysis notes — In-session Markdown notes with tags, camera/scene view links, and live scientific inserts (selected residues, contacts around selection, measurements).
- Glycobiology (next release) — SNFG-compliant (Symbol Nomenclature for Glycans) 3D cartoon symbols and color conventions for carbohydrate residues (
glycocartoon, glycocolor).
- Grid mode — Side-by-side multi-structure comparison in customizable grid cells with independent picking, clipping, and shadows (
set grid_mode, 1).
- Built-in MCP server for AI apps — Local Model Context Protocol server enabling Claude Code and the Claude desktop app to inspect and drive RayMol (macOS only; excluded from the Mac App Store build).
- Theme Studio — Live-preview theming system with presets (Classic, Paper, Sunset, Dawn) and custom palette configuration for application chrome and molecular defaults.
Documentation
User documentation is available online at https://javierbq.github.io/RayMol/, which is what Documentation on raymol.io links to.
The Markdown files in docs/src/content/docs/ are the source of that site: what you read under raymol.io ▸ Documentation is these pages, built with Astro Starlight and deployed automatically to GitHub Pages by .github/workflows/deploy-docs.yml whenever a release is published or a v* tag is pushed (or on manual dispatch). To update or add user documentation, edit those files and update the sidebar navigation in docs/astro.config.mjs; see the Documentation Contributor Guide for instructions.
Detailed per-version release notes are available in docs/release-notes/.
Install
macOS
iPad & iPhone
System Requirements
- macOS: 14.0 (Sonoma) or newer. Requires an Apple Silicon Mac (M-series); hardware ray tracing and on-device ML models require Apple Silicon.
- iOS / iPadOS: 17.0 or newer.
Building from Source
Native App (macOS & iOS)
The native app lives in swiftui/ and embeds both standalone CPython and a Metal-only build of the PyMOL C++ core (libpymol_core.a).
To build the macOS app locally:
- Install build dependencies via Homebrew:
brew install glm libpng freetype libomp
- Fetch the embedded standalone CPython 3.13:
scripts/fetch_macos_python.sh
- Compile the C++ core:
swiftui/build_macos.sh
- Build the app in Xcode using
swiftui/PyMOLViewer.xcodeproj (scheme PyMOLViewer_macOS), or run:
cd swiftui
xcodebuild -project PyMOLViewer.xcodeproj -scheme PyMOLViewer_macOS -configuration Debug -destination 'platform=macOS' build
For iOS build instructions and troubleshooting, see swiftui/README.md.
Classic PyMOL Core & Python Module
To build the traditional Python package and _cmd extension module:
pip install --verbose --no-build-isolation --config-settings testing=True .
Run the unit test suite with:
pymol -ckqy testing/testing.py --run all
See INSTALL and CLAUDE.md for build options and development guidelines.
Repository Layout
| Path | Purpose |
|---|
swiftui/ | Native macOS, iPadOS, and iOS app (SwiftUI, Metal, PyMOLBridge) |
layer0–layer5 | PyMOL C++ core layers (math, object models, representations, selectors, commands) |
layerGraphics | Graphics abstraction layer and Metal / OpenGL rendering engines |
modules/pymol | Python API, RayMol extension commands, predictors, and generators |
data/shaders | GLSL shader source files (Metal shaders live in layerGraphics/metal/) |
docs/ | Documentation site (Astro Starlight), release notes, and technical design documents |
testing/ | Python unit tests and custom test runner |
Contributing
We welcome contributions! Please review DEVELOPERS for coding style and project conventions.
RayMol uses a standard feature branch workflow:
- Fork or branch from
master.
- Create a feature branch for your changes.
- Open a pull request against
master for review before merging. Direct commits to master are not permitted.
Community & Support
Credits & License
RayMol is built on PyMOL, Copyright (c) Schrödinger, LLC, and is published under the same BSD-like license — see LICENSE. PyMOL is a trademark of Schrödinger, LLC; RayMol is an independent fork and is not affiliated with or endorsed by Schrödinger.
