Relation matrices

A relation matrix pairs origins with destinations. Each cell represents one origin-to-destination combination and can hold a value, so together the cells describe every possible connection between a product’s stations, station categories, or zones, depending on the matrix type.

Relation matrices are used by fare calculation: the adapter looks up the cell for a ride’s origin and destination and uses the stored value—a connection or zone code—to determine the price.

A relation matrix is one way a fare adapter can determine a price. Depending on its configuration, an adapter can instead price from per-station tariff codes.

Types

A relation matrix has one type, which is fixed when it is created:

• Station-based fare matrix. Origins and destinations are individual stations. Use it when the price depends on the exact pair of stations.
• Station-category-based fare matrix. Origins and destinations are station categories, so all stations that share a category share a cell. This keeps the matrix small when stations group naturally.
• Zone-based fare matrix. Origins and destinations are zones. A ride is priced from the zone its origin falls into and the zone of its destination.

Cells and values

Each cell is one origin → destination pair and stores a value—a connection code or zone code. Cells are directional: the value for A → B can differ from the value for B → A, and each origin-destination pair appears at most once in a matrix.

A fare adapter reads the value for a ride’s origin and destination and translates it into a price. For a zone-based matrix, the code is matched to a base price in the product’s fare adapter configuration (its zone-code base-price elements).

Completeness

A matrix is complete when every origin-destination combination has a cell; if any pair is missing, the matrix is incomplete.

For a zone-based matrix that a product uses for pricing, every station must also fall within one of the zones the matrix references. Stations that fall outside those zones are reported as uncovered and can’t be priced.

The product’s current fare matrix

A product designates one relation matrix as its current fare matrix—the matrix used to price its rides. If a product needs a fare matrix but none is set, or the current one is incomplete or leaves stations uncovered, a product validation reports it.

For creating and managing relation matrices in the UI, see Relation matrices in Control Center.