Launching a Calculation

There are two mechanisms for executing code with Arcane:

1. the time loop mechanism, which is the classic mechanism available since the first versions of Arcane.
2. direct execution

For both mechanisms, you must use the class Arcane::ArcaneLauncher. This class allows you to specify the execution parameters. All methods of this class are static.

The first thing to do is call the method Arcane::ArcaneLauncher::init() to specify the execution parameters to Arcane. This allows certain command-line values (such as the verbosity level, the output directory name, ...) to be automatically analyzed.

#include <arcane/launcher/ArcaneLauncher.h>
 
using namespace Arcane;
 
int
main(int argc,char* argv[])
{
  ArcaneLauncher::init(Arcane::CommandLineArguments(&argc,&argv));
  ...
}

There are two classes for specifying execution parameters: Arcane::ApplicationInfo and Arcane::ApplicationBuildInfo.

Note

These two classes exist for compatibility reasons with existing code. Eventually, only the Arcane::ApplicationBuildInfo class will remain, so this is the one that must be used.

The static instances of these two classes can be retrieved via the methods Arcane::ArcaneLauncher::applicationInfo() and Arcane::ArcaneLauncher::applicationBuildInfo(). The following example shows how to change the code name and version and the default directory for outputs:

#include <arcane/launcher/ArcaneLauncher.h>
 
using namespace Arcane;
 
int
main(int argc,char* argv[])
{
  ArcaneLauncher::init(Arcane::CommandLineArguments(&argc,&argv));
  Arcane::ApplicationBuildInfo& app_build_info = ArcaneLauncher::applicationBuildInfo();
  app_build_info.setCodeName("ArcaneTest");
  app_build_info.setCodeVersion(VersionInfo(1,0,0));
  app_build_info.setOutputDirectory("test_output");
  ...
}

Once initialization is complete, it is possible to launch the code execution via the call to Arcane::ArcaneLauncher::run():

#include <arcane/launcher/ArcaneLauncher.h>
 
using namespace Arcane;
 
int
main(int argc,char* argv[])
{
  ArcaneLauncher::init(Arcane::CommandLineArguments(&argc,&argv));
  Arcane::ApplicationBuildInfo& app_build_info = ArcaneLauncher::applicationBuildInfo();
  app_build_info.setCodeName("ArcaneTest");
  app_build_info.setCodeVersion(VersionInfo(1,0,0));
  app_build_info.setOutputDirectory("test_output");
  return ArcaneLauncher::run();
}

MPI Initialization

Using MPI requires calling the MPI_Init_thread() method from the MPI library. If Arcane is compiled with MPI support, MPI detection and the call to MPI_Init_thread() are done automatically by Arcane. The thread support level used for the call to MPI_Init_thread() depends on options such as the number of tasks or local subdomains in hybrid mode that you wish to use.

However, it is possible for the code to initialize MPI itself if it wishes. To do this, it must call the method MPI_Init_thread() before calling Arcane::ArcaneLauncher::run().

Note

Even if the executable is used sequentially (i.e., without going through a command such as mpiexec ...), Arcane attempts to initialize MPI. This is necessary because certain libraries (for example, linear solvers) require MPI to be initialized in all cases. It is possible to modify this behavior by explicitly specifying the desired parallelism service (TODO document).

Warning

You must be careful to use the mpiexec executable that corresponds to the version of MPI with which Arcane was compiled, otherwise you will run the sequential execution N times.

Code Execution

The method Arcane::ArcaneLauncher::run() allows you to launch the code execution. This method has three overloads:

1. The call without arguments (Arcane::ArcaneLauncher::run()) to launch the classic execution using a time loop (see Code Configuration (.CONFIG)). This mechanism should be preferred because it allows you to use all of Arcane's features. The page Launching a Calculation shows a minimal example of this type of usage.
2. Arcane::ArcaneLauncher::run(std::function<int(DirectSubDomainExecutionContext&)> func) to execute the code specified by func after initialization and subdomain creation. The page arcanedoc_general_direct_execution shows an example of direct execution.
3. Arcane::ArcaneLauncher::run(std::function<int(DirectExecutionContext&)> func) to execute the code specified by func sequentially only. This mechanism should be used if, for example, you want to perform simple unit tests without having a subdomain (Arcane::ISubDomain*). application without dataset or time loop.

Command Line Options

Arcane interprets command-line options that start with -A. For example, to change the verbosity level, simply specify the option -A,VerbosityLevel=3 in the command line.

The options are interpreted when calling Arcane::ArcaneLauncher::init(), and the values of ArcaneLauncher::applicationBuildInfo() are automatically filled with these options. However, it is possible to override them if necessary.

Remarks

It is also possible to modify the dataset using command-line options. This possibility is discussed on the page Command Line and Dataset.

The available options are:

