qiskit.QuantumProgram

class qiskit.QuantumProgram(specs=None)[source]

Bases: object

Quantum Program Class.

Class internal properties.

Elements that are not python identifiers or string constants are denoted by “–description (type)–”. For example, a circuit’s name is denoted by “–circuit name (string)–” and might have the value “teleport”.

Internal:

__quantum_registers (list[dic]): An dictionary of quantum registers
    used in the quantum program.
    __quantum_registers =
        {
        --register name (string)--: QuantumRegister,
        }
__classical_registers (list[dic]): An ordered list of classical
    registers used in the quantum program.
    __classical_registers =
        {
        --register name (string)--: ClassicalRegister,
        }
__quantum_program (dic): An dictionary of quantum circuits
    __quantum_program =
        {
        --circuit name (string)--:  --circuit object --,
        }
__init_circuit (obj): A quantum circuit object for the initial quantum
    circuit

Methods

__init__([specs])
add_circuit([name, quantum_circuit]) Add a new circuit based on an Object representation.
available_backends([compact]) All the backends that are seen by QISKIT.
compile([name_of_circuits, backend, config, …]) Compile the circuits into the execution list.
create_circuit([name, qregisters, cregisters]) Create a empty Quantum Circuit in the Quantum Program.
create_classical_register([name, size]) Create a new Classical Register.
create_classical_registers(registers_array) Create a new set of Classical Registers based on a array of them.
create_quantum_register([name, size]) Create a new Quantum Register.
create_quantum_registers(register_array) Create a new set of Quantum Registers based on a array of them.
destroy_circuit(name) Destroy a Quantum Circuit in the Quantum Program.
destroy_classical_register(name) Destroy an existing Classical Register.
destroy_classical_registers(registers_array) Destroy a set of Classical Registers based on a array of them.
destroy_quantum_register(name) Destroy an existing Quantum Register.
destroy_quantum_registers(register_array) Destroy a set of Quantum Registers based on a array of them.
disable_logs() Disable the console output of the logging messages.
enable_logs([level]) Enable the console output of the logging messages.
execute([name_of_circuits, backend, config, …]) Execute, compile, and run an array of quantum circuits).
get_api() Returns a function handle to the API.
get_api_config() Return the program specs.
get_backend_calibration(backend) Return the online backend calibrations.
get_backend_configuration(backend) Return the configuration of the backend.
get_backend_parameters(backend) Return the online backend parameters.
get_backend_status(backend) Return the online backend status.
get_circuit([name]) Return a Circuit Object by name.
get_circuit_names() Return all the names of the quantum circuits.
get_classical_register([name]) Return a Classical Register by name.
get_classical_register_names() Return all the names of the classical Registers.
get_compiled_configuration(qobj, name) Get the compiled layout for the named circuit and backend.
get_compiled_qasm(qobj, name) Return the compiled circuit in qasm format.
get_execution_list(qobj[, print_func]) Print the compiled circuits that are ready to run.
get_initial_circuit() Return the initialization Circuit.
get_qasm([name]) Get qasm format of circuit by name.
get_qasms([list_circuit_name]) Get qasm format of circuit by list of names.
get_quantum_register([name]) Return a Quantum Register by name.
get_quantum_register_names() Return all the names of the quantum Registers.
load([file_name]) Load Quantum Program Json file into the Quantum Program object.
load_qasm_file(qasm_file[, name, basis_gates]) Load qasm file into the quantum program.
load_qasm_text(qasm_string[, name, basis_gates]) Load qasm string in the quantum program.
online_backends() Get the online backends.
online_devices() Gets online devices via QX API calls.
online_simulators() Gets online simulators via QX API calls.
reconfig(qobj[, backend, config, shots, …]) Change configuration parameters for a compile qobj.
run(qobj[, timeout]) Run a program (a pre-compiled quantum program).
run_batch(qobj_list[, timeout]) Run various programs (a list of pre-compiled quantum programs).
save([file_name, beauty]) Save Quantum Program in a Json file.
set_api(token, url[, hub, group, project, …]) Setup the API.
set_api_hubs_config(hub, group, project) Update the API hubs configuration, replacing the previous one.
add_circuit(name=None, quantum_circuit=None)[source]

Add a new circuit based on an Object representation.

