Kipu Quantum Rimay Quantum Feature Extraction API reference

Quantum Functions
Quantum 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 quantum function.
Rimay Quantum Feature Extraction quantum function guide

Keep your mapping_id

A "fit-transform" run returns a mapping_id, which is the only way to reach the mapping it fitted. It cannot be looked up or recovered, and it authorizes the use of that mapping, so treat it like a credential. If you lose it, you have to fit a new mapping, which costs another run on quantum hardware.

Inputs

Which inputs a run needs depends on its mode. A "delete" run needs only mode and mapping_id.

`mode`

Type: str

What the run does:

"fit-transform": Fit a new quantum feature mapping on the training data, map the training data and, if given, the test data with it, and store the mapping.
"transform": Map new data with a mapping fitted earlier, identified by mapping_id.
"delete": Remove a stored mapping. This does no quantum work.
Required: Yes
Example: "fit-transform"

`input_file`

Type: list[str]

Names of the CSV files to read, uploaded beforehand with file_upload(). The list is positional: its length and order define what each file is. See Input files for the file format. A job reads the files when it starts, so an upload under the same name before then replaces what it reads; give the files of jobs that run at the same time their own names.

"fit-transform": [x_train, y_train], or [x_train, y_train, x_test] to map a test set in the same run
"transform": [x_inference]
Required: For "fit-transform" and "transform"
Example: ["x_train.csv", "y_train.csv", "x_test.csv"]

`backend_name`

Type: str

Name of the IBM Quantum processor that runs the circuits. It must be a processor your instance has access to, with at least as many qubits as the data has features.

A "transform" run must name the processor of the fit that produced its mapping_id. Any other processor is refused before anything is submitted.

Required: For "fit-transform" and "transform"
Example: "ibm_boston"

`shots`

Type: int

Number of shots per circuit. Must be at least 1. Rimay runs one circuit per sample, so the number of samples times shots must not exceed 10 million. A "transform" run uses the shot count of its fit and ignores this value.

Required: For "fit-transform" and "transform"
Example: 5000

`mapping_id`

Type: str

Identifies a stored mapping. Returned by a "fit-transform" run in the mapping_id output. A "fit-transform" run ignores it, because it always fits a new mapping.

Required: For "transform" and "delete"
Example: result["mapping_id"]

`function_size`

Type: str

Default value: "M"

Size the job runs at, which is "S", "M", or "L". Pass it to rimay.run(...) with the other inputs. The required size depends on the number of samples the job maps: up to 2,999 is "S", up to 9,999 is "M", and more is "L". Training and test samples count together, and labels do not count. To calculate the size before you submit a job, see Function sizes. If the size is too small, the job fails with error 4600. If the size is larger than the job needs, the job runs normally and records a 4601 advisory event. A "delete" run maps no samples and needs no size.

Required: No
Example: "L"

Input files

Every file is a CSV file with a header row.
Every column of a feature file (x_train, x_test, x_inference) is one feature, and every value must be numeric. Encode categorical features first, for example by one-hot encoding.
y_train holds exactly one numeric column, with one label per row of x_train.
x_test and x_inference must have the same columns as x_train, in the same order.

Limits

Every feature is mapped to one qubit, so a run can hold at most as many features as the processor has qubits.
A run can hold at most 15,000 samples, training and test samples together.
A run can request at most 10 million executions, which is the number of samples times shots.
A job must finish within 24 hours, including the time its circuits wait in the processor's queue. A job that runs longer is stopped without a result.

Output

Type: dict[str, Any]

Metadata of the run. The quantum-transformed features are written to the files listed in output_files, which you download with file_download().

Example: {"output_files": ["<job_id>_xq_train.csv", "<job_id>_xq_test.csv"], "mode": "fit-transform", "backend_name": "ibm_boston", "rows_mapped": 1000, "mapping_id": "..."}

Result dictionary

`output_files`

Type: list[str]

Names of the files the run wrote. Each name starts with the ID of the job that wrote it (job.job_id), so a later run never overwrites the files of an earlier one. Download the files by the names listed here.

"fit-transform": ["<job_id>_xq_train.csv"], or ["<job_id>_xq_train.csv", "<job_id>_xq_test.csv"] when a test set was given
"transform": ["<job_id>_xq_inference.csv"]
"delete": []

`mode`

Type: str

The mode of the run.

`backend_name`

Type: str

The processor the circuits ran on.

Modes: "fit-transform", "transform"

`rows_mapped`

Type: int

Number of samples mapped, which equals the number of circuits run. Training and test samples count together.

Modes: "fit-transform", "transform"

`mapping_id`

Type: str

The mapping the run fitted, used, or deleted. Pass the one a "fit-transform" run returns to later "transform" and "delete" runs.