Option	Environment Variable	Type	Default	Description
T	ARCANE_NB_TASK	Int32	1	Number of concurrent tasks to execute
S	ARCANE_NB_THREAD (This environment variable is obsolete)	Int32		Number of subdomains in shared memory
R	ARCANE_NB_REPLICATION (This environment variable is obsolete)	Int32	1	Number of replicated subdomains
P	ARCANE_NB_SUB_DOMAIN (This environment variable is obsolete)	Int32		Number of processes to use for subdomains. This value is normally calculated automatically based on MPI parameters. It is only useful if you wish to use fewer processes for domain partitioning than those allocated for the calculation.
AcceleratorRuntime		string		Accelerator runtime to use. The two possible values are cuda or hip. You must have compiled Arcane with accelerator support for this option to be accessible.
MaxIteration		Int32		Maximum number of iterations to perform for the execution. If the number of iterations specified by this variable is reached, the calculation stops.
OutputLevel	ARCANE_OUTPUT_LEVEL	Int32	3	Verbosity level of messages on standard output.
VerbosityLevel	ARCANE_VERBOSITY_LEVEL	Int32	3	Verbosity level of messages for listing file outputs. If the OutputLevel option is not specified, this option is also used for standard outputs.
MinimalVerbosityLevel		Int32		Minimum verbosity level. If specified, explicit calls in the code to change verbosity (via Arccore::ITraceMng::setVerbosityLevel()) cannot go below this minimum verbosity level. This mechanism is mainly used for debugging to ensure message display.
MasterHasOutputFile	ARCANE_MASTER_HAS_OUTPUT_FILE	Bool	False	Indicates whether the master process (generally process 0) writes the listing to a file in addition to standard output
OutputDirectory	ARCANE_OUTPUT_DIRECTORY	String	.	Base directory for generated files (listings, logs, curves, output, ...). This value is the one returned by Arcane::ISubDomain::exportDirectory().
CaseDatasetFileName		String		Dataset file name. If not specified and required, the last argument of the command line is considered the dataset file name.
ThreadBindingStrategy	ARCANE_THREAD_BINDING_STRATEGY	String		Thread binding strategy. This only works if Arcane is compiled with the 'hwloc' library. By default, no binding is performed. The only available mode is 'Simple', which allocates threads according to a round-robin mechanism. NOTE: this binding mechanism is under development and may not function optimally in all cases
ParallelLoopGrainSize		Int32		Grain size for multi-threaded parallel loops. If set, it indicates the number of elements in each block that decomposes a multi-threaded loop (from version 3.8).
ParallelLoopPartitioner		String		Choice of partitioner for multi-threaded parallel loops. Possible values are auto, static, or deterministic (from version 3.8).

Choosing the Message Exchange Manager

The message exchange manager (Arcane::IParallelSuperMng) is chosen when launching the calculation. Arcane provides the following managers:

• MpiParallelSuperMng
• SequentialParallelSuperMng
• MpiSequentialParallelSuperMng
• SharedMemoryParallelSuperMng
• HybridParallelSuperMng

Generally, Arcane automatically chooses the manager based on the parameters used to launch the calculation, but it is possible to explicitly specify the manager to use by setting the environment variable (obsolete) ARCANE_PARALLEL_SERVICE or by specifying the MessagePassingService option in the command line with one of the values above (without the ParallelSuperMng suffix, so for example Mpi, Sequential, MpiSequential, ...).

The automatic choice of the manager is made as follows:

Command Line	Manager Used	Description
./a.out ...	MpiSequentialParallelSuperMng or SequentialParallelSuperMng	MpiSequentialParallelSuperMng if Arcane was compiled with MPI, SequentialParallelSuperMng otherwise. The difference between the two is that the former initializes MPI so that communicators such as MPI_COMM_WORLD can be used
mpiexec -n $N ./a.out ...	MpiParallelSuperMng	$N processes, 1 subdomain per process
./a.out -A,S=$S ...	SharedMemoryParallelSuperMng	1 process, $S subdomains per process. Communication between subdomains is done via message exchange in shared memory.
mpiexec -n $N ./a.out -A,S=$S ...	HybridParallelSuperMng	$N processes, $S subdomains per process, resulting in $N * $S subdomains in total.

Here are some launch examples:

# sequential launch of the dataset 'Test.arc'
a.out Test.arc
 
# launch with 4 MPI subdomains
mpiexec -n 4 a.out Test.arc
 
# launch with 4 subdomains in shared memory mode
a.out -A,S=4 Test.arc
 
# launch with 12 subdomains and 4 processes (4 subdomains in
# shared memory per process)
mpiexec -n 3 -c 4 a.out -A,S=4 Test.arc
 
# launch with the CUDA accelerator runtime.
a.out -A,AcceleratorRuntime=cuda Test.arc

---

Execution, runtime Direct Execution Launch