Singularity Machine Learning API reference

Qiskit Functions
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.
Singularity Machine Learning Qiskit Function guide

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, create, delete, fit, predict, fit_predict, and 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:

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.

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.

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, 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	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	No	`None`
`sampler_options`	`dictionary`	Sampler options. For a complete list of available options, consult the Qiskit Runtime Client documentation	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:

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:

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:

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:

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:

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.

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:

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.

Was this page helpful?

Report a bug, typo, or request content on GitHub.