Qiskit-Neko Configuration Files#

To support running against different backends and also tune the execute of tests qiskit-neko supports configuration files to tweak the configuration and make reproducible testing simpler. The format for qiskit-neko’s configuration is a yaml file, a fully populated example is below:

---
test_timeout: 60.0
backend_plugin: ibmq
backend_selection: santiago
backend_script: /tmp/backend_script
default_log_level: DEBUG
module_log_level:
    qiskit: INFO
    numpy: WARNING
log_format: "%(asctime)s %(process)d [%(name)s] %(message)s"
log_file: /tmp/qiskit_neko.log

The options are defined as below:

  • test_timeout - A float value in seconds for the maximum per test timeout value. If a test takes longer than this value in seconds it will be marked as error/failed and the rest of the suite will run

  • backend_plugin - A string value that takes in the plugin name to use for backends. If this is not specified the backend plugin will default to the included AerPlugin class.

  • backend_selection - An selection string that will be passed to the configured plugin and will be used to influence the returned backend from the backend. Refer to the plugin documentation for how this can be used as the exact behavior will be based on the plugin in use.

  • backend_script - An optional absolute path to a script file to run in lieu of a plugin. This script file will be imported from this configured path. It must contain a function in the script named main() which when called returns a qiskit_neko.backend_plugin.BackendPlugin subclass object that can be used for the tests. If this option is specified it will take precedence over backend_plugin.

  • default_log_level - The default log level to use for all modules emitting log messages during the test run. This can be any valid predefined log level, see: https://docs.python.org/3/library/logging.html#logging-levels for the complete list.

  • module_log_level - this can be optionally set to a nested yaml dictionary where the keys are the module name and the value is the log level to use for that module. Just as with the default_log_level the values can be any valid predefined log leve, see: https://docs.python.org/3/library/logging.html#logging-levels for the complete list.

  • log_format - An optional log format string to control the output format for log messages. This uses the same format as logging.Formatter which is a printf-style string that uses the built-in LogRecord attributes

  • log_file - An optional file path that will be used to write all log messages to in addition to the default logging stored in the results stream all log messages emitted by the test run will be written to this file.

Specifying Configuration Files#

By default the the configuration file for qiskit-neko is looked for in 4 places in the following order. If a file is found in that location it will be used and none of the subsequent locations will be checked:

  1. $CWD/neko_config.yml

  2. ~/.qiskit/neko_config.yml

  3. ~/.config/qiskit-neko/neko_config.yml

  4. /etc/neko_config.yml

Since the actual execution of tests is handled by the external Python standard library unittest framework the only mechanism to explicitly specify a configuration file path is with an environment variable. You can set the environment variable NekoConfigPath to the absolute path to the configuration file. If this is specified it will be used regardless of a file being present in any of the default file locations.