ChoiceModel¶

class passengersim.core.ChoiceModel¶

Bases: object

Customer choice model for simulating passenger behavior.

A ChoiceModel represents the decision-making behavior associated with the “right to fly” (and no additional ancillaries) of a specific customer segment (e.g., ‘business’ or ‘leisure’). Each customer segment typically has its own ChoiceModel with parameters calibrated to represent that segment’s preferences and price sensitivity. We define the alternatives of the choice model as “offers presented to the customer,” where each offer corresponds to an ODF (origin-destination-fare product) available in the market along with its associated itinerary options. The definition of an offer will be expanded in future versions to include ancillaries beyond the right to fly as well as branded fares and matrix pricing.

PassengerSim supports different forms of choice models. Currently, two types are available: MNL (multinomial logit) and PODS (which is a mixed MNL with random coefficients and latent-class where each class represents a customer segment). The model type is specified when creating the ChoiceModel instance.

There is no limit to the number of customer segments or choice models that can be defined. Common practice uses two segments (‘business’ and ‘leisure’), but PassengerSim supports arbitrary segment names and any number of segments.

Each demand in the simulation specifies which customer segment it belongs to, and the corresponding ChoiceModel is used to simulate that customer’s itinerary behavior.

Choice Set Generation Process¶

The ChoiceModel uses a two-step process to select an offer for a given individual.

Step 1: Initial Screening and Choice Set Formation

A maximum willingness-to-pay (WTP) is calculated for each customer based on their segment characteristics and a random draw. The initial screening compares each offer’s fare against this maximum WTP to create a feasible choice set. Only offers where fare ≤ WTP pass this initial screen and enter the choice set.

Step 2: Offer Selection Using Discrete Choice Analysis (DCA)

From the feasible choice set, one offer is selected using a discrete choice model (DCA) that evaluates the relative attractiveness of each option based on fare, disutilities for schedule quality, carrier preference, and other attributes.

For MNL (Multinomial Logit) models: For each offer in the choice set, a utility is calculated (typically as a function of fare and other attributes). These utilities are exponentiated and normalized to create choice probabilities:

probability(offer_i) = exp(utility_i) / Σ exp(utility_j) for all j in choice set

A random draw is then made from this probability distribution to select one offer. This is implemented as a “weighted roulette wheel” where the random draw determines which offer is selected based on its probability mass.

For PODS models: The selection uses a “lowest generalized cost” approach where the offer with the minimum (fare + total_disutility) is selected. Note that disutilities are randomly generated and differ by customer segment. As discussed in [5], the PODS approach is a mixed MNL model with random coefficients, latent classes (customer segments), and infinite scale. That is, where logit models are typically normalized by setting the scale parameter to 1, PODS sets the scale to infinity, which results in the lowest generalized cost approach where the customer chooses the option with minimum (fare + disutility).

If no products remain in the choice set after the initial screening (all fares exceed the customer’s WTP), the customer is recorded as a “no-go” (no purchase).

Utility and Disutility Functions¶

The ChoiceModel class is used to specify the utility (or in the context of the PODS model, the disutility) function associated with each ODF (origin-destination-fare product). While classic discrete choice models define a utility function for each itinerary or mode choice, the PODS consortium historically reversed this convention and instead specified a disutility function. In addition, the PODS convention defined reference variables and categories so that positive disutility values correspond to intuitive behavioral relationships for non-reference categories, and ensures that all randomly generated disutilities are non-negative (greater than or equal to zero). For example, when comparing nonstop and connecting itineraries, customers are expected to prefer nonstops. Accordingly, connecting itineraries should have higher (more positive) disutility than nonstop itineraries (the reference).

Several pre-programmed functions are used to construct the disutility function, including preferences for product restrictions (e.g., refundability), airlines, schedule quality (nonstop vs. connections), and other schedule attributes. Airline preferences are implemented as unfavored airline preference to maintain positive disutilities when a non-preferred airline is selected. Additional schedule effects are captured through replanning disutilities, which draw heavily on the decision window model framework described in the Boeing reference used in the MIT Airline Management lecture (see [1]).

Default models typically used in PODS studies include disutilities for unfavored airline, connections, product restrictions, and schedule replanning (derived from the adapted decision window approach).

Functional Form and Reference Fare¶

Many of the disutilities used in prior PODS studies follow a two-step calculation:

