traveler.steps.sample_logsum_simulate#

class traveler.steps.sample_logsum_simulate(name, sample_utility_func, utility_func, altnames, param, *, sample_size=30, on=None, result_name=None, chunk_size=10_000)[source]#

Bases: Step

A sample-of-alternatives choice model with expensive final utilities.

The step first evaluates sample_utility_func over every alternative and draws sample_size alternatives with replacement. It then calls utility_func only for those sampled alternative codes, applies the sampling-probability correction, and simulates a multinomial-logit choice. This is useful when the final utility includes an expensive lower-level logsum.

Parameters:

  • name (str) – Stable step name used to derive chooser random-number streams.

  • sample_utility_func (Callable) – Function with signature (chooser, store, param) returning a utility vector over all alternatives for one chooser.

  • utility_func (Callable) – Function with signature (chooser, sampled_codes, store, param) returning final utilities for the sampled alternative slots.

  • altnames (tuple[str, ...] | tuple[int, ...] | str) – Ordered alternatives, or a predefined categorical group such as "@TAZ".

  • param (Parameters | dict[str, object]) – Parameters supplied to both utility functions.

  • sample_size (int, optional) – Number of alternatives drawn with replacement per chooser.

  • on (type[StoredTable], optional) – Chooser table used when no chooser table is passed explicitly.

  • result_name (str, optional) – Column written by run_on().

  • chunk_size (int, optional) – Number of choosers evaluated in each multithreaded chunk.

Methods#

run_on(store)

Run the choice model and assign its result column to a store copy.

sample_alternatives(store, *[, choosers, param])

Draw raw alternative codes from the sampling model.

simulate_choice(store, *[, choosers, param])

Sample alternatives, evaluate final utilities, and choose one.