← Previous Home Next →

How to use Icecream

Installation

The latest version of Icecream is always available on GitHub: https://github.com/swing-research/icecream. We recommend using git to clone the repository, ensuring that you can easily update it later.

First use of Icecream.

Clone the repository:

git clone https://github.com/swing-research/icecream.git
cd icecream

Create and activate a Python environment (Python ≥ 3.11 recommended):

conda create -n icecream python=3.11 -y
conda activate icecream

Next, install a CUDA-enabled version of PyTorch that matches your system configuration. For example, for Linux with CUDA 12.8: 

pip install torch --index-url https://download.pytorch.org/whl/cu128

Notice that we observed a significant slowdown with PyTorch version 3.9 instead of 3.8. Results of the paper were obtained with version 3.8.

Install Icecream and its dependencies:

pip install -e .

Test your installation:

icecream --help

You should see Icecream’s main commands listed: train and predict. You are now ready to use Icecream.

Already a user or Icecream.

Make sure to get the latest version, run the following command in the folder of the project

git pull

Generate two tomograms with one tilt-series

Icecream requires two statistically indepdent tomograms as input. The recommended workflow, similar to Cryo-CARE, is to split the dose of your tilt-series and reconstruct two independent tomograms. If that’s not possible, you can instead split the tilt-series by angle range. Icecream provides a dedicated command for this:

icecream split-tilt-series --input path/to/tilt-series.mrc --angles path/to/angles.tlt

Alternatively, you can specify the angular range manually using --min-angle and --max-angle (default values are -60 and +60). The command generates two new tilt-series in the same directory as the original one, named with _split1 and _split2 suffixes.

You can then reconstruct each tomogram using your preferred software. For instance, with IMOD: 

tilt -input /path/to/tilt-series_split1.mrc -output /path/to/tomogram_FBP_split1.mrc \
     -TILTFILE /path/to/angles_angles1.tlt -THICKNESS 512 -UseGPU 0

After reconstruction, you will have two tomograms ready to be used for Icecream training.

Train Icecream on your data

Training Icecream can be done either via a configuration file or by specifying parameters directly from the command line. During training, Icecream automatically reconstructs a volume after each training cycle.

The simplest: command line interface

You can train providing minimal information with the command-line arguments:

icecream train \
  --tomo0 /path/to/tomogram_0.mrc \
  --tomo1 /path/to/tomogram_1.mrc \
  --angles /path/to/angles.tlt \
  --save-dir /path/to/save/dir \
  --iterations 10000 \
  --batch_size 8

To see the full list of available training options, run: 

icecream train --help

This command trains Icecream using two tomograms (tomogram_0 and tomogram_1). Outputs, including reconstructions, configuration (config.json), and model checkpoints, are stored in /path/to/save/dir. The batch size is set to 8 but should be adjusted depending on the GPU memory available.

More options: config file

The command-line interface provides only few parameters. To get access to a wide range of additional parameters for training control and customization, you need to use config files. We recommand copying the default config file that is located in 'src/icecream/defaults.yaml' of the icecream folder and name it after you experiment. Run Icecream can be done simply with: 

icecream train --config /path/to/config/file.yaml

Please refere to the dedicated paragraph to know more about the role of each parameter.

Inference with Icecream

After training, Icecream can perform inference (reconstruction) using a trained model checkpoint.

Inference with command line interface

This can be done with the predict command: 

icecream predict \
  --tomo0 /path/to/tomogram_0.mrc \
  --tomo1 /path/to/tomogram_1.mrc \
  --angles /path/to/angles.tlt \
  --save_dir /path/to/output_dir \
  --iter_load -1

If --iter_load is not provided or set to -1, Icecream will use the latest available checkpoint.

Config file

You may also use a YAML configuration file instead of JSON. 
icecream predict \
  --config /path/to/config/file.yaml

Pre-training: how to avoid training for every new data

Precise procedure cooming soon!

Parameters of the config file

The default config file can be found here. The different possible parameters are reported below with a brief description.

    data
Key Default Description
tomo0 [] Path(s) to the first set of tomograms. Must be ordered consistently with tomo1.
tomo1 [] Path(s) to the second set of tomograms. Must match the order of tomo0.
save_dir "runs/default/" Path where results and training information are saved.
mask null Path to mask on the spatial domain, e.g. using slabify.
tilt_max 60.0 Maximum tilt angle in degrees. Default is +60.
tilt_min -60.0 Minimum tilt angle in degrees. Default is -60.
angles null Path to the tilt-angle file (.txt or .tlt).
    train_params
