Market

class passengersim.core.Market

Bases: object

An origin-destination market: travel from one airport to another.

A market groups the demands, fares and paths between its origin and destination, and counts the sales made in it. Markets are directional, so BOS to LAX and LAX to BOS are separate markets. A simulation keys its markets by identifier, and creates any market it needs that was not added to it.

Parameters:
orig : str

Origin airport code.

dest : str

Destination airport code.

Raises:
  • TypeError – If orig or dest is not a str.

  • ValueError – If orig or dest contains "~", which is used in identifier.

Methods

__init__(*args, **kwargs)

add_demand

Add a demand to this market.

add_offer

Add a copy of an offer to this market's competitor offers.

get_carrier_share

Get a carrier's market share in this market.

get_carrier_sold

Number of passengers a carrier sold in this market in the current sample.

get_competitor_price

Get the lowest price seen for a carrier in this market.

set_carrier_share

Set a carrier's market share in this market.

set_competitor_price

Set the lowest price seen for a carrier in this market.

Attributes

demands

The demands in this market.

dest

Destination airport code.

distance

Great circle distance of this market, usually in nautical miles.

fares

The fares in this market.

identifier

Unique identifier for this market, "<orig>~<dest>", such as "BOS~LAX".

orig

Origin airport code.

paths

The paths (itineraries) that serve this market.

revenue

Revenue from this market in the current sample.

sold

Number of passengers sold in this market in the current sample.

add_demand()

Add a demand to this market.

Called with a single Demand as its only argument, it links that demand to this market, adds it to demands unless it is already there, and returns it. The demand must be for this market’s airports, and must not already belong to a different Market object.

Called any other way, it creates a new Demand from the arguments with market= this market, and returns it. The new demand takes this market’s airports, so any orig and dest given are ignored, and it is added to demands once.

Parameters:
demand : Demand, optional

An existing demand to add.

*args

Otherwise, arguments for the Demand constructor, such as segment and base_demand.

**kwargs

Otherwise, arguments for the Demand constructor, such as segment and base_demand.

Returns:

Demand – The demand that was added.

Raises:
  • ValueError – If an existing demand is for other airports, or already belongs to a different Market object.

  • TypeError, ValueError – If the Demand constructor rejects the arguments.

add_offer()

Add a copy of an offer to this market’s competitor offers.

Only used for unit testing. The copies are cleared when the counters are reset, and the core does not currently read them (the contextual optimizer uses the simulation’s own competitor offers). The offer must be given by position.

Parameters:
offer : Offer

The offer to copy.

Returns:

int – Always 0.

Raises:

TypeError – If offer is not an Offer.

demands

The demands in this market.

Each read returns a new list-like view: it has a length, can be indexed and iterated, and shows items added to the market later.

Read-only; add demands with add_demand, or by creating a Demand with market= this market.

dest

Destination airport code.

Read-only; it is set when the Market is created.

distance

Great circle distance of this market, usually in nautical miles.

The decision window model uses it. If it is still 0 (the default) when a customer chooses, the length of the market’s shortest path is used instead and stored here. When demands are added to a simulation, a market without a distance takes the distance of the demand’s own market, and two different nonzero distances raise ValueError. Setting it requires a non-negative number.

fares

The fares in this market.

Each read returns a new list-like view: it has a length, can be indexed and iterated, and shows items added to the market later.

Read-only; the simulation adds each fare to its market when the fare is added to the simulation.

get_carrier_share()

Get a carrier’s market share in this market.

See set_carrier_share.

Parameters:
carrier : str

The carrier code.

Returns:

float – The share set for the carrier.

Raises:
  • TypeError – If carrier is not a str.

  • KeyError – If no share has been set for the carrier.

get_carrier_sold()

Number of passengers a carrier sold in this market in the current sample.

Resetting the counters at the start of each sample clears these counts.

Parameters:
carrier : str

The carrier code.

Returns:

int – The number sold, or 0 if the carrier has sold nothing in this market.

Raises:

TypeError – If carrier is not a str.

get_competitor_price()

Get the lowest price seen for a carrier in this market.

See set_competitor_price.

Parameters:
carrier : str

The carrier code.

Returns:

float – The price set for the carrier.

Raises:
  • TypeError – If carrier is not a str.

  • IndexError – If no price has been set for the carrier.

identifier

Unique identifier for this market, "<orig>~<dest>", such as "BOS~LAX".

The simulation keys its markets by this. Read-only.

orig

Origin airport code.

Read-only; it is set when the Market is created.

paths

The paths (itineraries) that serve this market.

Each read returns a new list-like view: it has a length, can be indexed and iterated, and shows items added to the market later.

Read-only; the simulation adds paths to their market as they are added or built.

revenue

Revenue from this market in the current sample.

Each booking adds its price times its number of passengers. Resetting the counters at the start of each sample sets it back to zero. Setting it requires a non-negative number.

set_carrier_share()

Set a carrier’s market share in this market.

Market shares model data an airline can buy or collect about a market, such as MIDT or DOT data. The core stores them for RM code to read with get_carrier_share, but does not use them itself. Setting a carrier again replaces its share, and the value is not checked.

Parameters:
carrier : str

The carrier code.

share : float

The carrier’s market share.

Returns:

int – Always 0.

Raises:

TypeError – If carrier is not a str or share is not a number.

set_competitor_price()

Set the lowest price seen for a carrier in this market.

These prices model web shopping data on competitors’ fares. The core stores them for RM code to read with get_competitor_price, but does not use them itself. Setting a carrier again replaces its price.

Parameters:
carrier : str

The carrier code.

price : float

The carrier’s lowest price.

Returns:

int – Always 0.

Raises:

TypeError – If carrier is not a str or price is not a number.

sold

Number of passengers sold in this market in the current sample.

Each booking adds its passengers. Resetting the counters at the start of each sample sets it back to zero. Setting it requires a non-negative int.