`deleted`

Type: bool

True when the mapping was removed.

Modes: "delete"

`metadata`

Type: dict[str, Any]

Information about the run.

version (str): the version of the function that ran.
resource_usage (dict): one entry per execution phase the run went through, "RUNNING: MAPPING" and "RUNNING: POST_PROCESSING", and on a quantum processor usually "RUNNING: WAITING_FOR_QPU" as well, each {"CPU_TIME": float, "QPU_TIME": float | None} in seconds. CPU_TIME is wall-clock time. "RUNNING: WAITING_FOR_QPU" is the time the jobs waited in the IBM queue, taken from IBM's job timestamps and not counted in "RUNNING: MAPPING"; it is absent when IBM does not report those timestamps for every job, and the wait is then part of "RUNNING: MAPPING". On a quantum processor, the QPU time that IBM billed is booked against "RUNNING: MAPPING". IBM finishes its usage calculation some time after a job finishes, and the run waits up to about a minute for it; usage still being calculated then is not included, and the final usage shows on IBM Quantum Platform. QPU_TIME is None when the usage could not be read from IBM.
Example: {"version": "0.3.0", "resource_usage": {"RUNNING: MAPPING": {"CPU_TIME": 12.4, "QPU_TIME": 6.0}, "RUNNING: WAITING_FOR_QPU": {"CPU_TIME": 28.8, "QPU_TIME": 0.0}, "RUNNING: POST_PROCESSING": {"CPU_TIME": 0.3, "QPU_TIME": 0.0}}}

Output files

<job_id> is the ID of the job that wrote the file. Every output file is a CSV file with a header row, one row per row of the corresponding input file, in the same order, and one column per quantum-transformed feature. Columns whose names start with corr_ hold two-body expectation values. The files hold no label column; the labels stay in your own y_train file.

File	Written by	Rows from
`<job_id>_xq_train.csv`	`"fit-transform"`	`x_train`
`<job_id>_xq_test.csv`	`"fit-transform"` with a test set	`x_test`
`<job_id>_xq_inference.csv`	`"transform"`	`x_inference`

Error handling

Before a job is created, IBM Quantum checks the inputs against Rimay's input schema. An input that is missing or unknown, a value of the wrong type, the wrong number of files in input_file, a backend_name that does not start with ibm_, or shots smaller than 1 is refused right away with an error that names the input. No job is created and nothing is billed. To check inputs without running a job, call rimay.validate_arguments({...}) with the same inputs you would pass to rimay.run.

Every error Rimay reports for a job carries a code from the IBM Quantum error codes, a message, and a solution that names the value passed and the value allowed. Fetch it with job.result() when the job status is ERROR.

Code	Cause
`1221`	A required parameter is missing or has the wrong type, or `mode` is not valid.
`1221`	A file named in `input_file` was not uploaded, or `input_file` holds the wrong number of files for the mode.
`1221`	`x_train` and `y_train` have different numbers of rows, `x_test` does not have the columns of `x_train`, `y_train` is not one numeric column, or a feature column is not numeric.
`1221`	`mapping_id` does not match a stored mapping, because it is mistyped or the mapping was deleted.
`1221`	A `"transform"` run names a different `backend_name` than the fit that produced its mapping.
`1216`	The instance the job runs under has no processor named `backend_name`. The solution lists the processors it does have.
`1200`	The API key does not have access to the instance the job runs under.
`1219`	IBM Quantum did not accept the API key the job runs under: it may be incorrect, expired, or revoked.
`1279`	IBM Quantum could not find the instance the job runs under, or the instance is no longer active.
`1229`	The processor named `backend_name` is not accepting jobs right now, for example because it is in maintenance.
`1233`	The processor named `backend_name` is reserved and runs only the jobs of its reservation.
`1218`	The instance the job runs under has reached its usage limit.
`1010`	IBM Quantum reported the job as failed. The solution names IBM's error code, if IBM gave one.
`1305`	The job ran longer than the maximum execution time IBM Quantum allows.
`1323`	The function could not access its storage, or could not reach IBM Quantum on your behalf. Retry the job, and contact support with the job ID if it recurs.
`3200`	`backend_name` does not start with `ibm_`.
`4500`	The data has more features than the processor has qubits.
`4600`	The `function_size` is too small for the number of samples. The job fails before anything is submitted, and the message names the size to use.
`4601`	The `function_size` is larger than the job needs. The job runs normally and records an advisory event that you can read with `job.events()`.
`6000`	The number of samples times `shots` exceeds 10 million executions.
`6001`	`shots` is smaller than 1.
`6002`	The data has more samples, or more features, than a run allows.
`1500`	An unexpected error. Retry the job, and contact [email protected] with the job ID if it recurs.

Was this page helpful?

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