Carrier

class passengersim.core.Carrier

Bases: object

An 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_ancillary

Add an ancillary that this carrier offers.

add_carrier_history

Add or replace one sample's entry in the carrier history.

add_customer_model

Add a customer model, for the "OPT" continuous pricing algorithm.

add_frat5_mkt

Set the Frat5 curve to use for one O&D market.

get_ancillary_by_index

Get one of this carrier's ancillaries by position.

get_ancillary_price

Get the price of one of this carrier's ancillaries, by code.

get_ancillary_sold

Get the number sold of one of this carrier's ancillaries, by code.

get_carrier_history

This carrier's sales totals for each sample.

get_forecast_accuracy

Forecast accuracy statistics, as a list of dictionaries.

get_frat5_mkt

Get the Frat5 curve used for an O&D market.

get_history_def

The history definition used to set up this carrier's histories.

get_spill_counters

Spill counters by first-choice booking class, like the PODS .SOT output.

raw_bid_price_trace

Statistics of this carrier's leg bid prices by day before departure.

raw_bookings_by_day

Cumulative bookings by fare class by day before departure.

raw_bookings_by_segment_fare_dcp

Bookings by customer segment, fare class and DCP.

raw_displacement_cost_trace

Statistics of this carrier's leg displacement costs at each DCP.

raw_fare_class_distribution

Sales and revenue totals by fare class.

raw_load_factor_distribution

Count of this carrier's leg departures by load factor.

raw_revenue_by_segment_fare_dcp

Revenue by customer segment, fare class and DCP.

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.

Attributes

ancillaries

An iterator over the ancillaries added with add_ancillary.

brand_preference

Brand preference multiplier for this carrier.

cabin_ordering

Ordering of cabin types on this carrier, from best to worst.

control

The RM control technique that decides which booking classes are available.

cp_algorithm

The continuous pricing (CP) algorithm, or "None" if CP is off.

cp_elasticity

Settings for guessing customers' price elasticity in "CBC" pricing.

cp_markets

Which markets the "OPT" continuous pricing optimizer works on.

cp_quantize

For continuous pricing, the step that prices would be rounded to.

cp_record

Which booking class a continuous pricing sale is recorded in.

cp_record_highest_closed_as_open

Whether to record the highest closed path class as open in its history.

cp_scale

Multiplier on the continuous pricing markup.

current_tf_index

Index of the current timeframe for this carrier.

dcp_days_prior

Days prior to departure of each DCP, which is when each timeframe starts.

decision_price_rule

Which price a path class uses as its decision price.

default_booking_classes

Default booking classes for legs and paths on this carrier.

frat5

The carrier's default Frat5 curve, or None if it has none.

gt_available_seat_miles

Grand total available seat miles (ASM) after the burn period.

gt_cp_revenue

Grand total revenue from continuous pricing sales after the burn period.

gt_cp_sold

Grand total number of passengers sold through continuous pricing.

gt_demand

Grand total demand for this carrier.

gt_revenue

Grand total revenue from this carrier's sales after the burn period.

gt_revenue_passenger_miles

Grand total revenue passenger miles (RPM) after the burn period.

gt_sold

Grand total number of passengers sold by this carrier after the burn period.

history_length

Number of past samples kept in the forecasting history.

load_factor_curve

Load factor curve for the load factor threshold RM system (deprecated).

metadata

A dict for storing arbitrary metadata on the carrier.

name

Name of the carrier, usually its code such as "AL1" or "DL".

num_objects

Number of Carrier objects currently allocated.

proration_rule

How the revenue of a connecting itinerary is split across its legs.

revenue

Revenue from this carrier's sales in the current sample.

rm_sys

The RM system used by this carrier, or None.

sold

Number of passengers sold by this carrier in the current sample.

sold_priceable

Number of the passengers in sold whose offer was priceable.

store_q_history

Whether to store Q-equivalent history at each DCP, for Q forecasting.

truncation_rule

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 uses multiplier as 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 the some_cap set.

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 i is the number of leg departures with a load factor of i percent.

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.