qsci_algo_interface

QSCI and TE-QSCI algorithm implementations compatible with quri-algo interface.

This module provides algorithm objects that conform to quri-algo's algorithm interface, enabling seamless integration with QURI SDK ecosystem.

Classes:

Name	Description
LoweringLevel	Analysis lowering levels for quantum circuits.
AlgorithmResult	Base class for algorithm results.
Algorithm	Base class for all algorithms.
Analysis	Analysis of algorithm resource requirements.
CircuitAnalysisMixin	Mixin for algorithms that support circuit analysis.
QuantumAlgorithm	Base class for quantum algorithms with circuit analysis.
QSCIAlgorithmResult	Result wrapper for QSCI algorithms compatible with quri-algo interface.
QSCIAnalysis	Analysis implementation for QSCI algorithms.
QSCIAlgorithmBase	Base class for QSCI algorithms compatible with quri-algo interface.
VanillaQSCIAlgorithm	Vanilla QSCI algorithm compatible with quri-algo interface.
SingleTimeTeQSCIAlgorithm	Single-time TE-QSCI algorithm compatible with quri-algo interface.
TimeAverageTeQSCIAlgorithm	Time-average TE-QSCI algorithm compatible with quri-algo interface.
StateVectorTeQSCIAlgorithm	State vector TE-QSCI algorithm compatible with quri-algo interface.

Functions:

Name	Description
create_qsci_algorithm	Factory function to create QSCI algorithm variants.

Attributes:

Name	Type	Description
T

T module-attribute

T = TypeVar('T')

LoweringLevel

Bases: Enum

Analysis lowering levels for quantum circuits.

Attributes:

Name	Type	Description
LogicalCircuit
ArchLogicalCircuit
ArchInstruction
DeviceInstruction

LogicalCircuit class-attribute instance-attribute

LogicalCircuit = 0

ArchLogicalCircuit class-attribute instance-attribute

ArchLogicalCircuit = 1

ArchInstruction class-attribute instance-attribute

ArchInstruction = 2

DeviceInstruction class-attribute instance-attribute

DeviceInstruction = 3

AlgorithmResult

AlgorithmResult(algorithm, elapsed_time=None)

Bases: ABC

Base class for algorithm results.

Attributes:

Name	Type	Description
algorithm
elapsed_time
name	str	The name of the algorithm.

Source code in src/qsci_algo_interface.py

def __init__(self, algorithm: "Algorithm", elapsed_time: Optional[float] = None):
    self.algorithm = algorithm
    self.elapsed_time = elapsed_time

algorithm instance-attribute

algorithm = algorithm

elapsed_time instance-attribute

elapsed_time = elapsed_time

name property

name

The name of the algorithm.

Algorithm

Bases: ABC

Base class for all algorithms.

Methods:

Name	Description
run	Run the algorithm itself.

Attributes:

Name	Type	Description
name	str	The name of the algorithm.

name abstractmethod property

name

The name of the algorithm.

run abstractmethod

run(*args, **kwargs)

Run the algorithm itself.

Source code in src/qsci_algo_interface.py

@abstractmethod
def run(self, *args: Any, **kwargs: Any) -> AlgorithmResult:
    """Run the algorithm itself."""
    pass

Analysis

Analysis(
    lowering_level,
    circuit_gate_count,
    circuit_depth,
    circuit_latency,
    circuit_execution_count,
    circuit_fidelities,
    circuit_qubit_count,
)

Bases: ABC

Analysis of algorithm resource requirements.

Attributes:

Name	Type	Description
lowering_level
circuit_gate_count
circuit_depth
circuit_latency
circuit_execution_count
circuit_fidelities
circuit_qubit_count
total_latency	TimeValue	Total latency of the circuit is algorithm dependent.
max_physical_qubit_count	int	Maximum physical qubit count is algorithm dependent.

Source code in src/qsci_algo_interface.py

