Carrier¶
- class passengersim.core.Carrier¶
Bases:
objectAn airline in the simulation, with its RM settings and sales counters.
A carrier operates legs and sells fares. Its settings tell the simulation how to control availability (control), how to use continuous pricing (the
cp_properties) and how much forecasting history to keep. It also keeps sales counters and summary statistics that the simulation reports at the end of a run.- Parameters:
- name : keyword-only. Each optional argument sets the property of the same
Name of the carrier, usually its code such as
"AL1"or"DL".- control : {"leg", "cabin", "theft", "vn", "bp", "bp_loose", "none"}, default "leg"
RM control technique; see control.
- store_q_history : bool, optional
Whether to store Q-equivalent history; see store_q_history.
- truncation_rule : {1, 2, 3}, optional
See truncation_rule.
- proration_rule : {"distance", "sqrt_distance", "off"}, optional
See proration_rule.
- history_length : int, optional
See history_length.
- brand_preference : float, optional
See brand_preference.
- cp_algorithm : str or None, optional
See cp_algorithm.
- cp_record : {"highest_closed", "lowest_open"}, optional
See cp_record.
- cp_record_highest_closed_as_open : bool, optional
See cp_record_highest_closed_as_open.
- cp_quantize : int, optional
See cp_quantize.
- cp_scale : float, optional
See cp_scale.
- cp_elasticity : dict or None, optional
See cp_elasticity.
- cp_markets : str, optional
See cp_markets.
- cabin_ordering : sequence of str, optional
See cabin_ordering.
- default_booking_classes : sequence of str or (str, str), optional
See default_booking_classes.
- are : Only name and control can be given by position; the rest
- name
:param : :param with the same rules: :param and an omitted one keeps its default.:
- Raises:
TypeError – If control is not a str, or another argument has the wrong type for its property.
ValueError – If control is not one of the values above, or another argument has a value its property rejects.
Methods
__init__(*args, **kwargs)Add an ancillary that this carrier offers.
Add or replace one sample's entry in the carrier history.
Add a customer model, for the
"OPT"continuous pricing algorithm.Set the Frat5 curve to use for one O&D market.
Get one of this carrier's ancillaries by position.
Get the price of one of this carrier's ancillaries, by code.
Get the number sold of one of this carrier's ancillaries, by code.
This carrier's sales totals for each sample.
Forecast accuracy statistics, as a list of dictionaries.
Get the Frat5 curve used for an O&D market.
The history definition used to set up this carrier's histories.
Spill counters by first-choice booking class, like the PODS .SOT output.
Statistics of this carrier's leg bid prices by day before departure.
Cumulative bookings by fare class by day before departure.
Bookings by customer segment, fare class and DCP.
Statistics of this carrier's leg displacement costs at each DCP.
Sales and revenue totals by fare class.
Count of this carrier's leg departures by load factor.
Revenue by customer segment, fare class and DCP.
Clear the statistics reported by raw_bid_price_trace.
Clear the statistics reported by raw_displacement_cost_trace.
Attributes
An iterator over the ancillaries added with add_ancillary.
Brand preference multiplier for this carrier.
Ordering of cabin types on this carrier, from best to worst.
The RM control technique that decides which booking classes are available.
The continuous pricing (CP) algorithm, or
"None"if CP is off.Settings for guessing customers' price elasticity in
"CBC"pricing.Which markets the
"OPT"continuous pricing optimizer works on.For continuous pricing, the step that prices would be rounded to.
Which booking class a continuous pricing sale is recorded in.
Whether to record the highest closed path class as open in its history.
Multiplier on the continuous pricing markup.
Index of the current timeframe for this carrier.
Days prior to departure of each DCP, which is when each timeframe starts.
Which price a path class uses as its decision price.
Default booking classes for legs and paths on this carrier.
The carrier's default Frat5 curve, or None if it has none.
Grand total available seat miles (ASM) after the burn period.
Grand total revenue from continuous pricing sales after the burn period.
Grand total number of passengers sold through continuous pricing.
Grand total demand for this carrier.
Grand total revenue from this carrier's sales after the burn period.
Grand total revenue passenger miles (RPM) after the burn period.
Grand total number of passengers sold by this carrier after the burn period.
Number of past samples kept in the forecasting history.
Load factor curve for the load factor threshold RM system (deprecated).
A dict for storing arbitrary metadata on the carrier.
Name of the carrier, usually its code such as
"AL1"or"DL".Number of Carrier objects currently allocated.
How the revenue of a connecting itinerary is split across its legs.
Revenue from this carrier's sales in the current sample.
The RM system used by this carrier, or None.
Number of passengers sold by this carrier in the current sample.
Number of the passengers in sold whose offer was priceable.
Whether to store Q-equivalent history at each DCP, for Q forecasting.
When a timeframe counts as closed for a booking class in its history.
- add_ancillary()¶
Add an ancillary that this carrier offers.
The ancillary is added to ancillaries, and its sales are counted from then on. If two ancillaries have the same code, lookups by code find the first one.
- Parameters:
- anc : Ancillary
The ancillary to add.
- Returns:
int – Always 0.
- Raises:
TypeError – If anc is not an Ancillary.
- add_carrier_history()¶
Add or replace one sample’s entry in the carrier history.
Only used for unit testing; the simulation records the history itself at the end of each sample. See get_carrier_history.
- Parameters:
- trial : int
Trial number.
- sample : int
Sample number.
- sold : int
Number of passengers sold.
- sold_priceable : int
Number of those passengers whose offer was priceable.
- revenue : float
Revenue.
- Returns:
int – Always 0.
- Raises:
ValueError – If sample is negative.
- add_customer_model()¶
Add a customer model, for the
"OPT"continuous pricing algorithm.The contextual optimizer looks up models by customer segment, so the model’s name should be the segment it describes, such as
"business"or"leisure". A model with the same name replaces the earlier one.- Parameters:
- customer_model : CustomerModel
The customer model to add.
- Raises:
TypeError – If customer_model is not a CustomerModel.
- add_frat5_mkt()¶
Set the Frat5 curve to use for one O&D market.
For that market, get_frat5_mkt and the core use this curve instead of the default frat5. Setting a market again replaces its curve. Markets are directional, so (orig, dest) and (dest, orig) are separate.
- Parameters:
- orig : str
Origin airport code.
- dest : str
Destination airport code.
- frat5 : Frat5
The Frat5 curve to use for this market.
- Raises:
IndexError – If orig or dest is not a str.
TypeError – If frat5 is not a Frat5.
- ancillaries¶
An iterator over the ancillaries added with add_ancillary.
They come in the order they were added. Read-only; each read returns a new iterator.
- brand_preference¶
Brand preference multiplier for this carrier.
The default is 1.0. The core stores this value but does not currently use it. Setting it requires a number.
- cabin_ordering¶
Ordering of cabin types on this carrier, from best to worst.
For any leg that has multiple cabins, all cabin names must appear in this list. The cabins are strictly ordered, so that any customer can be accommodated in the cabin for the ticket they purchased or any better cabin. Not every leg needs every cabin. Reading it returns a new list. Setting it takes a sequence of str (a single str is rejected) and replaces the ordering.
- control¶
The RM control technique that decides which booking classes are available.
"leg": leg (segment) control with standard nesting. A booking class is available on a path if its bucket is open on every leg, and a sale reduces the authorization of that bucket and every bucket above it."cabin": currently the same as"leg"."theft": leg control with theft nesting."vn": virtual nesting (DAVN)."bp": bid price control. A booking class is available if its adjusted fare is greater than the total of the leg bid prices on the path."bp_loose": like"bp", but a class is also available when its adjusted fare equals the total bid price."none": no RM control; every booking class is available.
Read-only; it is set by the constructor’s control argument.
- cp_algorithm¶
The continuous pricing (CP) algorithm, or
"None"if CP is off."None"(the default): no continuous pricing."BP": the price is the total bid price on the path, but at least the lowest fare."CBC": the price is the total bid price plus a modifier from the Frat5 curve, scaled by cp_scale (see also cp_elasticity)."OPT": prices come from the contextual optimizer, which uses the carrier’s customer models (see add_customer_model) and cp_markets."CLASSLESS": classless pricing. The price is the total bid price plus a Frat5 markup scaled by cp_scale, kept between the lowest and highest fares. It also changes how Q-equivalent history is stored.
Reading it returns one of these names. Setting it also accepts None,
"none","bid_price","cbc","opt"and"classless"; any other value raises ValueError.
- cp_elasticity¶
Settings for guessing customers’ price elasticity in
"CBC"pricing.When guessing is on, CBC guesses whether each customer is business or leisure, and gets it right with probability
accuracy. For customers it guesses are leisure, the Frat5 modifier usesmultiplieras the passenger type adjustment; for the others it uses 1.0.Reading it returns a new dict with
"accuracy"(default 0.9) and"multiplier"(default 1.0). Setting it takes a dict whose values must be floats (an int raises TypeError), with any of these keys:"accuracy": from 0.0 to 1.0. Setting it turns guessing on."multiplier": non-negative."beta_price"and"beta_connect": stored, but not shown when reading and not currently used.
Keys left out keep their current values. Setting it to None, or deleting it, resets everything to the defaults and turns guessing off. A bad key or value raises TypeError, and the keys before it may already be applied.
- cp_markets¶
Which markets the
"OPT"continuous pricing optimizer works on.One of
"all"(the default),"local"or"connect". The value is passed to the contextual optimizer. Setting it requires a str; the value is not checked.
- cp_quantize¶
For continuous pricing, the step that prices would be rounded to.
For example, 10 would round prices to a multiple of 10. The rounding is currently turned off in the core, so this value is stored but has no effect. The default is 0. Setting it accepts a number, which is truncated to an int.
- cp_record¶
Which booking class a continuous pricing sale is recorded in.
When continuous pricing sells a closed fare at a lower price, the sale is recorded in that fare’s own booking class with
"highest_closed"(the default), or in the carrier’s lowest open booking class with"lowest_open". This decides which class’s history and fare counters get the sale. Setting it requires one of these strings;"nearest"raises NotImplementedError and any other value raises ValueError.
- cp_record_highest_closed_as_open¶
Whether to record the highest closed path class as open in its history.
When continuous pricing is on and cp_record is
"highest_closed", CP sales are recorded in the highest closed class, so with this set that class is recorded as open in the path class history. It has no effect otherwise. The default is True. Setting it uses the truth value of what is assigned.
- cp_scale¶
Multiplier on the continuous pricing markup.
With the
"CBC"and"CLASSLESS"algorithms, the markup added to the total bid price is multiplied by this. For example, 0.5 adds half of the markup. The default is 1.0. Setting it requires a number.
- current_tf_index¶
Index of the current timeframe for this carrier.
The carrier’s RM system advances it at each DCP, and resetting the counters at the start of each sample sets it back to 0. Bid price availability uses it to choose each path class’s adjusted fare. Setting it requires an int from 0 to
len(dcp_days_prior); a negative value raises ValueError and a larger one raises IndexError. Setting it before dcp_days_prior is set raises ValueError.
- dcp_days_prior¶
Days prior to departure of each DCP, which is when each timeframe starts.
Reading it raises ValueError until it is set. It can only be set once: setting it takes a sequence of ints, and setting it again raises ValueError.
- decision_price_rule¶
Which price a path class uses as its decision price.
This matters when a path class can sell more than one fare, as with matrix pricing or continuous pricing. The decision price is the revenue that RM expects from a sale in the path class:
"lowest"(the default): the price of its lowest fare."weighted": the weighted average price of the fares it has sold, by timeframe. Without sales in the timeframe it falls back to the overall weighted average, and then to the lowest fare."weighted_scalar": the overall weighted average price, falling back to the lowest fare."brand": the price of its fare with the"economy"brand (the brand is currently fixed in the code). It is an error if there is none."unknown": the same as"lowest".
Path classes copy this rule when they are set up, so changing it later may not reach existing path classes. Setting it requires one of these strings.
- default_booking_classes¶
Default booking classes for legs and paths on this carrier.
Each entry is a pair (booking_class, lowest_cabin). booking_class is the name of the booking class, and lowest_cabin is the lowest cabin where customers who buy it may be accommodated; an empty lowest_cabin means any cabin. Reading it returns a new list. Setting it takes a sequence whose items are each a str (stored with an empty lowest_cabin) or a (str, str) pair, and replaces the list.
- frat5¶
The carrier’s default Frat5 curve, or None if it has none.
The Frat5 curve describes how willing customers are to buy up to higher fares. It is used by Q forecasting and fare adjustment, and the
"CBC"and"CLASSLESS"continuous pricing algorithms need it. get_frat5_mkt falls back to this curve for markets without one of their own, and get_history_def reports whether it is set. Setting it requires a Frat5; it cannot be set back to None.
- get_ancillary_by_index()¶
Get one of this carrier’s ancillaries by position.
Only used for debugging.
- Parameters:
- index : int
Position in the order the ancillaries were added, starting at 0.
- Returns:
Ancillary – The ancillary at that position.
- Raises:
IndexError – If index is negative or past the last ancillary.
- get_ancillary_price()¶
Get the price of one of this carrier’s ancillaries, by code.
- Parameters:
- name : str
The ancillary code, such as
"ANC1".
- Returns:
float – The price of the first ancillary with this code.
- Raises:
TypeError – If name is not a str.
Exception – If the carrier has no ancillary with this code.
- get_ancillary_sold()¶
Get the number sold of one of this carrier’s ancillaries, by code.
The count is for the current sample; resetting the counters sets it back to zero.
- Parameters:
- name : str
The ancillary code, such as
"ANC1".
- Returns:
int – The number sold of the first ancillary with this code.
- Raises:
TypeError – If name is not a str.
Exception – If the carrier has no ancillary with this code.
- get_carrier_history()¶
This carrier’s sales totals for each sample.
At the end of each sample after the burn period, the simulation records the carrier’s sold, sold_priceable and revenue.
- Returns:
list[dict] – One dict per sample, in order of trial and then sample, with the keys
"trial","sample","carrier"(this carrier’s name),"sold","sold_priceable"and"revenue".
- get_forecast_accuracy()¶
Forecast accuracy statistics, as a list of dictionaries.
These are collected by SimulationEngine.capture_forecast_accuracy. Each time it runs, for each of this carrier’s path classes with a forecast, and each timeframe in which the class was open, it adds the sales from the class’s most recent history entry and its forecast to the totals for that trial, sample, booking class and timeframe.
- Returns:
list[dict] – One dict per trial, sample, booking class and timeframe, with these keys:
"trial","sample"and"carrier"(this carrier’s name)."booking_class"and"timeframe"(the timeframe index)."num_obs": the number of path class timeframes added."sold"and"sold_priceable": total sales."fcst_mean": the total of the forecast means."fcst_variance": the total of the forecast variances."num_zero_displacement": not currently counted, so always 0.
They are sorted by trial, sample, booking class and timeframe compared as text, so for example sample 10 comes before sample 2.
- get_frat5_mkt()¶
Get the Frat5 curve used for an O&D market.
- Parameters:
- orig : str
Origin airport code.
- dest : str
Destination airport code.
- Returns:
Frat5 or None – The market’s own curve if one was set with add_frat5_mkt, otherwise the default frat5, or None if there is neither.
- Raises:
TypeError – If orig or dest is not a str.
- get_history_def()¶
The history definition used to set up this carrier’s histories.
The simulation uses it to set up the history of the carrier’s buckets and path classes. dcp_days_prior must be set first.
- Returns:
dict[str, int | bool] – A dict with these keys:
"num_departures"(int): history_length."num_timeframes"(int): the length of dcp_days_prior, minus one if its last entry is 0 (the day of departure)."store_priceable"(bool): whether the carrier has a default frat5.
- Raises:
ValueError – If dcp_days_prior is not set.
- get_spill_counters()¶
Spill counters by first-choice booking class, like the PODS .SOT output.
For each customer choice, the simulation finds the customer’s first choice: the offer with the lowest generalized cost among those that were not ruled out for any reason other than availability. If that offer is from this carrier, the counters for its booking class record what the customer did instead. These are grand totals, kept since the carrier was created and including the burn period.
- Returns:
list[dict[str, int | str]] – One dict per first-choice booking class, with these keys:
"carrier"and"booking_class"."n_obs": the number of choices with this first choice."sameP_sameF": passengers who bought their first choice."sameP_diffF": passengers who bought another class on the same path."diffP_sameF_sameA": the same class on another path of the same carrier."diffP_sameF_diffA": the same class on another carrier’s path."diffP_diffF_sameA": another class and path, same carrier."diffP_diffF_diffA": another class, path and carrier."no_go": passengers who bought nothing.
- gt_available_seat_miles¶
Grand total available seat miles (ASM) after the burn period.
For every booking, each leg on the booked path adds its capacity times its distance. Because this is counted per booking rather than once per departure, it is not a true ASM count.
Unlike the per-sample counters, it is not reset between samples. Setting it requires a number.
- gt_cp_revenue¶
Grand total revenue from continuous pricing sales after the burn period.
Unlike the per-sample counters, it is not reset between samples. Setting it requires a number.
- gt_cp_sold¶
Grand total number of passengers sold through continuous pricing.
Only sales after the burn period count.
Unlike the per-sample counters, it is not reset between samples. Setting it requires an int.
- gt_demand¶
Grand total demand for this carrier.
It is meant to hold the demand generated over the run, but the core does not update it, so it stays at 0 unless it is set. Setting it requires a number.
- gt_revenue¶
Grand total revenue from this carrier’s sales after the burn period.
Unlike the per-sample counters, it is not reset between samples. Setting it requires a number.
- gt_revenue_passenger_miles¶
Grand total revenue passenger miles (RPM) after the burn period.
Each booking adds its number of passengers times the total distance of the path. Unlike the per-sample counters, it is not reset between samples. Setting it requires a number.
- gt_sold¶
Grand total number of passengers sold by this carrier after the burn period.
Unlike the per-sample counters, it is not reset between samples. Setting it requires an int.
- history_length¶
Number of past samples kept in the forecasting history.
The histories on this carrier’s buckets and path classes keep this many departures; get_history_def reports it as
"num_departures". The default is 26. Setting it requires a non-negative int.
- load_factor_curve¶
Load factor curve for the load factor threshold RM system (deprecated).
This was an experiment with an RM control based on load factors. It can hold any object; deleting it sets it to None.
- metadata¶
A dict for storing arbitrary metadata on the carrier.
Reading it creates an empty dict if there is none, and returns the same dict each time, so changes made to it are kept. Setting it requires a dict, which is stored as is (not copied). Setting it to None, or deleting it, clears it.
- name¶
Name of the carrier, usually its code such as
"AL1"or"DL".Legs, paths and fares refer to their carrier by this name. Read-only; it is set when the Carrier is constructed.
- num_objects¶
Number of Carrier objects currently allocated.
This was used for memory leak detection. Read-only.
- proration_rule¶
How the revenue of a connecting itinerary is split across its legs.
"distance"(the default): in proportion to each leg’s distance."sqrt_distance": in proportion to the square root of each leg’s distance."off": each leg is credited with the full price.
If the legs have no distance, the revenue is split evenly. The rule only applies when the simulation has revenue proration turned on. Setting it requires one of these strings;
"disabled"is accepted as another name for"off".
- raw_bid_price_trace()¶
Statistics of this carrier’s leg bid prices by day before departure.
Each day that the simulation records statistics after the burn period (every day, including DCPs; see
SimulationEngine.record_daily_statistics), the leg-level bid price (for one seat) of every leg the carrier operates is added to the statistics for that day. Legs that are full are included in the first set of statistics but left out of thesome_capset.- Returns:
dict[int, dict[str, float]] – Keyed by days prior to departure. Each value is a dict with these keys:
"bid_price_mean"and"bid_price_stdev": the mean and sample standard deviation of all the bid prices."some_cap_bid_price_mean"and"some_cap_bid_price_stdev": the same, for legs with seats left."fraction_some_cap": the fraction of the observations with seats left, and"fraction_zero_cap", the fraction without.
- raw_bookings_by_day()¶
Cumulative bookings by fare class by day before departure.
Each day that the simulation records statistics after the burn period (every day, including DCPs; see
SimulationEngine.record_daily_statistics), each of this carrier’s fares adds its sales so far in the sample to the total for its booking class and that day. The totals are summed over the samples, so dividing by the number of samples gives the average bookings on hand on each day.- Returns:
dict[str, dict[int, int]] – Keyed by booking class, then by days prior to departure.
- raw_bookings_by_segment_fare_dcp()¶
Bookings by customer segment, fare class and DCP.
Each booking after the burn period adds its passengers to the total for the demand’s segment, the booking class the sale was recorded in (see cp_record), and the most recent DCP, so each total counts the bookings made in one timeframe. The totals are summed over the samples in the current trial, and are cleared when the trial counters are reset.
- Returns:
dict[str, dict[str, dict[int, int]]] – Keyed by segment (such as
"business"), then booking class, then the days prior to departure of the DCP that started the timeframe.
- raw_displacement_cost_trace()¶
Statistics of this carrier’s leg displacement costs at each DCP.
At each DCP after the burn period, the displacement of every leg the carrier operates is added to the statistics for that DCP.
- Returns:
dict[int, dict[str, float]] – Keyed by the DCP’s days prior to departure. Each value is a dict with the keys
"displacement_mean"and"displacement_stdev"(the sample standard deviation).
- raw_fare_class_distribution()¶
Sales and revenue totals by fare class.
At the end of each sample after the burn period, each of this carrier’s fares adds its sales and revenue to the totals for its booking class and brand.
- Returns:
dict[str, dict] – Keyed by fare class: the booking class, or
"<booking_class>-<brand>"for a fare with a brand. Each value is a dict with the keys"booking_class"(str),"brand"(str, empty if none),"sold"(int) and"revenue"(float).
- raw_load_factor_distribution()¶
Count of this carrier’s leg departures by load factor.
At the end of each sample after the burn period, each of the carrier’s legs adds one to the entry for its load factor,
floor(100 * sold / capacity), limited to the range 0 to 100.- Returns:
numpy.ndarray – A new int32 array of shape (101,). Entry
iis the number of leg departures with a load factor ofipercent.
- raw_revenue_by_segment_fare_dcp()¶
Revenue by customer segment, fare class and DCP.
The same as raw_bookings_by_segment_fare_dcp, but each booking adds its price times its number of passengers.
- Returns:
dict[str, dict[str, dict[int, float]]] – Keyed by segment, then booking class, then the days prior to departure of the DCP that started the timeframe.
- reset_bid_price_trace()¶
Clear the statistics reported by raw_bid_price_trace.
- reset_displacement_cost_trace()¶
Clear the statistics reported by raw_displacement_cost_trace.
- revenue¶
Revenue from this carrier’s sales in the current sample.
Each booking adds its full price times the number of passengers; it is not prorated across the legs. Resetting the counters at the start of each sample sets it back to zero. Setting it requires a number.
- rm_sys¶
The RM system used by this carrier, or None.
The RM system runs as a daily callback that is attached to the Simulation and triggered through the regular callback process. This attribute is provided for convenience, so that the RM system can be found from the carrier. It can hold any object; deleting it sets it back to None.
- sold¶
Number of passengers sold by this carrier in the current sample.
Each booking counts toward the carrier that operates the first leg of the path. Resetting the counters at the start of each sample sets it back to zero. Setting it requires an int.
- sold_priceable¶
Number of the passengers in sold whose offer was priceable.
Priceable sales are used by Q forecasting. Resetting the counters at the start of each sample sets it back to zero. Setting it requires an int.
- store_q_history¶
Whether to store Q-equivalent history at each DCP, for Q forecasting.
When it is True, this carrier’s paths and legs use the Frat5 curve to turn their sales into Q-equivalent (priceable) demand and store it in their history. It is False by default, which saves memory. Setting it uses the truth value of what is assigned.
- truncation_rule¶
When a timeframe counts as closed for a booking class in its history.
The history records whether each booking class was closed in each timeframe, so that forecasting can detruncate demand. With 1, a timeframe counts as closed if the class was closed at its beginning; with 2, at its end; with 3 (the default), at either. Paths use this rule when they reset their counters. Setting it requires an int that is 1, 2 or 3.