biogeme.draws.factory module

Factory tools for managing random draw generation in Biogeme.

This module defines classes for encapsulating and orchestrating the creation of random draws used in simulation-based estimation.

It distinguishes between native and user-defined draw generators, validates inputs, and constructs a final tensor of draws with shape:

(sample_size, number_of_draws, number_of_variables)

Michel Bierlaire Wed Mar 26 19:30:36 2025

class biogeme.draws.factory.DrawFactory(user_generators)

Bases: object

Manages native and user-defined random draw generators and builds draw specifications and arrays for multiple variables.

This class is useful for transforming a mapping of variable names and draw types into a single array of random numbers ready for use in simulation-based estimation.

Parameters:

user_generators (dict[str, RandomNumberGeneratorTuple] | None)

generate_draws(draw_types, variable_names, sample_size, number_of_draws)

Generates a 3D NumPy array of draws for all specified variables.

Parameters:

• draw_types (dict[str, str]) – Mapping from variable name to draw type.

• variable_names (list[str]) – Ordered list of variable names.

• sample_size (int) – Number of observations in the sample.

• number_of_draws (int) – Number of Monte Carlo draws per observation.

Return type:

ndarray

Returns:

A NumPy array of shape (sample_size, number_of_draws, len(variable_names)).

Raises:

BiogemeError – if any generator returns a mis-shaped array.

get_generator(draw_type, name)

Retrieves a draw generator function based on the requested type.

Parameters:

• draw_type (str) – Type identifier of the draw (e.g., ‘UNIFORM’, ‘HALTON’).

• name (str) – Variable name (used for error context).

Return type:

Callable[[int, int], ndarray]

Returns:

A function that generates a NumPy array of draws.

Raises:

BiogemeError – if the draw type is not recognized.

make_draw_specs(draw_types, variable_names)

Generates a list of DrawSpec objects for each variable.

Parameters:

• draw_types (dict[str, str]) – Mapping from variable name to draw type.

• variable_names (list[str]) – List of variable names requiring simulated draws.

Return type:

list[DrawSpec]

Returns:

List of fully constructed DrawSpec objects.

class biogeme.draws.factory.DrawSpec(name, draw_type, generator)

Bases: object

Encapsulates the configuration for generating draws for a specific variable.

Parameters:

• name (str) – Name of the variable that requires simulated draws.

• draw_type (str) – Identifier for the type of draw (native or user-defined).

• generator (Callable[[int, int], ndarray]) – A callable that takes (sample_size, number_of_draws) and returns a NumPy array of draws.

draw_type: str

generator: Callable[[int, int], ndarray]

name: str