~~NOTOC~~ ===== sp_viper ===== Initial 3D Model - VIPER: //ab initio// 3D structure determination using Validation of Individual Parameter Reproducibility (VIPER). Determines a validated initial model using a small set of class averages produced by [[pipeline:isac:sp_isac2|ISAC2]]. \\ ===== Usage ===== Usage in command line sp_viper.py stack directory --radius=outer_radius --sym=sym --moon_elimination=moon_elimination --ir=inner_radius --rs=ring_step --xr=x_range --yr=y_range --ts=translational_search_step --delta=angular_step --center=center_type --maxit1=max_iter1 --maxit2=max_iter2 --mask3D=mask3D --L2threshold=L2threshold --ref_a=ref_a --nruns=nruns --doga=doga --fl=fl --aa=aa --pwreference=pwreference --debug \\ ===== Typical usage ===== sp_rviper exists only in MPI version. mpirun --npernode 16 -np 24 --host node1,node2 sp_viper.py stack output_directory --fl=0.25 --radius=30 --xr=2 --moon_elimination=750,4.84 A faster version using restricted ranges of parameters. mpirun --npernode 16 -np 16 --host node1 sp_viper.py stack output_directory --fl=0.25 --radius=30 --xr=1 --nruns=2 --L2threshold=1.0e300 --doga=-1 The VIPER program exists only in MPI version. Number of MPI processes **must be** a multiple of %%--%%nruns (default = 6). Since VIPER uses group of processors working together, it is important for efficient execution to have processors within a group allocated to the same node. This way any data exchange within the group does not involve network traffic. The %%--%%npernode option of mpirun accomplishes this goal. As shown in the example below when %%--%%npernode is used MPI allocates the ranks of the processors sequentially, not moving to the next node until the current one is filled. If %%--%%npernode is not used then processors are allocated in a round robin fashion (i.e. jumping to the next node with each allocation). Since in VIPER, groups contain consecutively ranked processors, it is important to provide "%%--%%npernode XX", where XX is the number of processors per node. {{viper:npernode_rank.png?600}} \\ ===== Input ===== === Main Parameters === ; stack : Input images stack: A small subset of class averages produced by ISAC2. (default required string) ; directory : Output directory: The automatically-created output directory will contain results. If the directory already exists, results will be written there, possibly overwriting previous runs. (default required string) ; %%--%%radius : Particle radius [Pixels]: Use the same value as in ISAC2. It has to be less than half the box size. (default 29) ; %%--%%sym : Point-group symmetry: Point-group symmetry of the particle. (default c1) ; %%--%%moon_elimination : Eliminate disconnected regions: Used to removed disconnected pieces from the model. As an argument it requires a comma-separated string with the mass in KDa and the pixel size in [A]. (default none) \\ === Advanced Parameters === ; %%--%%ir : Inner rotational search radius [Pixels]: Inner rotational search radius [Pixels]. (default 1) ; %%--%%rs : Ring step size [Pixels]: Step between rings used for the rotational search. (default 1) ; %%--%%xr : X search range [Pixels]: The translational search range in the x direction. Search will be +/-xr in steps of ts. (default 0) ; %%--%%yr : Y search range [Pixels]: The translational search range in the y direction. If omitted, it will be set to xr. (default 0) ; %%--%%ts : Translational search step [Pixels]: The search will be performed in -xr, -xr+ts, 0, xr-ts, xr, can be fractional. (default 1.0) ; %%--%%delta : Projection angular step [Degrees]: Projection angular step, degrees. (default 2.0) ; %%--%%center : Centering method: For 3D template, -1: center of coordinates, 0: no centering; 1: center of gravity (default -1) ; %%--%%maxit1 : Maximum iterations - GA step: Maximum number of iterations for GA step. (default 400) ; %%--%%maxit2 : Maximum iterations - Finish step: Maximum iterations number of for Finish step. (default 50) ; %%--%%mask3D : 3D mask: Path to 3D mask file. By default, a spherical mask will be used. (default sphere) ; %%--%%L2threshold : GA stop threshold: Defines the maximum relative dispersion of structures' L2 norms. (default 0.03) ; %%--%%ref_a : Projection generation method: Method for generating the quasi-uniformly distributed projection directions. S - Saff algorithm, or P - Penczek 1994 algorithm. (default S) ; %%--%%nruns : Number of runs : GA population size, i.e., the number of quasi-independent structures generated. (default 6) ; %%--%%doga : Threshold to start GA: Do GA when the fraction of orientation that changes less than 1.0 degrees is at least this fraction. (default 0.1) ; %%--%%fl : Low-pass filter frequency [1/Pixels]: Using a hyperbolic tangent low-pass filter. Specify with absolute frequency. (default 0.25) ; %%--%%aa : Low-pass filter fall-off [1/Pixels]: Fall-off of for the hyperbolic tangent low-pass filter. Specify with absolute frequency. (default 0.1) ; %%--%%pwreference : Power spectrum reference: Text file containing a 1D reference power spectrum. (default none) ; %%--%%debug : Verbose: Print debug info. (default False) \\ ===== Output ===== \\ ===== Description ===== * This program uses a Genetic Algorithm (GA) strategy to deliver a validated 3D ab initio structure. It will first compute simultaneously ab initio structures * whose number will be equal to the population size. Next, it will compare solutions and apply evolutionary operators (merge some of the solutions) * to produce their offsprings, which subsequently are used as initial structures for the next generation of GA processing. * By default, structures in the first generation are initialized randomly. * However, the program will start alignment from the alignment parameters xform.projection stored in file headers, if provided. * The program only change the alignment parameters in header. The images in stack are untouched. (Neither rotated nor shifted.) \\ ==== Method ==== \\ ==== Reference ==== \\ ==== Developer Notes ==== \\ ==== Author / Maintainer ==== Pawel A. Penczek \\ ==== Keywords ==== Category 1:: APPLICATIONS \\ ==== Files ==== sphire/bin/sp_viper.py \\ ==== See also ==== [[pipeline:isac:sp_isac2|sp_isac2]] and [[pipeline:viper:sp_rviper|sp_rviper]] \\ ==== Maturity ==== Beta:: Under evaluation and testing. Please let us know if there are any bugs. \\ ==== Bugs ==== There are no known bugs so far. \\