Global variables and parameters#

Caution

If you are not familiar with C++ syntax, we recommend you to see C++ syntax before reading this page.

The init() function#

As said in Getting started, every program using XLiFE++ begins by a call to the init() function, taking up to 4 key/value arguments:

_lang: enum to set the language for print and log messages. Possible values are en for English, fr for French, de for German, or es for Spanish. Default value is en.

_verbose: integer to set the verbose level. Default value is 1.

_pushpop: boolean to activate backtrace of every call to a XLiFE++ routine. Default value is true.

_isLogged: boolean to activate log. Default value is false.

_trackingMode: boolean to prints logs of the backtrace of every call to a XLiFE++ routine. Default value is false.

Hint

When _trackingMode is set to true, _isLogged is implicitely set to true.

Furthermore, the init() function loads functionalities linked to the trace of where such messages come from. If this function is not called, XLiFE++ cannot work !!! These parameters can also be set from dedicated command line options:

Command line options for XLiFE++ executables:
-h                               prints the current help
-j <num>, -jobs <num>,           define the number of threads. Default is
--jobs <num>                     -1, meaning automatical behavior.
-l <string>, -lang <string>,     define the language used for messages.
--lang <string>                  Default is en.
-vl <num>, -verbose-level <num>, define the verbose level.
--verbose-level <num>            Default is 0.
-v                               set the verbose level to 1.
-vv                              set the verbose level to 2.
-vvv                             set the verbose level to 3.

To deal with these command line options, you have to give standard arguments to the init() function:

init(argc, argc, _lang=fr);

Management of custom options (Options class)#

XLiFE++ provides an Options object to manage user options, that can be read from the command line or from files.

What is an option ? An option has:

  • A name, that will be used to get the value of an option, as for a Parameter.

    Warning

    An option name cannot start with a sequence of “-” characters. First characters must be alphanumerical.

  • One or several keys used to define an option (key in a file or command line option). A key cannot be used twice, and some keys are forbidden, due to some keys dedicated to system options (see Step-by-step explanations about the init() function).

  • A value, that can be a String, a scalar (Int, Number, Real, Complex) or a vector (Ints, Numbers, Reals, Complexes or Strings). This is the default value of the option and determines its data type. For vector types, size is not relevant.

This class provides a default constructor. In order to define a user option, you can use the function addOption():

Options opts;
opts.addOption("t1", 1.2);
opts.addOption("t2", "tata");
opts.addOption("t3", "-t", Complex(0.,1.));
opts.addOption("t4", Strings("-tu","-tv"), Reals(1.1, -2.4, 0.7));
opts.addOption("t5", Strings("tata","titi"));

To parse options from file and or command line arguments, you may use one of the following line:

opts.parse(argc, argv);
String filename="param.txt";
opts.parse(filename);
opts.parse(filename, argc, argv);

where argc and argv are the arguments of the main function dedicated to command line arguments of the executable. When using both filename and command line arguments, the latter are given priority.

Let’s now talk about how use options in a file or command-line.

First option is named “t1”. So it can be used through the key “t1”, “-t1” or “–t1”. Fourth option is named “t4” and has 2 aliases: “-tu” et “-tv”. So it can be used through the key “t4”, “-t4”, “–t4”, “-tu” or “-tv”.

./exec --t1 2.5 -t2 tutu -t3 2.5 -0.1 -t4 2.2 -4.8 1.4 -t5 "tutu" toto "ta ta" titi

When passing options from command line, you consider a Complex value as 2 Real values. Furthermore, quotes are not necessary for String values, unless the value contains special characters such as blank spaces, escape characters, … Here is an example of ascii file used to define options:

t1 3.7
t2 "ti ti"
t3 (2.5,-0.2)
t4 2.5 -2 3.4 4.7
t5 "titi" tutu "ta ta" toto

When passing options from a file, a Complex value is now written as a complex, namely real part and imaginary part are delimited by a comma and inside parentheses. As for command-line case, quotes are not necessary for String values, unless the value contains special characters such as blank spaces, escape characters, …

XLiFE++ global parameters#

Global constants and objects#

