Remote and Batch Usage#

TexTOM’s interactive prompts (geometry editors, matplotlib previews) require a display. When running on clusters or through SSH, use the tips below to avoid stalls. We courrently discourage batch processing, as many steps are required for a successful reconstruction and user verification of intermediate results is absolutely necessary.

SSH Sessions#

  1. Connect with X forwarding enabled:

    ssh -Y user@workstation

  2. Ensure your local machine has an X server (XQuartz on macOS, Xming/VcXsrv on Windows). Without it, matplotlib windows cannot open and TexTOM will appear frozen.

  3. Prefer terminal editors (vim, nano) for the generated configuration files; TexTOM falls back to $EDITOR when a GUI editor is unavailable.

Headless / Batch Runs#

  • Set the matplotlib backend to a non-interactive one:

    import matplotlib
matplotlib.use("Agg")

    Add this near the top of scripts you submit to batch queues.

  • Pre-create configuration files (geometry.py, crystal.py, peak masks) so TexTOM does not pause to ask for edits mid-job.

  • Disable figure display in alignment/preprocessing by exporting plots to disk via helper functions such as save_images().

Resource Management#

Component

Recommendation

Alignment

Allocate as many CPU cores as you have physical cores; use n_tasks=1 when each projection is large.

Integration

Use n_tasks > 1 only if I/O can keep up; for GPU mode set both n_tasks and cores_per_task to 1.

Optimisation

Monitor memory—each voxel stores ODF coefficients plus metadata. Reduce HSH order or ROI size if you hit limits.

Recovering from Interruptions#

  • If an SSH session drops, TexTOM might keep running with stdout tied to the defunct terminal. Use a multiplexer (tmux, screen) before launching textom to preserve output.

  • Optimisations are checkpointed automatically; rerun optimize() and choose the existing result folder to resume.

CI / Automation#

  • Batch pipelines (e.g., GitLab CI) should invoke scripts rather than the interactive CLI. Create a Python driver that calls integrate(), align_data(), etc., with prepared config files.

  • When building documentation or ancillary artifacts in CI, rely on non-privileged installers (micromamba, pip) instead of apt-get, as shared runners may block package managers.