Fare

class passengersim.core.Fare

Bases: object

A 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_restriction

Add a numbered fare restriction to this fare.

adjust_price

Set the fare's adjusted price, and record it for a DCP.

get_adjusted_by_dcp

Get the average adjusted price recorded for a DCP.

get_restrictions

Get the numbered fare restrictions on this fare.

get_revenue_by_segment

Get the revenue realized on this fare from one demand segment.

get_sales_by_dcp

Get this fare's accumulated sales as of a DCP.

get_sales_by_dcp2

Get the seats sold on this fare in one timeframe of the current sample.

get_sales_by_segment

Get the seats sold on this fare to one demand segment.

num_restrictions

Get the number of numbered fare restrictions on this fare.

set_sales_by_dcp

Overwrite this fare's accumulated sales for a DCP.

set_sales_by_dcp2

Overwrite the seats sold on this fare in one timeframe of the current sample.

Attributes

adjusted_price

The fare's adjusted price, for fare adjustment methods such as MR or KI.

adv_purch

Advance purchase restriction, in days before departure.

booking_class

The fare's booking class, any string such as "Y0" or "Q".

brand

The fare's brand, any string such as "basic" or "premium".

cabin

The cabin the fare is sold from, typically "F", "C" or "Y".

carrier

The carrier that sells this fare, or None if it has none.

carrier_name

The code of the carrier that sells this fare.

category

An arbitrary label given when the fare is created.

cp_revenue

Revenue from continuous pricing sales of this fare, in the current sample.

cp_sold

Number of seats sold on this fare through continuous pricing, in the current sample.

dest

Destination airport code.

fare_id

Unique integer ID for the fare.

gt_cp_revenue

Grand total of continuous pricing revenue, over all samples after burn-in.

gt_cp_sold

Grand total of seats sold through continuous pricing, over all samples after burn-in.

gt_revenue

Grand total revenue from this fare, over all samples after burn-in.

gt_sold

Grand total of seats sold on this fare, over all samples after burn-in.

min_stay

Minimum stay, in days.

orig

Origin airport code.

price

The fare's price.

price_lower_bound

The lowest price continuous pricing may charge for this fare.

price_upper_bound

The highest price continuous pricing may charge for this fare.

revenue

Revenue from this fare in the current sample.

revenue_by_segment

Revenue realized on this fare in the current sample, by demand segment.

sales_by_segment

Seats sold on this fare in the current sample, by demand segment.

saturday_night_required

Whether the fare requires a Saturday night stay.

sold

Number of seats sold on this fare in the current sample.

sold_business

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 * price when 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.