Calculate a base penalty: base_penalty = alpha + beta × reference_fare
Apply an indicator or multiplier based on the specific disutility component

The reference fare is the lowest fare in the market for leisure travelers (default basefare_mult = 1.0 for leisure) and basefare_mult × lowest_fare for business travelers (default basefare_mult = 2.5 for business).

Examples of the complete disutility formulas:

Path quality: disutility = (PQI - 1) × base_penalty
Preferred carrier: disutility = indicator(non-preferred) × base_penalty
Elapsed time: base_penalty calculated with log(duration) included in formula
Buffer time: base_penalty calculated with (threshold - buffer_time) included in formula

This scaling captures two important behavioral effects:

Business travelers are more willing to pay for schedule and airline convenience: The higher reference fare (2.5× the lowest fare) means business travelers incur proportionally larger absolute disutilities, reflecting their higher willingness to pay to avoid inconveniences.
Willingness to pay in absolute dollar terms is higher for longer (higher-fare) itineraries than shorter (lower-fare) itineraries: The beta coefficient scales penalties proportionally to the reference fare, so a $20 penalty on a $200 fare (10%) is treated similarly to a $10 penalty on a $100 fare (10%), reflecting that customers’ tolerance for absolute dollar penalties scales with trip cost.

Complete Example: Generating a Full Disutility Function¶

An example using concepts from this class is shown below for completeness. The individual concepts (basefare_mult, reference fare, k_factor, path quality, preferred carrier, buffer time, decision window model, etc.) are described in detail in the parameter documentation that follows.

Consider a business traveler evaluating a connecting itinerary with these attributes:

Reference fare (leisure): $150
Business basefare_mult: 2.5
Adjusted reference fare: $150 × 2.5 = $375
Path Quality Index (PQI): 2.0 (single connection)
Non-preferred carrier
k_factor: 0.3 (typical value, but note: most PODS studies use fixed std_dev = 0.3 × mean)

Step 1: Draw base penalties (alpha + beta × reference_fare) and ensure they are greater than zero

Path Quality:

mean = pqi_alpha + pqi_beta × $375 = 10 + 0.2 × 375 = $85
std_dev = 0.3 × $85 = $25.50
Random draw = max(0, N($85, $25.50)) → e.g., $92.30
Applied penalty = (PQI - 1) × $92.30 = (2.0 - 1) × $92.30 = $92.30

Note: The max(0, …) operation ensures disutilities cannot be negative.

Preferred Carrier:

mean = pref_alpha + pref_beta × $375 = 5 + 0.15 × 375 = $61.25
std_dev = 0.3 × $61.25 = $18.38
Random draw = max(0, N($61.25, $18.38)) → e.g., $55.80
Applied penalty = $55.80 (since carrier is not preferred)

Buffer Time (if connection < threshold):

Suppose buffer_time = 30 min, threshold = 45 min
mean = alpha + beta × (45 - 30) × $375
std_dev = k_factor × mean
Random draw = max(0, N(mean, std_dev)) → connection penalty

Step 2: Sum all disutility components

Total disutility = $92.30 (PQI) + $55.80 (carrier) + [buffer penalty] + [DWM penalty] + …

Step 3: Compare to willingness-to-pay and fare

If (fare + total_disutility) < WTP → passenger accepts offer
If (fare + total_disutility) > WTP → passenger rejects offer

References

[1] Boeing Commercial Airplanes (1993). “The Boeing Passenger Origin-Destination Simulator: A Technical Design Overview.” Boeing Commercial Airplanes Marketing Research and Analysis Group. (Used in MIT Airline Management lectures) Available at: https://ocw.mit.edu/courses/16-75j-airline-management-spring-2006/f4cf28d87d1ac891f5fa4ebd5faa557d_lect6b.pdf Accessed January 1, 2026.

[2] Herring, J., Lurkin, V., Garrow, L. A., Clarke, J.-P., & Bierlaire, M. (2019). Airline customers’ connection time preferences in domestic U.S. markets. Journal of Air Transport Management, 79, Article 101688. https://www.sciencedirect.com/science/article/pii/S0969699719301899

[3] Theis, G., Adler, T., Clarke, J.-P., & Ben-Akiva, M. (2006). Risk aversion to short connections in airline itinerary choice. Transportation Research Record: Journal of the Transportation Research Board, 1951, 28-36. https://www.researchgate.net/publication/245562091_Risk_Aversion_to_Short_Connections_in_Airline_Itinerary_Choice