Key Default Description
device 0 GPU number or device name. Only a single GPU is supported currently.
crop_size 72 Size of cubic sub-tomograms used for training.
iterations 50000 Total number of training iterations.
eq_weight 2.0 Equivariant regularization weight. Increase to get more regularization.
batch_size 8 Training batch size. Reduce if you run into GPU memory issues.
seed 42 Random seed for reproducibility.
compile false Use torch.compile to speed up training (experimental).
use_fourier false Compute loss in Fourier space if true; in spatial domain if false.
use_spherical_support true Enforce Fourier-space support within a spherical region matching subtomogram size.
wedge_low_support 0 Percentage of low frequencies to keep in the input model (not part of the missing wedge).
ref_wedge_support 1 Percentage of low frequencies to keep in the reference tomogram.
wedge_double_size true Define the missing wedge over a doubled subtomogram size if true.
save_n_iterations 5000 Save model weights every N iterations.
save_tomo_n_iterations 0 Reconstruct tomogram every N iterations (0 disables reconstruction during training).
compute_avg_loss_n_iterations 1000 Compute and log average loss every N iterations.
use_flips true Include flip operators in the equivariance loss.
normalize_crops false Normalize each subtomogram before feeding it to the network.
use_inp_wedge false Use reconstructed wedge in the equivariance loss (false in the paper’s setting).
learning_rate 1e-4 Learning rate for the optimizer. Lower it if training becomes unstable.
use_mixed_precision true Use mixed precision (AMP) to accelerate training with minor numerical loss.
no_window false If true, use the entire tomogram for training; otherwise, only the central region.
view_as_real true Discard imaginary part after inverse Fourier transform if true.
upsample_volume false Upsample the reconstructed volume by a factor of 2.
eq_use_direct false If false, the rotated wedge is masked out of the loss computation.
min_distance 0.5 Minimum relative difference between rotated and unrotated wedges.
window_type "boxcar" Shape of the cropping window.
load_device false Load all the full tomograms on the device. Will be faster but requires more memory.
num_workers 8 Number of workers available for the dataloader.
pretrain_params.use_pretrain false If true, load pretrained model weights before training.
pretrain_params.model_path None Path to pretrained model weights file.
    predict_params
Key Default Description
save_dir_reconstructions same as data.save_dir Path where to save the reconstructions. Default is same as data.save_dir.
batch_size 5 Inference batch size. Reduce if memory is limited.
stride 36 Step size (in voxels) between reconstructed subtomograms. Overlap is averaged.
pre_pad true Pad input tomogram with zeros before inference.
pre_pad_size null Size of zero-padding to apply to the tomogram before inference.
avg_pool false Apply average pooling to smooth the input tomogram.
iter_load -1 Iteration of the model to load, -1 is the latest.
    model_params
Key Default Description
name "unet3d_bf" Model architecture name. Currently only "unet3d_bf" is supported.
num_levels 4 Number of U-Net levels (depth of the model).
upsample "default" Upsampling method used in the U-Net decoder.
layer_order "cr" Order of operations inside convolutional blocks (c = conv, r = ReLU, etc.).
use_bias false Whether to include bias terms in the convolutional layers. Setting to false improves robustness.
padding_mode "zeros" Padding mode for convolutions.
pool_type "max" Pooling operation type used in the U-Net.
dropout_prob 0.1 Dropout probability during training (fraction of weights randomly disabled).
    mask_params
Key Default Description
use_mask true Apply the missing wedge mask to the input tomograms.
mask_frac 0.5 Fractional threshold applied when generating the mask.
mask_tomo_side 5  
mask_tomo_density_perc 50  
mask_tomo_std_perc 50  
    debug
Key Default Description
use_pretrain false If true, load pretrained model weights before training.
model_path None Path to pretrained model weights file.

💡 Tips

  1. Tilt-angle handling: Icecream only requires the minimum and maximum tilt angles to generate a Fourier mask that accounts for the missing wedge. If no tilt-angle file (.tlt) is available, you can specify the angular range directly using --tilt-min and --tilt-max. The default values are -60 and +60.
  2. GPU memory optimization: GPU memory is often the main bottleneck during training. You can control memory usage with the --batch-size parameter. In general, use the largest batch size that fits in your GPU memory for optimal efficiency.
  3. Equivariance strength (--eq_weight): The eq_weight parameter determines how strongly the equivariance prior is enforced. Larger values produce stronger smoothing and denoising, while smaller values preserve details closer to the raw tomograms.
  4. Training duration (--iteration): The iteration parameter sets the total number of training iterations. On a modern GPU, running --iteration 50000 typically takes around 6 hours on our GPU and provides good reconstruction quality.
← Previous Home Next →