Command Line Interface#
gapstop is controlled via the command line interface gapstop. See
gapstop --help
Template Matching#
Template matching is started from gapstop via the run_tm subcommand:
/root/.local/lib/python3.10/site-packages/pandas/core/arrays/masked.py:60: UserWarning: Pandas requires version '1.3.6' or newer of 'bottleneck' (version '1.3.5' currently installed). from pandas.core import ( usage: gapstop run_tm [-h] [-n NTILES] [--random-seed RANDOM_SEED] [--restart] [--cleanup | --no-cleanup] params Run template matching. positional arguments: params path to input parameters star-file. options: -h, --help show this help message and exit -n NTILES, --ntiles NTILES (optional) number of tiles to decompose tomogram. --random-seed RANDOM_SEED (optional) random seed used for testing. --restart (optional) restart unfinished previous runs. --cleanup, --no-cleanup whether to keep temporary output files for debugging. (default: True)
The number of tiles can be set explicitly via the –ntiles option. In that case, it should ideally be an integral multiple of the number of MPI ranks times the number of allocated GPUs per rank. This will avoid recompilation of the GPU-kernel for left-over tiles. If unspecified, the number of tiles will be set to the overall number of GPUs available to gapstop.
The mandatory params option is a parameter file controlling template matching in starformat, see Default Parameters. Template matching can be dispatched over several sets of parameters that are specified as multiple lines in the value-section of the file, see also Parameter batching. gapstop will process these sets of parameters sequentially.
Parameter batching#
Multiline input-files can be automatically generated for different tomograms via the gapstop batch_params subcommand:
/root/.local/lib/python3.10/site-packages/pandas/core/arrays/masked.py:60: UserWarning: Pandas requires version '1.3.6' or newer of 'bottleneck' (version '1.3.5' currently installed). from pandas.core import ( usage: gapstop batch_params [-h] -t TEMPLATE -b BATCH [-o OUTPUT] Create multiline parameters from list of tomo-nums. options: -h, --help show this help message and exit -t TEMPLATE, --template TEMPLATE path to templated input parameters star-file. The parameter 'tomo_name' must contain one or more unique replacement tokens that can be found by the regex '\$[xX]+' ,i.e., a sequence of 'x' or 'X' preceded by '$'. The value for 'tomo_num' will be overwritten accordingly in every line and must not be templated explicitly. -b BATCH, --batch BATCH path to input tomo-list. Must be a file with a sequence of tomogram numbers that can be read with numpy.loadtxt. -o OUTPUT, --output OUTPUT (optional) output file; default: <template- name>.batch.<suffix>
The resulting output can subsequently be used as input to gaptstop run_tm.
Default Parameters#
Template matching is controlled via a set of parameters that have to be provided as (multiline-) starfile. Some of these parameters are mandatory, some have default values. To get an empty parameter template with defaults filled it, gapstop config can be used, see:
/root/.local/lib/python3.10/site-packages/pandas/core/arrays/masked.py:60: UserWarning: Pandas requires version '1.3.6' or newer of 'bottleneck' (version '1.3.5' currently installed). from pandas.core import ( usage: gapstop config [-h] -o OUTPUT [-n] Create template parameter file with defaults. options: -h, --help show this help message and exit -o OUTPUT, --output OUTPUT path to output parameters star-file. -n, --no-defaults Write subset of parameters without defaults. Note: Not all parameters are necessary for all subcommands.
IMPORTANT: The generated parameter file will have both anglist_name and angles parameters (angincr,
angiter, phi_angincr, phi_angiter). You have to either use anglist_name or the angles parameters. If you keep
both options in the parameter file the TM will run however it will produce outputs with zero values (“black” volumes).
Angles Generation#
gapstop can also be used to create angles to scan-over on-the-fly similar to the cryocat.geom module, when instead of _anglist_name, _angincr (and optionally _angiter, _phi_angincr and _phi_angiter are specified in the parameters. Note that _anglist_name always takes precedence when specified! The angles can also be created explicitly by running the subcommand generate_angles:
/root/.local/lib/python3.10/site-packages/pandas/core/arrays/masked.py:60: UserWarning: Pandas requires version '1.3.6' or newer of 'bottleneck' (version '1.3.5' currently installed). from pandas.core import ( usage: gapstop generate_angles [-h] --angincr ANGINCR [--angiter ANGITER] [--phi-angincr PHI_ANGINCR] [--phi-angiter PHI_ANGITER] [--symmetry SYMMETRY] [--order ORDER] Generate angles from cryocat.geom. options: -h, --help show this help message and exit --angincr ANGINCR out-of-plane angular increment in degrees. Defines how dense the cone will be sampled. In "zxz" Euler convention influences the theta (x) and psi (z2) angles. --angiter ANGITER (optional) out-of-plane angular iterations in degrees. Defines the total cone angle to be sampled as angincr*angiter*2 (the maximum should be 180 degrees for the full sphere). In "zxz" Euler convention influences the theta (x) and psi (z2) angles. If not specified, it will be set so the full sphere is sampled. --phi-angincr PHI_ANGINCR (optional) in-plane angular increments in degrees. Defines how densely the in-plane rotation will besampled. In "zxz" Euler convention influences the phi (z1) angle. If not specified it will be set with angincr parameter. --phi-angiter PHI_ANGITER (optional) in-plane angular iterations. Defines the total in-plane angle to be sampled as phi_angincr*phi_angiter*2 (the maximum should be 180 degrees for the full circle). In "zxz" Euler convention influences the phi (z1) angle. If not specified, it will be set so the circle is sampled. --symmetry SYMMETRY symmetry --order ORDER (optional) Euler-angles spec; "zxz" or "zzx"
IMPORTANT: You have to either use anglist_name or the angles parameters (angincr,
angiter, phi_angincr, phi_angiter). If you keep both options in the parameter file the TM will run however it
will produce outputs with zero values (“black” volumes).
IMPORTANT: Currently there is a bug in the angle list generation when other symmetry than C1 is used. Please use cryoCAT package instead to generate the correct angle list with symmetry as shown in the tutorial.
Additional Notes#
MPI support#
Due to jax’s memory allocation policy, it is necessary to either
either reduce the memory preallocation done by jax (see
here)
or bind GPUs explicitly to ranks so that GPUs are used exclusively by an
MPI-rank. With slurm the latter can, e.g., be achieved with
--gpu-bind=[verbose,]per_task:X to bind each rank to the number X
of GPUs.
Tiling#
Different mechanism for tiling can be set with the tiling parameter. Valid
values are ‘legacy’ (replicating the original matlab source), ‘legacy_fix’
(fixing a bug in the legacy tiling) and ‘new’ (a new implementation that is
more balanced than the legacy version). By default, currently ‘legacy_fix’
is set but the idea is to swith to new in the near future.