qdk_chemistry.utils.telemetry_events module
Telemetry event logging for QDK Chemistry module.
- qdk_chemistry.utils.telemetry_events.log_telemetry(name, value, count=1, properties=None, type='counter')
Log a custom telemetry metric.
Logs a custom metric with the name provided. Properties are optional and can be used to capture additional context about the metric (but should be a relatively static set of values, as each unique set of properties will be sent as a separate metric and creates a separate ‘dimension’ in the backend telemetry store).
The type can be either ‘counter’ or ‘histogram’. A ‘counter’ is a simple value that is summed over time, such as how many times an event occurs, while a ‘histogram’ is used to track ‘quantitative’ values, such as the distribution of values over time, e.g., the duration of an operation.
- qdk_chemistry.utils.telemetry_events.get_basis_functions_bucket(basis_functions)[source]
Categorize the number of basis functions into buckets for telemetry aggregation.
This function groups number of basis functions into discrete buckets to enable meaningful aggregation and analysis in telemetry data. Rather than tracking exact counts (which would result in too many unique values), this bucketing approach provides useful ranges for performance and usage analysis.
- Parameters:
basis_functions (
str|int) – The number of basis functions.- Return type:
- Returns:
The bucket that the basis function count falls into.
Examples
>>> get_basis_functions_bucket(7) "10" >>> get_basis_functions_bucket(23) "30" >>> get_basis_functions_bucket(150) "150" >>> get_basis_functions_bucket(750) "800" >>> get_basis_functions_bucket(1500) "1500+" >>> get_basis_functions_bucket("unknown") "unknown"
- qdk_chemistry.utils.telemetry_events.extract_data(result)[source]
Extract number of basis functions from algorithm result.
This function handles both single qdk_data objects and tuple results (e.g., (energy, qdk_data) pairs) returned by QDK chemistry algorithms. It extracts the number of basis functions from the qdk_data’s orbital data for telemetry tracking.
- Parameters:
result (
Any) – Algorithm result, either a qdk_data object or a tuple containing a qdk_data (typically at index 1 for (energy, wavefunction) pairs).- Return type:
- Returns:
Bucket of basis functions (e.g., “10”, “50”, “100”) or “unknown” if no qdk_data is available.
Examples
>>> # Single qdk_data result >>> n_basis = extract_data(qdk_data) '50'
>>> # Tuple result (energy, qdk_data) >>> n_basis = extract_data((energy, qdk_data)) '100'
>>> # No qdk_data >>> n_basis = extract_data(some_other_result) 'unknown'
- qdk_chemistry.utils.telemetry_events.on_qdk_chemistry_import()[source]
Logs a telemetry event indicating that the QDK Chemistry module has been imported.
- Return type:
- qdk_chemistry.utils.telemetry_events.on_algorithm(algorithm_type, algorithm_name)[source]
Logs a telemetry event for the execution of a quantum chemistry algorithm.
- qdk_chemistry.utils.telemetry_events.on_algorithm_end(algorithm_type, duration_sec, status, algorithm_name, error_type=None, **properties)[source]
Logs the execution duration and outcome of a chemistry algorithm.
Logs relevant metadata about algorithm execution including timing, success/failure status, and additional contextual information.
- Parameters:
algorithm_type (
str) – The category of algorithm executed (e.g., ‘scf_solver’, ‘active_space_selector’).duration_sec (
float) – The time taken to execute the algorithm, in seconds.status (
str) – The result of the execution, typically ‘success’ or ‘failed’.algorithm_name (
str) – The specific implementation or backend used (e.g., ‘qdk’, ‘pyscf’).error_type (
str|None) – The type of error encountered, if any. Defaults to None.properties – Additional contextual information about the execution (e.g., ‘num_basis_functions’).
- Return type: