Demand¶

class passengersim.core.Demand¶

Bases: object

Demand objects

Methods

__init__(*args, **kwargs)
add_booking_curve	Add a booking curve to this market segment.
add_curve	Add a booking curve to this market segment.
add_fare	Add a fare to this market segment.
add_group_sizes	Add a list of group sizes to this market segment.
add_override	Add demand override information to this market segment.
add_path	Add an itinerary path to this market segment.
choose_offer	Use this demand's choice model to choose among a sequence of offers.
get_carrier_revenue	Get the revenue generated for the specified carrier.
get_carrier_sold	Get the number of tickets sold for the specified carrier.
get_choice_model_name	Get the name of the choice model attached to this market segment.
get_demand_dcp	Get generated demand for the specified Days before Close of Passage (DCP).
get_demand_history	Get the demand history.
get_min_delta_t	Get the minimum delta_t across all paths for this demand.
get_min_elapsed_time	Get the minimum elapsed time across all paths for this demand.
get_overrides	Get the demand overrides for this market segment.
get_paths	Get the paths that can handle requests from this demand.
simulate_choices	Simulate many choices among a sequence of offers using this demand's choice model.

Attributes

base_demand	Average demand for this origin/destination/segment combination.
business	Indicator for 'business' demand segment.
choice_model	The choice model attached to this market segment.
curve_number	Curve number used for converting PODS input files.
dest	Destination airport code.
deterministic	Indicates if demand is deterministic for this object.
distance	Market distance in nautical miles.
dwm	The Decision Window Model attached to this market segment.
dwm_tolerance	Decision Window Model tolerance.
emult	E-multiplier parameter for this demand.
fares	Iterator for the fares corresponding to this demand.
generated_demand	The amount of demand generated for this segment.
gt_demand	Grand Total demand, excluding burn samples.
gt_eliminated_chose_nothing	Grand Total eliminated demand that chose nothing, excluding burn samples.
gt_eliminated_no_offers	Grand total NO-GO due to no offers available, excluding burn samples.
gt_eliminated_wtp	Grand total NO-GO due to Willingness To Pay (WTP), excluding burn samples.
gt_revenue	Grand Total revenue, excluding burn samples.
gt_sold	Grand Total sold, excluding burn samples.
identifier	The unique identifier of this demand.
market	The market this demand is part of.
market_identifier	The unique identifier of this demand's market.
orig	Origin airport code.
price	Default price for this demand.
prob_favored_carrier	Weights to compute favored carrier preferences.
prob_num_days	List of probabilities for length of trip.
prob_saturday_night	Probability of Saturday night stay.
reference_price	Reference fare used when computing Willingness To Pay (WTP).
revenue	Total revenue generated from this demand.
scenario_demand	Demand for this origin/destination/segment in this sample.
segment	Customer segment name.
sold	Number of tickets sold for this demand.
unsold	NO-GO count for demand that chose nothing.

add_booking_curve()¶

Add a booking curve to this market segment.

Parameters:

curve : BookingCurve

The booking curve object to add to this market segment.

Returns:

str – A confirmation message indicating the curve was added.

Raises:

TypeError – If the parameter is not a BookingCurve object.

add_curve()¶

Add a booking curve to this market segment.

Parameters:

curve : BookingCurve

The booking curve object to add to this market segment.

Returns:

str – A confirmation message indicating the curve was added.

Raises:

TypeError – If the parameter is not a BookingCurve object.

add_fare()¶

Add a fare to this market segment.

Parameters:

fare : Fare

The fare object to add to this market segment.

Returns:

None – This method does not return a value.

Raises:

TypeError – If the parameter is not a Fare object.

add_group_sizes()¶

Add a list of group sizes to this market segment.

Group sizes is an array of proportions that define the distribution of group sizes for bookings. For example, [0.5, 0.4, 0.1] indicates 50% single passengers, 40% groups of 2, and 10% groups of 3.

Parameters:

group_sizes : list of float

A list of proportions for different group sizes. Must sum to 1.0 (±0.001).

Returns:

str – A confirmation message indicating the group sizes were added.

Raises:

• TypeError – If the parameter is not a list.

• ValueError – If the group sizes do not sum to 1.0 (within tolerance of 0.001).

add_override()¶

Add demand override information to this market segment.

Overrides allow for carrier-specific adjustments to demand modeling, including discount percentages and preference adjustments.

Parameters:

carrier : str

The carrier code to apply the override to.

discount_pct : float

The discount percentage to apply for this carrier.

pref_adj : float

The preference adjustment factor for this carrier.

Returns:

int – Returns 0 to indicate successful addition.

Raises:

TypeError – If the carrier parameter is not a string.

