Add function to draw linear optics circuit for VQE

[nathanshammah]

Description

Currently, there is no built-in way to inspect or visualize the linear optical circuit generated by a VQE ansatz within qlass. Users must manually call Perceval's pcvl.pdisplay() on the underlying Processor.linear_circuit() object, which requires knowledge of Perceval internals.

This issue proposes adding a user-friendly draw_circuit utility to qlass that visualizes the photonic circuit for a given set of ansatz parameters outside the optimization loop (i.e., for inspection before or after a VQE run, not on every cost-function evaluation).

Current State

• Ansatz functions (e.g., le_ansatz, custom_unitary_ansatz) return a perceval.Processor.
• Perceval provides pcvl.pdisplay(circuit) and pcvl.pdisplay_to_file(circuit, path) with multiple output formats (MPLOT, HTML, LATEX, TEXT) and skins (PhysSkin, SymbSkin, DebugSkin).
• The VQE class stores the executor but never materializes or exposes the circuit for visualization.
• There is no unified drawing interface in qlass.

Proposed Design

1. Standalone utility function in qlass/utils/

A top-level function that takes a Processor or Circuit and wraps Perceval's drawing with sensible defaults:

def draw_circuit(
    circuit_or_processor: pcvl.Processor | pcvl.Circuit,
    output_format: str = "mpl",
    skin: str = "phys",
    compact: bool = False,
    save_path: str | None = None,
) -> None:
    """
    Draw a linear optical circuit.

    Args:
        circuit_or_processor: A Perceval Processor or Circuit object.
        output_format: One of "mpl", "html", "latex", "text".
        skin: One of "phys", "symb", "debug".
        compact: If True, use compact display mode.
        save_path: If provided, save the figure to this file path.
    """

2. Convenience method on the VQE class

A method that materializes the circuit for given parameters and draws it:

class VQE:
    def draw_ansatz(self, params: np.ndarray, pauli_string: str = "I..I", **kwargs) -> None:
        """
        Visualize the ansatz circuit for a specific set of parameters.
        Calls the executor to build the Processor, then draws it.
        """

3. Backend abstraction (future)

The draw_circuit utility should accept an optional backend argument so that when support for other photonic frameworks (e.g., Piquasso) is added, drawing can be routed through a unified interface without changing user code.

To-Do Checklist

• Add draw_circuit() utility function in qlass/utils/.
• Add draw_ansatz() convenience method to the VQE class.
• Export draw_circuit from qlass.__init__.
• Add usage examples in examples/ or documentation.
• Add unit test verifying that draw_circuit runs without error for each output format on a simple 2-qubit ansatz.

[Kitsunp]

@FarLab could you assign this to me?

[FarLab]

@Kitsunp done, thanks for reminding me to do that!