def __init__(
    self,
    lowering_level: LoweringLevel,
    circuit_gate_count: Mapping[Any, int],
    circuit_depth: Mapping[Any, int],
    circuit_latency: Mapping[Any, TimeValue | None],
    circuit_execution_count: Mapping[Any, int],
    circuit_fidelities: Mapping[Any, float | None],
    circuit_qubit_count: Mapping[Any, int],
) -> None:
    self.lowering_level = lowering_level
    self.circuit_gate_count = circuit_gate_count
    self.circuit_depth = circuit_depth
    self.circuit_latency = circuit_latency
    self.circuit_execution_count = circuit_execution_count
    self.circuit_fidelities = circuit_fidelities
    self.circuit_qubit_count = circuit_qubit_count

lowering_level instance-attribute

lowering_level = lowering_level

circuit_gate_count instance-attribute

circuit_gate_count = circuit_gate_count

circuit_depth instance-attribute

circuit_depth = circuit_depth

circuit_latency instance-attribute

circuit_latency = circuit_latency

circuit_execution_count instance-attribute

circuit_execution_count = circuit_execution_count

circuit_fidelities instance-attribute

circuit_fidelities = circuit_fidelities

circuit_qubit_count instance-attribute

circuit_qubit_count = circuit_qubit_count

total_latency abstractmethod property

total_latency

Total latency of the circuit is algorithm dependent.

max_physical_qubit_count abstractmethod property

max_physical_qubit_count

Maximum physical qubit count is algorithm dependent.

CircuitAnalysisMixin

Mixin for algorithms that support circuit analysis.

Methods:

Name	Description
analyze	The quantum resource analysis of the algorithm.

analyze abstractmethod

analyze(*args, **kwargs)

The quantum resource analysis of the algorithm.

Source code in src/qsci_algo_interface.py

@abstractmethod
def analyze(self, *args: Any, **kwargs: Any) -> Analysis:
    """The quantum resource analysis of the algorithm."""
    pass

QuantumAlgorithm

Bases: Algorithm, CircuitAnalysisMixin, ABC

Base class for quantum algorithms with circuit analysis.

Methods:

Name	Description
analyze	The quantum resource analysis of the algorithm.
run	Run the algorithm itself.

Attributes:

Name	Type	Description
name	str	The name of the algorithm.

name abstractmethod property

name

The name of the algorithm.

analyze abstractmethod

analyze(*args, **kwargs)

The quantum resource analysis of the algorithm.

Source code in src/qsci_algo_interface.py

@abstractmethod
def analyze(self, *args: Any, **kwargs: Any) -> Analysis:
    """The quantum resource analysis of the algorithm."""
    pass

run abstractmethod

run(*args, **kwargs)

Run the algorithm itself.

Source code in src/qsci_algo_interface.py

@abstractmethod
def run(self, *args: Any, **kwargs: Any) -> AlgorithmResult:
    """Run the algorithm itself."""
    pass

QSCIAlgorithmResult

QSCIAlgorithmResult(
    algorithm, qsci_result, elapsed_time=None
)

Bases: AlgorithmResult

Result wrapper for QSCI algorithms compatible with quri-algo interface.

Attributes:

Name	Type	Description
qsci_result
ground_state_energy	float	Ground state energy from QSCI calculation.
eigenvalues	Sequence[float]	All computed eigenvalues.
subspace_dimension	int	Dimension of the selected subspace.
algorithm
elapsed_time
name	str	The name of the algorithm.

Source code in src/qsci_algo_interface.py

def __init__(
    self, 
    algorithm: "QSCIAlgorithmBase", 
    qsci_result: QSCIResult,
    elapsed_time: Optional[float] = None
):
    super().__init__(algorithm, elapsed_time or qsci_result.execution_time)
    self.qsci_result = qsci_result

qsci_result instance-attribute

qsci_result = qsci_result

ground_state_energy property

ground_state_energy

Ground state energy from QSCI calculation.

eigenvalues property

eigenvalues

