VM-Aware QSCI API Reference

This page provides comprehensive API documentation for the VM-aware QSCI functionality, including quantum virtual machine integration, authentic time evolution, and resource estimation capabilities.

Core VM Components

VMFactory

qsci_vm_analysis.VMFactory

Factory for creating pre-configured QURI VM instances.

Methods:

Name	Description
create_ideal_vm	Create ideal VM for LogicalCircuit level sampling.
create_star_vm	Create STAR architecture VM with specified error rate.
create_star_vm_for_h6	Create STAR VM optimized for H6 TE-QSCI calculations.

create_ideal_vm staticmethod

create_ideal_vm()

Create ideal VM for LogicalCircuit level sampling.

Returns:

Type	Description
VM	VM instance configured for ideal quantum computation

Source code in src/qsci_vm_analysis.py

@staticmethod
def create_ideal_vm() -> 'VM':
    """Create ideal VM for LogicalCircuit level sampling.

    Returns:
        VM instance configured for ideal quantum computation
    """
    # Create abstract ideal VM (no device-specific constraints) 
    # Following tutorial: VM() creates abstract VM
    return VM()

create_star_vm staticmethod

create_star_vm(error_rate=0.0)

Create STAR architecture VM with specified error rate.

Parameters:

Name	Type	Description	Default
error_rate	float	Physical error rate (0.0 to 1.0)	0.0

Returns:

Type	Description
VM	VM instance configured with STAR device properties for given error rate

Source code in src/qsci_vm_analysis.py

@staticmethod
def create_star_vm(error_rate: float = 0.0) -> 'VM':
    """Create STAR architecture VM with specified error rate.

    Args:
        error_rate: Physical error rate (0.0 to 1.0)

    Returns:
        VM instance configured with STAR device properties for given error rate
    """
    # Following tutorial: Create STAR VM with specific physical error rate
    # QEC cycle time (1.0 microsecond is standard)
    qec_cycle = TimeValue(value=1.0, unit=TimeUnit.MICROSECOND)

    # Generate STAR device property with physical error rate
    # Following tutorial pattern for error rate configuration
    device_property = star_device.generate_device_property(
        qubit_count=16,  # Sufficient for H6 (12 qubits) + overhead
        code_distance=7,  # Standard distance for fault tolerance
        qec_cycle=qec_cycle,
        physical_error_rate=error_rate  # This is the key parameter from tutorial
    )

    return VM.from_device_prop(device_property)

create_star_vm_for_h6 staticmethod

create_star_vm_for_h6(error_rate=0.0)

Create STAR VM optimized for H6 TE-QSCI calculations.

Parameters:

Name	Type	Description	Default
error_rate	float	Physical error rate for STAR architecture	0.0

Returns:

Type	Description
VM	VM instance optimized for H6 molecular calculations

Source code in src/qsci_vm_analysis.py

@staticmethod
def create_star_vm_for_h6(error_rate: float = 0.0) -> 'VM':
    """Create STAR VM optimized for H6 TE-QSCI calculations.

    Args:
        error_rate: Physical error rate for STAR architecture

    Returns:
        VM instance optimized for H6 molecular calculations
    """
    return VMFactory.create_star_vm(error_rate)

The VMFactory class provides factory methods for creating pre-configured QURI VM instances optimized for different quantum architectures.

Key Methods: - create_ideal_vm(): Creates abstract ideal VM for LogicalCircuit analysis - create_star_vm(error_rate): Creates STAR architecture VM with specified error rate - create_star_vm_for_h6(error_rate): Creates STAR VM optimized for H6 calculations

VMSampler

qsci_vm_analysis.VMSampler

VMSampler(vm_instance)

VM-based sampler implementing quri-parts ConcurrentSampler interface.

Parameters:

Name	Type	Description	Default
vm_instance		Pre-configured QURI VM instance	required

Attributes:

Name	Type	Description
vm

Source code in src/qsci_vm_analysis.py

def __init__(self, vm_instance):
    """Initialize VM sampler.

    Args:
        vm_instance: Pre-configured QURI VM instance
    """
    self.vm = vm_instance

vm instance-attribute

vm = vm_instance

The VMSampler class implements the quri-parts ConcurrentSampler interface, delegating circuit sampling to QURI VM instances with proper error handling.

Key Features: - Direct delegation to VM.sample() - Comprehensive error wrapping - Support for multiple circuit-shot pairs - Clean integration with quri-parts sampling interface

QURIVMInterface

qsci_vm_analysis.QURIVMInterface

QURIVMInterface(logical_vm=None, arch_vm=None)

Interface to QURI VM for TE-QSCI analysis and sampling.

Parameters:

