Skip to content

Utilities Guide

This page provides an overview of the utilities in qbm.utils for preparing data and analyzing trained models. The Discretizer and PowerTransformer are used to prepare continuous data for training, since a BQRBM operates on binary values, and the functions in misc are used for reproducibility, model evaluation, and serialization.

Preparing Continuous Data

Discretizer

The Discretizer converts the columns of a dataframe into bit representations and converts them back. Continuous columns are linearly scaled between their minimum and maximum values into n_bits-bit integers, and any column whose name ends in _bit is treated as a pre-encoded single bit and passed through unscaled. 

import pandas as pd

from qbm.utils import Discretizer

df = pd.DataFrame({"x": [1.0, 2.0, 3.0], "y": [4.0, 5.0, 6.0]})
discretizer = Discretizer(df, n_bits=4)

V_train = discretizer.df_to_bit_array(df)
The resulting bit array V_train can be used to train a BQRBM directly, since the model accepts binary values in {0, 1} as well as spin eigenvalues in {+1, -1}. Samples generated by the model can be converted back to a dataframe of continuous values with bit_array_to_df. The intermediate discretize_df and undiscretize_df methods convert between continuous values and their integer representations. The epsilon parameter can be used to offset the minimum and maximum values per column, which is useful e.g. to ensure that samples slightly outside of the training range remain representable.

PowerTransformer

The PowerTransformer compresses outliers towards the mean before discretization, which reduces the number of bits required to represent the data without sacrificing resolution in the bulk of the distribution. Data points lying beyond threshold standard deviations from the mean are scaled by taking their power (\(0 < \text{power} < 1\)), and the transformation is reversed with inverse_transform. 

from qbm.utils import PowerTransformer

transformer = PowerTransformer(df, threshold=2.0, power=0.5)
df_transformed = transformer.transform(df)

Misc Utilities

  • get_rng(seed): Returns a reproducible np.random.RandomState generator, which should be used instead of the global NumPy RNG state everywhere reproducibility matters.
  • compute_kl_divergence(p_data, q_data): Computes the empirical Kullback-Leibler divergence between two sample distributions, which is useful for evaluating how well the model distribution matches the data distribution, e.g. as a training callback.
  • compute_lr_exp_decay(epoch, decay_epoch, period): Computes exponential learning rate decay multipliers, e.g. for the β learning rate schedule described in the annealer guide.
  • save_artifact(artifact, file_path) and load_artifact(file_path): Uniform serialization for .json and .pkl files, used internally by BQRBM.save() and BQRBM.load().
  • compute_df_stats, compute_df_ensemble_stats, filter_df_on_values, compute_lower_tail_concentration, compute_upper_tail_concentration: Additional helpers for analyzing dataframes and ensembles of training runs, described in detail in the API Reference.

API Reference

The full documentation of every utility can be found in the Utils API Reference.