Compiler Redo

[jaygambetta]

Fixes #978
Fixes #1716

Deprecated execute, compile and circuits_to_qobj and replaced with execute_circuits, transpire and assemble_circuits.

edit (Ali): execute() remains and wraps execute_circuits(), to limit changes.

assemble_circuits takes a list of circuits and makes a qobj. It uses a run_config to make it and supports an additional qobj_header for additional header input. See below and allows #1716 to work. The name change is because it is not a conversion like implied with circuits_to_qobj

transpile takes a list of circuits and a transpile_config to make a new set of circuits (this is why it does not replace compile and is different to the old transpile). This is the ugly code at the moment but we need to rework the transpiler to make it cleaner.

execute_circuits takes a list of circuits, a backend, a run_config, a transpile_config and a qobj_header to simplify running the circuits on a backend.

The deprecated functions are made to call the new functions.

For example for #1716

from qiskit.qobj import QobjHeader
qobj_header = QobjHeader(description = 'paul is so cool')

job_sim = execute_circuits(circuits, backend, qobj_header=qobj_header)

Then to get the description use

job_sim.qobj().header.description

or

job_sim.result().header.description

@nonhermitianI know you wanted job.description but I wonder if this is ok as the search function can call this.

concerns

@ajavadiaI do like having objects but in a wrapper, I wonder if for the user of run_circuits a list long inputs is prefered so for the wrapper user they don't have to make the objects (transpile_config, user_qobj_header, and run_config) to run the circuits.

Todo

[ ] clean up the transpile code (synthesis part).
[x] need to give examples
[x] need to make some more test
[ ] give some optional values to transpile_config could not do this with the backend getting hacked into it.

Follow up PR1

I would be to replace qobj_to_circuits with a function that returns the circuits and the run_config, and a user_qobj_header.

I imagine it is something like

[circuits, run_config, user_qobj_header] = disassemble_qobj(qobj)

follow up PR2

A function to simplify getting the options for the compiler.

[run_config, transpile_config] = default_compiler_configs(backend)

follow up PR3

A function to simplify updating a qobj_runconfig

new_qobj = update_qobj_runconfig(qobj, run_config)

follow up PR4

decide on how to address #1714.

[t-imamichi]

Great. It fixes #883 too.

[1ucian0]

I'm moving this discussion to an issue and adding https://github.com/Qiskit/qiskit-terra/wiki/Terra-high-level-workflow-API.

[ajavadia]

why close this? this already does most of the things, so we can pull request into this branch with any possible changes.

[ajavadia]

I'm merging this and will follow up with a clean up of transpile so that TranspileConfig doesn't take a backend.