Name	Type	Description	Default
logical_vm		Pre-configured VM for LogicalCircuit level (ideal)	None
arch_vm		Pre-configured VM for ArchLogicalCircuit level (with architecture)	None

Methods:

Name	Description
analyze_circuit_at_level	Analyze circuit at specified lowering level.
create_logical_sampler	Create sampler for LogicalCircuit level (ideal VM).
create_arch_sampler	Create sampler for ArchLogicalCircuit level (STAR architecture).
create_sampler	Create sampler for specified level.

Attributes:

Name	Type	Description
logical_vm
arch_vm

Source code in src/qsci_vm_analysis.py

def __init__(self, logical_vm=None, arch_vm=None):
    """Initialize QURI VM interface with pre-configured VM instances.

    Args:
        logical_vm: Pre-configured VM for LogicalCircuit level (ideal)
        arch_vm: Pre-configured VM for ArchLogicalCircuit level (with architecture)
    """
    if logical_vm is None:
        logical_vm = VMFactory.create_ideal_vm()
    if arch_vm is None:
        arch_vm = VMFactory.create_star_vm(0.0)  # Default to no error

    self.logical_vm = logical_vm
    self.arch_vm = arch_vm

logical_vm instance-attribute

logical_vm = logical_vm

arch_vm instance-attribute

arch_vm = arch_vm

analyze_circuit_at_level

analyze_circuit_at_level(circuit, level)

Analyze circuit at specified lowering level.

Parameters:

Name	Type	Description	Default
circuit	NonParametricQuantumCircuit	Circuit to analyze	required
level	LoweringLevel	Analysis level (LogicalCircuit or ArchLogicalCircuit)	required

Returns:

Type	Description
Dict[str, Any]	Analysis results dictionary

Source code in src/qsci_vm_analysis.py

def analyze_circuit_at_level(
    self,
    circuit: NonParametricQuantumCircuit,
    level: LoweringLevel
) -> Dict[str, Any]:
    """Analyze circuit at specified lowering level.

    Args:
        circuit: Circuit to analyze
        level: Analysis level (LogicalCircuit or ArchLogicalCircuit)

    Returns:
        Analysis results dictionary
    """
    if level == LoweringLevel.LogicalCircuit:
        return self._analyze_logical_level(circuit)
    elif level == LoweringLevel.ArchLogicalCircuit:
        return self._analyze_arch_level(circuit)
    else:
        # For higher levels, default to arch analysis
        return self._analyze_arch_level(circuit)

create_logical_sampler

create_logical_sampler()

Create sampler for LogicalCircuit level (ideal VM).

Returns:

Type	Description
	VMSampler instance for ideal quantum sampling

Source code in src/qsci_vm_analysis.py

def create_logical_sampler(self):
    """Create sampler for LogicalCircuit level (ideal VM).

    Returns:
        VMSampler instance for ideal quantum sampling
    """
    return VMSampler(self.logical_vm)

create_arch_sampler

create_arch_sampler()

Create sampler for ArchLogicalCircuit level (STAR architecture).

Returns:

Type	Description
	VMSampler instance for STAR architecture sampling

Source code in src/qsci_vm_analysis.py

def create_arch_sampler(self):
    """Create sampler for ArchLogicalCircuit level (STAR architecture).

    Returns:
        VMSampler instance for STAR architecture sampling
    """
    return VMSampler(self.arch_vm)

create_sampler

create_sampler(level)

Create sampler for specified level.

Parameters:

Name	Type	Description	Default
level	LoweringLevel	LoweringLevel for sampling (LogicalCircuit or ArchLogicalCircuit)	required

Returns:

Type	Description
	VMSampler instance for the specified level

Source code in src/qsci_vm_analysis.py

def create_sampler(self, level: LoweringLevel):
    """Create sampler for specified level.

    Args:
        level: LoweringLevel for sampling (LogicalCircuit or ArchLogicalCircuit)

    Returns:
        VMSampler instance for the specified level
    """
    if level == LoweringLevel.LogicalCircuit:
        return self.create_logical_sampler()
    elif level == LoweringLevel.ArchLogicalCircuit:
        return self.create_arch_sampler()
    else:
        # Default to arch level for higher levels
        return self.create_arch_sampler()

The QURIVMInterface class provides a unified interface for QURI VM analysis and sampling across different quantum architectures.

Key Capabilities: - Circuit analysis at LogicalCircuit and ArchLogicalCircuit levels - Automatic VM instance management - Sampler creation for different analysis levels - Error propagation and handling

VM-Aware Algorithms

VMAwareSingleTimeTE_QSCI

qsci_vm_interface.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
    )

The VMAwareSingleTimeTE_QSCI class extends the standard TE-QSCI algorithm with comprehensive VM analysis capabilities, including authentic time evolution and resource estimation.