All computed eigenvalues.

subspace_dimension property

subspace_dimension

Dimension of the selected subspace.

algorithm instance-attribute

algorithm = algorithm

elapsed_time instance-attribute

elapsed_time = elapsed_time

name property

name

The name of the algorithm.

QSCIAnalysis

QSCIAnalysis(
    lowering_level, qsci_result, circuit_analysis=None
)

Bases: Analysis

Analysis implementation for QSCI algorithms.

Attributes:

Name	Type	Description
qsci_result
total_latency	TimeValue	Total latency for QSCI execution.
max_physical_qubit_count	int	Maximum physical qubit count required.
lowering_level
circuit_gate_count
circuit_depth
circuit_latency
circuit_execution_count
circuit_fidelities
circuit_qubit_count

Source code in src/qsci_algo_interface.py

def __init__(
    self,
    lowering_level: LoweringLevel,
    qsci_result: QSCIResult,
    circuit_analysis: Optional[Dict[str, Any]] = None
):
    # Initialize with QSCI-specific circuit analysis
    circuit_gate_count = circuit_analysis.get("gate_count", {}) if circuit_analysis else {}
    circuit_depth = circuit_analysis.get("depth", {}) if circuit_analysis else {}
    circuit_latency = circuit_analysis.get("latency", {}) if circuit_analysis else {}
    circuit_execution_count = {"sampling": qsci_result.total_shots}
    circuit_fidelities = circuit_analysis.get("fidelities", {}) if circuit_analysis else {}
    circuit_qubit_count = circuit_analysis.get("qubit_count", {}) if circuit_analysis else {}

    super().__init__(
        lowering_level,
        circuit_gate_count,
        circuit_depth,
        circuit_latency,
        circuit_execution_count,
        circuit_fidelities,
        circuit_qubit_count
    )
    self.qsci_result = qsci_result

qsci_result instance-attribute

qsci_result = qsci_result

total_latency property

total_latency

Total latency for QSCI execution.

max_physical_qubit_count property

max_physical_qubit_count

Maximum physical qubit count required.

lowering_level instance-attribute

lowering_level = lowering_level

circuit_gate_count instance-attribute

circuit_gate_count = circuit_gate_count

circuit_depth instance-attribute

circuit_depth = circuit_depth

circuit_latency instance-attribute

circuit_latency = circuit_latency

circuit_execution_count instance-attribute

circuit_execution_count = circuit_execution_count

circuit_fidelities instance-attribute

circuit_fidelities = circuit_fidelities

circuit_qubit_count instance-attribute

circuit_qubit_count = circuit_qubit_count

QSCIAlgorithmBase

QSCIAlgorithmBase(
    hamiltonian, sampler=None, num_states_pick_out=None
)

Bases: QuantumAlgorithm

Base class for QSCI algorithms compatible with quri-algo interface.

Methods:

Name	Description
analyze	Analyze quantum resource requirements for QSCI algorithm.
run	Run the algorithm itself.

Attributes:

Name	Type	Description
hamiltonian
sampler
num_states_pick_out
name	str	Algorithm name.

Source code in src/qsci_algo_interface.py

def __init__(
    self,
    hamiltonian: Operator,
    sampler: Optional[ConcurrentSampler] = None,
    num_states_pick_out: Optional[int] = None
):
    self.hamiltonian = hamiltonian
    self.sampler = sampler
    self.num_states_pick_out = num_states_pick_out

hamiltonian instance-attribute

hamiltonian = hamiltonian

sampler instance-attribute

sampler = sampler

num_states_pick_out instance-attribute

num_states_pick_out = num_states_pick_out

name abstractmethod property

name

Algorithm name.

analyze

analyze(
    input_states,
    total_shots,
    lowering_level=LogicalCircuit,
    **kwargs
)

Analyze quantum resource requirements for QSCI algorithm.

Source code in src/qsci_algo_interface.py

