splittilt(1)                General Commands Manual               splittilt(1)



NAME
       splittilt - Produce multiple command files for running Tilt in parallel

SYNOPSIS
       splittilt  [options]  Tilt_command_file

DESCRIPTION
       splittilt will take a command file for running the Tilt program for
       tomogram generation and produce multiple command files that can be run
       in parallel by Processchunks.  It takes into account the computa-
       tional implications of some of the parameter settings when determining
       how many chunks to divide the task into.

       The only argument that the typical user needs to give is -n to specify
       the expected number of processors to be used.  Only an approximate num-
       ber is needed.  The default value is printed out by the program's usage
       statement.  Thus, a typical command might be
          splittilt -n 6 tilta.com
       After giving this command, there will be a series of command files
       tilta-nnn.com to compute the chunks, and a file tilta-finish.com to
       finish the task and clean up intermediate files.  One can then enter
          processchunks machine_list tilta
       where "machine_list" is the comma-separated list of machines to use, or
       just the number of processors to use on the local machine.

       The problem in dividing up the Tilt task is that the smaller the chunks
       are, the greater the total amount of resources needed because of the
       overhead involved in doing each chunk; whereas the larger the chunks,
       the greater the chance that a slow machine will hold up the entire
       process.  The overhead takes two forms: the file I/O and preprocessing
       involved in accessing all of the projection data needed to reconstruct
       a given number of slices; and the extra "vertical" slices that must be
       computed when there is X-axis tilting but no local alignments.  The
       former overhead is minimized simply by having a minimum number of
       slices in each chunk.  The latter overhead is explicitly minimized by
       taking into account the penalty for doing old-style X-axis tilting
       (direct backprojection of each output slice) versus interpolation
       between vertical slices.

       Initially, the program aims for a target number of chunks that is a
       fixed multiple of the expected number of processors (or that is entered
       with the -t option).  If the command file uses fixed X-axis tilting but
       no local alignments or Z factors, then the program drops back to a
       smaller number, referred to as the minimum number of chunks.  If the
       extra computational burden from computing vertical slices is greater
       than the defined penalty for doing old-style tilting, the program then
       switches to old-style tilting unless the -v option is given.  In that
       case, vertical slices are still computed but the number of chunks is
       further reduced until the penalty for doing vertical slices matches the
       penalty for switching to old-style tilting, and the number of chunks is
       allowed to go as low as the expected number of machines.  In all cases,
       the number of chunks is constrained by the minimum number of slices in
       each chunk.

       The program will also operate on a command file for reprojecting from a
       tomogram; here, it just maintains a minimum number of slices per chunk.


OPTIONS
       Splitblend uses the PIP package for input (see the manual page for
       pip).  Options can be specified either as command line arguments
       (with the -) or one per line in a command file (without the -).
       Options can be abbreviated to unique letters; the currently valid
       abbreviations for short names are shown in parentheses.

       -CommandFile    File name
              Tilt command file.  It can be entered with or without extension,
              i.e., as "tilt", "tilt.", or "tilt.com".

       -outroot (-ou) OR -RootNameOfOutput      Text string
              Root name for output command files (default is root of input
              file)

       -naming (-na) OR -NamingStyle       Integer
              0 if image files have descriptive extensions like ".preali", or
              1 or 2 if descriptive text is before the extension ".mrc" or
              ".hdf".  This entry is needed only if the style cannot be deter-
              mined from files in the dataset.

       -n OR -ProcessorNumber    Integer
              The number of machines that you expect to run the command files
              on.  The default is 8

       -s OR -SliceMinimum       Integer
              Minimum number of slices per chunk (default 50)

       -t OR -TargetChunks       Integer
              Target number of chunks (default 5 times expected # of machines)

       -m OR -ChunkMinimum       Integer
              Minimum number of chunks, except when vertical slices are speci-
              fied with the -v option.  The default is 2 times the expected
              number of machines, but with vertical slices, the minimum
              becomes one chunk per machine.

       -p OR -OldStyleXtiltPenalty    Floating point
              Computational penalty for old-style X-axis tilting (default
              1.33)

       -v OR -VerticalSlices
              Do vertical slices instead of old-style X-axis tilting, regard-
              less of the penalty.

       -c OR -SeparateChunks
              Write chunks to separate files named setname-nnn.rec and assem-
              ble the output file from these at the end.  The default is to
              write directly to the output file.

       -b OR -BoundaryPixels     Integer
              Number of pixels at each boundary between chunks to save in sep-
              arate boundary files (named setname-nnn.rbound) and rewrite to
              the output file in the -finish.com file, when directly writing
              to the output file.  The default is 2048.  This capability to
              rewrite lines at the boundary should make it unnecessary to
              write chunks to separate files.

       -i OR -InitialComNumber   Integer
              Start with given command file number instead of 1.  When this
              option is entered, the program will not delete any existing com-
              mand files.  If data are being written directly to output file,
              the first file is named -nnn-sync.com instead of -start.com.

       -o OR -OpenForMoreComs
              Leave the command file set open by naming the command file for
              reassembly -nnn-sync.com instead of -finish.com, and by not
              cleaning up command and log files in the reassembly file.

       -unique (-un) OR -UniqueInfoFile
              Attach the first command file number to a boundary info file

       -d OR -DimensionsOfStack       Two integers
              Use the given values as the dimensions of the aligned stack.
              This option is needed when calling from Sirtsetup if the log
              of the stack is being used or if a subarea is being done.

       -help (-h) OR -usage
              Print help output

       -StandardInput
              Read parameter entries from standard input


FILES
       The finishing command file deletes all the command and log files for
       the chunks after collecting minimun, maximum, and mean density informa-
       tion from the log files.  If the -c option is given, the temporary
       reconstruction files are deleted too.

AUTHOR
       David Mastronarde  <mast at colorado dot edu>

SEE ALSO
       processchunks, tilt



IMOD                                4.11.0                        splittilt(1)