sparsax.argmax_logprob

sparsax.argmax_logprob(Ai, Aj, Ax, mean, chosen, competitors=None, n_draws=128, seed=0, keys=None, draws='sobol')[source]

Log-probability that chosen is the largest component of a sparse-precision Gaussian.

For x ~ N(mean, A^{-1}) with A the SPD precision, returns log P(argmax_k x_k = chosen): the choice probability of a multinomial probit whose utilities form a Gaussian Markov random field (a spatial multinomial probit, say, with A = (I - ρW)'(I - ρW)). It is estimated by the GHK simulator, run on the sparse factor of A rather than on the dense covariance of the utility differences, so a draw costs O(nnz(L)) rather than O(n^2): the differences’ precision is A_{-j,-j} - v v'/c (v = (A 1)_{-j}, c = 1'A1), and the rank-one term has a closed-form factor.

A must be symmetric positive definite, but the model behind it need not be symmetric: for a SAR with any weights W, directed or not, A = M'M with M = I - ρW is SPD whenever M is nonsingular, so CHOLMOD always applies and no LU backend is needed. The same cached factor gives the means: M^{-1} X β = A^{-1} M' X β, one solve().

The estimate is unbiased for the probability (so slightly biased low for its log, by about half the relative variance), and its variance depends on the order in which the alternatives are drawn: those most likely to beat chosen should come first. Pass them as competitors, e.g. the K ≈ 10-30 alternatives with the largest mean; they are moved to the end of the elimination order (cholmod_rowdel plus a dense K x K block) while everything else keeps the fill-reducing order. Without them, variance grows quickly with n.

The first 256 steps of each path take scrambled Sobol points rather than independent draws, competitors first. Nested uniform scrambling, keyed on (seed, keys[p]), keeps each point uniform on the cube, so the estimate stays unbiased and each decision-maker’s points are independent of the others’. At n = 4,900 with 30 competitors and 128 draws, the median variance of the log-probability fell 34x when the means spread widely across alternatives and 2.2x when they were nearly flat, for about 5% more time, and up to about 30% more on small problems, where more of the steps are scrambled. Keep n_draws a power of two, which is where the points balance.

Draws are a fixed function of (seed, keys[p], draw, step), so repeated calls reproduce them and the result is a smooth function of mean, as simulated maximum likelihood needs; the competitor lists fix the variable order, so hold them fixed while optimizing. All paths share one cached factorization of A and run in parallel (SPARSAX_NUM_THREADS).

Differentiable in mean by reverse mode (jax.grad, jax.vjp): the handler computes d logp / d mean with a reverse sweep through the recursion, at about the cost of the forward pass. There is no derivative with respect to A, so a gradient that flows through Ax raises ValueError: wrap Ax in jax.lax.stop_gradient to hold it fixed, or difference in the parameter of A (the draws are fixed, so the log-probability is smooth in it). There is no forward-mode rule.

Memory: each worker thread holds about 2 * n * n_draws float64 values of per-draw state (4 * n * n_draws with gradients), e.g. 8 MB at n = 5000 and 100 draws.

Parameters:
Ai

COO of the SPD precision A, as in solve().

Aj

COO of the SPD precision A, as in solve().

Ax

COO of the SPD precision A, as in solve().

mean

[n] or [n_paths, n] float64 — means of x.

chosen

int or [n_paths] int — the index whose maximality is scored.

competitors=None

None or [n_paths, K] int — per path, the indices to draw first, most competitive first; -1 marks an unused slot. Must not contain chosen or repeat an index.

n_draws=128

GHK draws per path (static); a power of two suits "sobol".

seed=0

integer seed (static).

keys=None

None or [n_paths] int — per-path keys for the draws (default arange(n_paths)). Give each decision-maker a stable key to keep their draws fixed across calls and batchings.

draws='sobol'

"sobol" (default) or "iid", independent draws throughout (static).

Returns:

[n_paths] float64 log-probabilities, or a scalar for 1D mean.