NAME

elec2vlat - convert electron density to the vector lattice term

SYNOPSIS

elec2vlat [ options ] -i spifile -v L_v -dt desfile
elec2vlat [ options ] -dt desfile -e elefile

DESCRIPTION

The file of electron densities, spifile in the spider format of voxel size L_v Å in the first form of the command, or a simple format elefile in the second form of the command, is opened, read and translated to a vector lattice field (vlat) which is then appended to the existing text descriptor file desfile. If desfile does not exist it is created to contain only the vlat record.

The electron density map would define a unit cell and specify the dimensions (lengths a, b, c) and shape of the cell (angles between the sides alpha, beta, gamma) as well as the number of subdivisions (voxels) of the cell (L, M and N). The electron density is then listed for each voxel. For spider image files a linear dimension (L_v) must be supplied and the unit cell dimensions are calculated from the number of divisions read from the file and this supplied value. It is also assumed that the lattice is rectangular ( alpha, beta, gamma are all 90 degrees).

First, all the voxels are scanned to determine the lowest positive and highest electron densities. Then all the voxels are scanned again to locate all voxels with electron densities within a fraction (specified by -deldensity) of the maximum density. The midpoint of all the voxels in this group is calculated as part of the vlat record as the default destination.

Each voxel is then accorded an energy that scales linearly with the electron density such that the highest electron density corresponds to the minimum energy of -kT (at 300K) and the lowest electron density corresponds to an energy of 0. All other voxels are accorded the maximum energy of kT.

The gradients are determined next. All voxels with energies within a fraction (again specified by -deldensity) of the minimum energy are accorded zero gradients. For other voxels i, a search is carried out, one shell at a time, of the neighboring voxels. If the voxel in the first shell j with the lowest energy in the shell has a lower energy than for voxel i, then the gradient for voxel i is pointed towards voxel j. The magnitude of the gradient is the difference in the energy of the two voxels divided by the square of the distance between the midpoints of the two voxels. If no lower energy voxel is found the search is continued to a maximum number of shells specified by -maxshell. If no lower energy voxel can be found and if the energy of voxel i is greater than 0 (which would have corresponded to the minimum positive electron density) then the gradient is set to zero. For other voxels with energy greater than 0, the gradient is set to point towards the default destination.

options have the following values:

-maxshell S_max: The preset value is 1. This should be as large as possible for most electron density maps but this may lead to very long searches. Normally a search is completed on the first or second shells. However, if there are large regions of uniform densities, many of the searches for higher electron density will have to be carried out to the maximum of S_max shells. A value of 5 is recommended.

-numtypes N_type: Number of atom types. The preset value is 5. N_type weights will be written. All the weights will have the value 1.0 and this value cannot be specified although it can be modified in the descriptor that results.

-deldensity D: The smallest fraction of electron density that is to be considered significant. The preset value is 0.01.

-mindensity d_min: The minimum electron density that is to be considered significant. The preset value is the smallest positive electron density.

-Lx L_x: Along the x'-axis (of length a) L_x voxels are combined to form larger voxels and the density for this larger voxel is the average over these voxels. L_x must be an exact divisor for the original number of voxels along this side (L). The preset value is 1, i.e., no averaging.

-Mx M_x: Along the y'-axis (of length b) M_x voxels are combined to form larger voxels and the density for this larger voxel is the average over these voxels. M_x must be an exact divisor for the original number of voxels along this side (M). The preset value is 1, i.e., no averaging.

-Nx N_x: Along the z'-axis (of length c) N_x voxels are combined to form larger voxels and the density for this larger voxel is the average over these voxels. N_x must be an exact divisor for the original number of voxels along this side (N). The preset value is 1, i.e., no averaging.

-alt: The outcome of this argument is to reverse the c-axis and swap the a and b-axes. The default behavior of this program (when -alt is not specified) appears to be wrong so this option should always be selected.

Only data from a spider image file can be averaged. -Lx, -Mx and -Nx have no effect on electron density maps specified through -e. Averaging should be done only to quickly assess an image file or only if there is not enough memory to process a complete map.

