SpECTRE
v2024.12.16
|
There are several different types of executables that can be built:
Executables/ParallelInfo
main
, e.g. Executables/Examples/HelloWorldNoCharm
main
DebugPreprocessor
The minimal SpECTRE executable tutorial describes how to add a new parallel executable.
Another simple example of an executable using Charm++ for parallelization is in src/Executables/Examples/HelloWorld
. In this example, the only additional phase (besides Initialization
and Exit
) is Execute
, and the phases are executed in order. SingletonHelloWorld
defines a single component HelloWorld
which specifies via the chare_type
type alias that it is a singleton parallel component which means that only one such object will exist across all processors used by the executable. Each component must define the static function execute_next_phase
which is executed during the phases (other than Initialization
and Exit
) defined in the metavariables struct. In SingletonHelloWorld
, the PrintMessage
action is called during the Execute
phase.
The PrintMessage
action is executed on whatever process the singleton component is created upon, and prints a message.
Executables can read in an input file (specified by the --input-file
argument) that will be parsed when the executable begins. Options specified in the input file can be used to either place items in the Parallel::GlobalCache (by specifying tags in the const_global_cache_tags
type alias of the metavariables, component and action structs), to construct items in the db::DataBox of components during initialization (by specifying tags in the simple_tags_from_options
type alias of action struct), or be passed to the allocate_array
function of an array component (by specifying tags in the array_allocation_tags
type alias of the component). SingletonHelloWorld
specifies a single option
which a string specifying a name that will be placed into the constant global cache. The string is fetched when performing the PrintMessage
action. Items in the constant global cache are stored once per node that the executable runs on. An example input file for SingletonHelloWorld
can be found in tests/InputFiles/ExampleExecutables/SingletonHelloWorld.yaml
and shows how to specify the options (lines beginning with a #
are comments and can be ignored).
Furthermore among the included header files
must be the appropriate header for each parallel component type, which in the SingletonHelloWorld
example is AlgorithmSingleton.hpp
. Note that these headers are not in the source tree, but are generated automatically when the code is compiled.
See the Parallelization documentation for more details.
While this is technically possible, it has not been tested. We recommend using the Charm++ supplied main chare mechanism for the time being.
An example of an executable that does not use Charm++ for parallelization but still can use all other infrastructure in SpECTRE is in src/Executables/Examples/HelloWorldNoCharm
. Adding a non-Charm++ executable to SpECTRE mostly follows the standard way of adding an executable using CMake. The only deviation is that the CMakeLists.txt
file must tell Charm++ not to add a main()
by passing the link flags -nomain-module -nomain
. This is done using CMake's set_target_properties
:
To add the executable as a target you must use the add_spectre_executable
function, which is a light weight wrapper around CMake's add_executable
. For example,
You can link in any of the SpECTRE libraries by adding them to the target_link_libraries
, for example:
We recommend that you add a test that the executable properly runs by adding an input file to tests/InputFiles
in an appropriate subdirectory. See [tests/InputFiles/ExampleExecutables/HelloWorldNoCharm.yaml
] (https://github.com/sxs-collaboration/spectre/tree/develop/tests/InputFiles/ ExampleExecutables/HelloWorldNoCharm.yaml) for an example. The input file is passed to the executable using --input-file path/to/Input.yaml
. In the case of the executable not taking any input file this is just used to generate a test that runs the executable.
For these types of executables main
can take the usual (int argc, char *argv[])
and parse command line options. Executables not using Charm++ are just standard executables that can link in any of the libraries in SpECTRE.
Parallel::abort
results in a segfault deep inside Charm++ code. However, the error messages from ASSERT
and ERROR
are still printed.Use the CMake function set_target_properties
to add flags to an executable. To call a completely custom compiler invocation you should use the add_custom_target
CMake function. The need for the custom_target
level of control is rare and should generally be avoided since it adds quite a bit of technical debt to the code base. Thus, it is not explained here. If you are certain you need it you can see the DebugPreprocessor
executable's CMakeLists.txt
file for an example.
Once they are written, see the tutorials specific to evolution and elliptic solves.