qsci_vm_interface

VM-Aware TE-QSCI Interface

This module provides enhanced interfaces for running TE-QSCI algorithms with integrated QURI VM analysis capabilities. It extends the base QSCI algorithms to capture and analyze quantum circuits at both LogicalCircuit and ArchLogicalCircuit levels.

Classes:

Name	Description
VMAnalysisResult	Result of VM-enhanced circuit analysis.
TEQSCIVMResult	Enhanced TE-QSCI result with VM analysis.
VMAwareTimeEvolutionCircuit	Wrapper for time evolution circuits with VM analysis capabilities.
VMAwareSingleTimeTE_QSCI	TE-QSCI with integrated VM analysis capabilities.

Functions:

Name	Description
create_vm_aware_te_qsci	Create VM-aware TE-QSCI algorithm with VM sampling.
demonstrate_h6_vm_analysis	Demonstrate H6 TE-QSCI with VM analysis.

VMAnalysisResult dataclass

VMAnalysisResult(
    logical_analysis,
    arch_analysis,
    circuit_description,
    analysis_time,
)

Result of VM-enhanced circuit analysis.

Attributes:

Name	Type	Description
logical_analysis	Dict[str, Any]
arch_analysis	Dict[str, Any]
circuit_description	str
analysis_time	float

logical_analysis instance-attribute

logical_analysis

arch_analysis instance-attribute

arch_analysis

circuit_description instance-attribute

circuit_description

analysis_time instance-attribute

analysis_time

TEQSCIVMResult dataclass

TEQSCIVMResult(
    qsci_result,
    time_evolution_analysis,
    sampling_circuits_analysis,
    total_logical_time,
    total_arch_time,
    architecture_overhead,
    fidelity_impact,
    evolution_time,
    trotter_steps,
    architecture_name,
)

Enhanced TE-QSCI result with VM analysis.

Attributes:

Name	Type	Description
qsci_result	QSCIResult
time_evolution_analysis	VMAnalysisResult
sampling_circuits_analysis	List[VMAnalysisResult]
total_logical_time	TimeValue
total_arch_time	TimeValue
architecture_overhead	float
fidelity_impact	float
evolution_time	float
trotter_steps	int
architecture_name	str

qsci_result instance-attribute

qsci_result

time_evolution_analysis instance-attribute

time_evolution_analysis

sampling_circuits_analysis instance-attribute

sampling_circuits_analysis

total_logical_time instance-attribute

total_logical_time

total_arch_time instance-attribute

total_arch_time

architecture_overhead instance-attribute

architecture_overhead

fidelity_impact instance-attribute

fidelity_impact

evolution_time instance-attribute

evolution_time

trotter_steps instance-attribute

trotter_steps

architecture_name instance-attribute

architecture_name

VMAwareTimeEvolutionCircuit

VMAwareTimeEvolutionCircuit(
    base_circuit,
    evolution_time,
    trotter_steps,
    vm_interface,
    hamiltonian=None,
)

Wrapper for time evolution circuits with VM analysis capabilities.

Parameters:

Name	Type	Description	Default
base_circuit	NonParametricQuantumCircuit	Base quantum circuit	required
evolution_time	float	Time evolution parameter	required
trotter_steps	int	Number of Trotter decomposition steps	required
vm_interface	QURIVMInterface	QURI VM interface for analysis	required
hamiltonian	Optional[Operator]	Target Hamiltonian for authentic analysis	None

Methods:

Name	Description
analyze_at_level	Analyze circuit at specified level with caching.
get_analysis_summary	Get comprehensive analysis summary.

Attributes:

Name	Type	Description
base_circuit
evolution_time
trotter_steps
vm_interface
hamiltonian
circuit	NonParametricQuantumCircuit	Get the underlying circuit.

Source code in src/qsci_vm_interface.py