Parameters:
  • name (str or None) – the name of the circuit to add. If None, an automatically generated identifier will be assigned to the circuit.
  • quantum_circuit (QuantumCircuit) – a quantum circuit to add to the program-name
Raises:

QISKitError – if quantum_circuit is None, as the attribute is optional only for not breaking backwards compatibility (as it is placed after an optional argument).

available_backends(compact=True)[source]

All the backends that are seen by QISKIT.

Deprecated since version 0.5: This method will be deprecated in upcoming versions. Using the qiskit.backends family of functions instead is recommended.

compile(name_of_circuits=None, backend='local_qasm_simulator', config=None, basis_gates=None, coupling_map=None, initial_layout=None, shots=1024, max_credits=10, seed=None, qobj_id=None, hpc=None, skip_transpiler=False, skip_translation=False)[source]

Compile the circuits into the execution list.

Deprecated since version 0.5: The coupling_map parameter as a dictionary will be deprecated in upcoming versions. Using the coupling_map as a list is recommended.

create_circuit(name=None, qregisters=None, cregisters=None)[source]

Create a empty Quantum Circuit in the Quantum Program.

Parameters:
  • name (str or None) – the name of the circuit. If None, an automatically generated identifier will be assigned.
  • qregisters (list(QuantumRegister)) – is an Array of Quantum Registers by object reference
  • cregisters (list(ClassicalRegister)) – is an Array of Classical Registers by object reference
Returns:

A quantum circuit is created and added to the

Quantum Program

Return type:

QuantumCircuit

create_classical_register(name=None, size=1)[source]

Create a new Classical Register.

Parameters:
  • name (str or None) – the name of the classical register. If None, an automatically generated identifier will be assigned..
  • size (int) – the size of the classical register
Returns:

internal reference to a classical register

in __classical_registers

Return type:

ClassicalRegister

Raises:

QISKitError – if the register already exists in the program.

create_classical_registers(registers_array)[source]

Create a new set of Classical Registers based on a array of them.

Parameters:registers_array (list[dict]) –

An array of classical registers in dictionary format. For example:

[{"name": "cr", "size": 4},
    ...
]

Any other key in the dictionary will be ignored. If “name” is not defined (or None) a random name wil be assigned.

Returns:Array of classical registers objects
Return type:list(ClassicalRegister)
create_quantum_register(name=None, size=1)[source]

Create a new Quantum Register.

Parameters:
  • name (str or None) – the name of the quantum register. If None, an automatically generated identifier will be assigned.
  • size (int) – the size of the quantum register
Returns:

internal reference to a quantum register in

__quantum_registers

Return type:

QuantumRegister

Raises:

QISKitError – if the register already exists in the program.

create_quantum_registers(register_array)[source]

Create a new set of Quantum Registers based on a array of them.

Parameters:register_array (list[dict]) –

An array of quantum registers in dictionary format. For example:

[{"name": "qr", "size": 4},
    ...
]

Any other key in the dictionary will be ignored. If “name” is not defined (or None) a random name wil be assigned.

Returns:Array of quantum registers objects
Return type:list(QuantumRegister)
destroy_circuit(name)[source]

Destroy a Quantum Circuit in the Quantum Program. This will not destroy any registers associated with the circuit.

Parameters:name (str) – the name of the circuit
Raises:QISKitError – if the register does not exist in the program.
destroy_classical_register(name)[source]

Destroy an existing Classical Register.

Parameters:name (str) – the name of the classical register
Raises:QISKitError – if the register does not exist in the program.
destroy_classical_registers(registers_array)[source]

Destroy a set of Classical Registers based on a array of them.

Parameters:registers_array (list[dict]) –

An array of classical registers in dictionary format. For example:

[{"name": "cr"},
    ...
]

Any other key in the dictionary will be ignored.

destroy_quantum_register(name)[source]

Destroy an existing Quantum Register.

Parameters:name (str) – the name of the quantum register
Raises:QISKitError – if the register does not exist in the program.
destroy_quantum_registers(register_array)[source]

Destroy a set of Quantum Registers based on a array of them.

Parameters:register_array (list[dict]) –

An array of quantum registers in dictionary format. For example:

[{"name": "qr"},
    ...
]

Any other key in the dictionary will be ignored.

disable_logs()[source]

Disable the console output of the logging messages.