EXAMPLE

elec2vlat -e map -dt rna.dx

Process the electron density map contained in the file map and append the vlat record to the text descriptor rna.dx.

FILES

The spider file format is documented elsewhere.

A very simple electron density map format is assumed for the file specified with -e.

The top of the file contains three lines of three space-separated numbers each. The first line contains the cell dimensions in Å, a, b, and c. Next are the cell angles in degrees, alpha which is the angle between the second and third axes of the unit cell, beta between the first and third and gamma between the first and second. The third line contains the number of divisions along the first, second and third axes, L, M, and N.

a	b	c
alpha	beta	gamma
L	M	N

The rest of the file contains the electron densities

rho	...
...
...	...	...

The electron densities are read from left to right, top to bottom with no restriction on the number of densities per line. However, the order is important. It is assumed that the densities are listed for the three-dimensional array of voxels with the first index increasing fastest, i.e., (1,1,1), (2,1,1), (3,1,1), ..., ( L,1,1), (1,2,1), ..., ( L,2,1), ..., ( L, M,1), ..., ( L, M,N). There must be exactly LMN densities.

The format of the descriptor file is documented here.

SEE ALSO

The format of the vlat record.
Converting the text descriptor file using des.
The vlat force term can be uniformly scaled during a simulation.
The location of the atoms within the unit cell can be reported.
Spider image files should be analyzed first using checkspider.

DIAGNOSTICS

BUGS

NOTES

The -alt option is not currently available in the public distribution.

Be careful specifying the name of the descriptor file. It is possible to append more than one vlat record to the file. Such records can be very big and only the last record will survive conversion. Intermediate vlat records will occupy memory uselessly and may even take up too much memory for the entire file to be converted.

The creation of the vector lattice is a very time consuming process. Except for the very smallest image maps, this command should be run as a batch process. The time required for a conversion using a large number of search shells is approximately proportional to (LMN)³ since for each of the LMN voxels a search is made over a local volume for another voxel with a higher electron density. The conversion time on a 175-MHz SGI Octane workstation for image maps A and B under different conditions are shown in the table below.

Map	A	A	B	A	B	B	A	A	A	B	B
Lattice Size	303	303	303	453	453	453	903	903	903	903	903
Smax	5	7	5	5	5	11	3	5	5	5	22
Trimmed	100%	100%	100%	100%	100%	100%	100%	57%	100%	100%	100%
CPU Time	16 min.	33 min.	3 min.	1 hr.	13 min.	25 min.	3 hr.	5 hr.	11.5 hr.	3.3 hr.	34 hr.

For a 90³ map, the memory requirement on a machine with 128MB RAM is such that quite a bit of swapping occurs and the time depends on many external factors. On this system, which has half a gigabyte of virtual memory, a 100³ map is probably the largest that can be handled. The memory required for the conversion to the vector lattice is about ten times that required for a molecular mechanics calculation using the finished lattice. (Thus, the limiting factor is the conversion process not the actual use of the vector lattice.) The time required for calculations using the vector lattice is not dependent on the number of lattice points provided the lattice does not require so much memory that excessive paging occurs.

It may be worthwhile to trim some lattices (see checkspider). Trimming should be used with great care. If only a few outer slices can be removed it may not be worth the trouble. The speed at which simulations are carried out with the vlat term is not strongly dependent on the size of the lattice so the only reason to consider trimming is to be able to generate the lattice term quicker and to economize on memory during simulations.

Since a vector lattice requires a very long calculation it is recommended that an analysis is made of the image map before committing to a lengthy conversion. checkspider is provided for this purpose.

The vector lattice record is very big: the size of a file containing a 90³ vlat record is over 22MB (about 11MB if converted to binary). It is recommended that the lattice map is created as a new descriptor containing only the vlat record. Then, convert to binary, and back to text, remove the first line of the file so that it is no longer a proper descriptor file but it still contains a properly formatted vlat record. This file (possibly compressed - to about 6MB in our example - in between use) can then be appended to a text descriptor whenever the vector lattice is required in a simulation.