Numerically safe likelihood evaluation

Biogeme can prioritize numerical robustness by enabling numerically_safe:

the_biogeme = BIOGEME(
    database,
    log_probability,
    numerically_safe=True,
)

The same setting can be placed in the Specification section of biogeme.toml:

[Specification]
numerically_safe = true

The default is false for performance and backward compatibility. Safe mode is recommended when utilities may be extreme or when availability can make a nest empty. The setting is propagated to likelihood values, gradients, Hessians, BHHH matrices, simulation, bootstrap estimation, cross-validation, and Monte Carlo diagnostics. The PyMC/PyTensor likelihood builders use the finite safe formulation unconditionally.

Unavailable alternatives and empty nests

An availability expression equal to zero makes its alternative unavailable; any nonzero value makes it available. An unavailable alternative contributes no probability mass. A nest is active only if it contains at least one available alternative with a positive membership. Empty nests are excluded from the effective denominator.

If the recorded chosen alternative is unavailable, the observation is inconsistent with the model specification. Safe mode returns the finite log probability sentinel -1e30 for that observation. This keeps automatic derivatives and result serialization finite, but it does not repair the data: users should inspect the choice and availability definitions. The same sentinel is returned if every alternative is unavailable or if the chosen alternative has no positive CNL membership.

Finite masking strategy

The safe logit, nested-logit, dense CNL, and sparse CNL evaluators remain in the log domain. They determine active alternatives and nests directly from availability and membership masks, and use the finite sentinel -1e30 for inactive log terms. Empty-nest log sums are replaced by a finite neutral value before they are multiplied by a nest coefficient.

Using where(condition, valid_value, fallback) is not sufficient if either value contains undefined arithmetic. Automatic-differentiation systems may evaluate or trace both branches, so expressions such as 0 * -inf or -inf - -inf can still yield NaN derivatives. Biogeme therefore makes both branches finite before applying a conditional mask.

Safe and unsafe paths

When every relevant alternative and nest is active and utilities are in a regular numerical range, safe and unsafe evaluations are mathematically equivalent up to floating-point precision. The unsafe path retains the faster direct formulation and may produce infinities or NaNs for extreme utilities or empty nests. Safe mode incurs additional masks and log-domain operations.

Availability and positive CNL membership define discrete regimes. Derivatives are calculated within the regime selected at the evaluation point. At an allocation parameter equal to zero, the corresponding CNL edge is inactive and its local derivative contribution is zero. This convention provides finite values and derivatives at the boundary; users should not interpret it as a derivative across a change in model topology.

Second derivatives

The safe paths support analytical JAX gradients, Hessians, and BHHH matrices, including observations that empty one or several nests. Hessian memory management is a separate concern: large models may still require the chunked analytical Hessian configuration described by the estimation parameters. Numerical safety prevents undefined mask arithmetic; it does not reduce the size of the differentiated model.