--- title: ParityQC Parity Twine Optimizer API reference description: API reference for ParityQC Parity Twine Optimizer, including inputs, outputs, and configuration options source: https://quantum.cloud.ibm.com/docs/en/functions/parity-twine-optimizer/api-reference --- # ParityQC Parity Twine Optimizer API reference ## Inputs See the following list for all input parameters this API accepts. ### `problem` Type: `dict[str, float]` The cost function to be solved. Dictionary keys correspond to qubit labels, values to coefficients. - Required: Yes - Example: `{"()": 3, "(0,)": 1, "(0, 1)": 2, "(1, 2)": -1}` ### `variable_type` Type: `str` Whether the variables are of type `spin` ($s \in \{-1, 1\}$) or `binary` ($x \in \{0, 1\}$). - Required: Yes - Choices: `spin` or `binary` ### `backend_name` Type: `str` Name of backend to use. If not specified, the least busy backend is chosen. - Required: No - Example: `ibm_phoenix` ### `problem_type` Type: `str` Default value: `""` Specifies the type of problem to enable specialized post-processing. At the moment, only `mis` (maximum independent set) is supported. If `mis` is set, the algorithm applies specific post-processing that exploits the MIS structure. If left empty, standard post-processing is applied. - Required: No - Choices: `mis` ### `function_size` Type: `str` Default value: `"M"` Size the job runs at: `"S"`, `"M"`, or `"L"`. The required size depends on the number of variables in `problem` and their interaction density, the fraction of all variable pairs that appear together in a term: up to 50 variables and a density of 0.1 is `"S"`, up to 100 variables and a density of 0.25 is `"M"`, and anything larger is `"L"`. To calculate the size before you submit a job, see [Function sizes](/docs/functions/parity-twine-optimizer#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. `function.sizes_map` returns the mapping from size to compute profile, and `function.default_size` returns the default size. - Required: No - Example: `"L"` ### Options Type: `dict[str, Any]` Input options, including the following: (Optional) Options are specified as a nested dictionary. See the full [list of options](#options-list) and their default values. - Required: No - Example: `{"shots": 1000, "problem_type": "my_problem", "postprocessing_level": 1, "transpile_only": False, "job_tags": ["my_tag"]} ` #### Options list ##### `shots` Type: `int` Default value: `100000` The number of shots to use. ##### `postprocessing_level` Type: `int` Default value: `1` Whether to do classical post-processing or not. Possible values are 0 (no post-processing) and 1 (do post-processing). ##### `transpile_only` Type: `bool` Default value: `False` Boolean for whether only transpilation of the circuit is carried out. If so, circuit metrics are returned. ##### `job_tags` Type: `list[str]` Default value: `None` A label to identify job on IBM Quantum® Platform. - Default: `None` - Example: `["my_job_tag"]` ## Outputs The output of this API is a `dict` object containing solution, solution bitstring, objective value, and metadata. If the `transpile_only` flag is set, only the circuit metric fields are populated with values. Example: ``` { 'solution': {'0': -1, '1': 1, '2': 1}, 'objective_value': -1.0, 'solution_bitstring': '100', 'metadata': { 'circuit_metrics': { 'depth': 23, 'gate_count': 200, 'two_qubit_gate_depth': 4, 'two_qubit_gate_count': 4, 'num_qubits': 3, 'operations': {'delay': 158, 'rz': 18, 'sx': 15, 'cz': 4, 'measure': 3, 'x': 2} }, 'solver_info': { 'variable_mapping': {'0': 0, '1': 1, '2': 2}, 'bitstring_distributions': { 'before_postprocessing': {'011': 3, '001': 1, '110': 1, '111': 3, '101': 1, '010': 1}, 'after_postprocessing': {'011': 4, '100': 6} }, 'best_parameters': { 'beta': [-0.46259546391008877], 'gamma': [0.6181957189727373] } }, 'resource_usage': { 'RUNNING: MAPPING': {'CPU_TIME': 15.536}, 'RUNNING: OPTIMIZING_FOR_HARDWARE': {'CPU_TIME': 0.04}, 'RUNNING: WAITING_FOR_QPU': {'CPU_TIME': 0.0}, 'RUNNING: EXECUTING_QPU': {'QPU_TIME': 8.945}, 'RUNNING: POST_PROCESSING': {'CPU_TIME': 0.765} } } } ``` ### Output structure `solution` Type: `dict[str, int]` Value of solution. Keys correspond to those defined in `problem`. - Example: `{'0': -1, '1': 1, '2': 1}` `objective_value` Type: `float` Cost of the solution. Quantifies the solution quality. - Example: `-1.0` `solution_bitstring` Type: `str` The bitstring corresponding to the lowest cost. - Example: `'100'` `metadata` `circuit_metrics` Type: `dict[str, Any]` Information on the Twine transpilation. `depth` Type: `int` The depth of circuit. `gate_count` Type: `int` The number of gates in circuit. `two_qubit_gate_depth` Type: `int` The two-qubit depth of circuit. `two_qubit_gate_count` Type: `int` The two-qubit count of circuit. `num_qubits` Type: `int` Number of qubits active in circuit. `operations` Type: `dict[str, int]` Gate type (keys) and occurrence (value) in circuit. `solver_info` Type: `dict[str, Any]` Algorithmic insights `variable_mapping` Type: `dict[str, int]` The variable-to-qubit mapping used in the computation. `bitstring_distributions` Type: `dict[str, Any]` A mapping of the basis state and how often it was sampled. `before_postprocessing` Type: `dict[str, int]` Distribution of measured bitstrings before classical post-processing. `after_postprocessing` Type: `dict[str, int]` Distribution of measured bitstrings after classical post-processing. `best_parameters` Type: `dict[str, Any]` Optimized variational training parameters. `beta` Type: `list[float]` Optimized variational parameter beta. `gamma` Type: `list[float]` Optimized variational parameter gamma. `resource_usage` Type: `dict[str, Any]` Information on timing. `RUNNING: MAPPING` Type: `dict[str, float]` CPU time (s) for mapping problem. `RUNNING: OPTIMIZING_FOR_HARDWARE` Type: `dict[str, float]` CPU time (s) for hardware optimization. `RUNNING: WAITING_FOR_QPU` Type: `dict[str, float]` CPU time (s) waiting for QPU. `RUNNING: EXECUTING_QPU` Type: `dict[str, float]` QPU time (s) used. `RUNNING: POST_PROCESSING` Type: `dict[str, float]` CPU time (s) for post processing results. ## Error handling The function reports the following errors that relate to `function_size`. For all error codes, see the [IBM Quantum error codes](/docs/errors). | Code | Cause | | :----- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `4600` | The [`function_size`](#function_size) is too small for the problem. The job fails, 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()`. |