add_path()¶

Add an itinerary path to this market segment.

Parameters:

path : Path

The itinerary path object to add to this market segment.

Returns:

str – A confirmation message indicating the path was added.

Raises:

• TypeError – If the parameter is not a Path object.

• ValueError – If the market is not set for this Demand object.

base_demand¶

Average demand for this origin/destination/segment combination.

Returns:

float – The base demand value.

business¶

Indicator for ‘business’ demand segment.

This is a deprecated attribute.

Returns:

bool – True if this is a business demand segment, False otherwise.

choice_model¶

The choice model attached to this market segment.

Returns None if no choice model has been set. Assigning None clears any previously set choice model.

Returns:

ChoiceModel or None – The choice model object if one is attached, None otherwise.

Raises:

TypeError – If the assigned value is not a ChoiceModel object or None.

choose_offer()¶

Use this demand’s choice model to choose among a sequence of offers.

The method retrieves the choice model attached to this Demand and uses it to make a single choice among the provided offers.

Parameters:

offers : Sequence[Offer]

A sequence of Offer objects to choose from.

Returns:

int – The index of the chosen offer within the provided sequence, or -1 if no offer was chosen (i.e. the “chose nothing” outcome).

Raises:

• ValueError – If no choice model is attached to this Demand, or if the offers sequence is empty.

• TypeError – If offers is not a sequence, or if any element is not an Offer.

curve_number¶

Curve number used for converting PODS input files.

Returns:

int – The curve number identifier.

dest¶

Destination airport code.

Returns:

str – The destination airport code for this demand.

deterministic¶

Indicates if demand is deterministic for this object.

When demand is deterministic, the generated total demand will be exactly the base demand for every simulation day. All demand generation K factors are rendered moot in this case. There can still be some randomness in the timeframe distribution of this demand, but the total amount will be deterministic.

Returns:

bool – True if demand is deterministic, False otherwise.

distance¶

Market distance in nautical miles.

This is a pass-through attribute of the market object.

Returns:

float – The distance in nautical miles.

dwm¶

The Decision Window Model attached to this market segment.

Returns None if no Decision Window Model has been set. Assigning None clears any previously set Decision Window Model.

Returns:

DecisionWindow or None – The Decision Window Model if one is attached, None otherwise.

Raises:

TypeError – If the assigned value is not a DecisionWindow object or None.

dwm_tolerance¶

Decision Window Model tolerance.

How far outside the decision window will these passengers tolerate with replanning disutility.

Returns:

float – The DWM tolerance value.

emult¶

E-multiplier parameter for this demand.

Scales the price sensitivity of the demand relative to the reference price. A value of 1.0 means no adjustment; values greater than 1.0 increase price sensitivity. Must be >= 1.0.

Returns:

float – The e-multiplier value.

Raises:

ValueError – If the assigned value is less than 1.0.

fares¶

Iterator for the fares corresponding to this demand.

Returns:

Iterator[Fare] – An iterator over all Fare objects associated with this demand.

generated_demand¶

The amount of demand generated for this segment.

Returns:

float – The generated demand value.

get_carrier_revenue()¶

Get the revenue generated for the specified carrier.

Parameters:

carrier : str

The carrier code to query.

Returns:

float – The revenue generated for the specified carrier, or 0.0 if no revenue recorded.

Raises:

TypeError – If the carrier parameter is not a string.

get_carrier_sold()¶

Get the number of tickets sold for the specified carrier.

Parameters:

carrier : str

The carrier code to query.

Returns:

int – The number of tickets sold for the specified carrier, or 0 if no sales recorded.

Raises:

• TypeError – If the carrier parameter is not a string.

• Exception – If an error occurs during the lookup.

get_choice_model_name()¶

Get the name of the choice model attached to this market segment.

Returns:

str or None – The name of the choice model if one is attached, None otherwise.

get_demand_dcp()¶

Get generated demand for the specified Days before Close of Passage (DCP).

Used for debugging and unit tests to examine demand generation at specific timeframes.

Parameters:

dcp : int

The Days before Close of Passage (DCP) to query.

Returns:

float – The generated demand for the specified DCP.

Raises:

IndexError – If the specified DCP is not found in the demand timeframe data.

get_demand_history()¶

Get the demand history.

Returns:

list[dict] – A list of demand counters by trial and sample.

get_min_delta_t()¶

Get the minimum delta_t across all paths for this demand.

Used for unit testing of Decision Window Model (DWM). Finds the shortest delta_t value among all paths that can handle requests from this demand.

Returns:

int – The minimum delta_t value.

Raises:

Exception – If an error occurs during the calculation.

get_min_elapsed_time()¶