def analyze(
    self, 
    input_states: Sequence[CircuitQuantumState],
    total_shots: int,
    lowering_level: LoweringLevel = LoweringLevel.LogicalCircuit,
    **kwargs
) -> QSCIAnalysis:
    """Analyze quantum resource requirements for QSCI algorithm."""
    # For analysis, we can estimate without actually running
    circuit_analysis = {}

    if input_states:
        # Analyze input circuits
        total_gates = sum(len(state.circuit) for state in input_states)
        max_depth = max(state.circuit.depth for state in input_states) if input_states else 0
        qubit_count = input_states[0].qubit_count if input_states else 0

        circuit_analysis = {
            "gate_count": {"total": total_gates},
            "depth": {"max": max_depth},
            "qubit_count": {"required": qubit_count},
            "latency": {},  # Would need backend-specific estimation
            "fidelities": {}  # Would need noise model
        }

    # Create dummy result for analysis
    dummy_result = QSCIResult(
        eigenvalues=[0.0],
        eigenstates=[],
        selected_states=[],
        subspace_dimension=self.num_states_pick_out or 100,
        total_shots=total_shots,
        algorithm_variant=QSCIVariant.VANILLA
    )

    return QSCIAnalysis(lowering_level, dummy_result, circuit_analysis)

run abstractmethod

run(*args, **kwargs)

Run the algorithm itself.

Source code in src/qsci_algo_interface.py

@abstractmethod
def run(self, *args: Any, **kwargs: Any) -> AlgorithmResult:
    """Run the algorithm itself."""
    pass

VanillaQSCIAlgorithm

VanillaQSCIAlgorithm(
    hamiltonian, sampler=None, num_states_pick_out=None
)

Bases: QSCIAlgorithmBase

Vanilla QSCI algorithm compatible with quri-algo interface.

Methods:

Name	Description
run	Run vanilla QSCI algorithm.
analyze	Analyze quantum resource requirements for QSCI algorithm.

Attributes:

Name	Type	Description
name	str
hamiltonian
sampler
num_states_pick_out

Source code in src/qsci_algo_interface.py

def __init__(
    self,
    hamiltonian: Operator,
    sampler: Optional[ConcurrentSampler] = None,
    num_states_pick_out: Optional[int] = None
):
    self.hamiltonian = hamiltonian
    self.sampler = sampler
    self.num_states_pick_out = num_states_pick_out

name property

name

hamiltonian instance-attribute

hamiltonian = hamiltonian

sampler instance-attribute

sampler = sampler

num_states_pick_out instance-attribute

num_states_pick_out = num_states_pick_out

run

run(input_states, total_shots, **kwargs)

Run vanilla QSCI algorithm.

Source code in src/qsci_algo_interface.py

def run(
    self,
    input_states: Sequence[CircuitQuantumState],
    total_shots: int,
    **kwargs
) -> QSCIAlgorithmResult:
    """Run vanilla QSCI algorithm."""
    start_time = time.time()

    qsci_impl = self._create_qsci_implementation()
    qsci_result = qsci_impl.run(input_states, total_shots, start_time=start_time, **kwargs)

    elapsed_time = time.time() - start_time
    return QSCIAlgorithmResult(self, qsci_result, elapsed_time)

analyze

analyze(
    input_states,
    total_shots,
    lowering_level=LogicalCircuit,
    **kwargs
)

Analyze quantum resource requirements for QSCI algorithm.

Source code in src/qsci_algo_interface.py