def __init__(
    self,
    base_circuit: NonParametricQuantumCircuit,
    evolution_time: float,
    trotter_steps: int,
    vm_interface: QURIVMInterface,
    hamiltonian: Optional[Operator] = None
):
    """Initialize VM-aware time evolution circuit.

    Args:
        base_circuit: Base quantum circuit
        evolution_time: Time evolution parameter
        trotter_steps: Number of Trotter decomposition steps
        vm_interface: QURI VM interface for analysis
        hamiltonian: Target Hamiltonian for authentic analysis
    """
    self.base_circuit = base_circuit
    self.evolution_time = evolution_time
    self.trotter_steps = trotter_steps
    self.vm_interface = vm_interface
    self.hamiltonian = hamiltonian

    # Cache for analysis results
    self._logical_analysis: Optional[Dict] = None
    self._arch_analysis: Optional[Dict] = None

base_circuit instance-attribute

base_circuit = base_circuit

evolution_time instance-attribute

evolution_time = evolution_time

trotter_steps instance-attribute

trotter_steps = trotter_steps

vm_interface instance-attribute

vm_interface = vm_interface

hamiltonian instance-attribute

hamiltonian = hamiltonian

circuit property

circuit

Get the underlying circuit.

analyze_at_level

analyze_at_level(level)

Analyze circuit at specified level with caching.

Source code in src/qsci_vm_interface.py

def analyze_at_level(self, level: LoweringLevel) -> Dict[str, Any]:
    """Analyze circuit at specified level with caching."""
    if level == LoweringLevel.LogicalCircuit:
        if self._logical_analysis is None:
            self._logical_analysis = self.vm_interface.analyze_circuit_at_level(
                self.base_circuit, level
            )
        return self._logical_analysis
    else:
        if self._arch_analysis is None:
            self._arch_analysis = self.vm_interface.analyze_circuit_at_level(
                self.base_circuit, level
            )
        return self._arch_analysis

get_analysis_summary

get_analysis_summary()

Get comprehensive analysis summary.

Source code in src/qsci_vm_interface.py

def get_analysis_summary(self) -> VMAnalysisResult:
    """Get comprehensive analysis summary."""
    start_time = time.time()

    logical_analysis = self.analyze_at_level(LoweringLevel.LogicalCircuit)
    arch_analysis = self.analyze_at_level(LoweringLevel.ArchLogicalCircuit)

    analysis_time = time.time() - start_time

    circuit_description = f"Time evolution (t={self.evolution_time}, steps={self.trotter_steps})"

    return VMAnalysisResult(
        logical_analysis=logical_analysis,
        arch_analysis=arch_analysis,
        circuit_description=circuit_description,
        analysis_time=analysis_time
    )

VMAwareSingleTimeTE_QSCI

VMAwareSingleTimeTE_QSCI(
    hamiltonian,
    evolution_time,
    sampler=None,
    num_states_pick_out=None,
    trotter_steps=10,
    vm_interface=None,
    sampling_level=ArchLogicalCircuit,
    use_vm_sampling=True,
)

Bases: SingleTimeTE_QSCI

TE-QSCI with integrated VM analysis capabilities.

Parameters:

Name	Type	Description	Default
hamiltonian	Operator	Target Hamiltonian	required
evolution_time	float	Time evolution parameter	required
sampler		Quantum sampler (used as fallback if use_vm_sampling=False)	None
num_states_pick_out	Optional[int]	Number of states for QSCI subspace	None
trotter_steps	int	Number of Trotter steps for time evolution	10
vm_interface	Optional[QURIVMInterface]	Pre-configured QURIVMInterface with appropriate VMs	None
sampling_level	LoweringLevel	LoweringLevel for VM sampling (LogicalCircuit or ArchLogicalCircuit)	ArchLogicalCircuit
use_vm_sampling	bool	Whether to use VM sampling or fallback to provided sampler	True

Methods:

Name	Description
run_with_vm_analysis	Run TE-QSCI with comprehensive VM analysis.