[4] Brey, R., & Walker, J. L. (2011). Latent temporal preferences: An application to airline travel. Transportation Research Part A: Policy and Practice, 45(9), 880-895. https://doi.org/10.1016/j.tra.2011.07.003

[5] Bockelie, A., & Belobaba, P. (2017). Incorporating ancillary services in airline passenger choice models. Journal of Revenue and Pricing Management, 16(6), 553-568. https://doi.org/10.1057/s41272-016-0093-8

Methods

`__init__`(args, *kwargs)
`add_parm`	Add a parameter value to the choice model.
`add_restriction`	Add a fare restriction disutility to the choice model.
`choose_offer`	Choose an offer from a list using the choice model.
`get_dwm_penalty`	Get Decision Window Model penalty for departure/arrival time preferences.
`get_parameters`	Get current parameter values from the choice model.
`get_time_disutility`	Get time disutility penalty for short connections and elapsed time.
`max_wtp`	Calculate maximum willingness to pay statistics.
`prob_wtp`	Calculate the probability that a customer is willing to pay at least X.
`serialize`	Get all parameter values from the choice model.
`set_parameters`	Set parameter values in the choice model.

Attributes

`buffer_threshold`	Minimum connection time threshold in minutes.
`buffer_time_alpha`	Alpha parameter for short connection buffer time disutility.
`buffer_time_beta`	Beta parameter for short connection buffer time disutility.
`dwm`	Decision Window Model attached to this ChoiceModel.
`dwm_eliminate_outside_window`	Eliminate offers outside the decision window.
`dwm_tod`	A list of 24 values representing hourly probability distribution.
`early_dep_beta`	Maximum early departure penalty coefficient.
`early_dep_offset`	Offset parameter for early departure S-curve penalty (in minutes).
`early_dep_slope`	Slope of the S-curve for early departure penalty.
`elapsed_time_alpha`	Alpha parameter for elapsed time disutility.
`elapsed_time_beta`	Beta parameter for elapsed time disutility.
`k_factor`	K-factor parameter for choice model calibration and stochastic variation.
`late_arr_beta`	Maximum late arrival penalty coefficient.
`late_arr_offset`	Offset parameter for late arrival S-curve penalty (in minutes).
`late_arr_slope`	Slope of the S-curve for late arrival penalty.
`path_quality_alpha`	Alpha parameter for path quality index disutility.
`path_quality_beta`	Beta parameter for path quality index disutility.
`preferred_carrier`	Preferred carrier code for this customer segment.
`preferred_carrier_alpha`	Alpha parameter for the preferred carrier disutility.
`preferred_carrier_beta`	Beta parameter for the preferred carrier disutility.
`random_generator`	Random number generator for stochastic choice simulation.
`replanning_alpha`	Alpha parameter for replanning disutility (original PODS formulation).
`replanning_beta`	Beta parameter for replanning disutility (original PODS formulation).
`seat_share_alpha`	Alpha parameter for the seat-share preferred carrier model.
`seat_share_beta`	Beta parameter for the seat-share preferred carrier model.
`segment`	Named customer segment identifier.

add_parm()¶

Add a parameter value to the choice model.

Parameters:

name : str: Name of the parameter to add.
value : float: Primary parameter value.
value2 : float, optional: Secondary parameter value for parameters requiring two values. Default is 0.

add_restriction()¶

Add a fare restriction disutility to the choice model.

Parameters:

restriction_num : int: Restriction code/index to add.
value : float: Disutility value for this restriction.
sigma_ratio : float, optional: Standard deviation ratio for stochastic variation. Default is 0.3.

buffer_threshold¶

Minimum connection time threshold in minutes.

The buffer threshold captures customers’ avoidance of very short connections, namely those that are less than a threshold value. Connections with buffer time below this threshold incur penalties calculated using buffer_time_alpha and buffer_time_beta parameters.

This approach is based on research showing that airline customers exhibit risk aversion to short connection times due to concerns about missing connections.

References: - Herring et al. (2019), Journal of Air Transport Management, 79, Article 101688 - Theis et al. (2006), Transportation Research Record, 1951, 28-36

Returns:: float – The buffer threshold value.

buffer_time_alpha¶

