biogeme.models.cnl module

Implements the cross-nested logit model.

author:

Michel Bierlaire

date:

Wed Oct 25 11:08:59 2023

biogeme.models.cnl.cnl(util, availability, nests, choice)[source]

Implements the cross-nested logit model.

Parameters:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | None) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.

  • nests (NestsForCrossNestedLogit | tuple[tuple[Expression | float | int | bool, dict[int, Expression]], ...]) – object describing the nesting structure.

  • choice (Expression | float | int | bool) – id of the alternative for which the probability must be calculated.

Return type:

Expression

Returns:

choice probability for the cross-nested logit model.

biogeme.models.cnl.cnl_avail(util, availability, nests, choice)[source]

Warning

This function is deprecated. Use cnl() instead.

Same as cnl. Maintained for backward compatibility.

Return type:

Expression

Parameters:
biogeme.models.cnl.cnlmu(util, availability, nests, choice, mu)[source]

Implements the cross-nested logit model with explicit homogeneity.

Parameters:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | None) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.

  • nests (NestsForCrossNestedLogit | tuple[tuple[Expression | float | int | bool, dict[int, Expression]], ...]) – object describing the nesting structure.

  • choice (Expression | float | int | bool) – id of the alternative for which the probability must be calculated.

  • mu (Expression | float | int | bool) – Homogeneity parameter \(\mu\).

Return type:

Expression

Returns:

choice probability for the cross-nested logit model.

biogeme.models.cnl.getMevForCrossNested(util, availability, nests)[source]

Warning

This function is deprecated. Use get_mev_for_cross_nested() instead.

Deprecated name for get_mev_for_cross_nested.

Return type:

dict[int, Expression]

Parameters:
biogeme.models.cnl.getMevForCrossNestedMu(util, availability, nests, mu)[source]

Warning

This function is deprecated. Use get_mev_for_cross_nested_mu() instead.

Deprecated name for get_mev_for_cross_nested_mu.

Return type:

dict[int, Expression]

Parameters:
biogeme.models.cnl.get_mev_for_cross_nested(util, availability, nests)[source]

Implements the MEV derivative terms for the cross-nested logit model.

This function is kept for backward compatibility and for users who build generic MEV expressions explicitly. The public logcnl function now uses the dedicated LogCrossNested expression for better backend performance.

Parameters:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | None) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.

  • nests (NestsForCrossNestedLogit | tuple[tuple[Expression | float | int | bool, dict[int, Expression]], ...]) – object describing the nesting structure.

Return type:

dict[int, Expression]

Returns:

dictionary mapping each alternative to \(\log G_i(e^{V_1},\ldots,e^{V_J})\).

biogeme.models.cnl.get_mev_for_cross_nested_mu(util, availability, nests, mu)[source]

Implements the MEV derivative terms for explicit-mu CNL.

This function is kept for backward compatibility and for users who build generic MEV expressions explicitly. The public logcnlmu function now uses the dedicated LogCrossNested expression with its optional mu parameter for better backend performance.

Parameters:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | None) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.

  • nests (NestsForCrossNestedLogit | tuple[tuple[Expression | float | int | bool, dict[int, Expression]], ...]) – object describing the nesting structure.

  • mu (Expression | float | int | bool) – Homogeneity parameter \(\mu\).

Return type:

dict[int, Expression]

Returns:

dictionary mapping each alternative to \(\log G_i(e^{V_1},\ldots,e^{V_J})\).

biogeme.models.cnl.log_sparse_cnl(util, availability, nests, choice, mu=None)[source]

Return a CNL log probability using structurally sparse memberships.

Only literal zero allocation parameters are treated as inactive. Any expression involving a parameter is retained, even if its current value is zero. The optional mu selects the explicit-homogeneity formulation.

Return type:

Expression

Parameters:
biogeme.models.cnl.logcnl(util, availability, nests, choice)[source]

Implements the log of the cross-nested logit model.

The implementation uses the dedicated LogCrossNested expression, which preserves the CNL structure and allows efficient backend-specific code.

Parameters:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | None) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.

  • nests (NestsForCrossNestedLogit | tuple[tuple[Expression | float | int | bool, dict[int, Expression]], ...]) – object describing the nesting structure.

  • choice (Expression | float | int | bool) – id of the alternative for which the probability must be calculated.

Return type:

Expression

Returns:

log of the choice probability for the cross-nested logit model.

Raises:

BiogemeError – if the definition of the nests is invalid.

biogeme.models.cnl.logcnl_avail(util, availability, nests, choice)[source]

Warning

This function is deprecated. Use cnl() instead.

Same as logcnl. Maintained for backward compatibility.

Parameters:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | None) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.

  • nests (NestsForCrossNestedLogit | tuple[tuple[Expression | float | int | bool, dict[int, Expression]], ...]) – object describing the nesting structure.

  • choice (Expression | float | int | bool) – id of the alternative for which the probability must be calculated.

Return type:

Expression

Returns:

log of choice probability for the cross-nested logit model.

biogeme.models.cnl.logcnlmu(util, availability, nests, choice, mu)[source]

Implements the log of the explicit-mu cross-nested logit model.

The implementation uses the dedicated LogCrossNested expression with its optional global homogeneity parameter mu.

Parameters:

  • util (dict[int, Expression | float | int | bool]) – dict of objects representing the utility functions of each alternative, indexed by numerical ids.

  • availability (dict[int, Expression | float | int | bool] | None) – dict of objects representing the availability of each alternative, indexed by numerical ids. Must be consistent with util, or None. In this case, all alternatives are supposed to be always available.

  • nests (NestsForCrossNestedLogit | tuple[tuple[Expression | float | int | bool, dict[int, Expression]], ...]) – object describing the nesting structure.

  • choice (Expression | float | int | bool) – id of the alternative for which the probability must be calculated.

  • mu (Expression | float | int | bool) – Homogeneity parameter \(\mu\).

Return type:

Expression

Returns:

log of the choice probability for the cross-nested logit model.

Raises:

BiogemeError – if the definition of the nests is invalid.

biogeme.models.cnl.sparse_cnl(util, availability, nests, choice, mu=None)[source]

Return a CNL probability using structurally sparse memberships.

Literal zero allocation parameters are omitted from the JAX calculation. Parameter-dependent allocations remain active. The optional mu selects the explicit-homogeneity formulation.

Return type:

Expression

Parameters: