Configuration

Andrey reads a few environment variables, all named ANDREY_*. Each has a default, so none needs to be set. andrey config prints the value of each one in your shell and the backends your machine can use; andrey config --json prints the same as JSON.

A blank value counts as unset. A switch takes 1, true, yes, or on, and 0, false, no, or off. Any other value Andrey cannot read raises ValueError naming the variable, and andrey config and andrey run exit with invalid_configuration.

The backend, the worker count, and the tie-break rule can also be set in code. The most specific setting wins:

1. with andrey.config(backend=..., num_workers=..., tie_break=...):, for the calls inside the block;

2. andrey.config.backend = ..., andrey.config.num_workers = ..., or andrey.config.tie_break = ..., for every later call;

3. the environment variables below, read at each call;

4. the defaults.

Backend

• ANDREY_BACKEND: your preferred implementation for numeric operations. auto (the default) considers cuda when it is available and the input meets the operation’s size threshold, subject to the startup rule under GPU dispatch; otherwise it uses numpy. It never picks cpu or mps. numpy uses NumPy on the CPU in float64, which we use as the reference. cpu uses PyTorch on the CPU, cuda uses PyTorch on a CUDA-compatible GPU, and mps uses PyTorch on an Apple GPU in float32, which we have not validated. none and metal are aliases for cpu and mps. An explicit choice bypasses the size threshold and startup rule. If an operation supports your choice but the machine cannot run it, Andrey warns once with andrey.BackendFallbackWarning and uses auto for that operation.

• ANDREY_DEVICE: another name for ANDREY_BACKEND; if you set both, ANDREY_BACKEND takes precedence, but both values must be valid.

A GPU speeds up covariance, correlation, entropy, the KCI and CMIknn tests, and the independence tests of pnl. GES, hill climbing, and the other searches run on the CPU. An operation without the requested backend uses auto, without a warning.

Parallel search

• ANDREY_NUM_WORKERS: the worker processes for GES and GFCI, and the worker threads for the per-variable regressions of granger and the two directions of pnl. PC, FCI, GFCI, and CD-NOD also use the worker processes for their skeleton search with the fisherz and student_t tests, and send a conditioning-set size to them only when it has enough tests to repay them. 1 (the default) and 0 run serially; -1 uses every usable core. pnl with one worker leaves the BLAS threads unlimited and with several limits each thread to one, so on a machine with several cores its p-values and statistics can differ in the last digits between one worker and several. Each pnl thread holds three n x n float64 matrices; when the threads you ask for would hold more than 4 GiB, fewer run, with a PerformanceWarning.

• ANDREY_GES_PARALLEL_MIN_WORK: a GES pass uses the workers only when it expects to evaluate more candidates than this. The default is 10000; 0 always uses them.

• ANDREY_SKELETON_PARALLEL_MIN_WORK: a conditioning-size pass of the skeleton search of PC, FCI, GFCI, and CD-NOD uses the workers only when it holds at least this many conditional-independence tests. The default is 500000, measured on an AMD EPYC 9534 server running Linux; 0 always uses them.

The cutoffs matter only with more than one worker. andrey calibrate measures both for your machine and prints the values to set; andrey calibrate --method skeleton measures the skeleton’s alone. With more than one worker and a default cutoff, a fit warns once when a pass reaches a tenth of it; setting the variable, to any value, silences the warning.

GPU dispatch

• ANDREY_COV_GPU_THRESHOLD: under auto, covariance and correlation run on cuda from this many elements (rows times columns). The default is 90000.

• ANDREY_ENTROPY_GPU_THRESHOLD: the same for the entropy terms of DirectLiNGAM and the methods built on it. The default is 6250.

• ANDREY_KCI_GPU_THRESHOLD: under auto, a KCI query with a conditioning set runs on cuda, in float64, from this many kernel-matrix elements (rows squared). The default is 31250, about 177 rows.

• ANDREY_CMIKNN_GPU_THRESHOLD: the same for a CMIknn query, from this many distance-matrix elements (rows squared). The default is 1024, 32 rows. Its p-values on cuda equal those on the CPU.

• ANDREY_PNL_GPU_THRESHOLD: the same for the independence tests of pnl, in float64, from this many kernel-matrix elements (rows squared). The default is 26278, about 163 rows. A single pair uses the GPU only when it is already running, by the rule below.

• ANDREY_GPU_CALIBRATE: when on, the first auto use of covariance, correlation, or entropy measures where cuda starts to beat NumPy on this machine, and keeps the result in $XDG_CACHE_HOME/andrey/gpu_calibration.json, else ~/.cache/andrey/gpu_calibration.json. Off by default. A threshold you set wins.

Under auto, an operation that runs once per fit uses the GPU only when PyTorch and the device are already running in the process, so a CPU fit never pays to start a GPU. andrey.core.backend.dispatch_stats() counts which backend each operation ran on.

Reproducibility

• ANDREY_SEED: the seed of every stochastic method (BOSS, GRaSP, ICA-LiNGAM, CALM) when the call gives no seed= or random_state=. The default is 0; it takes any integer from 0 to 2**32 - 1. Deterministic methods ignore it.

• ANDREY_TIE_BREAK: how the searches choose between tied candidates. rank (the default) orders them by a rank computed from each column’s own data, so reordering the columns relabels the result. position orders them by column position, which skips computing the ranks, fires the orientation rules of pc, cdnod, fci, and gfci one at a time in column order, and visits the possible-d-separation step of fci and gfci in column order; the result can then depend on the column order.

Results repeat on the same machine; across platforms they can differ, CALM’s most of all. Column order and machines lists what each method keeps under a new column order and on another machine. andrey.seed_all(seed) seeds Python, NumPy, and PyTorch from one number, for data you simulate.

Datasets

• ANDREY_DATA_DIR: where andrey.data.load_dataset keeps the files it downloads. The default is $XDG_CACHE_HOME/andrey, else ~/.cache/andrey. A data_home= argument wins.

Testing

• ANDREY_REQUIRE_GPU: when on, Andrey’s own GPU tests fail, instead of skipping, without a CUDA or Apple GPU. It does not change a fit.