def analyze(
    self, 
    input_states: Sequence[CircuitQuantumState],
    total_shots: int,
    lowering_level: LoweringLevel = LoweringLevel.LogicalCircuit,
    **kwargs
) -> QSCIAnalysis:
    """Analyze quantum resource requirements for QSCI algorithm."""
    # For analysis, we can estimate without actually running
    circuit_analysis = {}

    if input_states:
        # Analyze input circuits
        total_gates = sum(len(state.circuit) for state in input_states)
        max_depth = max(state.circuit.depth for state in input_states) if input_states else 0
        qubit_count = input_states[0].qubit_count if input_states else 0

        circuit_analysis = {
            "gate_count": {"total": total_gates},
            "depth": {"max": max_depth},
            "qubit_count": {"required": qubit_count},
            "latency": {},  # Would need backend-specific estimation
            "fidelities": {}  # Would need noise model
        }

    # Create dummy result for analysis
    dummy_result = QSCIResult(
        eigenvalues=[0.0],
        eigenstates=[],
        selected_states=[],
        subspace_dimension=self.num_states_pick_out or 100,
        total_shots=total_shots,
        algorithm_variant=QSCIVariant.VANILLA
    )

    return QSCIAnalysis(lowering_level, dummy_result, circuit_analysis)

SingleTimeTeQSCIAlgorithm

SingleTimeTeQSCIAlgorithm(
    hamiltonian,
    evolution_time,
    sampler=None,
    num_states_pick_out=None,
    trotter_steps=None,
    time_evolution_method="trotter",
)

Bases: QSCIAlgorithmBase

Single-time TE-QSCI algorithm compatible with quri-algo interface.

Methods:

Name	Description
run	Run single-time TE-QSCI algorithm.
analyze	Analyze quantum resource requirements for QSCI algorithm.

Attributes:

Name	Type	Description
evolution_time
trotter_steps
time_evolution_method
name	str
hamiltonian
sampler
num_states_pick_out

Source code in src/qsci_algo_interface.py

def __init__(
    self,
    hamiltonian: Operator,
    evolution_time: float,
    sampler: Optional[ConcurrentSampler] = None,
    num_states_pick_out: Optional[int] = None,
    trotter_steps: Optional[int] = None,
    time_evolution_method: str = "trotter"
):
    super().__init__(hamiltonian, sampler, num_states_pick_out)
    self.evolution_time = evolution_time
    self.trotter_steps = trotter_steps
    self.time_evolution_method = time_evolution_method

evolution_time instance-attribute

evolution_time = evolution_time

trotter_steps instance-attribute

trotter_steps = trotter_steps

time_evolution_method instance-attribute

time_evolution_method = time_evolution_method

name property

name

hamiltonian instance-attribute

hamiltonian = hamiltonian

sampler instance-attribute

sampler = sampler

num_states_pick_out instance-attribute

num_states_pick_out = num_states_pick_out

run

run(initial_state, total_shots, **kwargs)

Run single-time TE-QSCI algorithm.

Source code in src/qsci_algo_interface.py

def run(
    self,
    initial_state: CircuitQuantumState,
    total_shots: int,
    **kwargs
) -> QSCIAlgorithmResult:
    """Run single-time TE-QSCI algorithm."""
    start_time = time.time()

    # Use trotter_steps from constructor, or from kwargs if not set in constructor
    trotter_steps = self.trotter_steps if self.trotter_steps is not None else kwargs.get("trotter_steps")

    # Remove trotter_steps from kwargs to avoid duplicate argument
    filtered_kwargs = {k: v for k, v in kwargs.items() if k != "trotter_steps"}

    te_qsci_impl = self._create_qsci_implementation()
    qsci_result = te_qsci_impl.run_single_time(
        initial_state,
        self.evolution_time,
        total_shots,
        trotter_steps,
        start_time=start_time,
        **filtered_kwargs
    )

    elapsed_time = time.time() - start_time
    return QSCIAlgorithmResult(self, qsci_result, elapsed_time)

analyze

analyze(
    input_states,
    total_shots,
    lowering_level=LogicalCircuit,
    **kwargs
)

Analyze quantum resource requirements for QSCI algorithm.

Source code in src/qsci_algo_interface.py

