Skip to content

Modes to Labels

The ModesToLabels system assigns semantic labels to eigenmodes for quantum simulations. You can use either a simple dictionary or the full ModesToLabels class with inference strategies.

Simple Dictionary Approach

For straightforward cases where you know the exact mode numbers:

from quansys.simulation import QuantumEPR

# Simple mapping: mode number → label
epr = QuantumEPR(
    setup_name="eigenmode_setup",
    design_name="my_design", 
    modes_to_labels={1: "transmon", 2: "readout", 3: "bus"}
)

ModesToLabels Class - Combined Strategy

For automatic mode labeling using multiple inference strategies:

from quansys.simulation import QuantumEPR
from quansys.simulation.quantum_epr.modes_to_labels import (
    ModesToLabels, ManualInference, OrderInference
)

# Example eigenmode data
eigenmode_results = {
    1: {'frequency': 3.5, 'quality_factor': 100},
    2: {'frequency': 5.1, 'quality_factor': 120}, 
    3: {'frequency': 5.8, 'quality_factor': 90},
    4: {'frequency': 6.0, 'quality_factor': 150}
}

# Combined strategy: pin control manually + select lossy modes automatically
modes_to_labels = ModesToLabels(inferences=[
    ManualInference(mode_number=3, label="control"),           # Pin mode 3 as 'control'
    OrderInference(                                        # For remaining modes:
        num=2,                                             # Select 2 modes  
        min_or_max='min',                                  # With lowest Q (lossy)
        quantity='quality_factor',                         # Based on quality factor
        ordered_labels_by_frequency=['readout', 'purcell'] # Order by frequency
    )
])

result = modes_to_labels.parse(eigenmode_results)
print(result) # Output: {1: 'readout', 2: 'purcell', 3: 'control'}
# First execute all manual inferences, then order remaining modes by quality factor and frequency.

Individual Inference Strategies

For detailed examples and usage patterns:

Execution Order

  1. ManualInference: Applied first, assigns fixed mode numbers to specific labels
  2. OrderInference: Applied to remaining modes, selects based on quality factor then orders by frequency

This ensures critical modes (like bus resonators) are always correctly labeled, while lossy modes are automatically identified and ordered.

Bases: BaseModel

A scheme for assigning labels to eigenmodes using a list of inference rules.

This class orchestrates the application of multiple inference strategies, first applying all ManualInference and then OrderInference in sequence to extract labels for eigenmodes.

Attributes:

Name Type Description
inferences list[SUPPORTED_INFERENCES]

A list of inference strategies. Each must be either ManualInference or OrderInference.

parse 

parse(
    eigenmode_results: dict[int, dict[str, float]],
) -> dict[int, str]

Applies all configured inference rules to generate a mapping from mode numbers to labels.

Manual inferences are executed before automatic (order-based) inferences. Once a mode is labeled by an inference, it is excluded from further processing by others.

Parameters:

Name Type Description Default
eigenmode_results dict[int, dict[str, float]]

A dictionary where each key is a mode number, and the value is a dictionary of mode properties such as frequency or quality factor.

 required

Returns:

Type Description
dict[int, str]

dict[int, str]: A mapping from mode number to assigned label.
Source code in src/quansys/simulation/quantum_epr/modes_to_labels/modes_labels_scheme.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
def parse(self, eigenmode_results: dict[int, dict[str, float]]) -> dict[int, str]:
    """
    Applies all configured inference rules to generate a mapping from mode numbers to labels.

    Manual inferences are executed before automatic (order-based) inferences.
    Once a mode is labeled by an inference, it is excluded from further processing by others.

    Args:
        eigenmode_results (dict[int, dict[str, float]]):
            A dictionary where each key is a mode number, and the value is a dictionary
            of mode properties such as frequency or quality factor.

    Returns:
        dict[int, str]: A mapping from mode number to assigned label.
    """

    # first execution of manual inferences
    manual_inferences = filter(lambda x: isinstance(x, ManualInference), self.inferences)
    other_inferences = filter(lambda x: not isinstance(x, ManualInference), self.inferences)

    modes_to_labels = {}

    #
    inference_execution_order = [manual_inferences, other_inferences]

    for group in inference_execution_order:
        for inference in group:

            d = inference.infer(eigenmode_results)

            new_modes = set(d.keys())
            available_modes = set(eigenmode_results.keys()) - new_modes
            eigenmode_results = {m: eigenmode_results[m] for m in available_modes}

            modes_to_labels.update(d)

    return modes_to_labels