Alpha parameter for short connection buffer time disutility.

Used in the formula: mean_disutility = alpha + beta × (threshold - buffer_time) × reference_fare. Applied when buffer_time < buffer_threshold.

Note: These parameters are not used in many PODS studies but are included to support future studies.

Returns:: float – The alpha parameter value.

buffer_time_beta¶

Beta parameter for short connection buffer time disutility.

Used in the formula: mean_disutility = alpha + beta × (threshold - buffer_time) × reference_fare. Applied when buffer_time < buffer_threshold.

Note: These parameters are not used in many PODS studies but are included to support future studies.

Returns:: float – The beta parameter value.

choose_offer()¶

Choose an offer from a list using the choice model.

Simulates customer choice behavior across multiple random draws, returning the count of how many times each offer was selected.

Parameters:

offers : list[Offer]: List of available offers to choose from.
dmd : Demand: Demand object representing the customer request.
n_draws : int, optional: Number of choice simulations to run. Default is 1.
snapshot_instruction : optional: Debugging/logging control parameter (keyword-only).

Returns:

tuple[int, …] – Tuple with same length as offers, where each element is the count of times that offer was chosen across all draws.

dwm¶

Decision Window Model attached to this ChoiceModel.

Returns:: DecisionWindow or None – The Decision Window Model configuration attached to this choice model, or None if no decision window model has been set.

dwm_eliminate_outside_window¶

Eliminate offers outside the decision window.

Deprecated since version This: parameter is based on the original formulation in the Boeing (1993) reference but is not recommended for use in current studies.

Returns:: bool – True if offers outside window should be eliminated when at least one offer is completely inside the window. Default is False.

dwm_tod¶

A list of 24 values representing hourly probability distribution. Must sum to 1.0 (probabilities) or 100.0 (percentages).

Time of Day curve for the Decision Window Model (DWM).

The Decision Window Model is described in detail in its separate class functions but conceptually is used to create a window representing an individual’s earliest preferred departure and latest preferred arrival. The TOD function is a distribution representing the center-point of this window. For example, for short-haul flights we may expect to see peak preferences centered around 8 AM morning periods and 5 PM afternoon periods.

Returns:: list[float] – List of 24 values representing hourly probability distribution. Values sum to 1.0 (probabilities).

early_dep_beta¶

Maximum early departure penalty coefficient.

Maximum penalty is (beta × reference_fare), applied when departure time is significantly before the customer’s preferred decision window start time (approximately 2 × offset from window start).

The S-curve shaped penalty ranges from 0 (at or inside window start) to this maximum value, providing a nonlinear alternative to the binary replanning_alpha/beta approach where one minute outside the window receives a much smaller penalty than departures far outside the window.

Note: Either use the replanning_alpha/beta parameters for the original binary penalty or the early_dep_* and late_dep_* parameters for the nonlinear S-curve penalty, but not both simultaneously.

Returns:: float – The beta parameter value.

early_dep_offset¶

Offset parameter for early departure S-curve penalty (in minutes).

Provides a nonlinear alternative to the binary replanning_alpha/beta approach. Instead of an all-or-nothing penalty, the S-curve assigns partial penalties based on how far outside the decision window the departure falls.

The offset defines the area where partial penalties apply. Specifically, 2 × offset represents the maximum replanning penalty region. For example, with offset = 60 minutes, departures up to 120 minutes before the window start receive increasing penalties along the S-curve. One minute outside the window receives a much smaller penalty than an itinerary that departs an hour outside the window.

The offset determines where the midpoint of the S-curve is positioned relative to the window start.

Note: Either use the replanning_alpha/beta parameters for the original binary penalty or the early_dep_* and late_dep_* parameters for the nonlinear S-curve penalty, but not both simultaneously.

Returns:: float – The offset value in minutes.

early_dep_slope¶

Slope of the S-curve for early departure penalty.

Controls the steepness of the S-curve, determining how quickly the penalty increases as departure time moves earlier before the decision window start. Applied when departure time is before the customer’s preferred window.

Used with early_dep_offset and early_dep_beta to create a smooth nonlinear penalty function, providing an alternative to the binary replanning_alpha/beta approach.

Note: Either use the replanning_alpha/beta parameters for the original binary penalty or the early_dep_* and late_dep_* parameters for the nonlinear S-curve penalty, but not both simultaneously.

