---
title: Environment and Configuration
---

# Environment and Configuration

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

## 1. Create a Clean Environment

```bash
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:

```bash
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`. |