Disable the output of logging messages (above level level) to the console, by removing the handlers from the qiskit logger.

Note

This is a convenience method over the standard Python logging facilities, and modifies the configuration of the ‘qiskit.*’ loggers. If finer control over the logging configuration is needed, it is encouraged to bypass this method.

enable_logs(level=20)[source]

Enable the console output of the logging messages.

Enable the output of logging messages (above level level) to the console, by configuring the qiskit logger accordingly.

Params:
level (int): minimum severity of the messages that are displayed.

Note

This is a convenience method over the standard Python logging facilities, and modifies the configuration of the ‘qiskit.*’ loggers. If finer control over the logging configuration is needed, it is encouraged to bypass this method.

execute(name_of_circuits=None, backend='local_qasm_simulator', config=None, timeout=60, basis_gates=None, coupling_map=None, initial_layout=None, shots=1024, max_credits=3, seed=None, hpc=None, skip_transpiler=False, skip_translation=False)[source]

Execute, compile, and run an array of quantum circuits).

This builds the internal “to execute” list which is list of quantum circuits to run on different backends.

Parameters:
  • name_of_circuits (list[str] or str or None) – circuit names to be executed. If None, all the circuits will be executed.
  • backend (str) – a string representing the backend to compile to.
  • config (dict) – a dictionary of configurations parameters for the compiler.
  • timeout (int) – Total time to wait until the execution stops
  • basis_gates (str) – a comma separated string and are the base gates, which by default are: u1,u2,u3,cx,id.
  • coupling_map (list) –

    A graph of coupling:

    [
        [control0(int), target0(int)],
        [control1(int), target1(int)],
    ]
    
    eg. [[0, 2], [1, 2], [3, 2]]
    
  • initial_layout (dict) – A mapping of qubit to qubit { (“q”, start(int)): (“q”, final(int)), … } eg. { (“q”, 0): (“q”, 0), (“q”, 1): (“q”, 1), (“q”, 2): (“q”, 2), (“q”, 3): (“q”, 3) }
  • shots (int) – the number of shots
  • max_credits (int) – the max credits to use 3, or 5
  • seed (int) – the initial seed the simulators use
  • hpc (dict) –

    This will setup some parameter for ibmq_qasm_simulator, using a JSON-like format like:

    {
        'multi_shot_optimization': Boolean,
        'omp_num_threads': Numeric
    }
    
  • skip_transpiler (bool) – If True, bypass most of the compilation process and creates a qobj with minimal check nor translation
Returns:

status done and populates the internal __quantum_program with the data.

Return type:

Result

Deprecated since version 0.5: The coupling_map parameter as a dictionary will be deprecated in upcoming versions. Using the coupling_map as a list is recommended.

get_api()[source]

Returns a function handle to the API.

Deprecated since version 0.5: This method will be deprecated in upcoming versions. Using the API object instead is recommended.

get_api_config()[source]

Return the program specs.

Deprecated since version 0.5: This method will be deprecated in upcoming versions. Using the API object instead is recommended.

get_backend_calibration(backend)[source]

Return the online backend calibrations.

The return is via QX API call.

Parameters:

backend (str) – Name of the backend.

Returns:

The calibration of the named backend.

Return type:

dict

Raises:
  • ConnectionError – if the API call failed.
  • LookupError – If a configuration for the named backend can’t be found.

Deprecated since version 0.5: This method will be deprecated in upcoming versions. Using the qiskit.backends family of functions instead is recommended.

get_backend_configuration(backend)[source]

Return the configuration of the backend.

The return is via QX API call.

Parameters:

backend (str) – Name of the backend.

Returns:

The configuration of the named backend.

Return type:

dict

Raises:
  • ConnectionError – if the API call failed.
  • LookupError – if a configuration for the named backend can’t be found.

Deprecated since version 0.5: This method will be deprecated in upcoming versions. Using the qiskit.backends family of functions instead is recommended.

get_backend_parameters(backend)[source]

Return the online backend parameters.

The return is via QX API call.

Parameters:

backend (str) – Name of the backend.

Returns:

The configuration of the named backend.

Return type:

dict

Raises:
  • ConnectionError – if the API call failed.
  • LookupError – If a configuration for the named backend can’t be found.

Deprecated since version 0.5: This method will be deprecated in upcoming versions. Using the qiskit.backends family of functions instead is recommended.

