search

nanovis / DiffFit

DiffFit: Visually-Guided Differentiable Fitting of Molecule Structures to Cryo-EM Map
Other
6 stars 0 forks source link

readme

DiffFit: Visually-Guided Differentiable Fitting of Molecule Structures to Cryo-EM Map

DiffFit_Teaser_30sec

If you use material from this repository, please cite the associated paper:

Deng Luo, Zainab Alsuwaykit, Dawar Khan, Ondřej Strnad, Tobias Isenberg, and Ivan Viola. DiffFit: Visually-Guided Differentiable Fitting of Molecule Structures to a Cryo-EM Map. IEEE Transactions on Visualization and Computer Graphics, 31, 2025. To appear. doi: 10.1109/TVCG.2024.3456404

bibTeX and more
``` @article{Luo:2025:DVG, author = {Deng Luo and Zainab Alsuwaykit and Dawar Khan and Ond{\v{r}}ej Strnad and Tobias Isenberg and Ivan Viola}, title = {{DiffFit}: Visually-Guided Differentiable Fitting of Molecule Structures to a Cryo-{EM} Map}, journal = {IEEE Transactions on Visualization and Computer Graphics}, year = {2025}, volume = {31}, doi = {10.1109/TVCG.2024.3456404}, doi_url = {https://doi.org/10.1109/TVCG.2024.3456404}, github_url = {https://github.com/nanovis/DiffFit}, osf_url = {https://osf.io/5tx4q/}, preprint = {https://doi.org/10.48550/arXiv.2404.02465}, hal_url = {https://hal.science/hal-04665408}, video = {https://youtu.be/dWcHDWT9_mw}, } ``` IEEE VIS 2024 Submission [arXiv preprint](https://arxiv.org/abs/2404.02465), [Video](https://youtu.be/dWcHDWT9_mw), [OSF repo](https://osf.io/5tx4q/) IEEE VIS 2024 Presentation Rehearsal https://youtu.be/xhUklGhR2FI

YouTube tutorial videos (playlist)

  1. Install, and enable CUDA
  2. Demo Usage Scenario 1: Fit a single structure
  3. Demo Usage Scenario 2: Composite multiple structures
  4. Demo Usage Scenario 3: Identify unknown densities
Old tutorial videos
1. [Install for developers](https://youtu.be/aYqNZ0SNUfk) 2. Demo Usage Scenario 1: Fit a single structure [before v0.2.0](https://youtu.be/dHquT2Lsh54) 3. Demo Usage Scenario 3: Identify unknown densities [before v0.2.0](https://youtu.be/4fV-qHO9spw)

Install

Option 1 - From the official ChimeraX Toolshed:

  1. Download, install, and open ChimeraX
  2. From the top menu bar, click Tools > More Tools...
  3. From the newly opened ChimeraX's built-in browser page, find and click "DiffFit". You may click "more newest releases »" if you cannot find it on the home page.
  4. Click Install (a big blue button). If it's your first time installing, it might take several minutes because it needs to install dependent packages such as PyTorch.

Option 2 - From the GitHub release page:

  1. Download the latest distribution (download the .whl file)
  2. Open ChimeraX and run the command toolshed install <path to the downloaded .whl file>

Now, DiffFit should be fully installed.

  1. Launch it via Tools > Volume Data > DiffFit.
  2. By default, the DiffFit panel floats above the ChimeraX window. You may right-click, check Dockable Tool, and move the panel around to dock it (suggest docking at the less preferred side, which usually is the left side). Then you may right-click and click Save Tool Position.

Enable CUDA

If you have an Nvidia GPU card, but in the Settings tab you don't see cuda:0 next to Device, you should go to the Dependencies tab and follow the instructions there to install CUDA-enabled PyTorch. From our experience, this extra step has only been needed for Windows. For Linux, CUDA has always been enabled automatically after installation. A video guide is also available for enabling CUDA.

Documentation for using the approach

In the general approach, open the structure and the volume map, click Fit.

The whole UI design is with the hope to allow users to be able to use DiffFit without training. This is especially the case if the user is familiar with ChimeraX's Fit in Map tool or fitmap command.

We do also provide a detailed step-by-step documentation document.

If you want to reproduce the figures in our paper, please refer to the reproduction guidelines.

If you see anything we can improve the design or the documentation, please raise an issue.