def analyze(
    self, 
    input_states: Sequence[CircuitQuantumState],
    total_shots: int,
    lowering_level: LoweringLevel = LoweringLevel.LogicalCircuit,
    **kwargs
) -> QSCIAnalysis:
    """Analyze quantum resource requirements for QSCI algorithm."""
    # For analysis, we can estimate without actually running
    circuit_analysis = {}

    if input_states:
        # Analyze input circuits
        total_gates = sum(len(state.circuit) for state in input_states)
        max_depth = max(state.circuit.depth for state in input_states) if input_states else 0
        qubit_count = input_states[0].qubit_count if input_states else 0

        circuit_analysis = {
            "gate_count": {"total": total_gates},
            "depth": {"max": max_depth},
            "qubit_count": {"required": qubit_count},
            "latency": {},  # Would need backend-specific estimation
            "fidelities": {}  # Would need noise model
        }

    # Create dummy result for analysis
    dummy_result = QSCIResult(
        eigenvalues=[0.0],
        eigenstates=[],
        selected_states=[],
        subspace_dimension=self.num_states_pick_out or 100,
        total_shots=total_shots,
        algorithm_variant=QSCIVariant.VANILLA
    )

    return QSCIAnalysis(lowering_level, dummy_result, circuit_analysis)

TimeAverageTeQSCIAlgorithm

TimeAverageTeQSCIAlgorithm(
    hamiltonian,
    evolution_times,
    sampler=None,
    num_states_pick_out=None,
    trotter_steps=None,
    time_evolution_method="trotter",
)

Bases: QSCIAlgorithmBase

Time-average TE-QSCI algorithm compatible with quri-algo interface.

Methods:

Name	Description
run	Run time-average TE-QSCI algorithm.
analyze	Analyze quantum resource requirements for QSCI algorithm.

Attributes:

Name	Type	Description
evolution_times
trotter_steps
time_evolution_method
name	str
hamiltonian
sampler
num_states_pick_out

Source code in src/qsci_algo_interface.py

def __init__(
    self,
    hamiltonian: Operator,
    evolution_times: Sequence[float],
    sampler: Optional[ConcurrentSampler] = None,
    num_states_pick_out: Optional[int] = None,
    trotter_steps: Optional[int] = None,
    time_evolution_method: str = "trotter"
):
    super().__init__(hamiltonian, sampler, num_states_pick_out)
    self.evolution_times = evolution_times
    self.trotter_steps = trotter_steps
    self.time_evolution_method = time_evolution_method

evolution_times instance-attribute

evolution_times = evolution_times

trotter_steps instance-attribute

trotter_steps = trotter_steps

time_evolution_method instance-attribute

time_evolution_method = time_evolution_method

name property

name

hamiltonian instance-attribute

hamiltonian = hamiltonian

sampler instance-attribute

sampler = sampler

num_states_pick_out instance-attribute

num_states_pick_out = num_states_pick_out

run

run(initial_state, shots_per_time, **kwargs)

Run time-average TE-QSCI algorithm.

Source code in src/qsci_algo_interface.py

def run(
    self,
    initial_state: CircuitQuantumState,
    shots_per_time: int,
    **kwargs
) -> QSCIAlgorithmResult:
    """Run time-average TE-QSCI algorithm."""
    start_time = time.time()

    # Use trotter_steps from constructor, or from kwargs if not set in constructor
    trotter_steps = self.trotter_steps if self.trotter_steps is not None else kwargs.get("trotter_steps")

    # Remove trotter_steps from kwargs to avoid duplicate argument
    filtered_kwargs = {k: v for k, v in kwargs.items() if k != "trotter_steps"}

    te_qsci_impl = self._create_qsci_implementation()
    qsci_result = te_qsci_impl.run_time_average(
        initial_state,
        self.evolution_times,
        shots_per_time,
        trotter_steps,
        start_time=start_time,
        **filtered_kwargs
    )

    elapsed_time = time.time() - start_time
    return QSCIAlgorithmResult(self, qsci_result, elapsed_time)

analyze

analyze(
    input_states,
    total_shots,
    lowering_level=LogicalCircuit,
    **kwargs
)

