--- title: Kipu Quantum Rimay Quantum Feature Extraction API reference description: API reference for Rimay Quantum Feature Extraction by Kipu Quantum, including inputs, outputs, and error codes source: https://eu-de.quantum.cloud.ibm.com/docs/en/functions/kipu-rimay/api-reference --- # Kipu Quantum Rimay Quantum Feature Extraction API reference - [**Quantum Functions**](/docs/functions/kipu-rimay) — 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. > **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`](#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`](#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](#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`](#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-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](/docs/functions/kipu-rimay#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`](#output_files), which you download with `file_download()`. - Example: `{"output_files": ["_xq_train.csv", "_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"`: `["_xq_train.csv"]`, or `["_xq_train.csv", "_xq_test.csv"]` when a test set was given - `"transform"`: `["_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 `` 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 | | :-------------------------- | :-------------------------------- | :------------ | | `_xq_train.csv` | `"fit-transform"` | `x_train` | | `_xq_test.csv` | `"fit-transform"` with a test set | `x_test` | | `_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](/docs/errors), 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`](#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`](#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 [support@kipu-quantum.com](mailto:support@kipu-quantum.com) with the job ID if it recurs. |