Tutorials

This tutorial section will give you step by step instructions and exemples on how to use all the modules.

The first mandatory tutorial is the getting started procedure you should have already followed at this step. Once the needed Travel Simulator packages are correctly installed, the following tutorials are what you need!

For general information and a technical description of the different modules head to the user manual page once you are finished here.

Also for focused information on precise problems make sure you have a look at the F.A.Q.

How can I build correct simulation inputs?

There are two ways of giving your simulation inputs: using directly a Business Object Model tree (now referred to as the BOM tree) or parsing simulation input files to automatically build the BOM tree. The BOM tree contains exactly the same information as those files: airlines, schedules, fares, yield rules, ...

There are many ways of giving your simulation inputs:

using the default BOM tree.
creating your own BOM tree.
using existing input files.
creating your own input files.

How can I use the default BOM tree?

To familiarize yourself with the default BOM tree, load the StdAir batch directory (for instance, if you are working within the metasim environment):

cd ~/metasimgit/workspace/build/stdair/stdair/

Then launch it with the default BOM tree option '-b':

./stdair -b

If you have a look at the log file (called after the launched batch), you can find the following BOM tree structure, in this exact order :

a BOM tree root at the top of the tree
some inventory objects at level one
each inventory (characterised by an airline code) contains one or more flight dates (i.e. a flight number and an associated date)
each flight date is composed of leg date and segment date objects
each leg and segment contains associated cabins
each segment cabin is composed of at least one fare family, whcih is in turn composed of one or more booking classes

To discover the second part of the BOM tree structure, you can launch SimFQT for instance:

cd ~/metasimgit/workspace/build/simfqt/simfqt/
./simfqt -b

This batch is an interactive one, try 'help' to obtain all the existing commands, and then 'list' to discover all the O&Ds and departure dates for which some fare rules are applicable.
Then 'quit' the interactive batch and open the log file named 'simfqt.log'. At the beginning of the file, we find the BOM root display:

a BOM tree root at the top of the tree
at level one we find some airport pairs (representing the origin and the destination of existing travels)
at the lower level, we have date period, followed by point-of sale and channel options, followed by time period
then we find the fares applicable and the corresponding options (saturday night, change fees, refundable criterion)
finally, we have the airline codes and booking classes for which each fare rule is applicable

How can I create my own BOM tree?

To understand how to create your own BOM tree, do not hesitate to have a look into the C++ file called CmdBomManager.cpp located in the following directory:

cd ~/metasimgit/workspace/src/stdair/stdair/command/

Let us create our own BOM tree now.
First, a BOM root object (i.e. a root for all the classes in the project) must be instantiated. This is done by the stdair::STDAIR_ServiceContext context object, when the stdair::STDAIR_Service is itself instantiated. The standard procedure is illustrated below:

const BomRootKey lBomRootKey ("My first Bom Root");
BomRoot& lBomRoot = FacBom<BomRoot>::instance().create(lBomRootKey);

An airline inventory object can then be instantiated.
Let us create the "BA" airline code (corresponding to British Airways airline):

const AirlineCode_T lAirlineCodeBA ("BA");

That is, an object (let us name it lInventoryKeyBA) of type (class) stdair::InventoryKey has first to be instantiated.

const InventoryKey lInventoryKeyBA (lAirlineCodeBA);

Thanks to that key, an airline inventory object, i.e. of type (class) stdair::Inventory, can be instantiated. Let us name that airline inventory object lBAInv.

Inventory& lBAInv = FacBom<Inventory>::instance().create(lInventoryKeyBA);

Then, we must create the link parent/child to attach those two objects as defined in the BOM tree structure. That operation is as simple as using the following methods:

FacBomManager::addToListAndMap (lBomRoot, lBAInv);
FacBomManager::linkWithParent (lBomRoot, lBAInv);

Another airline inventory object, corresponding to the AF (Air France) company, can be instantiated the same way:

const AirlineCode_T lAirlineCodeAF ("AF");
const InventoryKey lAFKey (lAirlineCodeAF);
Inventory& lAFInv = FacBom::instance().create (lAFKey);
FacBomManager::addToListAndMap (lBomRoot, lAFInv);
FacBomManager::linkWithParent (lBomRoot, lAFInv);