Returns:: float – The slope parameter value.

elapsed_time_alpha¶

Alpha parameter for elapsed time disutility.

Elapsed time (duration) is calculated as the final arrival time minus the first departure time, accounting for time zones. This represents the actual time the passenger spends traveling from the departure of the first leg to the arrival of the last leg.

Used in the formula: mean_disutility = alpha + beta × log(duration_minutes) × reference_fare.

Note: These parameters are not used in many PODS studies because elapsed time effects are implicitly captured in the decision window model framework. However, they are provided as an alternative approach for future studies.

Returns:: float – The alpha parameter value.

elapsed_time_beta¶

Beta parameter for elapsed time disutility.

Used in the formula: mean_disutility = alpha + beta × log(duration_minutes) × reference_fare.

Returns:: float – The beta parameter value.

get_dwm_penalty()¶

Get Decision Window Model penalty for departure/arrival time preferences.

Calculates penalties when flight times fall outside the customer’s preferred departure/arrival window. Used for unit tests and debugging.

Parameters:

decision_window : DecisionWindow: Decision Window Model configuration.
distance : int: Market distance in nautical miles.
start_time : int: Start time of the decision window in minutes from midnight.
end_time : int: End time of the decision window in minutes from midnight.
path : Path: Path to evaluate.
reference_fare : float: Reference fare for penalty scaling.
dwm_z : float: Random z-value for stochastic window placement.
snapshot_instruction: Debugging/logging control parameter.

Returns:

float – DWM penalty value.

get_parameters()¶

Get current parameter values from the choice model.

Returns:: dict – Dictionary containing: - ‘restrictions’ : list[float] - Fare restriction disutilities - ‘restriction_sigmas’ : list[float] - Restriction sigma ratios - ‘reference_price_multiplier’ : float - Base fare multiplier - ‘emult’ : float - E-multiplier parameter

get_time_disutility()¶

Get time disutility penalty for short connections and elapsed time.

This method calculates penalties for offers with short connection times or excessively long elapsed times. Used for unit tests and debugging.

Parameters:

dmd : Demand: Demand object representing the customer request.
offer : Offer: Offer to evaluate for time-based penalties.
snapshot_instruction: Debugging/logging control parameter.

Returns:

float – Time disutility penalty value.

k_factor¶

K-factor parameter for choice model calibration and stochastic variation.

The k_factor controls the standard deviation of the random draws used to generate stochastic disutility values. For most disutility components, the standard deviation is calculated as: std_dev = k_factor × mean_disutility.

This introduces heterogeneity across passengers, so that two passengers facing the same itinerary attributes will have different disutility realizations, leading to different choice outcomes.

Important: All disutility random draws are constrained to be non-negative using max(0, random_normal(mean, std_dev)). This ensures that disutilities cannot be negative, which would be inconsistent with the PODS convention where positive disutilities represent undesirable attributes.

The k_factor (or fixed 0.3 ratio) ensures that different passengers have different disutility draws, creating realistic heterogeneity in choice behavior. A passenger with a lower PQI draw might choose a connection, while another with a higher draw prefers a nonstop.

Note: In practice, most PODS studies use a fixed std_dev = 0.3 × mean rather than std_dev = k_factor × mean. The k_factor parameter is provided for flexibility but is often set to match the 0.3 convention.

Returns:: float – The k-factor value.

late_arr_beta¶

Maximum late arrival penalty coefficient.

Maximum penalty is (beta × reference_fare), applied when arrival time is significantly after the customer’s preferred decision window end time (approximately 2 × offset from window end).

The S-curve shaped penalty ranges from 0 (at or inside window end) to this maximum value, providing a nonlinear alternative to the binary replanning_alpha/beta approach where one minute outside the window receives a much smaller penalty than arrivals far outside the window.

Early_dep and late_arr parameters allow for differential impacts depending on whether an itinerary falls before or after the desired decision window.

Note: Either use the replanning_alpha/beta parameters for the original binary penalty or the early_dep_* and late_dep_* parameters for the nonlinear S-curve penalty, but not both simultaneously.

Returns:: float – The beta parameter value.

late_arr_offset¶

Offset parameter for late arrival S-curve penalty (in minutes).