Enhanced Features: - Authentic Trotter decomposition using quri-algo - Fallback to simplified Trotter when quri-algo unavailable - VM metrics calculation (overhead and fidelity impact) - Integration with molecular Hamiltonian systems - Multi-error-rate comparison support

VMAwareTimeEvolutionCircuit

qsci_vm_interface.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
    )

The VMAwareTimeEvolutionCircuit class wraps quantum circuits with VM analysis capabilities, providing caching and comprehensive circuit characterization.

Key Features: - Analysis result caching for performance - Summary generation with timing information - Integration with VM interfaces - Support for both LogicalCircuit and ArchLogicalCircuit analysis

Result Classes

TEQSCIVMResult

qsci_vm_interface.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

The TEQSCIVMResult dataclass encapsulates enhanced TE-QSCI results with comprehensive VM analysis data.

Included Data: - Standard QSCI results (energies, states) - VM analysis results at multiple levels - Performance metrics (overhead, fidelity impact) - Circuit characterization data - Algorithm metadata

VMAnalysisResult

qsci_vm_interface.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

The VMAnalysisResult dataclass contains detailed VM circuit analysis information.

Analysis Data: - LogicalCircuit and ArchLogicalCircuit analysis - Circuit description and metadata - Analysis timing information - Resource estimation data

Factory Functions

create_vm_aware_te_qsci

qsci_vm_interface.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
    )

Factory function for creating VM-aware TE-QSCI algorithms with VM sampling capabilities.

Parameters: - hamiltonian: Target molecular Hamiltonian - evolution_time: Time evolution parameter - vm_interface: Pre-configured VM interface (optional) - sampling_level: Analysis level (LogicalCircuit or ArchLogicalCircuit) - use_vm_sampling: Enable VM-based sampling - Additional TE-QSCI parameters

create_star_vm_for_h6

qsci_vm_analysis.create_star_vm_for_h6

create_star_vm_for_h6(error_rate=0.0)

Create STAR architecture VM interface optimized for H6 TE-QSCI.

Parameters:

Name	Type	Description	Default
error_rate	float	Physical error rate for STAR architecture (0.0 for ideal)	0.0

Source code in src/qsci_vm_analysis.py

def create_star_vm_for_h6(error_rate: float = 0.0) -> QURIVMInterface:
    """Create STAR architecture VM interface optimized for H6 TE-QSCI.

    Args:
        error_rate: Physical error rate for STAR architecture (0.0 for ideal)
    """
    logical_vm = VMFactory.create_ideal_vm()
    arch_vm = VMFactory.create_star_vm_for_h6(error_rate)
    return QURIVMInterface(logical_vm=logical_vm, arch_vm=arch_vm)

Factory function for creating STAR architecture VM interface optimized for H6 TE-QSCI calculations.

Parameters: - error_rate: Physical error rate for STAR architecture (0.0 for ideal)

Returns: - QURIVMInterface: Configured interface with ideal and STAR VMs

Integration Points

QURI VM Integration

The VM-aware QSCI functionality integrates seamlessly with QURI VM for realistic quantum hardware simulation:

• Device Property Generation: Uses star_device.generate_device_property() for STAR architecture configuration
• VM Analysis: Leverages VM.analyze() for circuit resource estimation
• VM Sampling: Utilizes VM.sample() for quantum sampling with noise models

quri-algo Integration

Authentic time evolution leverages quri-algo for real quantum circuit generation:

• TrotterTimeEvolutionCircuitFactory: Generates authentic Trotter decomposition circuits
• QubitHamiltonian: Converts quri-parts Operators to quri-algo format
• Fallback Mechanisms: Graceful degradation when quri-algo unavailable

Error Handling

Comprehensive error handling throughout the VM stack:

• Import Error Handling: Graceful fallback when dependencies unavailable
• Runtime Error Wrapping: Clear error messages with context
• Validation: Parameter validation and boundary checking
• Resource Management: Proper cleanup and error propagation

Performance Considerations

Analysis Caching

The VM-aware components implement intelligent caching for performance:

• Circuit Analysis Caching: Avoids redundant VM analysis calls
• Level-Specific Caching: Separate caches for LogicalCircuit and ArchLogicalCircuit
• Cache Invalidation: Proper cache management for accuracy

Resource Optimization

Optimized for efficient quantum resource usage:

• Minimal VM Overhead: Efficient delegation patterns
• Batch Processing: Support for multiple circuit analysis
• Memory Management: Proper resource cleanup and management

Scalability

Designed for molecular system scalability:

• Hamiltonian Complexity: Scales with molecular system size
• Circuit Depth: Handles realistic molecular time evolution
• Error Rate Sensitivity: Efficient multi-error-rate analysis