How can I use existing input files?

When running a batch with no option specified, predefined default files are parsed and used to construct the BOM tree.

How can I create my own input files?

In this tutorial, we are going to create our own input files one by one.
Please first read the simulation input files description to familiarize yourself with each type of file.

Then, follow the steps to build:

How can I familiarise myself with the simulation event queue?

The module in charge of the event queue management is SEvMgr.
To understand its main functionality, let's launch the sevmgr interactive batch named 'sevmgr'. Hardcoded events are already present in the default queue to make it easier to understand the simulation event management.

The display should look like (here, the date of the simulation world is the 21st of January 2010):

Log filename is: sevmgr.log
sevmgr P / 2010-Jan-21 00:00:00>

Try the 'display' command to learn more about the current event. The output should look like this:

2010-Jan-21 00:00:00, BreakPoint, 2010-Jan-21 00:00:00

Let's now have a look at the whole simulation queue using the 'list' command. There are three events to come, including two booking requests and a second break point (the first one was the first event of the queue):

2010-Jan-22 10:00:00, BookingRequest, At 2010-Jan-22 10:00:00, for (SIN, IN) SIN-BKK (RI) 2010-Jan-30 (7 days) 10:00:00 Eco 3 M 1000 100 1 50 1 50
2011-May-14 00:00:00, BreakPoint, 2011-May-14 00:00:00
2011-May-15 10:00:00, BookingRequest, At 2011-May-15 10:00:00, for (LHR, DN) LHR-SYD (RI) 2011-Jun-10 (7 days) 08:00:00 Eco 3 M 1000 100 0 30 0 50

The 'next' command plays the current event and pops the next one from the queue. This is exactly the simulation principle: the events in the queue will be popped and played one by one. The simulation will only stop when a break point is encountered which is the objective of the 'run' command.

How should I generate and insert my own booking requests in the event queue?

Now, the objective is to stop using default hard-coded events (see the tutorial How can I familiarise myself with the simulation event queue?) but to insert our own booking requests in the event queue. The module in charge of building and inserting booking requests in the queue is TraDemGen.

Load the TraDemGen batch directory (for instance, if you are working within the metasim environment):

cd ~/metasimgit/workspace/build/trademgen/trademgen/

When launching the trademgen interactive batch with no parameter, a default demand input file is parsed. This file can be found in the StdAir sample directory.

./trademgen

To see all the demand streams for which booking requests can be generated, try the command 'list_demand_stream'. You can check that you end up with the same demand streams as those defined in the input file. The output should look like:

List of demand streams
SIN-BKK 2012-Apr-30 Y
SIN-BKK 2012-May-07 Y
SIN-BKK 2012-May-14 Y
SIN-BKK 2012-May-21 Y
SIN-BKK 2012-May-28 Y
SIN-BKK 2012-Jun-04 Y
SIN-BKK 2012-Jun-11 Y
SIN-BKK 2012-Jun-18 Y
SIN-BKK 2012-Jun-25 Y
SIN-BKK 2012-Jul-02 Y
...

Then, the command 'list_event' will enable you to check that for now, the event list is empty:

List of events
EQ01
(0) 0/{11520,11520}

Let's now generate our first booking request for the first demand stream. The corresponding command is :

generate_next_br SIN-BKK 2012-Apr-30 Y

Let's now display again the event list ('list_event' command):

List of events
EQ01
(1) 0/{11520,11520}
2011-Jun-06 22:50:04.001000, BookingRequest, At 2011-Jun-06 22:50:04.001000, for (BKK, DN) SIN-BKK (RO) 2012-Apr-30 (5 days) 07:01:27 Y 1 G 185.452 55.6372 0 50

A booking request has been created: the corresponding traveller is making his request on the 6th of June 2011 and is wishing to travel on the 30th of April 2012 from Singapour to Bangkok in the Economy cabin (as expected from the demand stream key). The other parameters'values have been created using the distribution defined in the demand input file.

Let's now generate all the booking requests for this same demand stream:

generate_all_br SIN-BKK 2012-Apr-30 Y

The output display should look like:

339 more event(s) have been generated for the demand stream: 'SIN-BKK 2012-Apr-30 Y'.

Display again the event list to see all the stored booking requests.

Finally, to visualize the booking requests arrival pattern, 'quit' the interactive command line and launch a python dedicated script located in the tool directory:

./tools/trademgen_drawBookingArrivals -p trademgen.log

Do not hesitate to repeat the steps above using your own demand input file. Please, refer to the How can I build my own demand input file? tutorial first. Then launch the demand generation script with your demand file specified as input parameter:

./trademgen --input <your_demand_file.csv>

How can I perform my first fareQuote?

Let us say we want to simulate the Singapour airline flight number 11 from SIN to BKK every day of the 2011 year. Our first network rule looks like:

SQ; 11; 2011-01-01; 2011-12-31; 1111111; SIN; BKK; ...

Let us add some details about departure time, arrival time and elapsed flight (in this exact order):

SQ; 11; 2011-01-01; 2011-12-31; 1111111; SIN; BKK; 08:20; 11:00; 07:40; ...

We know that the aircraft is composed of only one Economy cabin 'Y' with 300 seats available.

SQ; 11; 2011-01-01; 2011-12-31; 1111111; SIN; BKK; 08:20; 11:00; 07:40; Y; 300; ...

The economy cabin is itself composed of 2 booking classes 'Y' and 'M':

SQ; 11; 2011-01-01; 2011-12-31; 1111111; SIN; BKK; 08:20; 11:00; 07:40; Y; 300; Y; YM; ...

We have two fare families '1' and '2'. The first one contains the 'Y' booking class and the second one the 'M' booking class:

SQ; 11; 2011-01-01; 2011-12-31; 1111111; SIN; BKK; 08:20; 11:00; 07:40; Y; 300; Y; YM; 1; ... Y; 2; ... M;

Because we take into account fare families here, we need to add a fare family disutility curve and a FRAT5 one for each fare family. Some instances are available in the frat5.csv and ffDisutility.csv files in the StdAir samples directory. We finally obtain our first network rule:

SQ; 11; 2011-01-01; 2011-12-31; 1111111; SIN; BKK; 08:20; 11:00; 07:40; Y; 300; Y; YM; 1;  F1; D1; Y; 2; F2; D2;

Now that we agreed on the flight to simulate, we need to generate the demand, that is to say the customers wishing to purchase seat(s) on the concerned flight.
This is the objective of the demand input file. This last one is organised around lines, each line representing a demand stream. Let us focus on the first demand stream:
we know we want to generate passengers wishing to travel from Singapour to Bangkok every day of the year 2011 (this matches exactly the Singapour flight numbered 11):

2011-01-01; 2011-12-31; 1111111; SIN; BKK; ...

Those passengers are wishing to travel in the Economy cabin 'Y', let us arbitrary decide that 70% of those passengers are located in Singapour when willing to purchase a ticket, 20% of them are in Bangkok and the remaining 10% elsewhere ('row' stands for the rest of the world):

2011-01-01; 2011-12-31; 1111111; SIN; BKK; SIN:0.7, BKK:0.2, row:0.1; ...

Let us now arbitrarily define the channel distribution:

2011-01-01; 2011-12-31; 1111111; SIN; BKK; SIN:0.7, BKK:0.2, row:0.1; DF:0.1, DN:0.3, IF:0.4, IN:0.2; ...

The sum of the channel distribution is as expected equal to 1. Let us now define the trip type:

2011-01-01; 2011-12-31; 1111111; SIN; BKK; SIN:0.7, BKK:0.2, row:0.1; DF:0.1, DN:0.3, IF:0.4, IN:0.2; RO:0.6, RI:0.2, OW:0.2; ...

For 60% of the passengers, the Singapour-Bangkok flight is the outbound flight of their trip, for 20% of them it is the inbound flight of their trip and for the last 10% it is just a one-way trip.
Then, we find the stay duration ditribution:

2011-01-01; 2011-12-31; 1111111; SIN; BKK; SIN:0.7, BKK:0.2, row:0.1; DF:0.1, DN:0.3, IF:0.4, IN:0.2; RO:0.6, RI:0.2, OW:0.2; 0:0.1, 1:0.1, 2:0.15, 3:0.15, 4:0.15, 5:0.35;...

