Environment and Configuration#

Follow this guide to prepare a reproducible TexTOM workspace and keep configuration under version control.

1. Create a Clean Environment#

conda create --name textom python=3.11
conda activate textom
pip install --upgrade pip
pip install textom

Why conda? TexTOM depends on NumPy/SciPy/pyFAI stacks that benefit from consistent BLAS libraries. Conda (or micromamba) keeps those low-level packages aligned. If you prefer pip-only workflows, ensure OpenBLAS/MKL is installed system-wide before installing TexTOM.

2. Optional Dependencies#

Scenario	Packages
GPU-assisted alignment (Mumott)	`cudatoolkit` (matching driver release)
GPU integration (pyFAI)	`pyopencl`, vendor OpenCL drivers
GUI-friendly matplotlib	`pyqt5` or `qtpy`

Install them after activating the environment.

3. Configure TexTOM Defaults#

Run:

textom_config

Key fields inside textom/config.py:

n_threads: Maximum CPU threads TexTOM may spawn. Set it to your physical core count for predictable performance.
use_gpu: Toggle GPU-backed alignment if drivers are available.
data_type: Choose np.float32 (default) or np.float64 depending on memory/precision needs.
fun_mode: Enable or disable playful and informative banner messages when launching textom.

The edited file lives under your environment’s site-packages. Commit a copy to your project repo (e.g., config.example.py) if you want shared defaults.

4. Project Layout Checklist#

Inside each sample directory:

my_sample/
├─ raw_data/                # optional; store detector frames here
├─ integration_inputs/      # poni, masks, calibration files
├─ analysis/                # created automatically by TexTOM
├─ data_integrated/         # generated by integrate()
├─ fits/                    # optimisation outputs
└─ notebooks/               # optional: analysis notebooks

Launch textom from inside my_sample/ so TexTOM writes into the correct folders.

5. Keeping Environments in CI#

For GitLab CI, reuse micromamba environments to avoid reinstalling Python every job.
Add a docs job (see .gitlab-ci.yml) that runs sphinx-build -b html docs _build/docs so the web documentation stays in sync with these guides.

Troubleshooting#

Symptom	Fix
Numba warning about TBB version	Update your micromamba/conda base or install `tbb` ≥ 2021.6.
`pyqt5` import errors	Install the distro’s Qt dependencies or run TexTOM headless with `matplotlib` set to `Agg`.
`pip install textom` pulls old dependencies	Clear wheels (`pip cache purge`) before reinstalling, or pin versions in `requirements.txt`.