The offset defines the area where partial penalties apply. Specifically, 2 × offset represents the maximum replanning penalty region. For example, with offset = 60 minutes, arrivals up to 120 minutes after the window end receive increasing penalties along the S-curve. One minute outside the window receives a much smaller penalty than an itinerary that arrives an hour outside the window.

The offset determines where the midpoint of the S-curve is positioned relative to the window end. Early_dep and late_arr parameters allow for differential impacts depending on whether an itinerary falls before or after the desired decision window.

Note: Either use the replanning_alpha/beta parameters for the original binary penalty or the early_dep_* and late_dep_* parameters for the nonlinear S-curve penalty, but not both simultaneously.

Returns:: float – The offset value in minutes.

late_arr_slope¶

Slope of the S-curve for late arrival penalty.

Controls the steepness of the S-curve, determining how quickly the penalty increases as arrival time moves later after the decision window end. Applied when arrival time is after the customer’s preferred window.

Used with late_arr_offset and late_arr_beta to create a smooth nonlinear penalty function, providing an alternative to the binary replanning_alpha/beta approach.

Note: Either use the replanning_alpha/beta parameters for the original binary penalty or the early_dep_* and late_dep_* parameters for the nonlinear S-curve penalty, but not both simultaneously.

Returns:: float – The slope parameter value.

max_wtp()¶

Calculate maximum willingness to pay statistics.

Simulates the distribution of maximum WTP values across multiple random draws to understand customer price sensitivity.

Parameters:

reference_price : float: The reference price for the WTP distribution.
n_draws : int, optional: Number of random draws to simulate. Default is 1.
snapshot_instruction : optional: Debugging/logging control parameter (keyword-only).
raw : bool, optional: If True, include raw vector of all draws in output (keyword-only). Default is False.
emult : float, optional: Override emult value to pass to the WTP calculation (keyword-only). If not provided, the choice model’s own emult value is used. Must be >= 1.0.

Returns:

dict – Dictionary with keys: - ‘mean’ : float - Mean of maximum WTP across draws - ‘stdev’ : float - Sample standard deviation of maximum WTP - ‘raw’ : ndarray - Raw vector of WTP values (only if raw=True)

path_quality_alpha¶

Alpha parameter for path quality index disutility.

The path quality index (PQI) is a numeric value assigned to each path in the network configuration to represent itinerary quality. The disutility calculation proceeds in two steps:

Calculate base disutility per connection: base_penalty = alpha + beta × reference_fare
Multiply by path quality factor: pqi_disutility = (PQI - 1) × base_penalty

The (PQI - 1) convention was chosen so that PQI = 1.0 represents the baseline quality level with no penalty. Common conventions: - Nonstop paths: PQI = 1.0 (no penalty, since (1.0 - 1) × base_penalty = 0) - Single connection paths: PQI = 2.0 (penalty = (2.0 - 1) × base_penalty = 1× base_penalty) - Two connection paths: PQI = 3.0 (penalty = (3.0 - 1) × base_penalty = 2× base_penalty)

Returns:: float – The alpha parameter value.

path_quality_beta¶

Beta parameter for path quality index disutility.

Works with path_quality_alpha to define the base penalty per connection level.

The complete formula is: pqi_disutility = (PQI - 1) × (alpha + beta × reference_fare)

where PQI is the path quality index specified in the network configuration file. The (PQI - 1) factor means PQI = 1.0 yields zero penalty (baseline quality).

Returns:: float – The beta parameter value.

preferred_carrier¶

Preferred carrier code for this customer segment.

The preferred carrier is selected dynamically for each demand using a random draw. Two methods are available:

Demand-specific probabilities (default): Probabilities are specified directly on each Demand object (probFavoredCarrier), allowing different carrier preferences for different customer types or markets. This is the default method.
Seat share at origin: If the SimulationEngine’s preferred_airline_pct_share property is set to True, carriers are selected with probabilities proportional to their capacity share at the origin airport.

A random draw determines which carrier becomes the preferred carrier for that specific customer. The disutility for flying on a non-preferred carrier is then calculated using the preferred_carrier_alpha and preferred_carrier_beta parameters.

If no probabilities are specified via either method, the preferred carrier remains empty and no carrier preference penalties are applied.

Returns:: str – The preferred carrier code.

preferred_carrier_alpha¶

Alpha parameter for the preferred carrier disutility.

Applied only when the itinerary uses a non-preferred carrier. The formula is: mean_disutility = alpha + beta × reference_fare (if non-preferred carrier)

