Bucket¶

class passengersim.core.Bucket¶

Bases: object

Booking class or virtual nesting (VN) bucket.

Represents a bucket in a revenue management system, which can be a booking class or a virtual nesting bucket. Each bucket tracks allocations, prices and revenue, sales, forecasts, and historical data.

Methods

__init__(*args, **kwargs)
capture_history	Capture history for a specified DCP.
get_history_closed	Get the closed indicator from history.
get_history_demand	Get the demand from history.
get_history_num_dcp	Get the number of DCPs stored in history.
get_history_num_dep	Get the number of historical departures in history.
get_history_sold	Get the seats sold from history.
push_history	Push the history into the departures list.
set_history_demand	Set the demand in history.

Attributes

alloc	Nested allocation level for this bucket.
booking_class	Bucket name, could be 'Y0' or a booking class like 'Q'.
cabin	Cabin code indicating the service class.
detruncated_demand	Untruncated (detruncated) demand estimate for this bucket.
fcst_mean	Forecast mean from now until departure.
fcst_revenue	Forecast revenue for this bucket from now until departure.
fcst_std_dev	Forecast standard deviation from now until departure.
force_closed	Make this bucket unavailable for sale, overrides the allocations.
forecast	Returns the appropriate Forecast object based on forecasting system in use.
forecast_multiplier	Multiplier applied to all forecasts on this bucket.
gt_revenue	Grand total revenue (excluding burn samples).
gt_sold	Grand total sold (excluding burn samples).
history	Returns the History object.
naive_value	Naive value for this Bucket, typically the non-stop fare.
name	Bucket name, could be 'Y0' or a booking class like 'Q'.
num_objects	How many Bucket objects are currently allocated? Was used for memory leak detection
price	Price for this bucket.
prorated_value	Prorated value for this Bucket.
protection	Number of seats protected, as calculated by EMSRb or other algorithm.
q_forecast	Returns the Q forecast (priceable forecast) object.
revenue	Revenue for this bucket, reset after each sample.
sold	Number sold, reset after each sample.
tf_index_closed_by_ap	Index of the timeframe where this bucket is completely closed due to AP restrictions.
y_forecast	Returns the Y forecast (yieldable forecast) object.

alloc¶

Nested allocation level for this bucket.

A booking limit system where lower fare classes can access capacity allocated to higher fare classes. Each bucket’s allocation represents the cumulative number of seats available to it.

For example, if a leg has 100 seats and 3 fare classes (High, Medium, Low): - High bucket alloc: 54 seats (only high fares can book these 54) - Medium bucket alloc: 37 seats (medium + high fares can book up to 37 of remaining 46) - Low bucket alloc: 14 seats (any fare can book up to 14 of remaining seats)

Returns:

float – The allocation level.

booking_class¶

Bucket name, could be ‘Y0’ or a booking class like ‘Q’.

Returns:

str – The bucket name.

cabin¶

Cabin code indicating the service class.

Cabin codes are single-letter identifiers for different service classes on an aircraft. Typical examples include: - ‘Y’: Economy/Coach class - ‘C’: Business class - ‘F’: First class

If not explicitly set, defaults to the first character of the bucket name.

Returns:

str – The cabin code.

capture_history()¶

Capture history for a specified DCP.

Parameters:

dcp_index : int

Days prior to departure index.

detruncated_demand¶

Untruncated (detruncated) demand estimate for this bucket.

When a bucket closes before departure, we only observe truncated demand (seats sold), not how many more customers would have booked. Untruncation algorithms (e.g., EM) estimate the true underlying demand from historical patterns.

Notes: - Single aggregate value (not per DCP/timeframe) - Used as input to forecasting algorithms - Resets each sample like other counters - Optional - not all RM systems use untruncation

Returns:

float – The detruncated demand.

fcst_mean¶

Forecast mean from now until departure.

Returns:

float – The forecast mean.

fcst_revenue¶

Forecast revenue for this bucket from now until departure.