Attributes:

Name	Type	Description
vm_interface
sampling_level
use_vm_sampling
fallback_sampler
trotter_steps
architecture
circuit_analyses	List[VMAnalysisResult]
time_evolution_analysis	Optional[VMAnalysisResult]
name	str	Algorithm name with VM capabilities.

Source code in src/qsci_vm_interface.py

def __init__(
    self,
    hamiltonian: Operator,
    evolution_time: float,
    sampler=None,
    num_states_pick_out: Optional[int] = None,
    trotter_steps: int = 10,
    vm_interface: Optional[QURIVMInterface] = None,
    sampling_level: LoweringLevel = LoweringLevel.ArchLogicalCircuit,
    use_vm_sampling: bool = True
):
    """Initialize VM-aware TE-QSCI.

    Args:
        hamiltonian: Target Hamiltonian
        evolution_time: Time evolution parameter
        sampler: Quantum sampler (used as fallback if use_vm_sampling=False)
        num_states_pick_out: Number of states for QSCI subspace
        trotter_steps: Number of Trotter steps for time evolution
        vm_interface: Pre-configured QURIVMInterface with appropriate VMs
        sampling_level: LoweringLevel for VM sampling (LogicalCircuit or ArchLogicalCircuit)
        use_vm_sampling: Whether to use VM sampling or fallback to provided sampler
    """
    # Use provided VM interface or create default one
    if vm_interface is None:
        # Create default VM interface with ideal and zero-error STAR VMs
        vm_interface = QURIVMInterface()

    self.vm_interface = vm_interface

    # Set up sampling strategy
    self.sampling_level = sampling_level
    self.use_vm_sampling = use_vm_sampling
    self.fallback_sampler = sampler

    # Create appropriate sampler
    if use_vm_sampling:
        vm_sampler = self.vm_interface.create_sampler(sampling_level)
    else:
        vm_sampler = sampler

    super().__init__(
        hamiltonian=hamiltonian,
        sampler=vm_sampler,
        num_states_pick_out=num_states_pick_out,
        evolution_time=evolution_time
    )

    self.trotter_steps = trotter_steps
    self.architecture = "STAR"  # Default architecture for VM analysis

    # Storage for VM analysis
    self.circuit_analyses: List[VMAnalysisResult] = []
    self.time_evolution_analysis: Optional[VMAnalysisResult] = None

vm_interface instance-attribute

vm_interface = vm_interface

sampling_level instance-attribute

sampling_level = sampling_level

use_vm_sampling instance-attribute

use_vm_sampling = use_vm_sampling

fallback_sampler instance-attribute

fallback_sampler = sampler

trotter_steps instance-attribute

trotter_steps = trotter_steps

architecture instance-attribute

architecture = 'STAR'

circuit_analyses instance-attribute

circuit_analyses = []

time_evolution_analysis instance-attribute

time_evolution_analysis = None

name property

name

Algorithm name with VM capabilities.

run_with_vm_analysis

run_with_vm_analysis(
    initial_state, analyze_sampling=True, num_shots=1000
)

Run TE-QSCI with comprehensive VM analysis.

Parameters:

Name	Type	Description	Default
initial_state	CircuitQuantumState	Initial quantum state	required
analyze_sampling	bool	Whether to analyze sampling circuits	True

Returns:

Type	Description
TEQSCIVMResult	Enhanced TE-QSCI result with VM analysis

Source code in src/qsci_vm_interface.py