35% of the passengers are staying at the destination location 5 days, 15% are only staying 4 days, ...
After that, we encounter the frequent flyer status (P=Platinum, G=Gold, S=Silver, M=Member, N=None) of the potential customers:

2011-01-01; 2011-12-31; 1111111; SIN; BKK; SIN:0.7, BKK:0.2, row:0.1; DF:0.1, DN:0.3, IF:0.4, IN:0.2; RO:0.6, RI:0.2, OW:0.2; 0:0.1, 1:0.1, 2:0.15, 3:0.15, 4:0.15, 5:0.35; P:0.01, G:0.05, S:0.15, M:0.3, N:0.49; ...

Next, we find restriction information:

2011-01-01; 2011-12-31; 1111111; SIN; BKK; SIN:0.7, BKK:0.2, row:0.1; DF:0.1, DN:0.3, IF:0.4, IN:0.2; RO:0.6, RI:0.2, OW:0.2; 0:0.1, 1:0.1, 2:0.15, 3:0.15, 4:0.15, 5:0.35; P:0.01, G:0.05, S:0.15, M:0.3, N:0.49; 0.5; 50; 06; 50; ...

50% of the passengers are accepting a restriction regarding the change fees whereas the other 50% are refusing such restriction (in the hard-restriction custumer choice model) or see this restriction
as a disutility value which is added to the actual fare (in the disutility customer choice model). Then we find the continuous cumulative distribution about preferred departure time:

2011-01-01; 2011-12-31; 1111111; SIN; BKK; SIN:0.7, BKK:0.2, row:0.1; DF:0.1, DN:0.3, IF:0.4, IN:0.2; RO:0.6, RI:0.2, OW:0.2; 0:0.1, 1:0.1, 2:0.15, 3:0.15, 4:0.15, 5:0.35; P:0.01, G:0.05, S:0.15, M:0.3, N:0.49; 0.5; 50; 06; 50; 06:0, 07:0.1, 09:0.3, 17:0.4, 19:0.8, 20:0.95, 22:1; ...

In a more explicit way, we are saying that no passenger is wishing to travel before 6 in the morning, 10% are wishing to travel before 7 am, 30% are wishing to leave before 9 am (so 20% are wishing to take off between 7 and 9 am), ... Let us now add information about the willingness-to-pay of such passengers: such passengers are at least ready to pay 200 (arbitrary currency) for their travel.

2011-01-01; 2011-12-31; 1111111; SIN; BKK; SIN:0.7, BKK:0.2, row:0.1; DF:0.1, DN:0.3, IF:0.4, IN:0.2; RO:0.6, RI:0.2, OW:0.2; 0:0.1, 1:0.1, 2:0.15, 3:0.15, 4:0.15, 5:0.35 P:0.01, G:0.05, S:0.15, M:0.3, N:0.49; 0.5; 50; 06; 50; 06:0, 07:0.1, 09:0.3, 17:0.4, 19:0.8, 20:0.95, 22:1; 200; ...

Let us add the value of time in the customer point of view: what is the cost if he leaves one hour later than his preferred departure time:

2011-01-01; 2011-12-31; 1111111; SIN; BKK; SIN:0.7, BKK:0.2, row:0.1; DF:0.1, DN:0.3, IF:0.4, IN:0.2; RO:0.6, RI:0.2, OW:0.2; 0:0.1, 1:0.1, 2:0.15, 3:0.15, 4:0.15, 5:0.35; P:0.01, G:0.05, S:0.15, M:0.3, N:0.49; 0.5; 50; 06; 50; 06:0, 07:0.1, 09:0.3, 17:0.4, 19:0.8, 20:0.95, 22:1; 200; 15:0, 60:1; ...

Let us now specify the arrival pattern of customers: 20% of them are making their request between one year and 40 days before departure, 60% of them have make their requests when we reach the date of 20 days before departure, ...:

2011-01-01; 2011-12-31; 1111111; SIN; BKK; SIN:0.7, BKK:0.2, row:0.1; DF:0.1, DN:0.3, IF:0.4, IN:0.2; RO:0.6, RI:0.2, OW:0.2; 0:0.1, 1:0.1, 2:0.15, 3:0.15, 4:0.15, 5:0.35; P:0.01, G:0.05, S:0.15, M:0.3, N:0.49; 0.5; 50; 06; 50; 06:0, 07:0.1, 09:0.3, 17:0.4, 19:0.8, 20:0.95, 22:1; 200; 15:0, 60:1; 330:0, 40:0.2, 20:0.6, 1:1; ...

Finally, we give the distribution of the number of requests: let us take here a normal law with mean 100 and standard deviation 10 (specified as N, 100.0, 10.0):

2011-01-01; 2011-12-31; 1111111; SIN; BKK; SIN:0.7, BKK:0.2, row:0.1; DF:0.1, DN:0.3, IF:0.4, IN:0.2; RO:0.6, RI:0.2, OW:0.2; 0:0.1, 1:0.1, 2:0.15, 3:0.15, 4:0.15, 5:0.35; P:0.01, G:0.05, S:0.15, M:0.3, N:0.49; 0.5; 50; 06; 50; 06:0, 07:0.1, 09:0.3, 17:0.4, 19:0.8, 20:0.95, 22:1; 200; 15:0, 60:1; 330:0, 40:0.2, 20:0.6, 1:1; N, 100.0, 10.0;

If we refer to the schedule input build, we deduce we need one or more fare rules:

whose origin-destination couple is "SIN, BKK"
valid for every day in the 2011 year
valid for a flight departure time of 8:20 in the morning
valid for the operating airline "SQ", which is likely to be the pricing airline

We can deduce a part of our first fare rule:

1; SIN; BKK; ??; 2011-01-01; 2011-12-31; 00:00; 23:59; ???; ?; ??; ?; ?; ?; ?; ?; ????; SQ; ?;

In this case, we are not filtering requests according to departure time.
In a second time, if we refer to the demand input file, we need to filter requests according to the stay duration and the advance purchase: for now, let us put "0" to embrace all the requests possible. We need as well to filter according to the point-of-sale and the channel: let us put "DC" to embrace all the different channels and "ALL" to embrace all the point-of-sales.

1; SIN; BKK; ??; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; ?; DC; 0; ?; ?; ?; 0; ????; SQ; ?;

Let us say we just have the Economy cabin "Y" and Singapour airlines prices ticket for class "Y" and for class "M":

1; SIN; BKK; ??; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 0; ?; ?; ?; 0; ????; SQ; Y;
2; SIN; BKK; ??; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 0; ?; ?; ?; 0; ????; SQ; M;

We need to duplicate the fare rule to take into account both trip types: one-way "OW" and round-trip "RT":

1; SIN; BKK; OW; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 0; ?; ?; ?; 0; ????; SQ; Y;
2; SIN; BKK; OW; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 0; ?; ?; ?; 0; ????; SQ; M;
3; SIN; BKK; RT; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 0; ?; ?; ?; 0; ????; SQ; Y;
4; SIN; BKK; RT; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 0; ?; ?; ?; 0; ????; SQ; M;

The fare options are all set to a default value "T" (meaning true) for the "M" class, "F" (meaning false) for the "Y" class. The fare values (arbitrary currency) are chosen to be all distinct.

1; SIN; BKK; OW; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 0; F; F; F; 0; 150; SQ; Y;
2; SIN; BKK; OW; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 0; T; T; T; 0; 100; SQ; M;
3; SIN; BKK; RT; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 0; F; F; F; 0; 220; SQ; Y;
4; SIN; BKK; RT; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 0; T; T; T; 0; 160; SQ; M;

Once you have created your fare input file, building the yield one is very simple. Just copy your fare input file and remove everything related to restrictions, advance purchase and stay duration:

1; SIN; BKK; OW; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 150; SQ; Y;
2; SIN; BKK; OW; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 100; SQ; M;
3; SIN; BKK; RT; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 220; SQ; Y;
4; SIN; BKK; RT; 2011-01-01; 2011-12-31; 00:00; 23:59; ALL; Y; DC; 160; SQ; M;