Configuration

You can configure abTEM with a YAML configuration file (abtem.yaml), which controls a number of options and feature flags.

Configuration files

The configuration is specified by any YAML file in ~/.config/abtem/ or /etc/abtem/. abTEM searches for all YAML files within each of these directories and merges them together.

Below is the full default configuration file. Anything you set in your own YAML will be merged into these defaults before they are used to configure the build.

# Configuration file for abtem

# The device can be either 'cpu' or 'gpu'
device: cpu
# The fft library to use. Options are 'numpy', 'fftw' or 'mkl'
fft: fftw
# The float precision to use. Options are 'float32' or 'float64'
precision: float32
diagnostics:
  # Show the progress bar. Options are 'true', 'false' or 'tqdm'
  progress_bar: "tqdm"
  # Show the progress of each task. Options are 'true' or 'false'
  task_progress: false
dask:
  # Use lazy evaluation by default. Options are 'true' or 'false'
  lazy: true
  # The target chunk size to use for dask arrays on the cpu
  chunk-size: 128 MB
  # The target chunk size to use for dask arrays on the gpu
  chunk-size-gpu: 512 MB
  # Automatically distribute gpu computations over all visible gpus by starting a
  # dask-cuda cluster. Requires the optional dask-cuda package.
  multi-gpu: false
  # Optional RMM memory-pool size per multi-gpu worker (e.g. "20 GB").
  # null disables the RMM pool.
  multi-gpu-rmm-pool: null
  # Optional subset of GPUs for the multi-gpu cluster, as a list of device
  # indices (e.g. [0, 1]) or a comma-separated string (e.g. "0,1").
  # null spans all visible GPUs.
  multi-gpu-devices: null
cupy:
  # Maximum GPU memory (bytes) used by the cuFFT plan cache.
  # https://docs.cupy.dev/en/stable/user_guide/fft.html#fft-plan-cache
  # auto  — 25% of the device's total memory, resolved per device: scales
  #          with the card like the auto-sized batches whose plans it holds,
  #          keeping live plans hot while capping stale-plan retention. A
  #          ceiling, not a reservation — unused headroom costs no memory.
  # 0 MB  — disable caching entirely (workspace freed after every FFT call;
  #          use when VRAM is tight and large-grid OOMs occur).
  # > 0   — bound cached workspace to this many bytes (e.g. "512 MB").
  # -1    — unlimited (CuPy default; fastest but accumulates workspace,
  #          which on Bluestein-fallback grid sizes can reach tens of GB).
  # null  — same as -1 (no bound).
  fft-cache-size: auto
mkl:
  # The number of threads to use for mkl
  threads: 2
fftw:
  # The number of threads to use for fftw
  # https://www.fftw.org/fftw3_doc/Threading-and-MPI.html
  threads: 1
  # The planning effort to use for fftw. Options are 'FFTW_ESTIMATE', 'FFTW_MEASURE' or 'FFTW_PATIENT'
  # https://www.fftw.org/fftw3_doc/Planner-Flags.html
  planning_effort: FFTW_MEASURE
  # The time limit in seconds for the fftw planner
  planning_timelimit: 60
  # Whether to allow falling back to not using wisdom if the cache fails
  allow_fallback: true
grid:
  # Round automatically derived gpts up to the next fast FFT length (all prime
  # factors in {2, 3, 5, 7}). Fast lengths avoid the slow, memory-hungry
  # Bluestein FFT fallback on GPU and speed up CPU FFTs as well. Rounding is
  # upward only, so a grid derived from a numeric sampling never comes out
  # coarser than requested. gpts given explicitly are never altered.
  #   'auto'  round only grids abTEM derives on its own (sampling='auto')
  #   true    additionally round gpts derived from a numeric sampling
  #   false   never round
  round-to-fast-fft: auto
warnings:
  # Show the dask warning about the blockwise performance when the number are increased dramatically
  dask-blockwise-performance: false
  # Show a warning when the grid is overspecified
  overspecified-grid: true
potential:
  # Number of slices to build at once during multislice. "auto" = memory-budget-aware.
  slice-chunk-size: "auto"
antialias:
  # The antialias cutoff in reciprocal space
  cutoff: 0.6666666
  # The antialias taper width in reciprocal space
  taper: 0.01
visualize:
  # The default units to use in real space
  real_space_units: "Angstrom"
  # The default units to use in reciprocal space
  reciprocal_space_units: "Angstrom"
  # The default colormap to use for plotting
  cmap: "viridis"
  # The default colormap to use for plotting the phase
  phase_cmap: "hsluv"
  # Update interactive plots continuously
  continuous_update: false
  # Scale the values of interactive plots automatically
  autoscale: false
  # Use tex rendering in plots
  use_tex: true

Access configuration

abtem.config.get

Get elements from global config

The abTEM configuration system is usually accessed using the abtem.config.get function. You can use . for nested access, for example:

import abtem
abtem.config.get("dask.chunk-size") # use "." for nested access

Specify configuration in Python

abtem.config.set

Temporarily set configuration values within a context manager

The configuration is stored within a normal Python dictionary in abtem.config.config and can be modified using normal Python operations.

Additionally, you can temporarily set a configuration value using the abtem.config.set function. This function accepts a dictionary as an input and interprets “.” as nested access:

abtem.config.set({"dask.chunk-size": "256 MB"})

This function can also be used as a context manager for consistent cleanup:

with abtem.config.set({"dask.chunk-size": "256 MB"}):
    exit_waves = probe.multislice(potential)