= 0 (if preferred carrier)

Returns:: float – The alpha parameter value.

preferred_carrier_beta¶

Beta parameter for the preferred carrier disutility.

Applied only when the itinerary uses a non-preferred carrier. The formula is: mean_disutility = alpha + beta × reference_fare (if non-preferred carrier)

= 0 (if preferred carrier)

Returns:: float – The beta parameter value.

prob_wtp()¶

Calculate the probability that a customer is willing to pay at least X.

Computes the quantile of the .

Parameters:

x : float: The price being evaluated.
reference_price : float: The reference price for the WTP distribution.
emult : float, optional: Override emult value to pass to the WTP calculation (keyword-only). If not provided, the choice model’s own emult value is used. Must be >= 1.0.

Returns:

float – The probability that a random customer drawn from the distribution would be willing to pay at least x.

random_generator¶

Random number generator for stochastic choice simulation.

The random_generator is used during the actual simulation to generate all stochastic disutility values (path quality, carrier preference, buffer time, decision window placement, etc.)

Purpose:¶

Generate stochastic variation: Creates heterogeneity in passenger behavior by drawing random values for each disutility component during simulation.
Enable reproducibility: By providing a seed when creating the Generator, you can reproduce exact simulation results across multiple runs. Without a seed, each run produces different stochastic outcomes.

Note: The random_generator is shared across all disutility calculations in the choice model, so the sequence of random draws matters for reproducibility. All components (PQI, carrier preference, fare restrictions, etc.) draw from the same generator in a fixed order.

returns:: Generator – The random number generator object.

replanning_alpha¶

Alpha parameter for replanning disutility (original PODS formulation).

Based on the original PODS formulation, this provides a binary all-or-nothing penalty. If any part of the itinerary falls outside the customer’s preferred decision window, the full replanning penalty is applied. Under this approach, one minute outside the window receives the same penalty as six hours outside the window.

Formula: penalty = alpha + beta × reference_fare (if any part outside window): = 0 (if completely inside window)

Note 1: The early_dep and late_arr parameters provide an alternative nonlinear S-curve approach that assigns partial penalties based on how far outside the window the itinerary falls. Separate functions for early departures and late arrivals are provided to capture instances where itineraries departing before the desired window may be more (or less) onerous than those arriving after the desired window, allowing for asymmetric schedule delay preferences.

Note 2: Either use the replanning_alpha/beta parameters for the original binary penalty or the early_dep_* and late_dep_* parameters for the nonlinear S-curve penalty, but not both simultaneously.

Returns:: float – The alpha parameter value.

replanning_beta¶

Beta parameter for replanning disutility (original PODS formulation).

Formula: penalty = alpha + beta × reference_fare (if any part outside window): = 0 (if completely inside window)

Note 2: Either use the replanning_alpha/beta parameters for the original binary penalty or the early_dep_* and late_dep_* parameters for the nonlinear S-curve penalty, but not both simultaneously.

Returns:: float – The beta parameter value.

seat_share_alpha¶

Alpha parameter for the seat-share preferred carrier model.

Deprecated since version This: parameter is deprecated and not recommended for use. Use the standard preferred_carrier_alpha and preferred_carrier_beta parameters with the SimulationEngine’s preferred_airline_pct_share property set to True for seat-share based carrier preferences.

Returns:: float – The alpha parameter value.

seat_share_beta¶

Beta parameter for the seat-share preferred carrier model.

Returns:: float – The beta parameter value.

segment¶

Named customer segment identifier.

Returns:: str – The name of the customer segment, such as ‘leisure’ or ‘business’.

serialize()¶

Get all parameter values from the choice model.

Returns:: dict – Dictionary containing all choice model parameters.

Notes

This method is not yet fully implemented.

set_parameters()¶

Set parameter values in the choice model.

Can be called with a single positional dict argument or with keyword arguments (which are treated as a dict).

Parameters:

parameters : dict, optional: Dictionary containing parameter values to set. Valid keys: - ‘restrictions’ : list[float] - Fare restriction disutilities - ‘restriction_sigmas’ : list[float] - Restriction sigma ratios - ‘reference_price_multiplier’ : float - Base fare multiplier - ‘emult’ : float - E-multiplier parameter
**kwargs: Parameter values as keyword arguments, merged with parameters when both are provided.