Demand

Demand objects represent travel demand for a specific origin-destination-segment combination.

A Demand object encapsulates all aspects of passenger demand including booking patterns, choice models, group sizes, and various demand metrics used in airline revenue management and network planning simulations.

base_demand instance-attribute

base_demand: float

Average demand for this origin/destination/segment combination.

business instance-attribute

business: bool

Indicator for 'business' demand segment.

This is a deprecated attribute.

curve_number instance-attribute

curve_number: int

Curve number used for converting PODS input files.

dest instance-attribute

dest: str

Destination airport code.

deterministic class-attribute instance-attribute

deterministic: bool = False

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.

distance instance-attribute

distance: float

Market distance in nautical miles.

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

dwm_tolerance instance-attribute

dwm_tolerance: float

Decision Window Model tolerance.

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

fares instance-attribute

fares: Iterator[Fare]

Iterator for the fares corresponding to this demand.

generated_demand instance-attribute

generated_demand: float

The amount of demand generated for this segment.

gt_demand instance-attribute

gt_demand: int

Grand Total demand, excluding burn samples.

gt_eliminated_chose_nothing instance-attribute

gt_eliminated_chose_nothing: int

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

gt_eliminated_no_offers instance-attribute

gt_eliminated_no_offers: int

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

gt_eliminated_wtp instance-attribute

gt_eliminated_wtp: int

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

gt_revenue instance-attribute

gt_revenue: float

Grand Total revenue, excluding burn samples.

gt_sold instance-attribute

gt_sold: int

Grand Total sold, excluding burn samples.

identifier instance-attribute

identifier: str

The unique identifier of this demand, in the form "origin~destination@segment".

market instance-attribute

market: Market

The market this demand is part of.

orig instance-attribute

orig: str

Origin airport code.

price instance-attribute

price: float

Default price for this demand.

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

prob_favored_carrier instance-attribute

prob_favored_carrier: dict[str, float]

Weights to compute favored carrier preferences.

Based on the PODS approach for carrier preference modeling.

prob_num_days instance-attribute

prob_num_days: list[float]

List of probabilities for length of trip.

Used for ML experiments, not used internally.

prob_saturday_night instance-attribute

prob_saturday_night: float

Probability of Saturday night stay.

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

reference_fare instance-attribute

reference_fare: float

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

revenue instance-attribute

revenue: float

Total revenue generated from this demand.

This value is reset after every simulation sample.

scenario_demand instance-attribute

scenario_demand: float

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

Usually generated as a random draw based on base_demand.

segment instance-attribute

segment: str

Customer segment name such as 'business' or 'leisure'.

sold instance-attribute

sold: int

Number of tickets sold for this demand.

This value is reset after every simulation sample.

unsold instance-attribute

unsold: int

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.

__init__

__init__(
    orig: str | None = None,
    dest: str | None = None,
    segment: str = "",
    base_demand: float = 0,
    scenario_demand: float = 0,
    *,
    market: Market | None = None,
    deterministic: bool = False,
)

add_booking_curve

add_booking_curve(curve: BookingCurve) -> str

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_choice_model

add_choice_model(choice_model: ChoiceModel) -> str

Add a choice model to this market segment.

Parameters:

• choice_model (ChoiceModel) –

  The choice model object to add to this market segment.

Returns:

• str –

  A confirmation message indicating the choice model was added.

Raises:

• TypeError –

  If the parameter is not a ChoiceModel object.

add_curve

add_curve(curve: BookingCurve) -> str

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_dwm

add_dwm(decision_window: DecisionWindow) -> int

Add a Decision Window Model to this market segment.

Parameters:

• decision_window (DecisionWindow) –

  The Decision Window Model object to add to this market segment.

Returns:

• int –

  Returns 0 to indicate successful addition.

Raises:

• TypeError –

  If the parameter is not a DecisionWindow object.

add_fare

add_fare(fare: Fare) -> None

Add a fare to this market segment.

Parameters:

• fare (Fare) –

  The fare object to add to this market segment.

Raises:

• TypeError –

  If the parameter is not a Fare object.

add_group_sizes

add_group_sizes(group_sizes: list[float]) -> str

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_override(
    carrier: str, discount_pct: float, pref_adj: float
) -> int

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_path(path: Path) -> str

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.

get_carrier_revenue

get_carrier_revenue(carrier: str) -> float

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_carrier_sold(carrier: str) -> int

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

get_choice_model() -> ChoiceModel | None

Get the choice model attached to this market segment.

Returns:

• ChoiceModel or None –

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

get_choice_model_name

get_choice_model_name() -> str | None

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_demand_dcp(dcp: int) -> float

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_min_delta_t

get_min_delta_t() -> int

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_min_elapsed_time() -> int

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_overrides() -> list[dict[str, str | float]]

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_paths() -> tuple[Path, ...]

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.