Expose process-count limits on a per-transpile basis

[jakelishman]

What should we add?

It's currently possible to limit the number of processes used by all calls to transpile in a given Python process by the configuration file entry num_processes, or by the environment variable QISKIT_NUM_PROCS, but both of these are only read on import qiskit, and affect every call to transpile.

It would be good to expose a num_processes kwarg in transpile, which overrides either of these two options, and can be used to restrict an individual call to certain behaviour. We already have the right kwarg available in parallel.parallel_map, so exposing this to users should mostly be as straightforward as adding an option to transpile and propagating it through.

We might want to re-arrange the internal logic of parallel_map a little so that it's easier to pass num_processes=None without clobbering its internal default of taking the value from the environment if the option is empty.

[Ca1eb3]

I would like to give this one a go. My understanding is that we want the option in Transpile to override the option in the environment configuration. Is there any restriction to this? Do we want the num_processes in transpile to be restricted to less than/equal to processes in the overall environment config or are there cases in which the number of processes in the single transpilation may want to exceed the processes allowed by the environment as a whole?

[jakelishman]

Thanks @Ca1eb3!

I don't think there's any reason to attempt to limit the number of processes requested, and it might even be the case that a user deliberately wants to use more processes than they have virtual CPUs if they have some really funky transpiler pass that's dominated (somehow) by IO.

The usual priority order in this sort of situation is (from highest priority to lowest):

1. Keyword arguments given explicitly
2. An argument set by environment variable (i.e. QISKIT_NUM_PROCS in this case)
3. An argument read from a user's configuration file
4. The system default

We should keep that order of priority, and lower-priority items shouldn't affect the result if a higher-priority item is given. We might need to tweak the parallel_map function so that it doesn't store "item 4" of my list as the default, so it's easier for the more user-facing functions like transpile and PassManager.run to simply have num_procs=None, and pass that on to mean "item 1 was not given", and have the logic for "system default" be only in parallel_map.

Let me know if you've got any more questions.