Add ax kwarg to matplotlib visualization functions

[mtreinish]

Summary

This commit adds support for passing a matplotlib axes to visualization
functions. This enables integrating the qiskit visualizations into a
larger matplotlib visualization. When an ax kwarg is set that input will
be used for the output visualization and a new figure will not be
generated or returned.

Details and comments

Fixes #1950

[1ucian0]

Given that matplotlib calls the module axes, why not calling the argument axes?

[1ucian0]

It seems that the parameters are not optional. Previously working code is breaking :

psi = [0.70710678118654746, 0, 0, 0.70710678118654746]
plot_state_hinton(psi)

---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
<ipython-input-3-7e1883ce9c63> in <module>
      1 psi = [0.70710678118654746, 0, 0, 0.70710678118654746]
----> 2 plot_state_hinton(psi)

~/repos/qiskit-terra/qiskit/visualization/state_visualization.py in plot_state_hinton(rho, title, figsize, ax_real, ax_imag)
     99             fig = ax_real.get_figure()
    100         else:
--> 101             fig = ax_imag.get_figure()
    102         ax1 = ax_real
    103         ax2 = ax_imag

AttributeError: 'NoneType' object has no attribute 'get_figure'

It's not obvious for me how this new options are used. Maybe a more explicit subplot example in the release notes?

[mtreinish]

It seems that the parameters are not optional. Previously working code is breaking :

psi = [0.70710678118654746, 0, 0, 0.70710678118654746]
plot_state_hinton(psi)

---------------------------------------------------------------------------
AttributeError                            Traceback (most recent call last)
<ipython-input-3-7e1883ce9c63> in <module>
      1 psi = [0.70710678118654746, 0, 0, 0.70710678118654746]
----> 2 plot_state_hinton(psi)

~/repos/qiskit-terra/qiskit/visualization/state_visualization.py in plot_state_hinton(rho, title, figsize, ax_real, ax_imag)
     99             fig = ax_real.get_figure()
    100         else:
--> 101             fig = ax_imag.get_figure()
    102         ax1 = ax_real
    103         ax2 = ax_imag

AttributeError: 'NoneType' object has no attribute 'get_figure'

It's not obvious for me how this new options are used. Maybe a more explicit subplot example in the release notes?

It was a typo in plot_state_hinton() fixed in the latest patch. I'll take another look at release note and see if I can come up with a clearer example.

[1ucian0]

do you have any thoughts about #3053 (comment) ?

[mtreinish]

do you have any thoughts about #3053 (comment) ?

Sorry I missed that among the other review comments earlier. I really don't care about the name much, ax is also commonly used in the matplotlib documentation for things that deal with an Axes object. I'd be fine deferring to whatever your preference is, however in this case we are already using ax in an existing API, see: https://github.com/Qiskit/qiskit-terra/blob/master/qiskit/visualization/gate_map.py#L70-L80 so I used ax to be consistent.

[1ucian0]

however in this case we are already using ax in an existing API

Okey. That's a good argument to keep it. Let's merge.

[mtreinish]

@1ucian0 I manually rebased the branch locally to correct the broken merge that was accidentally pushed removing the pylint disable. You should double check that I didn't mess something up in that process because there were a lot of changes in that rebase stack and I might have messed up one of the conflict fixes.