Returns:

float – The forecast revenue.

fcst_std_dev¶

Forecast standard deviation from now until departure.

Returns:

float – The forecast standard deviation.

force_closed¶

Make this bucket unavailable for sale, overrides the allocations.

When set to True, this flag forces a bucket to be closed (unavailable for booking) regardless of its allocation level. This provides a manual override mechanism that bypasses normal revenue management controls.

Common use cases include:

1. Load Factor Threshold: Automatically close low-fare buckets when the flight’s load factor (percentage of seats sold) exceeds a threshold for that fare class.

2. User Adjustments: RM analysts can manually override system recommendations. For instance, closing the lowest fare bucket when the airline’s price is below competitors to avoid being the cheapest option in the market.

3. Tactical Revenue Management: Close specific fare classes based on booking patterns, such as closing discount fares when bookings are ahead of forecast to maximize revenue.

Note: Advance purchase restrictions are NOT implemented using force_closed. AP restrictions are handled separately through the bucket’s advance purchase DCP index, which automatically closes fares when the booking window passes the AP cutoff date.

Returns:

bool – True if bucket is forced closed, False otherwise.

forecast¶

Returns the appropriate Forecast object based on forecasting system in use.

Returns forecasts in this priority order: 1. Total forecast - Used in hybrid forecasting, which combines Y and Q forecasts

(total = Y forecast + Q forecast)

2. Y forecast (yieldable/plain forecast) - Standard forecast for non-price-sensitive demand

3. Q forecast (priceable forecast) - Forecast for price-sensitive demand only

This provides a single convenient property to access whichever forecast is active, without needing to know which forecasting system is configured.

Returns:

Forecast – The forecast object for this bucket.

forecast_multiplier¶

Multiplier applied to all forecasts on this bucket.

get_history_closed()¶

Get the closed indicator from history.

Parameters:

period : int

Historical period index.

dcp_index : int

Days prior to departure index.

Returns:

float – Closed indicator value.

get_history_demand()¶

Get the demand from history.

Parameters:

period : int

Historical period index.

dcp_index : int

Days prior to departure index.

Returns:

float – Demand value.

get_history_num_dcp()¶

Get the number of DCPs stored in history.

Returns:

int – Number of DCP timeframes in history.

get_history_num_dep()¶

Get the number of historical departures in history.

Returns:

int – Number of historical departures.

get_history_sold()¶

Get the seats sold from history.

Parameters:

period : int

Historical period index.

dcp_index : int

Days prior to departure index.

Returns:

float – Number of seats sold.

gt_revenue¶

Grand total revenue (excluding burn samples).

This is the cumulative allocated revenue across all samples after the burn period. Unlike revenue which resets each sample, gt_revenue keeps accumulating for the entire simulation run.

Key differences from revenue:

1. Excludes burn samples: The simulation has an initial “burn period” (warm-up phase) where the RM system is learning and stabilizing. This is typically 30-100 samples depending on configuration. Statistics from burn samples are not counted in grand totals to ensure reported results reflect stable system performance.

2. Never resets: While revenue resets to zero after each sample, gt_revenue accumulates continuously across all non-burn samples throughout the simulation.

3. Used for final reporting: This is the primary metric used in simulation outputs and comparisons, as it represents the total revenue performance after the system has stabilized.

Like revenue, this is the sum of allocated revenue (not price × sold), accounting for fare proration across multi-leg itineraries.

Returns:

float – The grand total revenue.

gt_sold¶

Grand total sold (excluding burn samples).

Counts the number of seats sold in this bucket across all non-burn samples. Note that this is a per-leg counter: if one passenger books a 2-leg itinerary, each leg’s bucket will increment gt_sold by 1, resulting in a total of 2 across both legs.

Returns:

int – The grand total number of seats sold.

history¶

Returns the History object.

The History object stores historical booking data for this bucket across multiple past departures and timeframes. This data is used by forecasting algorithms to predict future demand.

