qdk_chemistry.utils.telemetry_events module

Telemetry event logging for QDK Chemistry module.

qdk_chemistry.utils.telemetry_events.wraps(wrapped, assigned=WRAPPER_ASSIGNMENTS, updated=WRAPPER_UPDATES)

Decorator factory to apply update_wrapper() to a wrapper function

Returns a decorator that invokes update_wrapper() with the decorated function as the wrapper argument and the arguments to wraps() as the remaining arguments. Default arguments are as for update_wrapper(). This is a convenience function to simplify applying partial() to update_wrapper().

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.

Return type:

None

Parameters:
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.

Return type:

str

Parameters:

basis_functions (str | int) – The number of basis functions.

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.

Return type:

str

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

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:

None

qdk_chemistry.utils.telemetry_events.on_algorithm(algorithm_type, algorithm_name)[source]

Logs a telemetry event for the execution of a quantum chemistry algorithm.

Return type:

None

Parameters:

  • algorithm_type (str) – The type or category of the algorithm being executed.

  • algorithm_name (str) – The specific name of the 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.

Return type:

None

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’).

qdk_chemistry.utils.telemetry_events.telemetry_tracker()[source]

Decorator to track telemetry for algorithm run execution.