mirror of
https://gitlab.kitware.com/vtk/vtk-m
synced 2024-10-05 01:49:02 +00:00
Load options from environment variables
Some common VTK-m options such as the device and log level could be specified on the command line but not through environment variables. It is not always possible to set VTK-m command line options, so environment variables are added. Also added documentation to the user's guide about what options are available and how to set them.
This commit is contained in:
parent
8a67dea2fa
commit
310579b9a7
9
docs/changelog/env-options.md
Normal file
9
docs/changelog/env-options.md
Normal file
@ -0,0 +1,9 @@
|
|||||||
|
## Load options from environment variables
|
||||||
|
|
||||||
|
Some common VTK-m options such as the device and log level could be
|
||||||
|
specified on the command line but not through environment variables. It is
|
||||||
|
not always possible to set VTK-m command line options, so environment
|
||||||
|
variables are added.
|
||||||
|
|
||||||
|
Also added documentation to the user's guide about what options are
|
||||||
|
available and how to set them.
|
@ -19,6 +19,44 @@ But it can also optionally take the ``argc`` and ``argv`` arguments to the ``mai
|
|||||||
|VTKm| accepts arguments that, for example, configure the compute device to use or establish logging levels.
|
|VTKm| accepts arguments that, for example, configure the compute device to use or establish logging levels.
|
||||||
Any arguments that are handled by |VTKm| are removed from the ``argc``/``argv`` list so that your program can then respond to the remaining arguments.
|
Any arguments that are handled by |VTKm| are removed from the ``argc``/``argv`` list so that your program can then respond to the remaining arguments.
|
||||||
|
|
||||||
|
Many options can also be set with environment variables.
|
||||||
|
If both the environment variable and command line argument are provided, the command line argument is used.
|
||||||
|
The following table lists the currently supported options.
|
||||||
|
|
||||||
|
.. list-table:: |VTKm| command line arguments and environment variable options.
|
||||||
|
:widths: 23 22 15 40
|
||||||
|
:header-rows: 1
|
||||||
|
|
||||||
|
* - Command Line Argument
|
||||||
|
- Environment Variable
|
||||||
|
- Default Value
|
||||||
|
- Description
|
||||||
|
* - ``--vtkm-help``
|
||||||
|
-
|
||||||
|
-
|
||||||
|
- Causes the program to print information about |VTKm| command line arguments and then exits the program.
|
||||||
|
* - ``--vtkm-log-level``
|
||||||
|
- ``VTKM_LOG_LEVEL``
|
||||||
|
- ``WARNING``
|
||||||
|
- Specifies the logging level.
|
||||||
|
Valid values are ``INFO``, ``WARNING``, ``ERROR``, ``FATAL``, and ``OFF``.
|
||||||
|
This can also be set to a numeric value for the logging level.
|
||||||
|
* - ``--vtkm-device``
|
||||||
|
- ``VTKM_DEVICE``
|
||||||
|
-
|
||||||
|
- Force |VTKm| to use the specified device.
|
||||||
|
If not specified or ``Any`` given, then any available device may be used.
|
||||||
|
* - ``--vtkm-num-threads``
|
||||||
|
- ``VTKM_NUM_THREADS``
|
||||||
|
-
|
||||||
|
- Set the number of threads to use on a multi-core device.
|
||||||
|
If not specified, the device will use the cores available in the system.
|
||||||
|
* - ``--vtkm-device-instance``
|
||||||
|
- ``VTKM_DEVICE_INSTANCE``
|
||||||
|
-
|
||||||
|
- Selects the device to use when more than one device device of a given type is available.
|
||||||
|
The device is specified with a numbered index.
|
||||||
|
|
||||||
:func:`vtkm::cont::Initialize` returns a :struct:`vtkm::cont::InitializeResult` structure.
|
:func:`vtkm::cont::Initialize` returns a :struct:`vtkm::cont::InitializeResult` structure.
|
||||||
This structure contains information about the supported arguments and options selected during initialization.
|
This structure contains information about the supported arguments and options selected during initialization.
|
||||||
|
|
||||||
|
@ -17,6 +17,7 @@
|
|||||||
|
|
||||||
#include <vtkm/thirdparty/diy/environment.h>
|
#include <vtkm/thirdparty/diy/environment.h>
|
||||||
|
|
||||||
|
#include <cstdlib>
|
||||||
#include <memory>
|
#include <memory>
|
||||||
#include <sstream>
|
#include <sstream>
|
||||||
|
|
||||||
@ -123,7 +124,7 @@ InitializeResult Initialize(int& argc, char* argv[], InitializeOptions opts)
|
|||||||
}
|
}
|
||||||
else
|
else
|
||||||
{
|
{
|
||||||
vtkm::cont::InitLogging(argc, argv, loggingFlag);
|
vtkm::cont::InitLogging(argc, argv, loggingFlag, "VTKM_LOG_LEVEL");
|
||||||
}
|
}
|
||||||
if (!vtkmdiy::mpi::environment::initialized())
|
if (!vtkmdiy::mpi::environment::initialized())
|
||||||
{
|
{
|
||||||
@ -225,37 +226,70 @@ InitializeResult Initialize(int& argc, char* argv[], InitializeOptions opts)
|
|||||||
vtkm::cont::DeviceAdapterTagAny{}, runtimeDeviceOptions, argc, argv);
|
vtkm::cont::DeviceAdapterTagAny{}, runtimeDeviceOptions, argc, argv);
|
||||||
}
|
}
|
||||||
|
|
||||||
|
// Check for device on command line.
|
||||||
if (options[opt::OptionIndex::DEVICE])
|
if (options[opt::OptionIndex::DEVICE])
|
||||||
{
|
{
|
||||||
const char* arg = options[opt::OptionIndex::DEVICE].arg;
|
const char* arg = options[opt::OptionIndex::DEVICE].arg;
|
||||||
auto id = vtkm::cont::make_DeviceAdapterId(arg);
|
config.Device = vtkm::cont::make_DeviceAdapterId(arg);
|
||||||
if (id != vtkm::cont::DeviceAdapterTagAny{})
|
}
|
||||||
|
// If not on command line, check for device in environment variable.
|
||||||
|
if (config.Device == vtkm::cont::DeviceAdapterTagUndefined{})
|
||||||
|
{
|
||||||
|
const char* deviceEnv = std::getenv("VTKM_DEVICE");
|
||||||
|
if (deviceEnv != nullptr)
|
||||||
{
|
{
|
||||||
vtkm::cont::GetRuntimeDeviceTracker().ForceDevice(id);
|
auto id = vtkm::cont::make_DeviceAdapterId(std::getenv("VTKM_DEVICE"));
|
||||||
|
if (VtkmDeviceArg::DeviceIsAvailable(id))
|
||||||
|
{
|
||||||
|
config.Device = id;
|
||||||
|
}
|
||||||
|
else
|
||||||
|
{
|
||||||
|
// Got invalid device. Log an error, but continue to do the default action for
|
||||||
|
// the device (i.e., ignore the environment variable setting).
|
||||||
|
VTKM_LOG_S(vtkm::cont::LogLevel::Error,
|
||||||
|
"Invalid device `"
|
||||||
|
<< deviceEnv
|
||||||
|
<< "` specified in VTKM_DEVICE environment variable. Ignoring.");
|
||||||
|
VTKM_LOG_S(vtkm::cont::LogLevel::Error,
|
||||||
|
"Valid devices are: " << VtkmDeviceArg::GetValidDeviceNames());
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
// If still not defined, check to see if "any" device should be added.
|
||||||
|
if ((config.Device == vtkm::cont::DeviceAdapterTagUndefined{}) &&
|
||||||
|
(opts & InitializeOptions::DefaultAnyDevice) != InitializeOptions::None)
|
||||||
|
{
|
||||||
|
config.Device = vtkm::cont::DeviceAdapterTagAny{};
|
||||||
|
}
|
||||||
|
// Set the state for the device selected.
|
||||||
|
if (config.Device == vtkm::cont::DeviceAdapterTagUndefined{})
|
||||||
|
{
|
||||||
|
if ((opts & InitializeOptions::RequireDevice) != InitializeOptions::None)
|
||||||
|
{
|
||||||
|
auto devices = VtkmDeviceArg::GetValidDeviceNames();
|
||||||
|
VTKM_LOG_S(vtkm::cont::LogLevel::Fatal, "Device not given on command line.");
|
||||||
|
std::cerr << "Target device must be specified via --vtkm-device.\n"
|
||||||
|
"Valid devices: "
|
||||||
|
<< devices << std::endl;
|
||||||
|
if ((opts & InitializeOptions::AddHelp) != InitializeOptions::None)
|
||||||
|
{
|
||||||
|
std::cerr << config.Usage;
|
||||||
|
}
|
||||||
|
exit(1);
|
||||||
}
|
}
|
||||||
else
|
else
|
||||||
{
|
{
|
||||||
vtkm::cont::GetRuntimeDeviceTracker().Reset();
|
// No device specified. Do nothing and let VTK-m decide what it is going to do.
|
||||||
}
|
}
|
||||||
config.Device = id;
|
|
||||||
}
|
}
|
||||||
else if ((opts & InitializeOptions::DefaultAnyDevice) != InitializeOptions::None)
|
else if (config.Device == vtkm::cont::DeviceAdapterTagAny{})
|
||||||
{
|
{
|
||||||
vtkm::cont::GetRuntimeDeviceTracker().Reset();
|
vtkm::cont::GetRuntimeDeviceTracker().Reset();
|
||||||
config.Device = vtkm::cont::DeviceAdapterTagAny{};
|
|
||||||
}
|
}
|
||||||
else if ((opts & InitializeOptions::RequireDevice) != InitializeOptions::None)
|
else
|
||||||
{
|
{
|
||||||
auto devices = VtkmDeviceArg::GetValidDeviceNames();
|
vtkm::cont::GetRuntimeDeviceTracker().ForceDevice(config.Device);
|
||||||
VTKM_LOG_S(vtkm::cont::LogLevel::Error, "Device not given on command line.");
|
|
||||||
std::cerr << "Target device must be specified via --vtkm-device.\n"
|
|
||||||
"Valid devices: "
|
|
||||||
<< devices << std::endl;
|
|
||||||
if ((opts & InitializeOptions::AddHelp) != InitializeOptions::None)
|
|
||||||
{
|
|
||||||
std::cerr << config.Usage;
|
|
||||||
}
|
|
||||||
exit(1);
|
|
||||||
}
|
}
|
||||||
|
|
||||||
|
|
||||||
|
@ -30,7 +30,7 @@
|
|||||||
|
|
||||||
#endif // VTKM_ENABLE_LOGGING
|
#endif // VTKM_ENABLE_LOGGING
|
||||||
|
|
||||||
#include <cassert>
|
#include <cstdlib>
|
||||||
#include <iomanip>
|
#include <iomanip>
|
||||||
#include <sstream>
|
#include <sstream>
|
||||||
#include <stdexcept>
|
#include <stdexcept>
|
||||||
@ -108,7 +108,10 @@ namespace cont
|
|||||||
{
|
{
|
||||||
|
|
||||||
VTKM_CONT
|
VTKM_CONT
|
||||||
void InitLogging(int& argc, char* argv[], const std::string& loggingFlag)
|
void InitLogging(int& argc,
|
||||||
|
char* argv[],
|
||||||
|
const std::string& loggingFlag,
|
||||||
|
const std::string& loggingEnv)
|
||||||
{
|
{
|
||||||
SetLogLevelName(vtkm::cont::LogLevel::Off, "Off");
|
SetLogLevelName(vtkm::cont::LogLevel::Off, "Off");
|
||||||
SetLogLevelName(vtkm::cont::LogLevel::Fatal, "FATL");
|
SetLogLevelName(vtkm::cont::LogLevel::Fatal, "FATL");
|
||||||
@ -130,8 +133,16 @@ void InitLogging(int& argc, char* argv[], const std::string& loggingFlag)
|
|||||||
loguru::set_verbosity_to_name_callback(&verbosityToNameCallback);
|
loguru::set_verbosity_to_name_callback(&verbosityToNameCallback);
|
||||||
loguru::set_name_to_verbosity_callback(&nameToVerbosityCallback);
|
loguru::set_name_to_verbosity_callback(&nameToVerbosityCallback);
|
||||||
|
|
||||||
// Set the default log level to warning
|
const char* envLevel = std::getenv(loggingEnv.c_str());
|
||||||
SetStderrLogLevel(vtkm::cont::LogLevel::Warn);
|
if (envLevel != nullptr)
|
||||||
|
{
|
||||||
|
SetStderrLogLevel(envLevel);
|
||||||
|
}
|
||||||
|
else
|
||||||
|
{
|
||||||
|
// Set the default log level to warning
|
||||||
|
SetStderrLogLevel(vtkm::cont::LogLevel::Warn);
|
||||||
|
}
|
||||||
loguru::init(argc, argv, loggingFlag.c_str());
|
loguru::init(argc, argv, loggingFlag.c_str());
|
||||||
}
|
}
|
||||||
#else // VTKM_ENABLE_LOGGING
|
#else // VTKM_ENABLE_LOGGING
|
||||||
|
@ -371,7 +371,10 @@ enum class LogLevel
|
|||||||
*/
|
*/
|
||||||
VTKM_CONT_EXPORT
|
VTKM_CONT_EXPORT
|
||||||
VTKM_CONT
|
VTKM_CONT
|
||||||
void InitLogging(int& argc, char* argv[], const std::string& loggingFlag = "--vtkm-log-level");
|
void InitLogging(int& argc,
|
||||||
|
char* argv[],
|
||||||
|
const std::string& loggingFlag = "--vtkm-log-level",
|
||||||
|
const std::string& loggingEnv = "VTKM_LOG_LEVEL");
|
||||||
VTKM_CONT_EXPORT
|
VTKM_CONT_EXPORT
|
||||||
VTKM_CONT
|
VTKM_CONT
|
||||||
void InitLogging();
|
void InitLogging();
|
||||||
|
Loading…
Reference in New Issue
Block a user