README.md 5.95 KB
Newer Older
1
# Pyrite 1.1.1
2
3

## Description
jdurrant's avatar
jdurrant committed
4

jdurrant's avatar
Updates    
jdurrant committed
5
"Pyrite" is a program for importing a molecular dynamics trajectory into
jdurrant's avatar
jdurrant committed
6
7
8
Blender, to take advantage of Blender's advanced rendering features. A copy of
the plugin is available at
[http://durrantlab.com/pyrite/](http://durrantlab.com/pyrite/), released under
jdurrant's avatar
jdurrant committed
9
the terms of the GNU General Public License Version 3. [Click here](https://durrantlab.com/apps/pyrite/docs/pyrite_tutorial.mp4) for a video tutorial.
jdurrant's avatar
jdurrant committed
10

jdurrant's avatar
jdurrant committed
11
If you use Pyrite, please [cite our paper](https://onlinelibrary.wiley.com/doi/full/10.1002/jcc.25155).
jdurrant's avatar
jdurrant committed
12

13
## The Latest Version
jdurrant's avatar
jdurrant committed
14

15
16
To view the source code of the latest version, visit
[http://git.durrantlab.com/jdurrant/pyrite](http://git.durrantlab.com/jdurrant/pyrite).
jdurrant's avatar
jdurrant committed
17
18
19
20
The same code is mirrored on GitHub.

Visit [http://durrantlab.com/pyrite/](http://durrantlab.com/pyrite/) to:

21
* read the documentation
jdurrant's avatar
jdurrant committed
22
23
24
25
* suggest an improvement
* point out a bug
* ask a question about usage

26
## Installation
jdurrant's avatar
jdurrant committed
27
28
29
30

Pyrite installation within Blender is the same as with any Blender plugin:

1. Visit [http://durrantlab.com/pyrite/](http://durrantlab.com/pyrite/) to
31
   download the Pyrite ZIP file.
32
33
34
2. Within Blender, click on the ```Edit > Preferences...``` menu item to open
   the ```Blender Preferences``` window.
3. Click the ```Add-ons``` button at the left of that window to open the
35
   add-ons panel.
jdurrant's avatar
jdurrant committed
36
4. Specify the location of the downloaded ZIP file by clicking on the
37
38
39
40
41
   ```Install...``` button at the bottom of the window.
5. Once installed, click the ```Import-Export: Pyrite``` checkbox to
   activate the plugin.
6. To keep the plugin active after Blender restarts, you may need to use
   the ```Save Preferences``` option.
jdurrant's avatar
jdurrant committed
42

43
## Authors and Contacts
jdurrant's avatar
jdurrant committed
44
45
46
47

Pyrite was produced by Jacob Durrant
([durrantj@pitt.edu](mailto:durrantj@pitt.edu)) with the assistance of Nivi
Rajendiran.
jdurrant's avatar
jdurrant committed
48

49
## Tutorial
jdurrant's avatar
jdurrant committed
50

51
### 1. Create a Protein or Nucleic-Acid Mesh
jdurrant's avatar
jdurrant committed
52

jdurrant's avatar
jdurrant committed
53
54
55
56
57
Free programs such as VMD, PyMOL, and Chimera export molecular representations
in Blender-compatible formats (e.g., OBJ, WRL, X3D, etc). Exported mesh files
use camera coordinates rather than the world coordinates of the original
model. Before exporting, all transformation matrices must be set to identity.
In VMD, this simple TCL script, adapted from code provided by John Stone
58
(VMD’s primary developer), sets the coordinate system:
jdurrant's avatar
jdurrant committed
59

60
```tcl
jdurrant's avatar
jdurrant committed
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
set m {
  {{1.0 0.0 0.0 0.0}
   {0.0 1.0 0.0 0.0}
   {0.0 0.0 1.0 0.0}
   {0.0 0.0 0.0 1.0}}
  {{1.0 0.0 0.0 0.0}
   {0.0 1.0 0.0 0.0}
   {0.0 0.0 1.0 0.0}
   {0.0 0.0 0.0 1.0}}
  {{1.0 0.0 0.0 0.0}
   {0.0 1.0 0.0 0.0}
   {0.0 0.0 1.0 0.0}
   {0.0 0.0 0.0 1.0}}
  {{1.0 0.0 0.0 0.0}
   {0.0 1.0 0.0 0.0}
   {0.0 0.0 1.0 0.0}
   {0.0 0.0 0.0 1.0}}
}

for {set i 0} {$i < [molinfo num]} {incr i} {
  molinfo ${i} set {center_matrix rotate_matrix scale_matrix global_matrix} $m
}
jdurrant's avatar
jdurrant committed
83
```
jdurrant's avatar
jdurrant committed
84

jdurrant's avatar
jdurrant committed
85
86
In PyMOL, the same can be accomplished with this Python script, which moves
and rotates the camera to the appropriate location:
jdurrant's avatar
jdurrant committed
87

88
```python
jdurrant's avatar
jdurrant committed
89
90
91
92
93
94
cmd.set_view([ 1.0,   0.0,   0.0,
               0.0,   1.0,   0.0,
               0.0,   0.0,   1.0,
               0.0,   0.0,   0.0,
               0.0,   0.0,   0.0,
              40.0, 100.0, -20.0])
jdurrant's avatar
jdurrant committed
95
```
jdurrant's avatar
jdurrant committed
96

jdurrant's avatar
jdurrant committed
97
98
99
100
After setting up the scene in your program of choice (e.g., using ribbon or
surface representation for the proteins), export the first frame as an OBJ
file.

101
### 2. Import Mesh into Blender
jdurrant's avatar
jdurrant committed
102
103
104

Import your Wavefront OBJ file using Blender's menu: ```File > Import >
Wavefront (.obj)```.  After importing the mesh, prepare it for animation. For
jdurrant's avatar
jdurrant committed
105
example, using Blender's "Remove Doubles" command is often critical. Available
jdurrant's avatar
jdurrant committed
106
107
108
109
110
111
112
in Edit Mode, this command merges duplicate vertices into one to ensure that
all mesh faces are connected.

Blender itself sometimes imports meshes using the incorrect coordinate system.
Setting the object position and rotation vectors to ```(0.0, 0.0, 0.0)```, and
the scaling vector to ```(1.0, 1.0, 1.0)```, ensures that the imported object
and trajectory use the same system. Pressing the "Auto-Fix" button in Pyrite's
113
Sidebar Panel will automatically set these vectors. You can also set the
jdurrant's avatar
jdurrant committed
114
115
values in Blender’s Object Properties Panel.

116
### 3. Specify the Trajectory File
jdurrant's avatar
jdurrant committed
117
118
119
120
121
122

If an object has the appropriate transformation vectors, the Pyrite tab
presents options for simulation import. Use the first option to specify the
location of the MD trajectory file, in multi-frame PDB format. Trajectories
saved in other formats (e.g., the binary DCD format) can be converted to PDB
using [VMD](http://www.ks.uiuc.edu/Research/vmd/) or
123
[catdcd](http://www.ks.uiuc.edu/Development/MDTools/catdcd/).
jdurrant's avatar
jdurrant committed
124

125
### 4. Set the Trajectory-Simplification Options
jdurrant's avatar
jdurrant committed
126
127
128
129
130

Loading the position of every atom across the entire MD trajectory is often
too memory and CPU intensive. Instead, Pyrite coarse grains the simulation
across time and space by discarding some frames and atoms. Select the temporal
and spatial resolution by indicating how often to keep a frame or atom (e.g.,
131
only every nth frame and every mth atom).
jdurrant's avatar
jdurrant committed
132

133
### 5. Create High-Detail Regions
jdurrant's avatar
jdurrant committed
134
135
136
137
138

You may wish to more accurately represent the MD-captured motions of some
regions (e.g., active sites):

1. Add a sphere to Blender's viewport by positioning the 3D cursor and
139
   clicking the "Create Region" button in the "High-Detail Regions" subpanel.
jdurrant's avatar
jdurrant committed
140
2. Adjust the position and scaling until the sphere encompasses the region of
141
   interest.
jdurrant's avatar
jdurrant committed
142
143
144
145
3. Use the Pyrite panel to specify how often to keep atoms within the sphere.
   By selecting a lower skip/stride value, fewer atoms within the
   sphere-defined region are discarded. The captured MD motions within this
   region will have higher spatial resolution.
jdurrant's avatar
jdurrant committed
146
147
4. After positioning and scaling the sphere, press the "Back to Mesh"
   button to save. Alternatively, the "Delete Region" button will remove the
148
   current sphere.
jdurrant's avatar
jdurrant committed
149
150
151
152

You can add several spheres to the scene if multiple distinct regions require
higher spatial resolution.

153
### 6. Load the Trajectory
jdurrant's avatar
jdurrant committed
154

jdurrant's avatar
jdurrant committed
155
After saving the high-detail regions, press the "Load Trajectory" button to
jdurrant's avatar
jdurrant committed
156
import trajectory data. Empty objects populate the viewport at the locations
157
of the retained atoms.