Analyze quantum resource requirements for QSCI algorithm.

Source code in src/qsci_algo_interface.py

def analyze(
    self, 
    input_states: Sequence[CircuitQuantumState],
    total_shots: int,
    lowering_level: LoweringLevel = LoweringLevel.LogicalCircuit,
    **kwargs
) -> QSCIAnalysis:
    """Analyze quantum resource requirements for QSCI algorithm."""
    # For analysis, we can estimate without actually running
    circuit_analysis = {}

    if input_states:
        # Analyze input circuits
        total_gates = sum(len(state.circuit) for state in input_states)
        max_depth = max(state.circuit.depth for state in input_states) if input_states else 0
        qubit_count = input_states[0].qubit_count if input_states else 0

        circuit_analysis = {
            "gate_count": {"total": total_gates},
            "depth": {"max": max_depth},
            "qubit_count": {"required": qubit_count},
            "latency": {},  # Would need backend-specific estimation
            "fidelities": {}  # Would need noise model
        }

    # Create dummy result for analysis
    dummy_result = QSCIResult(
        eigenvalues=[0.0],
        eigenstates=[],
        selected_states=[],
        subspace_dimension=self.num_states_pick_out or 100,
        total_shots=total_shots,
        algorithm_variant=QSCIVariant.VANILLA
    )

    return QSCIAnalysis(lowering_level, dummy_result, circuit_analysis)

StateVectorTeQSCIAlgorithm

StateVectorTeQSCIAlgorithm(
    hamiltonian,
    evolution_time,
    num_states_pick_out=None,
    time_evolution_method="exact",
)

Bases: QSCIAlgorithmBase

State vector TE-QSCI algorithm compatible with quri-algo interface.

Methods:

Name	Description
run	Run state vector TE-QSCI algorithm.
analyze	Analyze quantum resource requirements for QSCI algorithm.

Attributes:

Name	Type	Description
evolution_time
time_evolution_method
name	str
hamiltonian
sampler
num_states_pick_out

Source code in src/qsci_algo_interface.py

def __init__(
    self,
    hamiltonian: Operator,
    evolution_time: float,
    num_states_pick_out: Optional[int] = None,
    time_evolution_method: str = "exact"
):
    super().__init__(hamiltonian, None, num_states_pick_out)  # No sampler needed
    self.evolution_time = evolution_time
    self.time_evolution_method = time_evolution_method

evolution_time instance-attribute

evolution_time = evolution_time

time_evolution_method instance-attribute

time_evolution_method = time_evolution_method

name property

name

hamiltonian instance-attribute

hamiltonian = hamiltonian

sampler instance-attribute

sampler = sampler

num_states_pick_out instance-attribute

num_states_pick_out = num_states_pick_out

run

run(initial_state, num_eigenstates=1, **kwargs)

Run state vector TE-QSCI algorithm.

Source code in src/qsci_algo_interface.py

def run(
    self,
    initial_state: CircuitQuantumState,
    num_eigenstates: int = 1,
    **kwargs
) -> QSCIAlgorithmResult:
    """Run state vector TE-QSCI algorithm."""
    start_time = time.time()

    te_qsci_impl = self._create_qsci_implementation()
    qsci_result = te_qsci_impl.run_state_vector(
        initial_state,
        self.evolution_time,
        num_eigenstates,
        start_time=start_time,
        **kwargs
    )

    elapsed_time = time.time() - start_time
    return QSCIAlgorithmResult(self, qsci_result, elapsed_time)

analyze

analyze(
    input_states,
    total_shots,
    lowering_level=LogicalCircuit,
    **kwargs
)

Analyze quantum resource requirements for QSCI algorithm.

Source code in src/qsci_algo_interface.py

