Merge branch 'env-options' into 'master'

Load options from environment variables

Closes #598 and #813

See merge request vtk/vtk-m!3243

docs/changelog/env-options.md

@@ -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.

docs/users-guide/initialization.rst

@@ -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.
 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.
 This structure contains information about the supported arguments and options selected during initialization.
 

vtkm/cont/Initialize.cxx

@@ -17,6 +17,7 @@
 
 #include <vtkm/thirdparty/diy/environment.h>
 
+#include <cstdlib>
 #include <memory>
 #include <sstream>
 
@@ -123,7 +124,7 @@ InitializeResult Initialize(int& argc, char* argv[], InitializeOptions opts)
   }
   else
   {
-    vtkm::cont::InitLogging(argc, argv, loggingFlag);
+    vtkm::cont::InitLogging(argc, argv, loggingFlag, "VTKM_LOG_LEVEL");
   }
   if (!vtkmdiy::mpi::environment::initialized())
   {
@@ -239,6 +240,19 @@ InitializeResult Initialize(int& argc, char* argv[], InitializeOptions opts)
       }
       config.Device = id;
     }
+    else if (std::getenv("VTKM_DEVICE"))
+    {
+      auto id = vtkm::cont::make_DeviceAdapterId(std::getenv("VTKM_DEVICE"));
+      if (id != vtkm::cont::DeviceAdapterTagAny{})
+      {
+        vtkm::cont::GetRuntimeDeviceTracker().ForceDevice(id);
+      }
+      else
+      {
+        vtkm::cont::GetRuntimeDeviceTracker().Reset();
+      }
+      config.Device = id;
+    }
     else if ((opts & InitializeOptions::DefaultAnyDevice) != InitializeOptions::None)
     {
       vtkm::cont::GetRuntimeDeviceTracker().Reset();

vtkm/cont/Logging.cxx

@@ -30,7 +30,7 @@
 
 #endif // VTKM_ENABLE_LOGGING
 
-#include <cassert>
+#include <cstdlib>
 #include <iomanip>
 #include <sstream>
 #include <stdexcept>
@@ -108,7 +108,10 @@ namespace 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::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_name_to_verbosity_callback(&nameToVerbosityCallback);
 
-    // Set the default log level to warning
-    SetStderrLogLevel(vtkm::cont::LogLevel::Warn);
+    const char* envLevel = std::getenv(loggingEnv.c_str());
+    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());
   }
 #else  // VTKM_ENABLE_LOGGING

vtkm/cont/Logging.h

@@ -371,7 +371,10 @@ enum class LogLevel
  */
 VTKM_CONT_EXPORT
 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
 void InitLogging();