def run_with_vm_analysis(
    self, 
    initial_state: CircuitQuantumState,
    analyze_sampling: bool = True,
    num_shots: int = 1000
) -> TEQSCIVMResult:
    """Run TE-QSCI with comprehensive VM analysis.

    Args:
        initial_state: Initial quantum state
        analyze_sampling: Whether to analyze sampling circuits

    Returns:
        Enhanced TE-QSCI result with VM analysis
    """
    print(f" Running {self.name}")
    print(f"   • Evolution time: {self.evolution_time}")
    print(f"   • Trotter steps: {self.trotter_steps}")
    print(f"   • Architecture: {self.architecture}")
    print(f"   • Sampling mode: {'VM (' + self.sampling_level.name + ')' if self.use_vm_sampling else 'Qulacs (fallback)'}")

    # Validate sampling setup
    if self.use_vm_sampling and not isinstance(self.sampler, VMSampler):
        print(f"   Warning: Expected VMSampler but got {type(self.sampler)}")
        if self.fallback_sampler:
            print(f"   Falling back to Qulacs sampler...")
            self.sampler = self.fallback_sampler
            self.use_vm_sampling = False

    # Create and analyze time evolution circuit
    print("   Analyzing time evolution circuit...")
    te_circuit = self._create_time_evolution_circuit(initial_state)
    time_evolution_analysis = te_circuit.get_analysis_summary()
    self.time_evolution_analysis = time_evolution_analysis

    # Run standard TE-QSCI algorithm
    print("   Running TE-QSCI computation...")
    qsci_result = self.run([initial_state], num_shots)

    # Analyze sampling circuits if requested
    sampling_analyses = []
    if analyze_sampling:
        print("   Analyzing sampling circuits...")
        # For demonstration, create a few representative sampling circuits
        sampling_analyses = self._analyze_sampling_circuits(initial_state)

    # Calculate performance metrics
    logical_time = time_evolution_analysis.logical_analysis.latency or TimeValue(0, TimeUnit.MICROSECOND)
    arch_time = time_evolution_analysis.arch_analysis.latency or TimeValue(0, TimeUnit.MICROSECOND)

    total_logical_time = logical_time
    total_arch_time = arch_time

    # Add sampling time if analyzed
    for analysis in sampling_analyses:
        logical_latency = analysis.logical_analysis.latency
        arch_latency = analysis.arch_analysis.latency
        if logical_latency:
            total_logical_time = TimeValue(
                total_logical_time.in_ns() + logical_latency.in_ns(),
                TimeUnit.NANOSECOND
            )
        if arch_latency:
            total_arch_time = TimeValue(
                total_arch_time.in_ns() + arch_latency.in_ns(),
                TimeUnit.NANOSECOND
            )

    # Calculate overhead and fidelity impact
    if total_logical_time.in_ns() > 0:
        architecture_overhead = total_arch_time.in_ns() / total_logical_time.in_ns()
    else:
        architecture_overhead = 1.0  # No overhead if no time measured

    logical_fidelity = time_evolution_analysis.logical_analysis.fidelity or 1.0
    arch_fidelity = time_evolution_analysis.arch_analysis.fidelity or 1.0
    fidelity_impact = logical_fidelity - arch_fidelity

    print(f"   VM analysis complete!")
    print(f"      • Architecture overhead: {architecture_overhead:.1f}x")
    print(f"      • Fidelity impact: {fidelity_impact:.1%}")

    return TEQSCIVMResult(
        qsci_result=qsci_result,
        time_evolution_analysis=time_evolution_analysis,
        sampling_circuits_analysis=sampling_analyses,
        total_logical_time=total_logical_time,
        total_arch_time=total_arch_time,
        architecture_overhead=architecture_overhead,
        fidelity_impact=fidelity_impact,
        evolution_time=self.evolution_time,
        trotter_steps=self.trotter_steps,
        architecture_name=self.architecture
    )

create_vm_aware_te_qsci

create_vm_aware_te_qsci(
    hamiltonian,
    evolution_time=1.5,
    vm_interface=None,
    sampling_level=ArchLogicalCircuit,
    use_vm_sampling=True,
    **kwargs
)

Create VM-aware TE-QSCI algorithm with VM sampling.

Parameters:

