---
title: Remote and Batch Usage
---

# 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:
   ```bash
   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:
  ```python
  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.