get_backend_status(backend)[source]

Return the online backend status.

It uses QX API call or by local backend is the name of the local or online simulator or experiment.

Parameters:

backend (str) – The backend to check

Returns:

{‘available’: True}

Return type:

dict

Raises:
  • ConnectionError – if the API call failed.
  • ValueError – if the backend is not available.

Deprecated since version 0.5: This method will be deprecated in upcoming versions. Using the qiskit.backends family of functions instead is recommended.

get_circuit(name=None)[source]

Return a Circuit Object by name.

Parameters:

name (str or None) – the name of the quantum circuit. If None and there is only one circuit available, returns that one.

Returns:

The quantum circuit with this name

Return type:

QuantumCircuit

Raises:
  • KeyError – if the circuit is not on the quantum program.
  • QISKitError – if the register does not exist in the program.
get_circuit_names()[source]

Return all the names of the quantum circuits.

get_classical_register(name=None)[source]

Return a Classical Register by name.

Parameters:

name (str or None) – the name of the classical register. If None and there is only one classical register available, returns that one.

Returns:

The classical register with this name.

Return type:

ClassicalRegister

Raises:
  • KeyError – if the classical register is not on the quantum program.
  • QISKitError – if the register does not exist in the program.
get_classical_register_names()[source]

Return all the names of the classical Registers.

get_compiled_configuration(qobj, name)[source]

Get the compiled layout for the named circuit and backend.

Parameters:
  • name (str) – the circuit name
  • qobj (dict) – the qobj
Returns:

the config of the circuit.

Return type:

dict

Raises:

QISKitError – if the circuit has no configurations

get_compiled_qasm(qobj, name)[source]

Return the compiled circuit in qasm format.

Parameters:
  • qobj (dict) – the qobj
  • name (str) – name of the quantum circuit
Returns:

the QASM of the compiled circuit.

Return type:

str

Raises:

QISKitError – if the circuit has no configurations

get_execution_list(qobj, print_func=<built-in function print>)[source]

Print the compiled circuits that are ready to run.

Note

This method is intended to be used during interactive sessions, and prints directly to stdout instead of using the logger by default. If you set print_func with a log function (eg. log.info) it will be used instead of the stdout.

Returns:names of the circuits in qobj
Return type:list(str)
get_initial_circuit()[source]

Return the initialization Circuit.

get_qasm(name=None)[source]

Get qasm format of circuit by name.

Parameters:name (str or None) – name of the circuit. If None and only one circuit is available, that one is selected.
Returns:The quantum circuit in qasm format
Return type:str
Raises:QISKitError – if the register does not exist in the program.
get_qasms(list_circuit_name=None)[source]

Get qasm format of circuit by list of names.

Parameters:list_circuit_name (list[str] or None) – names of the circuit. If None, it gets all the circuits in the program.
Returns:List of quantum circuit in qasm format
Return type:list(QuantumCircuit)
Raises:QISKitError – if the register does not exist in the program.
get_quantum_register(name=None)[source]

Return a Quantum Register by name.

Parameters:

name (str or None) – the name of the quantum register. If None and there is only one quantum register available, returns that one.

Returns:

The quantum register with this name.

Return type:

QuantumRegister

Raises:
  • KeyError – if the quantum register is not on the quantum program.
  • QISKitError – if the register does not exist in the program.
get_quantum_register_names()[source]

Return all the names of the quantum Registers.

load(file_name=None)[source]

Load Quantum Program Json file into the Quantum Program object.

Parameters:file_name (str) – file name and path.
Returns:The dictionary with the status and result of the operation
Return type:dict
Raises:LookupError – if the file_name is not correct, or reading from the file resulted in an error.
load_qasm_file(qasm_file, name=None, basis_gates='u1, u2, u3, cx, id')[source]

Load qasm file into the quantum program.

Parameters:
  • qasm_file (str) – a string for the filename including its location.
  • name (str or None) – the name of the quantum circuit after loading qasm text into it. If no name is give the name is of the text file.
  • basis_gates (str) – basis gates for the quantum circuit.
Returns:

Adds a quantum circuit with the gates given in the qasm file to the quantum program and returns the name to be used to get this circuit

Return type:

str

Raises:

QISKitError – if the file cannot be read.