Name	Type	Description	Default
hamiltonian	Operator	Target Hamiltonian	required
evolution_time	float	Time evolution parameter	1.5
vm_interface	Optional[QURIVMInterface]	Pre-configured QURIVMInterface with appropriate VMs	None
sampling_level	LoweringLevel	LoweringLevel for VM sampling (LogicalCircuit for ideal, ArchLogicalCircuit for STAR)	ArchLogicalCircuit
use_vm_sampling	bool	Whether to use VM sampling or fallback to Qulacs	True
**kwargs		Additional arguments for TE-QSCI	{}

Returns:

Type	Description
VMAwareSingleTimeTE_QSCI	VM-aware TE-QSCI algorithm with VM sampling capabilities

Source code in src/qsci_vm_interface.py

def create_vm_aware_te_qsci(
    hamiltonian: Operator,
    evolution_time: float = 1.5,
    vm_interface: Optional[QURIVMInterface] = None,
    sampling_level: LoweringLevel = LoweringLevel.ArchLogicalCircuit,
    use_vm_sampling: bool = True,
    **kwargs
) -> VMAwareSingleTimeTE_QSCI:
    """Create VM-aware TE-QSCI algorithm with VM sampling.

    Args:
        hamiltonian: Target Hamiltonian
        evolution_time: Time evolution parameter
        vm_interface: Pre-configured QURIVMInterface with appropriate VMs
        sampling_level: LoweringLevel for VM sampling (LogicalCircuit for ideal, ArchLogicalCircuit for STAR)
        use_vm_sampling: Whether to use VM sampling or fallback to Qulacs
        **kwargs: Additional arguments for TE-QSCI

    Returns:
        VM-aware TE-QSCI algorithm with VM sampling capabilities
    """
    return VMAwareSingleTimeTE_QSCI(
        hamiltonian=hamiltonian,
        evolution_time=evolution_time,
        vm_interface=vm_interface,
        sampling_level=sampling_level,
        use_vm_sampling=use_vm_sampling,
        **kwargs
    )

demonstrate_h6_vm_analysis

demonstrate_h6_vm_analysis()

Demonstrate H6 TE-QSCI with VM analysis.

Source code in src/qsci_vm_interface.py

def demonstrate_h6_vm_analysis():
    """Demonstrate H6 TE-QSCI with VM analysis."""
    from quri_parts.core.operator import pauli_label

    # Create simplified H6 Hamiltonian for demonstration
    hamiltonian = Operator()

    # Add typical terms found in H6 molecular Hamiltonian
    n_qubits = 12  # H6 requires 12 qubits

    # Single-qubit terms
    for i in range(n_qubits):
        hamiltonian += 0.1 * pauli_label(f"Z{i}")

    # Two-qubit terms
    for i in range(0, n_qubits - 1, 2):
        hamiltonian += 0.05 * pauli_label(f"Z{i} Z{i+1}")
        hamiltonian += 0.02 * pauli_label(f"X{i} X{i+1}")

    # Create VM-aware TE-QSCI
    te_qsci = create_vm_aware_te_qsci(
        hamiltonian=hamiltonian,
        evolution_time=1.5,
        architecture="STAR",
        num_states_pick_out=100,
        trotter_steps=10
    )

    # Create simple initial state
    from quri_parts.circuit import QuantumCircuit
    from quri_parts.core.state import CircuitQuantumState

    circuit = QuantumCircuit(n_qubits)
    # Create HF-like state for H6 (6 electrons)
    for i in range(6):
        circuit.add_X_gate(i)

    initial_state = CircuitQuantumState(n_qubits, circuit)

    # Run with VM analysis
    result = te_qsci.run_with_vm_analysis(initial_state)

    print("\n VM Analysis Results:")
    print(f"   Architecture overhead: {result.architecture_overhead:.1f}x")
    print(f"   Fidelity impact: {result.fidelity_impact:.1%}")
    print(f"   Logical execution time: {result.total_logical_time}")
    print(f"   STAR execution time: {result.total_arch_time}")

    return result