Get the minimum elapsed time across all paths for this demand.

Finds the shortest elapsed time (total travel time) among all paths that can handle requests from this demand.

Returns:

int – The minimum elapsed time in minutes.

Raises:

Exception – If an error occurs during the calculation.

get_overrides()¶

Get the demand overrides for this market segment.

Returns a list of dictionaries containing override information for different carriers. Each dictionary contains ‘carrier’, ‘discount_pct’, and ‘pref_adj’ keys.

Returns:

list of dict – A list of dictionaries, each containing: - ‘carrier’ (str): The carrier code - ‘discount_pct’ (float): The discount percentage - ‘pref_adj’ (float): The preference adjustment factor

Raises:

Exception – If an error occurs while processing the overrides.

get_paths()¶

Get the paths that can handle requests from this demand.

Returns a tuple of Path objects representing all itinerary paths available for this market segment.

Returns:

tuple of Path – A tuple containing all Path objects that can handle requests from this demand. Returns an empty tuple if no paths are available.

Raises:

• ValueError – If the market is not set for this Demand object.

• Exception – If an error occurs while creating path objects.

gt_demand¶

Grand Total demand, excluding burn samples.

Returns:

int – The grand total demand count.

gt_eliminated_chose_nothing¶

Grand Total eliminated demand that chose nothing, excluding burn samples.

Returns:

int – The count of demand that was eliminated because customers chose nothing.

gt_eliminated_no_offers¶

Grand total NO-GO due to no offers available, excluding burn samples.

Returns:

int – The count of demand eliminated due to lack of available offers.

gt_eliminated_wtp¶

Grand total NO-GO due to Willingness To Pay (WTP), excluding burn samples.

Returns:

int – The count of demand eliminated due to WTP constraints.

gt_revenue¶

Grand Total revenue, excluding burn samples.

Returns:

float – The grand total revenue amount.

gt_sold¶

Grand Total sold, excluding burn samples.

Returns:

int – The grand total number of tickets sold.

identifier¶

The unique identifier of this demand.

Returns:

str – The unique identifier in the form “origin~destination@segment”.

market¶

The market this demand is part of.

Returns:

Market or None – The Market object this demand belongs to, or None if not set.

market_identifier¶

The unique identifier of this demand’s market.

Returns:

str – The unique identifier in the form “origin~destination”.

orig¶

Origin airport code.

Returns:

str – The origin airport code for this demand.

price¶

Default price for this demand.

This was used for initial scheduling experiments and is now deprecated.

Returns:

float – The default price value.

prob_favored_carrier¶

Weights to compute favored carrier preferences.

Based on the PODS approach for carrier preference modeling.

Returns:

dict of str to float – Dictionary mapping carrier codes to preference weights.

prob_num_days¶

List of probabilities for length of trip.

Used for ML experiments, not used internally.

Returns:

list of float – Probabilities for different trip durations.

prob_saturday_night¶

Probability of Saturday night stay.

Sets a flag in the Offer, used for ML experiments. Not used internally.

Returns:

float – The probability of Saturday night stay.

reference_price¶

Reference fare used when computing Willingness To Pay (WTP).

Returns:

float – The reference fare value.

revenue¶

Total revenue generated from this demand.

This value is reset after every simulation sample.

Returns:

float – The total revenue amount.

scenario_demand¶

Demand for this origin/destination/segment in this sample.

Usually generated as a random draw based on base_demand.

Returns:

float – The scenario demand value.

segment¶

Customer segment name.

Returns:

str – The customer segment name such as ‘business’ or ‘leisure’.

simulate_choices()¶

Simulate many choices among a sequence of offers using this demand’s choice model.

This will approximate the probability of each of the offers being chosen, given the set of offers.

This method invokes the Demand’s choice model to choose among the provided offers. “Chose nothing” outcomes are not counted in the returned array, so the sum of choices may not equal the number of draws.

Parameters:

offers : Sequence[Offer]

A sequence of Offer objects to choose from.

n_draws : int, optional

The number of choice draws to simulate. Defaults to 100000.

Returns:

numpy.ndarray – A 1-d numpy array of ints with length equal to the number of offers, where each element is the count of times that offer was chosen.

Raises:

• ValueError – If no choice model is attached to this Demand, if the offers sequence is empty, or if n_draws is less than 1.

• TypeError – If offers is not a sequence, or if any element is not an Offer.

sold¶

Number of tickets sold for this demand.

This value is reset after every simulation sample.

Returns:

int – The number of tickets sold.

unsold¶

NO-GO count for demand that chose nothing.

Count of demand that could not be satisfied due to capacity or Willingness To Pay (WTP) constraints.

Returns:

int – The number of unsold demand instances.