load_qasm_text(qasm_string, name=None, basis_gates='u1, u2, u3, cx, id')[source]

Load qasm string in the quantum program.

Parameters:
  • qasm_string (str) – a string for the file name.
  • name (str or None) – the name of the quantum circuit after loading qasm text into it. If no name is give the name is of the text file.
  • basis_gates (str) – basis gates for the quantum circuit.
Returns:

Adds a quantum circuit with the gates given in the qasm string to the quantum program.

Return type:

str

online_backends()[source]

Get the online backends.

Queries network API if it exists and gets the backends that are online.

Returns:
List of online backends names if the online api has been set or an empty
list if it has not been set.
Return type:list(str)
Raises:ConnectionError – if the API call failed.

Deprecated since version 0.5: This method will be deprecated in upcoming versions. Using the qiskit.backends family of functions instead is recommended.

online_devices()[source]

Gets online devices via QX API calls.

Returns:List of online devices names.
Return type:list(str)
Raises:ConnectionError – if the API call failed.

Deprecated since version 0.5: This method will be deprecated in upcoming versions. Using the qiskit.backends family of functions instead is recommended.

online_simulators()[source]

Gets online simulators via QX API calls.

Returns:List of online simulator names.
Return type:list(str)
Raises:ConnectionError – if the API call failed.

Deprecated since version 0.5: This method will be deprecated in upcoming versions. Using the qiskit.backends family of functions instead is recommended.

reconfig(qobj, backend=None, config=None, shots=None, max_credits=None, seed=None)[source]

Change configuration parameters for a compile qobj. Only parameters which don’t affect the circuit compilation can change, e.g., the coupling_map cannot be changed here!

Notes

If the inputs are left as None then the qobj is not updated

Parameters:
  • qobj (dict) – already compile qobj
  • backend (str) – see .compile
  • config (dict) – see .compile
  • shots (int) – see .compile
  • max_credits (int) – see .compile
  • seed (int) – see .compile
Returns:

updated qobj

Return type:

qobj

run(qobj, timeout=60)[source]

Run a program (a pre-compiled quantum program). This function will block until the Job is processed.

The program to run is extracted from the qobj parameter.

Parameters:
  • qobj (dict) – the dictionary of the quantum object to run.
  • timeout (int) – Total time to wait until the execution stops
Returns:

A Result (class).

Return type:

Result

run_batch(qobj_list, timeout=120)[source]

Run various programs (a list of pre-compiled quantum programs). This function will block until all programs are processed.

The programs to run are extracted from qobj elements of the list.

Parameters:
  • qobj_list (list(dict)) – The list of quantum objects to run.
  • timeout (int) – Total time to wait until the execution stops
Returns:

A list of Result (class). The list will contain one Result object per qobj in the input list.

Return type:

list(Result)

save(file_name=None, beauty=False)[source]

Save Quantum Program in a Json file.

Parameters:
  • file_name (str) – file name and path.
  • beauty (boolean) – save the text with indent 4 to make it readable.
Returns:

The dictionary with the status and result of the operation

Return type:

dict

Raises:

LookupError – if the file_name is not correct, or writing to the file resulted in an error.

set_api(token, url, hub=None, group=None, project=None, proxies=None, verify=True)[source]

Setup the API.

Fills the __api, and __api_config variables. Does not catch exceptions from IBMQuantumExperience.

Parameters:
  • token (str) – The token used to register on the online backend such as the quantum experience.
  • url (str) – The url used for online backend such as the quantum experience.
  • hub (str) – The hub used for online backend.
  • group (str) – The group used for online backend.
  • project (str) – The project used for online backend.
  • proxies (dict) – Proxy configuration for the API, as a dict with ‘urls’ and credential keys.
  • verify (bool) – If False, ignores SSL certificates errors.
Raises:
  • ConnectionError – if the API instantiation failed.
  • QISKitError – if no hub, group or project were specified.

Deprecated since version 0.5: This method will be deprecated in upcoming versions. Using the API object instead is recommended.

set_api_hubs_config(hub, group, project)[source]

Update the API hubs configuration, replacing the previous one.

hub (str): The hub used for online backend. group (str): The group used for online backend. project (str): The project used for online backend.

Deprecated since version 0.5: This method will be deprecated in upcoming versions. Using the API object instead is recommended.