Stored data includes: - Sold: Number of seats sold in each timeframe of each past departure - Closure: Whether the bucket was closed in each timeframe - Priceable sold: Separate tracking of price-sensitive demand (optional)

The history typically stores the most recent 26 departures with 16 timeframes per departure, creating a rolling buffer of historical patterns that forecasting algorithms analyze to estimate future demand.

Returns:

History – The history object for this bucket.

naive_value¶

Naive value for this Bucket, typically the non-stop fare.

name¶

Bucket name, could be ‘Y0’ or a booking class like ‘Q’.

Returns:

str – The bucket name.

num_objects¶

How many Bucket objects are currently allocated? Was used for memory leak detection

price¶

Price for this bucket.

Returns:

float – The bucket price.

prorated_value¶

Prorated value for this Bucket.

protection¶

Number of seats protected, as calculated by EMSRb or other algorithm.

Protection levels represent the number of seats that should be “protected” or reserved for higher-revenue fare classes. This is the inverse concept of allocation: while allocation specifies how many seats a bucket can access, protection specifies how many seats should be withheld from lower fare classes.

For example, using the same 100-seat leg with 3 fare classes (High, Medium, Low): - High bucket protection: 46 seats (protect 46 seats from Medium and Low) - Medium bucket protection: 33 seats (protect 33 seats from Low only) - Low bucket protection: 0 seats (nothing below to protect from)

The relationship between protection and allocation is:

allocation = capacity - protection - sold

Note: Protection is undefined/not used for O&D (Origin-Destination) controls.

Returns:

int – Number of protected seats.

push_history()¶

Push the history into the departures list.

q_forecast¶

Returns the Q forecast (priceable forecast) object.

The Q forecast represents demand from price-sensitive passengers who primarily make booking decisions based on price considerations.

In hybrid forecasting, Q forecast is combined with Y forecast to create the total forecast. In non-hybrid systems, Q forecast can be used alone.

Returns:

Forecast – The Q forecast object for this bucket.

revenue¶

Revenue for this bucket, reset after each sample.

Revenue is the sum of allocated revenue per passenger sold in this bucket during the current sample (departure). Note that this is NOT simply price × sold, because:

1. Revenue is prorated across legs: When passengers book multi-leg itineraries, the total fare they pay is allocated (prorated) across the different legs and buckets they use. Each bucket receives its portion of the total fare.

   Example: A passenger pays $500 for a two-leg journey (BOS-ORD-LAX). The first leg’s bucket might be allocated $300 of revenue, while the second leg’s bucket gets $200, even though both buckets show “1 sold”.

2. Multiple fares can use the same bucket: Different fare products with different prices might all book into the same booking class, contributing different amounts of revenue per seat.

3. Reset after each sample: The revenue counter is reset to zero at the start of each sample (departure) and accumulates bookings during that sample. After the sample completes, it resets for the next departure.

For grand totals accumulated across all samples, see gt_revenue.

Returns:

float – The bucket revenue.

set_history_demand()¶

Set the demand in history.

Parameters:

dcp_index : int

Days prior to departure index.

demand : float

Demand value to set.

sold¶

Number sold, reset after each sample.

Counts the number of seats sold in this bucket for the current sample. Note that this is a per-leg counter: if one passenger books a 2-leg itinerary, each leg’s bucket will increment sold by 1, resulting in a total of 2 across both legs.

Returns:

int – The number of seats sold.

tf_index_closed_by_ap¶

Index of the timeframe where this bucket is completely closed due to AP restrictions.

Returns:

int

y_forecast¶

Returns the Y forecast (yieldable forecast) object.

The Y forecast represents demand from passengers who are not primarily price-sensitive. They book based on schedule, availability, loyalty, or other non-price factors.

In hybrid forecasting, Y forecast is combined with Q forecast to create the total forecast. In non-hybrid systems, Y forecast can be used alone.

Returns:

Forecast – The Y forecast object for this bucket.