Setting runtime environment

In this section, we present some tools to initialize and manipulate Feel++ environment.

1. Initialize Feel++

Environment class is necessary to initialize your application, as seen in FirstApp. The interface is as follows:

Environment env( _argc, _argv, _desc, _about );

None of those parameters are required but it is highly recommended to use the minimal declaration:

Environment env( _argc=argc, _argv=argv,
                 _desc=feel_option(),
                 _about=about(_name="name_of_your_app",
                              _author="your_name",
                              _email="your_email_adress"));

  • _argc and _argv are the arguments of your main function.

  • _desc is a description of your options.

  • _about is a brief description of your application.

1.1. Options Description

1.1.1. Adding Options

feel_options() returns a list of default options used in Feel++.

You can create your own list of options as follows:

using namespace Feel;
inline
po::options_description
makeOptions()
{
    po::options_description myappOptions( "My app options" );
    myappOptions.add_options()
      ( "option1", po::value<type1>()->default_value( value1 ), "description1" )
      ( "option2", po::value<type2>()->default_value( value2 ), "description2" )
      ( "option3", po::value<type3>()->default_value( value3 ), "description3" )
      ;
     // Add the default feel options to your list
    return myappOptions.add( feel_options() );
}

makeOptions is the usual name of this routine but you can change it amd myappOptions is the name of you options list.

Parameter

Description

option

the name of parameter

type

the type parameter

value

the default value of parameter

description

the description of parameter

You can then use makeOptions() to initialize the Feel++ Environment as follows

Environment env( _argc=argc, _argv=argv,
                 _desc=makeOptions(),
                 _about=about(_name="myapp",
                              _author="myname",
                              _email="my@email.com") );

Then, at runtime, you can change the parameter as follows

$ ./myapp --option1=alpha --option2=beta --option3=gamma
Excerpt from quickstart/qs_laplacian.cpp

1.1.2. Options Accessors

Options Description :
Environment::optionsDescription();

Returns options description data structure of type po::options_description po where is a namespace alias defined in Feel++ for boost::program_options.

Variable map

You can access to the parameters of your application environment using the following function:

Environment::vm(_name);

_name is the name of the parameter as seen in the previous paragraph. This function returns a data structure of type po::variable_value. You can then extract the proper parameter value as follows

const double E = Environment::vm(_name="E").template as<double>();
const double nu = Environment::vm(_name="nu").template as<double>();

auto Tfinal =  Environment::vm( _name="test" ).template as<int>()*dt;

1.2. Repository

1.2.1. Change changeRepository

You can change the default repository where the results are stored

void changeRepository( _directory, _subdir, _filename );

Parameter

Description

Status

Default value

_directory

directory name

Required

_subdir

true

_filename

logfile

You can use boost format to customize the path as follows:

Environment::changeRepository( boost::format( "doc/manual/laplacian/%1%/%2%-%3%/P%4%/h_%5%/" )
                                   % this->about().appName()
                                   % shape
                                   % Dim
                                   % Order
                                   % meshSize );

Then results will be store in: /doc/manual/laplacian/<appName>/<shape>-<Dim>/P<Order>/h_<meshSize>/

1.2.2. findFile

Interface
std::string findFile( std::string const& filename );

Returns the string containing the filename path.

The lookup is as follows:

  • look into current path

  • look into paths that went through changeRepository(), it means that we look for example into the path from which the executable was run

If the file has an extension .geo or .msh, try also to

  • look into localGeoRepository() which is usually $HOME/feel/geo

  • look into systemGeoRepository() which is usually $FEELPP_DIR/share/feel/geo

If filename is not found, then the empty string is returned.

1.3. Utility functions

1.3.1. Communications

A lot of data structures, in fact most of them, in Feel++ are parallel and are associated with a WorldComm data structure which allows us to access and manipulate the MPI communicators. We provide some utility free functions that allow a transparent access to the WorldComm data structure.

We denote by c a Feel++ data structure associated to a WorldComm.

Feel++ Keyword

Description

rank(c)

returns the local MPI rank of the data structure c

globalRank(c)

returns the global MPI rank of the data

For example to print the rank of a mesh data structure

// initialise environment...
auto mesh = makeMesh<Simplex<2,1>>();
std::cout << "local rank : " << rank(mesh) << "\n";