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 () or binary ().
- Required: Yes
- Choices:
spinorbinary
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. 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 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.
Code | Cause |
|---|---|
4600 | The function_size is too small for the problem. The job fails, 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(). |