List of items that might be helpful to implement

[liu-zixiong]

Hi everyone, happy new year! Over the past year working in this repo, there are a list of things which I've picked out which might be helpful to implement.

1. c2qa.util.avg_photon_num() function only works with single qumode

The docstring for avg_photon_num() does not yet mention that it's only designed to work with a single qumode. Attempts to use it with multiple qumodes/qumode registers will produce erroneous outputs.

# Create two qumode registers containing 2 qumodes and 1 qumode respectively.
qmr1 = c2qa.QumodeRegister(2, 3)
qmr2 = c2qa.QumodeRegister(1, 3)
circ = c2qa.CVCircuit(qmr1, qmr2)

# Initialize the three qumodes to |3>, |4>, |5> Fock states.
circ.cv_initialize(3, qmr1[0]) # Qumode in |3>
circ.cv_initialize(4, qmr1[1]) # Qumode in |4>
circ.cv_initialize(5, qmr2[0]) # Qumode in |5>

# Print out the indices of qubits in qumodes, grouped by qumode
print(circ.qumode_qubits_indices_grouped)
## >> [[0, 1, 2], [3, 4, 5], [6, 7, 8]]

# Obtain state
state, _, _ = c2qa.util.simulate(circ)

# avg_photon_num output is erroneous without using partial_trace 
print(c2qa.util.avg_photon_num(state))
## >> 355.0

# Tracing out qumodes qmr1[0] and qmr1[1] gives correct photon number for qmr2[0]
new_state = qiskit.quantum_info.partial_trace(state, [0, 1, 2, 3, 4, 5]) 
print(c2qa.util.avg_photon_num(new_state))
## >> 5.0

# Tracing out just qumode qmr1[0] gives wrong output for qmr1[1] and qmr2[0]
new_state = qiskit.quantum_info.partial_trace(state, [0, 1, 2]) 
print(c2qa.util.avg_photon_num(new_state))
## >> 44.0

It would be convenient to have a function that takes in a state and a qumode of interest and returns the state for just that particular qumode. Additionally, it would also be helpful to rework avg_photon_num so that it returns a proper average across multiple qumodes.

2. The c2qa.util.simulate() docstring needs to be updated. It is currently missing an explanation for certain args like "per_shot_state_vector" or "max_parallel_threads".

3. It might be helpful to expand the README.md file in the tutorials folder so that there is an explanation for what each of the tutorials are. This is just so that it's easier to figure out what the tutorials are meant for, without needing to manually open every tutorial notebook. Alternatively, adding README.md files to every subfolder would also achieve the same purpose (this would also make it easier to track which tutorials require READMEs, as and when they're added).

4. I'm not sure if the compatibility betweenc2qa.circuit.cv_gate_from_matrix() and discretize has ever been tested. This is not a super important because cv_gate_from_matrix() allows you to define physically unimplementable gates, and applying discretize to those gates wouldn't make sense anyways. But in the event that a user actually does define a physically implementable gate, it may be helpful to check that discretize actually produces the correct result in those cases.

5. I've never managed to get c2qa.animate.animate_wigner() working. I've tried installing the ffmpeg package since it is mentioned to be a requirement in the docstring for c2qa.animate.animate_wigner() (even though it wasn't included in requirements.txt), but I suspect I'm still missing a few key package installs. Other new users will likely also face trouble running c2qa.animate.animate_wigner(), especially if they are installing Bosonic Qiskit in a new virtual environment. It might be helpful to add the packages needed for c2qa.animate.animate_wigner() in a separaterequirements-optional.txt.

Hope this helps! And thank you for the opportunity to work on this project, I had a lot of fun contributing new features.

[tjstavenger-pnnl]

Some intitial thoughts as I read through the suggestions the first time:

1. Git history looks like you last worked with this function (or at least last changed the method signature). Do you want to make these changes?
2. That should be pretty quick to change. Documentation does tend to be out of date at the time it is written. :)
3. This should be pretty straight forward too, we can always talk with those who implemented each to get a summary if we need to.
4. Looks like a few of us have made changes here. We do have a function that is supposed to be testing this at https://github.com/C2QA/bosonic-qiskit/blob/main/tests/test_circuit.py#L146. I'll take a look to see if it is really working the way expected. If you have changes you'd like to make, we're certainly open to that too.
5. We have tests for that too, like several in https://github.com/C2QA/bosonic-qiskit/blob/main/tests/test_animate.py. These are passing in GIthub's automated build. Do you have stack traces you could send of your error? I can help see what is going on.

[tjstavenger-pnnl]

I pushed a docuemntation change for 2. For 4., I do see that we're using the bosonic-qiskit custom ParameterizedUnitaryGate. Since we're not trying to parameterize the matrix and we're already checking if it is unitary, could we instead follow the standard Qiskit way by using the UnitaryGate? https://docs.quantum.ibm.com/api/qiskit/qiskit.circuit.library.UnitaryGate I think then the disretization code should just send the gate as all one step without discretizing it at all.

[tjstavenger-pnnl]

In re-reading 5 -- ffmpeg is a software package installed on the system, it isn't a Python package, so it won't be in requirements.txt (I wasn't sure if you meant you installed the ffmpeg software separately or if you installed the ffmpeg named Python package). I've been able to get animate_wigner() working on Linux & Windows systems, and the tests are also running on MacOS in github. MacOS, Linux, and Windows are all tested on Github for Python 3.8, 3.9, 3.10, and 3.11, so it ought to work, but do please send your stack trace & errors my way. I'd defintely like to help get it working for you.

[tjstavenger-pnnl]

1, 2, and 4 are now addressed. The tutorials/README.md was updated or 3., but not to include full descriptions of each tutorial. The ffmpeg software is a system install, as far as I'm aware, there isn't a Python package that can be installed to include it for 5.