Add barrier labels and display in 3 circuit drawers

[enavarro51]

Summary

Fixes #8428
Fixes #1298

Details and comments

This PR adds a label parameter to the Barrier class and displays the label at the top of the barrier in the 3 circuit drawers. The existing label on snapshot directives is now also displayed. The display in the 'latex' drawer may not be optimal, but there are limitations in qcircuit for displaying text outside boxes. The info is still readable and does not overwrite any gate info.

qc = QuantumCircuit(2)
qc.x(0)
qc.y(1)
qc.barrier()
qc.y(0)
qc.x(1)
qc.barrier(label="End Y/X")
qc.draw('text')

     ┌───┐ ░ ┌───┐ End Y/X 
q_0: ┤ X ├─░─┤ Y ├────░────
     ├───┤ ░ ├───┤    ░    
q_1: ┤ Y ├─░─┤ X ├────░────
     └───┘ ░ └───┘    ░    

[qiskit-bot]

Thank you for opening a new pull request.

Before your PR can be merged it will first need to pass continuous integration tests and be reviewed. Sometimes the review process can be slow, so please be patient.

While you're waiting, please feel free to review other open PRs. While only a subset of people are authorized to approve pull requests for merging, everyone is encouraged to review open pull requests. Doing reviews helps reduce the burden on the core team and helps make the project's code better for everyone.

One or more of the the following people are requested to review this:

• @Qiskit/terra-core
• @enavarro51

[coveralls]

Pull Request Test Coverage Report for Build 2890221517

• 13 of 21 (61.9%) changed or added relevant lines in 5 files are covered.
• 4 unchanged lines in 3 files lost coverage.
• Overall coverage increased (+0.002%) to 84.051%

---

Changes Missing Coverage	Covered Lines	Changed/Added Lines	%
qiskit/visualization/matplotlib.py	0	8	0.0%

Files with Coverage Reduction	New Missed Lines	%
qiskit/extensions/simulator/snapshot.py	1	76.74%
qiskit/visualization/matplotlib.py	1	25.29%
qiskit/extensions/quantum_initializer/squ.py	2	79.78%

Totals
Change from base Build 2882958684:	0.002%
Covered Lines:	56322
Relevant Lines:	67009

---

💛 - Coveralls

[jakelishman]

This looks great, thanks Edwin. How well does it handle barriers that don't include the top-most qubit in each of the drawers? I had a quick play, and I think the text drawer adds an extra blank line which messes up subsequent spanning gates:

import qiskit
qc = qiskit.QuantumCircuit(6)
qc.barrier((0, 1), label="a")
qc.barrier((3, 4, 5), label="b")
qc.cx(1, 4)
qc.draw()

gives

      a
q_0: ─░──────
      ░
q_1: ─░───■──
      ░   │
q_2: ─────┼──
          │
      b
q_3: ─░──────
      ░ ┌─┴─┐
q_4: ─░─┤ X ├
      ░ └───┘
q_5: ─░──────
      ░

I guess it's something to do with the layer joining logic? It seems to work fine in the mpl drawer (though a little nitpick: the font of the label is rather small).

The latex form overlapping the barrier isn't ideal, but then again, the barriers don't produce a particularly great effect in the latex drawer anyway. Let's not worry about it.

[enavarro51]

I'll dig into the text problem. It's repeatable. Replacing the barrier piece with text should not change the connections.

(Edit) This relates to vertical_compression. It can be set by the user or it happens when there needs to be space for text to display between gates vertically. Turns out this code does this,

qc = QuantumCircuit(6)
qc.cx(1, 4)
qc.x(1)
qc.draw('text', vertical_compression="low")

q_0: ──────────
               
          ┌───┐
q_1: ──■──┤ X ├
       │  └───┘
               
q_2: ──────────
               
               
q_3: ──────────
               
     ┌─┴─┐     
q_4: ┤ X ├─────
     └───┘     
               
q_5: ──────────
               

So this is something that needs to be addressed for controlled gates with low_compression. I assume open a separate issue for this.

[enavarro51]

Also on the font size for 'mpl' drawer. There are 2 defined font sizes in the styles - fontsize - fs and subfontsize - sfs, which users can change by setting the style parameter. I thought I would need to use sfs for the barrier label to avoid interfering with a control label, but after testing it, I think fs will work fine. I'll make the change.

Done in 1a17e25.

[jakelishman]

Thanks for the changes Edwin. I had one minor design question (first review comment), but other than that, this is good to merge. Thanks for finding the issue with vertical_compression - it'd definitely be good to get that fixed if we're adding situations where it's going to be called implicitly within library code.

[jakelishman]

Perhaps it would make more sense to wrap the label in \text instead of \mathrm - the latter still uses math-mode spacing/kerning rules (hence the \,), whereas \text swaps back to the full text font. It depends on amsmath being available (I think), but that's part of the de facto LaTeX standard library. Users would be able to have parts of the label rendered in math-mode by including the $ ... $ manually.

That's just on the basis that I would expect "label" to be a text field, not an equation one. If we feel like it's more of an "equation" field, then the current math-mode way makes sense.

[enavarro51]

\text doesn't work on my TeX Live version of LaTex. I don't think we'd want to do another usepackage for amsmath just for this, so I'd suggest we leave the \mathrm as is.

[jakelishman]

Yeah, that's fair enough. I'm surprised that nothing is already loading amsmath, since it's about as common as import numpy in mathematical Python code, but fair enough. If it's not already loaded, yeah, let's not add the extra dependency.

[jakelishman]

Thanks for this, I can certainly see it as a useful feature for visualisation of complex circuits.