$projectbrief

$searchbox

Users Guide

Introduction

The SimFQT library contains classes for fare rule management. This document does not cover all the aspects of the SimFQT library. It does however explain the most important things you need to know in order to start using SimFQT.

Get Started

Get the SimFQT library

Clone locally the full Git project:

cd ~
mkdir -p dev/sim
cd ~/dev/sim
git clone git://simfqt.git.sourceforge.net/gitroot/simfqt/simfqt simfqtgit
cd simfqtgit
git checkout trunk

Build the SimFQT project

Link with StdAir, create the distribution package (say, 0.5.0) and compile using the following commands:

cd ~/dev/sim/simfqtgit
rm -rf build && mkdir -p build
cd build
cmake -DCMAKE_INSTALL_PREFIX=~/dev/deliveries/simfqt-0.5.0 \
 -DWITH_STDAIR_PREFIX=~/dev/deliveries/stdair-stable \
 -DCMAKE_BUILD_TYPE:STRING=Debug -DINSTALL_DOC:BOOL=ON ..
make

Run the Tests

After building the SimFQT project, the following commands run the tests:

cd ~/dev/sim/simfqtgit
cd build
make check

As a result, you should obtain a similar report:

[  0%] Built target hdr_cfg_simfqt
[ 90%] Built target simfqtlib
[100%] Built target FQTTestSuitetst
Test project /home/localoriuser/dev/sim/simfqt/simfqtgit/build/test/simfqt
    Start 1: FQTTestSuitetst
1/1 Test #1: FQTTestSuitetst ..................   Passed    0.15 sec

100% tests passed, 0 tests failed out of 1

Total Test time (real) =   0.16 sec
[100%] Built target check_simfqttst
[100%] Built target check

Install the SimFQT Project (Binaries, Documentation)

After the step Build the SimFQT project, to install the library and its header files, type:

cd ~/dev/sim/simfqtgit
cd build
make install

You can check that the executables and other required files have been copied into the given final directory:

cd ~dev/deliveries/simfqt-0.5.0

To generate the SimFQT project documentation, the commands are:

cd ~/dev/sim/simfqtgit
cd build
make doc

The SimFQT project documentation is available in the following formats: HTML, LaTeX. Those documents are available in a subdirectory:

cd ~/dev/sim/simfqtgit
cd build
cd doc

Input file of SimFQT Project

The fare input file structure should look like the following sample:

// Fares: fare ID; OriginCity; DestinationCity; TripType; DateRangeStart; DateRangeEnd; DepartureTimeRangeStart; DepartureTimeRangeEnd; POS; CabinCode; Channel; AdvancePurchase; SaturdayNight; ChangeFees; NonRefundable; MinimumStay; Price; nb Segments
// Segment: AirlineCode; Class; 
1; SIN; BKK; OW; 2010-01-15; 2010-12-31; 00:00; 23:59; SIN; Y; IN; 7; T; T; T; 3; 150.0; SQ; Y;
2; SIN; BKK; OW; 2010-01-15; 2010-12-31; 00:00; 23:59; BKK; Y; IN; 7; T; T; T; 3; 150.0; SQ; Y;
3; SIN; HND; OW; 2010-01-15; 2010-12-31; 00:00; 23:59; SIN; Y; IN; 7; T; T; T; 3; 150.0; SQ; Y;
4; SIN; HND; OW; 2010-01-15; 2010-12-31; 00:00; 23:59; HND; Y; IN; 7; T; T; T; 3; 150.0; SQ; Y;
5; SIN; HND; OW; 2010-01-15; 2010-12-31; 00:00; 23:59; ROW; Y; IN; 7; T; T; T; 3; 150.0; SQ; Y;
6; SIN; BKK; OW; 2010-01-15; 2010-12-31; 00:00; 23:59; SIN; Y; IF; 7; T; T; T; 3; 150.0; SQ; Y;
7; SIN; BKK; OW; 2010-01-15; 2010-12-31; 00:00; 23:59; BKK; Y; IF; 7; T; T; T; 3; 150.0; SQ; Y;
8; SIN; HND; OW; 2010-01-15; 2010-12-31; 00:00; 23:59; SIN; Y; IF; 7; T; T; T; 3; 150.0; SQ; Y;
9; SIN; HND; OW; 2010-01-15; 2010-12-31; 00:00; 23:59; HND; Y; IF; 7; T; T; T; 3; 150.0; SQ; Y;
10; SIN; HND; OW; 2010-01-15; 2010-12-31; 00:00; 23:59; ROW; Y; IF; 7; T; T; T; 3; 150.0; SQ; Y;

Each line represents a fare rule (see SIMFQT::FareRuleStruct), i.e., each line tells us the price a customer will be asked according to a lot of criteria such as:

the origin and destination of his travel (for instance from Singapour to Bangok in the first fare rule).
the type of his travel, i.e. one-way "OW" or round trip "RT".
the date and time he is willing to travel (each fare rule has a date range and a time range of validity).
the place where he is buying the ticket, i.e. the point of sale.
his prefered cabin.
the channel of the booking described by a two letters code: direct(D)/indirect(I) and online(N)/offline(F).
the date when he wants to buy the ticket, i.e. the advanced purchase required in number of days.
the saturday night stay option, i.e. is he staying a staturday night between his inbound trip and his outbound one? "T" stands for true and "F" stands for false.
the change fees option, i.e. are there fees to change his ticket? "T" stands for true and "F" stands for false.
the refundable criterion, i.e. is the ticket refundable? "T" stands for true and "F" stands for false.
the number of days he is willing to stay at the destination location (each fare rule has a minimum stay requirement in number of days).

Some fare input examples (including the example above named fare01.csv) are given in the stdair::samples directory.

The fare quoting BOM Tree

The Fare Quoting Business Object Model (BOM) tree is a structure permitting to store all the SIMFQT::FareRuleStruct objects of the simulation. That is why, the BOM tree is built parsing the fare file containing all the fare rules (as described in the previous section Input file of SimFQT Project). For convenience and first use of SimFQT (the input fare file building can be long and heavy), SimFQT API enables to build a small default BOM tree.

Build of the fare quoting BOM tree

First, a BOM root object (i.e., a root for all the classes in the project) is instantiated by the stdair::STDAIR_ServiceContext context object, when the stdair::STDAIR_Service is itself instantiated, that is to say during the instanciation of the simfqt::SIMFQT_Service object. The corresponding type (class) stdair::BomRoot is defined in the StdAir library.

Then, the BOM root can be either constructed thanks to the simfqt::SIMFQT_Service::buildSampleBom() method:

    void buildSampleBom();

or can be constructed using the fare dump file described above thanks to the simfqt::SIMFQT_Service::parseAndLoad (const stdair::Filename_T&) method:

    void parseAndLoad (const FareFilePath& iFareFilename);

Display of the fare quoting BOM tree

The fare quoting BOM tree can be displayed as done in the batches::simfqt.cpp program:

When the default bom tree is used (-b option of the main program simfqt.cpp), the fare quoting BOM tree display should look like:

===============================================================
BomRoot:  -- ROOT -- 
===============================================================
+++++++++++++++++++++++++++++++++++++++++++++++++
AirportPair: LHR, SYD
+++++++++++++++++++++++++++++++++++++++++++++++++
------------------------------------------
DatePeriod: [2011-Jan-15/2011-Dec-30]
------------------------------------------
******************************************
PosChannel: LHR,DN
******************************************
----------------------------------------
TimePeriod: 00:00:00-23:00:00
----------------------------------------
--------------------------------------
Fare-Features: RT -- 0-1-1-1-0
--------------------------------------
------------------------------------
AirlineClassList: BA Y
------------------------------------

Here the fare quoting BOM tree is just composed of one fare rule.

Structure of the fare quoting BOM tree

As one can guess looking at the BOM tree display above, the tree is constructed as follow:

At the top of the tree, we find a stdair::BomRoot object (i.e., a root for all the classes in the project).
Just under the root, at the first level, we find stdair::AirportPair objects (i.e., all the possible combinations of origin-destination). In the instance above, the only combination possible is from London to Sydney.
At the next level, under a particular stdair::AirportPair, we find all the date periods of the fare rules applicable for this origin-destination.
Then, under a particular stdair::DatePeriod, we find all the possible combinations of point-of-sale and channel applicable.
Under a particular stdair::PosChannel object, we have the correponding stdair::TimePeriod objects.
At the next-to-last level, we have stdair::FareFeatures objects, that is to say the trip type, the advanced purchase and stay duration required, ...
Finally we find the code of the airline publishing the current fare rule and the applicable class code.

The fare quoting procedure

The project SimFQT aims at fare quoting a list of travel solutions corresponding to a booking request. The fare quoter looks for all the fare rules matching a travel solution: when a fare rule matches, it creates a fare option object and adds this object to the current travel solution.

A few steps:

Instanciate the default booking request

A default booking request can be built using the simfqt::SIMFQT_Service::buildBookingRequest method:

    stdair::BookingRequestStruct buildBookingRequest(const bool isForCRS = false);

Instanciate the default travel solution list

In the following sample, a list of travel solutions is given as input/output parameter of the simfqt::SIMFQT_Service::buildSampleTravelSolutions method:

    void buildSampleTravelSolutions (stdair::TravelSolutionList_T&);

Fare Quoting a list of travel solution

Once a booking request, its correponding list of travel solutions and the fare Quote BOM tree are constructed, the main fonction of the module can be called:

    void quotePrices (const stdair::BookingRequestStruct&,
                      stdair::TravelSolutionList_T&);

For each travel solution of the list, the applicable fare rules are picked from the BOM tree (information such as the trip type or the booking request date are only contained into the booking request, that is why we need this object too).