def analyze(
    self, 
    input_states: Sequence[CircuitQuantumState],
    total_shots: int,
    lowering_level: LoweringLevel = LoweringLevel.LogicalCircuit,
    **kwargs
) -> QSCIAnalysis:
    """Analyze quantum resource requirements for QSCI algorithm."""
    # For analysis, we can estimate without actually running
    circuit_analysis = {}

    if input_states:
        # Analyze input circuits
        total_gates = sum(len(state.circuit) for state in input_states)
        max_depth = max(state.circuit.depth for state in input_states) if input_states else 0
        qubit_count = input_states[0].qubit_count if input_states else 0

        circuit_analysis = {
            "gate_count": {"total": total_gates},
            "depth": {"max": max_depth},
            "qubit_count": {"required": qubit_count},
            "latency": {},  # Would need backend-specific estimation
            "fidelities": {}  # Would need noise model
        }

    # Create dummy result for analysis
    dummy_result = QSCIResult(
        eigenvalues=[0.0],
        eigenstates=[],
        selected_states=[],
        subspace_dimension=self.num_states_pick_out or 100,
        total_shots=total_shots,
        algorithm_variant=QSCIVariant.VANILLA
    )

    return QSCIAnalysis(lowering_level, dummy_result, circuit_analysis)

create_qsci_algorithm

create_qsci_algorithm(
    variant,
    hamiltonian,
    sampler=None,
    num_states_pick_out=None,
    **variant_kwargs
)

Factory function to create QSCI algorithm variants.

Parameters:

Name	Type	Description	Default
variant	QSCIVariant	QSCI algorithm variant	required
hamiltonian	Operator	Target Hamiltonian	required
sampler	Optional[ConcurrentSampler]	Quantum sampler	None
num_states_pick_out	Optional[int]	Number of states to select	None
**variant_kwargs		Variant-specific parameters	{}

Returns:

Type	Description
QSCIAlgorithmBase	QSCI algorithm instance

Source code in src/qsci_algo_interface.py

def create_qsci_algorithm(
    variant: QSCIVariant,
    hamiltonian: Operator,
    sampler: Optional[ConcurrentSampler] = None,
    num_states_pick_out: Optional[int] = None,
    **variant_kwargs
) -> QSCIAlgorithmBase:
    """Factory function to create QSCI algorithm variants.

    Args:
        variant: QSCI algorithm variant
        hamiltonian: Target Hamiltonian
        sampler: Quantum sampler
        num_states_pick_out: Number of states to select
        **variant_kwargs: Variant-specific parameters

    Returns:
        QSCI algorithm instance
    """
    if variant == QSCIVariant.VANILLA:
        return VanillaQSCIAlgorithm(hamiltonian, sampler, num_states_pick_out)

    elif variant == QSCIVariant.SINGLE_TIME_TE:
        evolution_time = variant_kwargs.get("evolution_time", 1.0)
        trotter_steps = variant_kwargs.get("trotter_steps")
        time_evolution_method = variant_kwargs.get("time_evolution_method", "trotter")
        return SingleTimeTeQSCIAlgorithm(
            hamiltonian, evolution_time, sampler, num_states_pick_out, trotter_steps, time_evolution_method
        )

    elif variant == QSCIVariant.TIME_AVERAGE_TE:
        evolution_times = variant_kwargs.get("evolution_times", [0.5, 1.0, 1.5])
        trotter_steps = variant_kwargs.get("trotter_steps")
        time_evolution_method = variant_kwargs.get("time_evolution_method", "trotter")
        return TimeAverageTeQSCIAlgorithm(
            hamiltonian, evolution_times, sampler, num_states_pick_out, trotter_steps, time_evolution_method
        )

    elif variant == QSCIVariant.STATE_VECTOR:
        evolution_time = variant_kwargs.get("evolution_time", 1.0)
        time_evolution_method = variant_kwargs.get("time_evolution_method", "exact")
        return StateVectorTeQSCIAlgorithm(hamiltonian, evolution_time, num_states_pick_out, time_evolution_method)

    else:
        raise ValueError(f"Unknown QSCI variant: {variant}")