Some global constants are available and may be useful to you:

pi_: the pi constant with the Real precision

i_: the imaginary number with the Complex precision

theEulerConst: the Euler-Mascheroni constant

theTolerance: the precision used to convergence in norms (2.22045e-12 in double precision)

theEpsilon: the machine epsilon (2.22045e-16 in double precision)

Hint

By default, XLiFE++ library is installed with intermediate precision (say double precision for reals).

Some useful objets are also available:

thePrintStream_: the dedicated file stream to the print.txt file generated while executing a program using XLiFE++.

theCout: using this stream object means using either the standard output stream std::cout and the previous file stream thePrintStream_. This is the reason why we recommend you to always use this stream.

eol: an alias to std::endl (end of line).

Multi-threading#

XLiFE++, when configured with omp, uses automatically multi-threading. We saw that the init() function enables you to define the number of threads that will be used, but you can change the number of threads everywhere you want in your program. To modify its value, use the numberOfThreads() function:

numberOfThreads(24);
...
numberOfThreads(12);
...

When used without argument, the routine returns the number of threads currently defined.

Tip

In multithreading environment, the stream theCout prints only on the thread 0.

Warning

Unless you are an expert, do not use omp command (e.g. #pragma omp for) in main program.

Verbosity#

The init() function enables to define the verbosity, but the verbose level can be changed anywhere in program. To modify its value, use the verboseLevel() function:

verboseLevel(10);
...
verboseLevel(0);
...

When the verbose level is set to 0, nothing is printed except the errors and warnings.

Tip

In multithreading environment, it may appear in execution folder other print files (printxx.txt) corresponding to outputs of each thread.

Angle unit#

XLiFE++ uses radian as reference angle unit. As a consequence, you have to give angles expressed in radian unit and angles are also returned or printed in radian unit. However, it is possible to pass angles in degree unit using the following syntax processing the degree to radian conversion:

Real angle = 45*deg_; // angle contains pi/4 !

The Timer class#

The Timer class is a utility class to perform computational time analysis (cpu time and elapsed time) and manage dates. For a user, only a few functions are useful. They do not involve explicitly some Timer objects. There are some functions to get date in various forms :

String theTime();      // returns current time
String theDate();      // returns current date as dd.mmm.yyyy
String theShortDate(); // returns current date as mm/dd/yyyy or dd/mm/yyyy
String theLongDate();  // returns current date as Month Day, Year or Day Month Year
String theIsoDate();   // returns ISO8601 format of current date (yyyy−mm−dd)
String theIsoTime();   // returns ISO8601 format of current time (hh−mi−ss)

and others to get cpu or elapsed time :

double cpuTime();                      // user time ("cputime") in sec. since last call
double cpuTime(const String&);         // same and prints it with comment
double totalCpuTime();                 // elapsed time in sec. since first call
double totalCpuTime(const String&);    // same and prints it with comment
double elapsedTime();                  // elapsed time in sec. since last call
double elapsedTime(const String&) ;    // same and prints it with comment
double totalElapsedTime();             // elapsed time in sec. since first call
double totalElapsedTime(const String&);// same with comment

Using these functions, it is easy to perform time computation analysis. For instance :

#include "xlife++.h"
using namespace xlifepp;
int main()
{
  init(fr); // initializes timers
  // task 1
  ...
  cpuTime("cpu time for task 1");
  elapsedTime("elapsed time for task 1");
  // task 2
  ...
  cpuTime("cpu time for task 2");
  elapsedTime("elapsed time for task 2");
  // end of tasks
  totalCpuTime("total cpu time");
  totalElapsedTime("total elapsed time");
}

The Memory class#

Using the Memory class, the memory usage can be inspected using the following functions:

Real physMem = Memory::physicalMem();         //physical memory
Real freeMem = Memory::physicalFreeMem();     //free physical memory
Real procMem = Memory::processPhysicalMem();  //physical memory used by the process

The default unit is the MegaBytes (Mo), but you can change the unit by specifying one of the following units in the argument of memory functions:

enum MemoryUnit {_byte, _kilobyte, _megabyte, _gigabyte, _terabyte};
On this page