Each chosen fare rule enables to create a fare option structure which is finally stored into the travel solution.

Error Messages

This section lists the fatal errors you may encounter when using SimFQT:

Fare input file not found

In this case, the output error message will be similar to:

terminate called after throwing an instance of 'SIMFQT::FareInputFileNotFoundException'
  what():  The fare input file '~/<YourFileName>.csv' does not exist or can not be read
Aborted

You can check:

the given path to your input file is correct.
the specified file name <YourFileName> is correct.
the file permission settings: is the file "readable"?.

Fare input file can not be parsed

This error message means that your input file has been opened but has not been fully read.

terminate called after throwing an instance of 'SIMFQT::FareFileParsingFailedException'
  what():  Parsing of fare input file: ~/<YourFileName>.csv failed
Aborted

Your input file structure is somehow incorrect. See the tutorial section How to build a fare input file?.

Error Messages for missing fare rules

If you obtain one of the error messages below and you are currently using your own input file, that means it has been fully read. However, at least one fare rule is missing to complete the fare quote.

If your error message is about a missing airport pair, you should obtain a similar report:
```
terminate called after throwing an instance of 'SIMFQT::AirportPairNotFoundException'
  what():  No available fare rule for the Origin-Destination pair: xxx, xxx
Aborted
```
You need to be sure that all your travel solutions have at least one corresponding origin-destination fare rule. It seems you should add one origin-destination (i.e., xxx, xxx) fare rule into your input file.

If your error message is about a missing fare rule for a flight date, you should obtain a similar report:
```
terminate called after throwing an instance of 'SIMFQT::FlightDateNotFoundException'
  what():  No available fare rule for the flight date x, xxxx-xxx-xx and to the Origin-Destination pair: xxx, xxx
Aborted
```
You need to be sure that all your travel solutions have at least one corresponding fare rule: same origin-destination and valid date range. It seems you should add/change a fare rule with the Origin-Destination pair: xxx, xxx: its date range must include the flight date xxxx-xxx-xx.

If your error message is about a missing fare rule for a point-of sale and/or channel, you should obtain a similar report:
```
terminate called after throwing an instance of 'SIMFQT::PosOrChannelNotFoundException'
  what():  No available fare rule for the point of sale xxx, the channel xx, the flight date x, xxxx-xxx-xx and the Origin-Destination pair: xxx, xxx
Aborted
```
You need to be sure that all your travel solutions have at least one corresponding fare rule: same origin-destination, valid date range, same point-of-sale and same channel. It seems you should add/change a fare rule to have the same combination as given in the output error message: "the point of sale xxx, the channel xx, the flight date x, xxxx-xxx-xx and the Origin-Destination pair: xxx, xxx".

If your error message is about a missing fare rule for a flight time, you should obtain a similar report:
```
terminate called after throwing an instance of 'SIMFQT::FlightTimeNotFoundException'
  what():  No available fare rule corresponding to 'xx; x, xxxx-xxx-xx; xxx, xxx; xx:xx' (parsed key) and to 'xxx, xx' (POS and channel)
Aborted
```
You need to be sure that all your travel solutions have at least one corresponding fare rule: same origin-destination, valid date range, same point-of-sale, same channel and valid time range. Add/change a fare rule if necessary.

If your error message is about a missing fare rule for some features, you should obtain a similar report:
```
terminate called after throwing an instance of 'SIMFQT::FeaturesNotFoundException'
  what():  No available fare rule corresponding to a trip type xx, to a stay duration of x, to a request date time of xxxx-xxx-xx xx:xx:xx, to 'xx; x, xxxx-xxx-xx; xxx, xxx; xx:xx' (parsed key) and to 'xxx, xx' (POS and channel), to 'xx; x, xxxx-xxx-xx; xxx, xxx; xx:xx' (parsed key) and to 'xxx, xx' (POS and channel)
Aborted
```
You need to be sure that all your travel solutions have at least one corresponding fare rule: same origin-destination, valid date range, same point-of-sale, same channel, valid time range and valid features. The features are:
- the trip type. Maybe you need both "OW" (One-Way) and "RT" (Round-trip) fare rules?
- the minimum stay duration. You can try "0" for this parameter to include all the possible stay durations.
- the advance purchase. You can try "0" for this parameter to include all the booking requests up to departure date.

If your error message is about a missing fare rule for an airline, you should obtain a similar report:

terminate called after throwing an instance of 'SIMFQT::AirlineNotFoundException'
  what():  No available fare rule corresponding to 'xx; x, xxxx-xxx-xx; xxx, xxx; xx:xx' (parsed key), to 'xxxx-xxx-xx xx:xx:xx, for (xxx, xx) xxx-xxx (xx) xxxx-xxx-xx (x days) xx:xx:xx x x x x x' (booking request) and to 'xxx, xx' (POS and channel)
Aborted

At least one of your fare rules is correct except that the fare into question must be defined by the airline operating (see the first two letters of the parsed key in the error message to know which airline is operating).