--- title: Multiverse Singularity Machine Learning API reference description: API reference for Singularity Machine Learning, a Qiskit Function by Multiverse Computing source: https://eu-de.quantum.cloud.ibm.com/docs/en/api/functions/multiverse-computing-singularity --- # Multiverse Singularity Machine Learning API reference - [**Qiskit Functions**](/docs/guides/multiverse-computing-singularity) — Qiskit Functions — pre-built tools created by partner organizations — abstract away parts of the software development workflow to simplify and accelerate utility-scale algorithm discovery and application development. Click to view the guide for this Qiskit Function. ## Action-based approach The function uses an action-based approach. You can think of it as a virtual environment where you use actions to perform tasks or change its state. Currently, it offers the following actions: [`list`](#list), [`create`](#create), [`delete`](#delete), [`fit`](#fit), [`predict`](#predict), [`fit_predict`](#fit_predict), and [`create_fit_predict`](#create_fit_predict). The following example demonstrates the `create_fit_predict` action. ### `list` The `list` action retrieves all stored classifiers in `*.pkl.tar` format from the shared data directory. You can also access the contents of this directory by using the `catalog.files()` method. In general, the list action searches for files with the `*.pkl.tar` extension in the shared data directory and returns them in a list format. - Inputs: #### `action` Type: `` `str` `` The name of the action from among `create`, `list`, `fit`, `predict`, `fit_predict`, `create_fit_predict` and `delete`. Required: Yes - Usage: ```python job = singularity.run(action="list") ``` ### `create` The `create` action creates a classifier of the specified `quantum_classifier` type by using the provided parameters, and saves it in the shared data directory. > **Note** > > The function currently supports only the `QuantumEnhancedEnsembleClassifier`. - Inputs: #### `action` Type: `` `str` `` The name of the action from among `create`, `list`, `fit`, `predict`, `fit_predict`, `create_fit_predict` and `delete`. - Required: Yes #### `name` Type: `` `str` `` The name of the quantum classifier, for example, `spam_classifier`. - Required: Yes #### `instance` Type: `` `str` `` IBM instance. - Required: Yes #### `backend_name` Type: `` `str` `` Default value: `` `None` `` IBM compute resource. Default is `None`, which means the backend with the fewest pending jobs will be used. - Required: No #### `quantum_classifier` Type: `` `str` `` The type of the quantum classifier, for example, `QuantumEnhancedEnsembleClassifier`. - Required: No #### `num_learners` Type: `` `int` `` Default value: `10` The number of learners in the ensemble. - Required: No #### `learners_types` Type: `` `list` `` Default value: `` `[DecisionTreeClassifier]` `` Types of learners. Among supported types are: `DecisionTreeClassifier`, `GaussianNB`, `KNeighborsClassifier`, `MLPClassifier`, and `LogisticRegression`. Further details related to each can be found in the [scikit-learn documentation](https://scikit-learn.org/stable/supervised_learning.html). - Required: No #### `learners_proportions` Type: `` `list` `` Default value: `` `[1.0]` `` Proportions of each learner type in the ensemble. - Required: No #### `learners_options` Type: `` `list` `` Default value: `` `[{`max_depth`: 3, `splitter`: `random`, `class_weight`: None}]` `` Options for each learner type in the ensemble. For a complete list of options corresponding to the chosen learner type/s, consult [scikit-learn documentation](https://scikit-learn.org/stable/supervised_learning.html). - Required: No #### `regularization_type` Type: `` `str` or `list` `` Default value: `` `onsite` `` Type(s) of regularization to be used: `onsite` or `alpha`. `onsite` controls the onsite term where higher values lead to sparser ensembles. `alpha` controls trade-off between interaction and onsite terms where lower values lead to sparser ensembles. If a list is provided, models will be trained for each type and the best performing one will be selected. - Required: No #### `regularization` Type: `` `str` or `float` or `list` `` Default value: `` `0.01` `` Regularization value. Bounded between `0` and `+inf` if regularization\_type is `onsite`. Bounded between `0` and `1` if regularization\_type is `alpha`. If set to `auto`, auto-regularization is used - optimal regularization parameter is found by binary search with the desired ratio of selected classifiers to total classifiers (`regularization_desired_ratio`) and the upper bound for the regularization parameter (`regularization_upper_bound`). If a list is provided, models will be trained for each value and the best performing one will be selected. - Required: No #### `regularization_desired_ratio` Type: `` `float` or `list` `` Default value: `` `0.75` `` Desired ratio(s) of selected classifiers to total classifiers for auto-regularization. If a list is provided, models will be trained for each ratio and the best performing one will be selected. - Required: No #### `regularization_upper_bound` Type: `` `float` or `list` `` Default value: `200` Upper bound(s) for the regularization parameter when using auto-regularization. If a list is provided, models will be trained for each upper bound and the best performing one will be selected. - Required: No #### `weight_update_method` Type: `` `str` `` Default value: `` `logarithmic` `` Method for update of sample weights from among `logarithmic` and `quadratic`. - Required: No #### `sample_scaling` Type: `` `boolean` `` Default value: `` False` `` Whether sample scaling should be applied. - Required: No #### `prediction_scaling` Type: `` `float` `` Default value: `` `None` `` Scaling factor for predictions. - Required: No #### `optimizer_options` Type: `` `dict` `` QAOA optimizer options. | Name | Type | Description | Required | Default | | ----------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------- | | `num_solutions` | `integer` | The number of solutions | No | `1024` | | `reps` | `integer` | The number of repetitions | No | `4` | | `sparsify` | `float` | The sparsification threshold | No | `0.001` | | `theta` | `float` | The initial value of theta, a variational parameter of QAOA | No | `None` | | `simulator` | `boolean` | Whether to use a simulator or a QPU | No | `False` | | `classical_optimizer` | `str` | Name of the classical optimizer for the QAOA. All solvers offered by SciPy, as enlisted [here](https://docs.scipy.org/doc/scipy/reference/generated/scipy.optimize.minimize.html#scipy.optimize.minimize), are usable. You will need to set `classical_optimizer_options` accordingly | No | `COBYLA` | | `classical_optimizer_options` | `dictionary` | Classical optimizer options. For a complete list of available options, consult [SciPy documentation](https://docs.scipy.org/doc/scipy/reference/) | No | `{"maxiter": 60}` | | `optimization_level` | `integer` | The depth of the QAOA circuit | No | `3` | | `num_transpiler_runs` | `integer` | Number of transpiler runs | No | `30` | | `pass_manager_options` | `dictionary` | Options for generating preset pass manager | No | `{"approximation_degree": 1.0}` | | `estimator_options` | `dictionary` | Estimator options. For a complete list of available options, consult [Qiskit Runtime Client documentation](/docs/api/qiskit-ibm-runtime/options-estimator-options) | No | `None` | | `sampler_options` | `dictionary` | Sampler options. For a complete list of available options, consult the [Qiskit Runtime Client documentation](/docs/api/qiskit-ibm-runtime/options-sampler-options) | No | `None` | - Default `estimator_options` are: | Name | Type | Value | | ---------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `default_shots` | `integer` | `1024` | | `resilience_level` | `integer` | `2` | | `twirling` | `dictionary` | `{"enable_gates": True}` | | `dynamical_decoupling` | `dictionary` | `{"enable": True}` | | `resilience_options` | `dictionary` | `{"zne_mitigation": False, "zne": {"amplifier": "pea", "noise_factors": [1.0, 1.3, 1.6], "extrapolator": ["linear", "polynomial_degree_2", "exponential"],}}` | - Default `sampler_options` are: | Name | Type | Value | | ---------------------- | ------------ | ------------------------ | | `default_shots` | `integer` | `1024` | | `resilience_level` | `integer` | `1` | | `twirling` | `dictionary` | `{"enable_gates": True}` | | `dynamical_decoupling` | `dictionary` | `{"enable": True}` | - Required: No #### `voting` Type: `` `str` `` Default value: `` `hard` `` Use majority voting (`hard`) or average of probabilities (`soft`) for aggregating learners' predictions/probabilities. - Required: No #### `prob_threshold` Type: `` `float` `` Default value: `` `0.5` `` Optimal probability threshold. - Required: No #### `random_state` Type: `` `int` `` Default value: `` `None` `` Control randomness for repeatability. - Required: No * Usage: ```python job = singularity.run( action="create", name="classifier_name", # specify your custom name for the classifier here num_learners=10, regularization=0.01, optimizer_options={"simulator": True}, ) ``` - Validations: - `name`: - The name must be unique, a string up to 64 characters long. - It can only include alphanumeric characters and underscores. - It must start with a letter and cannot end with an underscore. - No classifier with the same name should already exist in the shared data directory. ### `delete` The `delete` action removes a classifier from the shared data directory. - Inputs: #### `action` Type: `` `str` `` he name of the action. Must be `delete`. - Required: Yes #### `name` Type: `` `str` `` The name of the classifier to delete. - Required: Yes * Usage: ```python job = singularity.run( action="delete", name="classifier_name", # specify the name of the classifier to delete here ) ``` - Validations: - `name`: - The name must be unique, a string up to 64 characters long. - It can only include alphanumeric characters and underscores. - It must start with a letter and cannot end with an underscore. - A classifier with the same name should already exist in the shared data directory. ### `fit` The `fit` action trains a classifier using the provided training data. - Inputs: #### `action` Type: `` `str` `` The name of the action. Must be `fit`. - Required: Yes #### `name` Type: `` `str` `` The name of the classifier to train. - Required: Yes #### `X` Type: `` `array` or `list` or `str` `` The training data. This can be a NumPy array, a list, or a string referencing a filename in the shared data directory. - Required: Yes #### `y` Type: `` `array` or `list` or `str` `` The training target values. This can be a NumPy array, a list, or a string referencing a filename in the shared data directory. - Required: Yes #### `fit_params` Type: `` `dict` `` Additional parameters to pass to the `fit` method of the classifier. See dictionary below. - Required: No | Name | Type | Description | Required | Default | | ------------------- | ------------------ | ---------------------------------------------------------------------------------- | -------- | ------- | | `validation_data` | `tuple` | The validation data and labels. | No | `None` | | `pos_label` | `integer` or `str` | The class label to be mapped to 1. | No | `None` | | `optimization_data` | `str` | Dataset to optimize the ensemble on. Can be one of: `train`, `validation`, `both`. | No | `train` | - Usage: ```python job = singularity.run( action="fit", name="classifier_name", # specify the name of the classifier to train here X=X_train, # or "X_train.npy" if you uploaded it in the shared data directory y=y_train, # or "y_train.npy" if you uploaded it in the shared data directory fit_params={}, # define the fit parameters here ) ``` - Validations: - `name`: - The name must be unique, a string up to 64 characters long. - It can only include alphanumeric characters and underscores. - It must start with a letter and cannot end with an underscore. - A classifier with the same name should already exist in the shared data directory. ### `predict` The `predict` action is used to obtain hard and soft predictions (probabilities). - Inputs: #### `action` Type: `` `str` `` The name of the action. Must be `predict`. - Required: Yes #### `name` Type: `` `str` `` The name of the classifier to be used. - Required: Yes #### `X` Type: `` `array` or `list` or `str` `` The test data. This can be a NumPy array, a list, or a string referencing a filename in the shared data directory. - Required: Yes #### `options["out"]` Type: `` `str` `` The output JSON filename to save the predictions in the shared data directory. If not provided, the predictions are returned in the job result. - Required: No * Usage: ```python job = singularity.run( action="predict", name="classifier_name", # specify the name of the classifier to use here X=X_test, # or "X_test.npy" if you uploaded it to the shared data directory options={ "out": "output.json", }, ) ``` - Validations: - `name`: - The name must be unique, a string up to 64 characters long. - It can only include alphanumeric characters and underscores. - It must start with a letter and cannot end with an underscore. - A classifier with the same name should already exist in the shared data directory. - `options["out"]`: - The filename must be unique, a string up to 64 characters long. - It can only include alphanumeric characters and underscores. - It must start with a letter and cannot end with an underscore. - It must have the `.json` extension. ### `fit_predict` The `fit_predict` action trains a classifier using the training data and then uses it to obtain hard and soft predictions (probabilities). - Inputs: #### `action` Type: `` `str` `` The name of the action. Must be `fit_predict`. - Required: Yes #### `name` Type: `` `str` `` The name of the classifier to be used. - Required: Yes #### `X_train` Type: `` `array` or `list` or `str` `` The training data. This can be a NumPy array, a list, or a string referencing a filename in the shared data directory. - Required: Yes #### `y_train` Type: `` `array` or `list` or `str` `` The training target values. This can be a NumPy array, a list, or a string referencing a filename in the shared data directory. - Required: Yes #### `X_test` Type: `` `array` or `list` or `str` `` The test data. This can be a NumPy array, a list, or a string referencing a filename in the shared data directory. - Required: Yes #### `fit_params` Type: `` `dict` `` Additional parameters to pass to the `fit` method of the classifier. - Required: No #### `options["out"]` Type: `` `str` `` The output JSON filename to save the predictions in the shared data directory. If not provided, the predictions are returned in the job result. - Required: No * Usage: ```python job = singularity.run( action="fit_predict", name="classifier_name", # specify the name of the classifier to use here X_train=X_train, # or "X_train.npy" if you uploaded it in the shared data directory y_train=y_train, # or "y_train.npy" if you uploaded it in the shared data directory X_test=X_test, # or "X_test.npy" if you uploaded it in the shared data directory fit_params={}, # define the fit parameters here options={ "out": "output.json", }, ) ``` - Validations: - `name`: - The name must be unique, a string up to 64 characters long. - It can only include alphanumeric characters and underscores. - It must start with a letter and cannot end with an underscore. - A classifier with the same name should already exist in the shared data directory. - `options["out"]`: - The filename must be unique, a string up to 64 characters long. - It can only include alphanumeric characters and underscores. - It must start with a letter and cannot end with an underscore. - It must have the `.json` extension. ### `create_fit_predict` The `create_fit_predict` action creates a classifier, trains it using the provided training data, and then uses it to obtain hard and soft predictions (probabilities). See an example in of the `create_fit_predict` action in the [guide](/docs/guides/multiverse-computing-singularity#create_fit_predict-example). - Inputs: #### `action` Type: `` `str` `` The name of the action from among `create`, `list`, `fit`, `predict`, `fit_predict`, `create_fit_predict` and `delete`. - Required: Yes #### `name` Type: `` `str` `` The name of the classifier to be used. - Required: Yes #### `quantum_classifier` Type: `` `str` `` Default value: `` `QuantumEnhancedEnsembleClassifier` `` The type of the classifier, for example, `QuantumEnhancedEnsembleClassifier`. - Required: No #### `X_train` Type: `` `array` or `list` or `str` `` The training data. This can be a NumPy array, a list, or a string referencing a filename in the shared data directory. - Required: Yes #### `y_train` Type: `` `array` or `list` or `str` `` The training target values. This can be a NumPy array, a list, or a string referencing a filename in the shared data directory. - Required: Yes #### `X_test` Type: `` `array` or `list` or `str` `` The test data. This can be a NumPy array, a list, or a string referencing a filename in the shared data directory. - Required: Yes #### `fit_params` Type: `` `dict` `` Additional parameters to pass to the `fit` method of the classifier. - Required: No #### `options["save"]` Type: `` `bool` `` Default value: `` `True` `` Whether to save to trained classifier in the shared data directory. - Required: No #### `options["out"]` Type: `` `str` `` The output JSON filename to save the predictions in the shared data directory. If not provided, the predictions are returned in the job result. - Required: No * Usage: ```python job = singularity.run( action="create_fit_predict", name="classifier_name", # specify your custom name for the classifier here num_learners=10, regularization=0.01, optimizer_options={"simulator": True}, X_train=X_train, # or "X_train.npy" if you uploaded it in the shared data directory y_train=y_train, # or "y_train.npy" if you uploaded it in the shared data directory X_test=X_test, # or "X_test.npy" if you uploaded it in the shared data directory fit_params={}, # define the fit parameters here options={ "save": True, "out": "output.json", }, ) ``` - Validations: - `name`: - If `options["save"]` is set to `True`: - The name must be unique, a string up to 64 characters long. - It can only include alphanumeric characters and underscores. - It must start with a letter and cannot end with an underscore. - No classifier with the same name should already exist in the shared data directory. - `options["out"]`: - The filename must be unique, a string up to 64 characters long. - It can only include alphanumeric characters and underscores. - It must start with a letter and cannot end with an underscore. - It must have the `.json` extension.