Configuration Reference¶

class qens.config.Config(files_to_fit=<factory>, primary_file='', resolution_file=None, frozen_temp_threshold=270, q_min=0.3, q_max=2.5, energy_window=1.25, n_q_bins=12, n_walkers=32, n_warmup=500, n_keep=2000, thin=5, n_map_starts=30, random_seed=42, save_dir='qens_results')[source]

Bases: object

Runtime parameters for the analysis pipeline.

Parameters:

files_to_fit (List[str])
primary_file (str)
resolution_file (str | None)
frozen_temp_threshold (int)
q_min (float)
q_max (float)
energy_window (float)
n_q_bins (int)
n_walkers (int)
n_warmup (int)
n_keep (int)
thin (int)
n_map_starts (int)
random_seed (int)
save_dir (str)

files_to_fit

Filenames to load (relative to data_dir passed to qens.io.load_dataset()).

Type:: list[str]

primary_file

Which of the loaded files is the target spectrum to fit.

Type:: str

resolution_file

Frozen-sample file used as resolution function. If None, the loader auto-picks any T ≤ frozen_temp_threshold incoherent file.

Type:: str | None

frozen_temp_threshold

Files at T ≤ this temperature (K) are treated as resolution refs.

Type:: int

q_min, q_max

Q range in Å⁻¹ over which the fit is performed.

Type:: float

energy_window

Half-width of the ω window in meV used for the joint fit (paper found ±1.25 meV needed for benzene anisotropy).

Type:: float

n_q_bins

Number of Q-bins for the joint S(Q,ω) fit.

Type:: int

n_walkers

Number of emcee walkers (must be even, ≥ 2 × n_dim).

Type:: int

n_warmup, n_keep

Burn-in and production steps per walker.

Type:: int

thin

Chain thinning factor.

Type:: int

n_map_starts

Random starts for the MAP search.

Type:: int

random_seed

Master seed for reproducibility.

Type:: int

save_dir

Output directory for figures, samples, summaries.

Type:: str

files_to_fit: List[str]

primary_file: str = ''

resolution_file: str | None = None

frozen_temp_threshold: int = 270

q_min: float = 0.3

q_max: float = 2.5

energy_window: float = 1.25

n_q_bins: int = 12

n_walkers: int = 32

n_warmup: int = 500

n_keep: int = 2000

thin: int = 5

n_map_starts: int = 30

random_seed: int = 42

save_dir: str = 'qens_results'

to_dict()[source]

Return type:: dict

to_json(path)[source]

Return type:: None
Parameters:: path (str)

classmethod from_json(path)[source]

Return type:: Config
Parameters:: path (str)

Serialisation¶

from qens import Config

cfg = Config(n_walkers=64, energy_window=1.5, random_seed=7)
cfg.to_json("run_config.json")

# Reload in a different script — exact same parameters
cfg2 = Config.from_json("run_config.json")

Parameter Guide¶

Q range (`q_min`, `q_max`)¶

Detectors outside this range are excluded from all fitting. A good starting range for molecular liquids at ISIS is 0.6 to 1.8 Å^-1. Avoid regions affected by coherent scattering (de Gennes narrowing near Q ≈ 1.3 Å^-1 for benzene). Widen to 0.3–2.5 Å^-1 only when using polarisation-separated data.

Energy window (`energy_window`)¶

Half-width of the ω window in meV. Set wide enough to capture the full quasi-elastic wing. Richardson et al. (2026) found ±1.25 meV necessary for benzene anisotropy at E_i = 3.60 meV.

MCMC settings¶

n_walkers: must be even and ≥ 2 × number of parameters. Use 32 for 2-parameter fits, 64 for 4-parameter anisotropic rotor fits.
n_warmup: burn-in per walker. Start at 500 and increase if the acceptance fraction is outside 0.25–0.55.
n_keep: production steps. 2000 gives smooth histograms; 5000 for publication figures.
thin: default 5 reduces autocorrelation without wasting samples.

Resolution (`resolution_file`, `frozen_temp_threshold`)¶

If resolution_file is set explicitly, that file is always used as the resolution reference regardless of temperature. Otherwise assign_resolution() auto-picks any incoherent file at T ≤ frozen_temp_threshold (default 270 K).