Fare¶
- class passengersim.core.Fare¶
Bases:
objectA fare: a price at which a carrier sells a booking class between two airports.
The simulation offers fares to customers, who choose among them. On each leg of a path, a fare is sold from the buckets with the same booking class (in the fare’s cabin). A fare can carry restrictions (an advance purchase requirement, a minimum stay, a Saturday night stay, and numbered fare restrictions that the choice model turns into disutilities). It also counts its own sales and revenue.
- Parameters:
- carrier : Carrier or None
The carrier that sells this fare.
- orig : str
Origin airport code.
- dest : str
Destination airport code.
- booking_class : str
The booking class, any string such as
"Y0"or"Q".- price : float
The price the customer pays. It is also the starting adjusted_price. Unlike the price property, the constructor does not reject negative values, and it leaves price_lower_bound and price_upper_bound at 0.
- category : str, optional
An arbitrary label. The default is an empty string.
- advance_purchase : int, default 0
Advance purchase restriction, in days; see adv_purch. Unlike the property, the constructor does not reject negative values.
- Raises:
TypeError – If carrier is neither a Carrier nor None, or a string argument is not a str.
Methods
__init__(*args, **kwargs)Add a numbered fare restriction to this fare.
Set the fare's adjusted price, and record it for a DCP.
Get the average adjusted price recorded for a DCP.
Get the numbered fare restrictions on this fare.
Get the revenue realized on this fare from one demand segment.
Get this fare's accumulated sales as of a DCP.
Get the seats sold on this fare in one timeframe of the current sample.
Get the seats sold on this fare to one demand segment.
Get the number of numbered fare restrictions on this fare.
Overwrite this fare's accumulated sales for a DCP.
Overwrite the seats sold on this fare in one timeframe of the current sample.
Attributes
The fare's adjusted price, for fare adjustment methods such as MR or KI.
Advance purchase restriction, in days before departure.
The fare's booking class, any string such as
"Y0"or"Q".The fare's brand, any string such as
"basic"or"premium".The cabin the fare is sold from, typically
"F","C"or"Y".The carrier that sells this fare, or None if it has none.
The code of the carrier that sells this fare.
An arbitrary label given when the fare is created.
Revenue from continuous pricing sales of this fare, in the current sample.
Number of seats sold on this fare through continuous pricing, in the current sample.
Destination airport code.
Unique integer ID for the fare.
Grand total of continuous pricing revenue, over all samples after burn-in.
Grand total of seats sold through continuous pricing, over all samples after burn-in.
Grand total revenue from this fare, over all samples after burn-in.
Grand total of seats sold on this fare, over all samples after burn-in.
Minimum stay, in days.
Origin airport code.
The fare's price.
The lowest price continuous pricing may charge for this fare.
The highest price continuous pricing may charge for this fare.
Revenue from this fare in the current sample.
Revenue realized on this fare in the current sample, by demand segment.
Seats sold on this fare in the current sample, by demand segment.
Whether the fare requires a Saturday night stay.
Number of seats sold on this fare in the current sample.
Number of seats sold on this fare to the
"business"demand segment.- add_restriction()¶
Add a numbered fare restriction to this fare.
Restrictions are numbered from 1 to 32 and stored as bit flags, so adding the same one twice has no further effect. In the choice model, each restriction number k on a fare adds the customer’s drawn disutility for the model’s k-th fare restriction to the utility of offers using the fare. Restriction numbers beyond the choice model’s list of restriction disutilities are ignored.
- Parameters:
- restriction_num : int
The restriction number, from 1 to 32. This is positional-only.
- Raises:
IndexError – If restriction_num is not between 1 and 32.
- adjust_price()¶
Set the fare’s adjusted price, and record it for a DCP.
This sets adjusted_price. It also adds the value to a running total for dcp_index, so get_adjusted_by_dcp can report the average adjusted price set at that DCP. The core itself does not use the adjusted price.
- Parameters:
- dcp_index : int
The DCP to record the adjusted price under. It is only used for tracking and reporting. This is positional-only.
- adjusted_price : float
The new adjusted price. This is positional-only.
- Returns:
int – The adjusted price, truncated to an int.
- Raises:
ValueError – If adjusted_price is negative.
- adjusted_price¶
The fare’s adjusted price, for fare adjustment methods such as MR or KI.
It starts equal to price, and is changed by adjust_price or reset by setting price. The core itself does not use it; it is there for RM code. Read-only; use adjust_price to change it.
- adv_purch¶
Advance purchase restriction, in days before departure.
A customer who arrives fewer than this many days before departure cannot buy the fare, unless the simulation disables advance purchase rules. 0 means there is no restriction. When the fare is added to a simulation, a nonzero value must match the days prior of one of the DCPs, and that DCP becomes _adv_purch_dcp_index. Setting it requires a non-negative int.
- booking_class¶
The fare’s booking class, any string such as
"Y0"or"Q".On each leg of a path, the fare is sold from the buckets with this booking class (in the fare’s cabin). Read-only; it is set when the Fare is constructed.
- brand¶
The fare’s brand, any string such as
"basic"or"premium".The core uses it together with booking_class to group the carrier’s fare sales by class and brand. Setting it requires a str.
- cabin¶
The cabin the fare is sold from, typically
"F","C"or"Y".On each leg of a path, the fare is sold from the buckets with its booking class in this cabin. It is an empty string when cabins are not used. Setting it requires a str.
- carrier¶
The carrier that sells this fare, or None if it has none.
Read-only; it is set when the Fare is constructed.
- carrier_name¶
The code of the carrier that sells this fare.
This is
"Undefined-Carrier"if the fare has no carrier. Read-only.
- category¶
An arbitrary label given when the fare is created.
The core does not use it. Read-only.
- cp_revenue¶
Revenue from continuous pricing sales of this fare, in the current sample.
It is reset at the start of each sample. Setting it requires a non-negative number.
- cp_sold¶
Number of seats sold on this fare through continuous pricing, in the current sample.
It is reset at the start of each sample. Setting it requires a non-negative int.
- dest¶
Destination airport code.
Read-only; it is set when the Fare is constructed.
- fare_id¶
Unique integer ID for the fare.
It is assigned automatically, in creation order, when the fare is created. Read-only.
- get_adjusted_by_dcp()¶
Get the average adjusted price recorded for a DCP.
This is the average of all the values passed to adjust_price with this dcp_index. These are never reset, so the average covers every sample so far.
- Parameters:
- dcp_index : int
The DCP, as passed to adjust_price. This is positional-only.
- Returns:
float – The average adjusted price, or 0.0 if none was recorded for dcp_index.
- get_restrictions()¶
Get the numbered fare restrictions on this fare.
- Returns:
tuple of int – The restriction numbers, from 1 to 32, in increasing order.
- get_revenue_by_segment()¶
Get the revenue realized on this fare from one demand segment.
- Parameters:
- segment : str
The demand segment name. This is positional-only.
- Returns:
float – The revenue from that segment in the current sample.
- Raises:
IndexError – If the fare has no sales to segment in the current sample.
TypeError – If segment is not a str.
- get_sales_by_dcp()¶
Get this fare’s accumulated sales as of a DCP.
When the simulation’s database writer runs at a DCP, it adds the fare’s sales so far in the sample (sold) to a running total for that DCP. This happens for every sample after burn-in, and the totals are reset at the start of each trial. This returns that total.
- Parameters:
- dcp : int
The DCP, given as days before departure. This is positional-only.
- Returns:
int – The accumulated sales for that DCP, or 0 if there are none.
- get_sales_by_dcp2()¶
Get the seats sold on this fare in one timeframe of the current sample.
Each sale is recorded under the most recent DCP the simulation has passed, so this is the number sold after that DCP and before the next one. The counts are reset at the start of each sample.
- Parameters:
- dcp : int
The DCP at the start of the timeframe, given as days before departure. This is positional-only.
- Returns:
int – The seats sold in that timeframe, or 0 if there are none.
- get_sales_by_segment()¶
Get the seats sold on this fare to one demand segment.
- Parameters:
- segment : str
The demand segment name. This is positional-only.
- Returns:
int – The seats sold to that segment in the current sample.
- Raises:
IndexError – If the fare has no sales to segment in the current sample.
TypeError – If segment is not a str.
- gt_cp_revenue¶
Grand total of continuous pricing revenue, over all samples after burn-in.
Setting it requires a non-negative number.
- gt_cp_sold¶
Grand total of seats sold through continuous pricing, over all samples after burn-in.
Setting it requires a non-negative int.
- gt_revenue¶
Grand total revenue from this fare, over all samples after burn-in.
Like revenue, this is the realized revenue, which is not necessarily
gt_sold * price, especially with class-based continuous pricing. Setting it requires a non-negative number.
- gt_sold¶
Grand total of seats sold on this fare, over all samples after burn-in.
Setting it requires a non-negative int.
- min_stay¶
Minimum stay, in days.
A customer whose trip is shorter than this cannot buy the fare. 0 means there is no minimum. Setting it requires a non-negative int.
- num_restrictions()¶
Get the number of numbered fare restrictions on this fare.
- Returns:
int – How many restrictions have been added with add_restriction.
- orig¶
Origin airport code.
Read-only; it is set when the Fare is constructed.
- price¶
The fare’s price.
This is what the customer pays and what is counted as revenue, unless continuous pricing changes the price actually charged. Setting it requires a non-negative number. It also resets adjusted_price, price_lower_bound and price_upper_bound to the new price, so set the price before the bounds.
- price_lower_bound¶
The lowest price continuous pricing may charge for this fare.
See price_upper_bound. It is 0 when the fare is created, and setting price resets it to the price. Setting it requires a non-negative number that is at most price (ValueError otherwise).
- price_upper_bound¶
The highest price continuous pricing may charge for this fare.
A continuous pricing quote is clamped between price_lower_bound and this bound. It is 0 when the fare is created, and setting price resets it to the price. Setting it requires a non-negative number that is at least price (ValueError otherwise).
- revenue¶
Revenue from this fare in the current sample.
This is the revenue actually realized, so it is not necessarily
sold * pricewhen continuous pricing is used. It is reset at the start of each sample. Read-only.
- revenue_by_segment¶
Revenue realized on this fare in the current sample, by demand segment.
A new dictionary is returned on each access. The values add up to revenue. Segments with no sales in the current sample may be absent. Read-only.
- sales_by_segment¶
Seats sold on this fare in the current sample, by demand segment.
A new dictionary is returned on each access. Segments with no sales in the current sample may be absent. Read-only.
- saturday_night_required¶
Whether the fare requires a Saturday night stay.
If True, only customers whose trip includes a Saturday night can buy the fare. Setting it accepts any value and uses its truth value.
- set_sales_by_dcp()¶
Overwrite this fare’s accumulated sales for a DCP.
See get_sales_by_dcp. Only a DCP that already has a total can be set.
- Parameters:
- dcp : int
The DCP, given as days before departure. This is positional-only.
- sales : int
The new total. This is positional-only.
- Returns:
int – The value of sales.
- Raises:
IndexError – If dcp has no accumulated total yet.
- set_sales_by_dcp2()¶
Overwrite the seats sold on this fare in one timeframe of the current sample.
See get_sales_by_dcp2. Unlike set_sales_by_dcp, this creates the entry if it does not exist yet.
- Parameters:
- dcp : int
The DCP at the start of the timeframe, given as days before departure. This is positional-only.
- sales : int
The new count. This is positional-only.
- Returns:
int – Always 0.
- sold¶
Number of seats sold on this fare in the current sample.
It is reset at the start of each sample. Setting it requires a non-negative int.
- sold_business¶
Number of seats sold on this fare to the
"business"demand segment.This is for the current sample, and is the same as
get_sales_by_segment("business")except that it is 0 when there were no such sales. Deprecated; use sales_by_segment instead. Read-only.