= Name =
sxmeridien - 3D Refinement: Performs 3D structure refinement.


= Usage =

''usage in command line''

sxmeridien.py  stack  output_directory  initial_volume  --radius=particle_radius  --mask3D=MASK3D  --symmetry=SYMMETRY  --inires=INIRES  --delta=DELTA  --do_final=DO_FINAL  --memory_per_node=MEMORY_PER_NODE  --xr=XR  --ts=TS  --skip_prealignment  --initialshifts  --center_method=CENTER_METHOD  --target_radius=TARGET_RADIUS  --shake=SHAKE  --small_memory  --ref_a=REF_A  --ccfpercentage=CCFPERCENTAGE  --nonorm  --ctrefromsort3d  --subset=subset_file_path  --oldrefdir=refine_dir_path  --ctrefromiter=restarting_iteration  --function=user_function


=== Typical usage ===

sxmeridien exists only in MPI version.

    1. Fresh run::

    ''' mpirun  -np  88  sxmeridien.py  bdb:data  meridien_outdir  ref3d.hdf  --mask3D=mask3d.hdf  --radius=145  --symmetry=c5 ''' <<BR>><<BR>>

    2. Continue run/simple restart::

    ''' mpirun  -np  88  sxmeridien.py  meridien_outdir ''' <<BR>><<BR>>

    3. Continue run/restart with altered parameters::

    ''' mpirun  -np  88  sxmeridien.py  meridien_outdir  —-raduis=140 ''' <<BR>><<BR>>

    4. Do only final reconstruction at a specific iteration::

    ''' mpirun  -np  88  sxmeridien.py  meridien_outdir  —-do_final=23 ''' <<BR>><<BR>>

    5. Do only final reconstruction using the iteration which achieved the best resolution::

    ''' mpirun  -np  88  sxmeridien.py  meridien_outdir  —-do_final=0 ''' <<BR>><<BR>>

    6. Continue refinement from sorting results:: Please use --ctrefromsort3d option, then specify the directory where you wish to continue the refinement to --oldrefdir option and a subset of data to —-subset option. The command will load the refinement information from the directory and continue refinement. Optionally, you can specify the iteration number for continuing refinement using -—ctrefromiter option, which is not necessarily be the same iteration where you used for the 3D sorting. Also, one can modify refinement parameters of the selected iteration through the other options. 

    ''' mpirun  -np  88  sxmeridien.py  --ctrefromsort3d  --oldrefdir=meridien_outdir  --ctrefromiter=20  --subset=Clusters3.txt ''' <<BR>><<BR>>


== Input ==
    stack:: Input image stack: (default none)
    initial_volume:: Initial 3D reference: (default none)

    radius:: Particle radius [Pixels]: Outer radius [in pixels] of particles < int(nx/2)-1 (default -1) 
    mask3D:: 3D mask: Soft mask for the volume. If not given, a hard sphere of radius boxsize/2-1 will be used. (default none)
    symmetry:: Point-group symmetry: Symmetry of the refined structure. Acceptable values are: cn, dn, where n is multiplicity. (default c1)
    inires:: Starting resolution [A]: Resolution used to start the refinement. (default 25.0)
    delta:: Initial angular sampling step: Initial angular sampling step. (default 7.5)
    do_final::Perform final reconstruction: Perform final reconstruction using orientation parameters from the specified iteration. By default, it uses iteration achieved best resolution. (default -1)
    memory_per_node:: Memory per node [GB]: User provided information about memory per node in GB (NOT per CPU). By default, it uses 2GB * (number of CPUs per node) (default -1.0)
    ctrefromsort3d::Continue refinement after 3D sorting: Continue local/exhaustive refinement with a data subset generated by a 3D sorting. (default False)
    subset::Subset text file path: A text contains indexes of data subset sorted by a 3D sorting. Typically, use Cluster#.txt created by sxrsort3d (e.g. Cluster1.txt). (default none)
    oldrefdir::3D refinement directory: The master output directory of a 3D refinement which is used for the input of 3D sorting. (default none)
    ctrefromiter::Restarting iteration: The iteration from which 3D refinement should be continued. (default -1)

    * The remaining parameters are optional.
    xr:: Search range [Pixels]: Range for translation search in both directions. Search is +/-xr. It can be fractional (default 5.0) 
    ts:: Search step size [Pixels]: Step size of translation search in both directions. Search is within a circle of radius xr on a grid with steps ts. It can be fractional. (default 1.0)
    skip_prealignment:: Skip 2D pre-alignment step: Use this option if images are already centered. (default False)
    initialshifts:: Read shifts from header: Start with the shift parameters stored in the image headers. Useful to jumpstart the procedure. (default False)
    center_method:: Centering method: Method for centering averages during initial 2D prealignment of data (0: no centering; -1: average shift method; For 1-7, see center_2D in utilities.py) (default -1)
    target_radius:: Target particle radius: For 2D prealignment, images will be shrank/enlarged to this radius. (default 29)
    shake:: Shake: Shake (default 0.5)
    small_memory:: Do not keep data in memory: Data will not be kept in memory if small_memory is true (default False)
    ref_a::Projection generation method: Method for generating the quasi-uniformly distributed projection directions. S- Saff algorithm, or P - Penczek 1994 algorithm. (default S)
    ccfpercentage::Correlation peaks to be included [%]: Percentage of correlation peaks to be included. 0.0 corresponds to hard matching. (default 99.9)
    nonorm::Skip image norm correction: Do not apply image norm correction. (default False)
    function:: Reference preparation function: Function used to prepare the reference volume after each iteration. (default do_volume_mask)


== Output ==
    output_directory:: Output directory: The results will be written here. This directory will be created automatically if it does not exist. (default none)


= Description =

= Author / Maintainer =
Pawel A. Penczek

= Keywords =
    category 1:: APPLICATIONS

= Files =
sxmeridien.py

= See also =
References to relevant other routines.

= Maturity =
 alpha:: in development
