Add get config functions

cirq-google/cirq_google/cloud/quantum/__init__.py

@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+from cirq_google.cloud.quantum import gapic_version as package_version
+
+__version__ = package_version.__version__
+
 
 from cirq_google.cloud.quantum_v1alpha1.services.quantum_engine_service.client import (
     QuantumEngineServiceClient,

cirq-google/cirq_google/cloud/quantum/gapic_version.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+__version__ = "0.0.0"  # {x-release-please-version}

cirq-google/cirq_google/cloud/quantum_v1alpha1/__init__.py

@@ -13,6 +13,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 #
+from . import gapic_version as package_version
+
+__version__ = package_version.__version__
+
 
 from .services.quantum_engine_service import QuantumEngineServiceClient
 from .services.quantum_engine_service import QuantumEngineServiceAsyncClient

cirq-google/cirq_google/cloud/quantum_v1alpha1/gapic_version.py

@@ -0,0 +1,16 @@
+# -*- coding: utf-8 -*-
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+__version__ = "0.0.0"  # {x-release-please-version}

cirq-google/cirq_google/engine/__init__.py

@@ -20,6 +20,10 @@
 
 from cirq_google.engine.abstract_processor import AbstractProcessor as AbstractProcessor
 
+from cirq_google.engine.abstract_processor_config import (
+    AbstractProcessorConfig as AbstractProcessorConfig,
+)
+
 from cirq_google.engine.abstract_program import AbstractProgram as AbstractProgram
 
 from cirq_google.engine.abstract_local_engine import AbstractLocalEngine as AbstractLocalEngine
@@ -95,3 +99,5 @@
 from cirq_google.engine.engine_result import EngineResult as EngineResult
 
 from cirq_google.engine.processor_sampler import ProcessorSampler as ProcessorSampler
+
+from cirq_google.engine.processor_config import ProcessorConfig as ProcessorConfig

cirq-google/cirq_google/engine/abstract_engine.py

@@ -26,7 +26,12 @@
 if TYPE_CHECKING:
     import cirq
     from cirq_google.cloud import quantum
-    from cirq_google.engine import abstract_job, abstract_processor, abstract_program
+    from cirq_google.engine import (
+        abstract_job,
+        abstract_processor,
+        abstract_processor_config,
+        abstract_program,
+    )
 
 VALID_DATE_TYPE = datetime.datetime | datetime.date
 
@@ -134,3 +139,35 @@ def get_sampler(self, processor_id: str | list[str]) -> cirq.Sampler:
             processor_id: String identifier, or list of string identifiers,
                 determining which processors may be used when sampling.
         """
+
+    @abc.abstractmethod
+    def get_processor_config_by_snapshot_id(
+        self, processor_id: str, snapshot_id: str, config_id: str
+    ) -> abstract_processor_config.AbstractProcessorConfig | None:
+        """Returns a ProcessorConfig from this project and the given processor id.
+
+        Args:
+           processor_id: The processor unique identifier.
+           snapshot_id: The unique identifier for the snapshot.
+           config_id: The unique identifier for the snapshot.
+
+        Returns:
+           The ProcessorConfig from this project and processor.
+        """
+
+    @abc.abstractmethod
+    def get_processor_config_by_run_name(
+        self, processor_id: str, config_id: str, run_name: str = 'current'
+    ) -> abstract_processor_config.AbstractProcessorConfig | None:
+        """Returns a ProcessorConfig from this project and the given processor id.
+
+        If no run_name is provided, the config from the most recent run is returned.
+
+        Args:
+            processor_id: The processor unique identifier.
+            run_name: The unique identifier for the automation run.
+            config_id: The unique identifier for the snapshot.
+
+        Returns:
+            The ProcessorConfig from this project and processor.
+        """

cirq-google/cirq_google/engine/abstract_local_engine.py

@@ -175,3 +175,15 @@ def get_sampler(self, processor_id: str | list[str]) -> cirq.Sampler:
         if not isinstance(processor_id, str):
             raise ValueError(f'Invalid processor {processor_id}')
         return self._processors[processor_id].get_sampler()
+
+    def get_processor_config_by_snapshot_id(
+        self, processor_id: str, snapshot_id: str, config_id: str
+    ):
+        # TODO: Implement later as needed.
+        pass
+
+    def get_processor_config_by_run_name(
+        self, processor_id: str, config_id: str, run_name: str = 'current'
+    ):
+        # TODO: Implement later as needed.
+        pass

cirq-google/cirq_google/engine/abstract_local_engine_test.py

@@ -81,6 +81,12 @@ def list_programs(
     def get_program(self, program_id: str) -> AbstractProgram:
         return self._programs[program_id]
 
+    def get_config_by_run_name(self, *args, **kwargs):
+        pass
+
+    def get_config_by_snapshot(self, *args, **kwargs):
+        pass
+
 
 class NothingEngine(AbstractLocalEngine):
     """Engine for Testing."""

cirq-google/cirq_google/engine/abstract_local_processor_test.py

@@ -71,6 +71,12 @@ def list_programs(self, *args, **kwargs):
     def get_program(self, *args, **kwargs):
         pass
 
+    def get_config_by_run_name(self, config_id: str, run_name: str = "current"):
+        pass
+
+    def get_config_by_snapshot(self, config_id: str, snapshot_id: str):
+        pass
+
 
 def test_datetime():
     recovery_time = datetime.datetime.now()

cirq-google/cirq_google/engine/abstract_processor.py

@@ -35,6 +35,7 @@
     import cirq_google.engine.abstract_engine as abstract_engine
     import cirq_google.engine.abstract_job as abstract_job
     import cirq_google.engine.calibration as calibration
+    from cirq_google.engine import abstract_processor_config
 
 
 class AbstractProcessor(abc.ABC):
@@ -377,3 +378,35 @@ def get_schedule(
         Returns:
             Schedule time slots.
         """
+
+    @abc.abstractmethod
+    def get_config_by_run_name(
+        self, config_id: str, run_name: str = "current"
+    ) -> abstract_processor_config.AbstractProcessorConfig | None:
+        """Retrieves a ProcessorConfig from an automation run.
+
+            If no run name is provided, the config from the most recent run
+            is returned.
+
+        Args:
+            processor_id: The processor unique identifier.
+            config_id: The quantum processor's unique identifier.
+            run_name: The automation run name.  Use 'current'
+                      if none id provided.
+
+        Returns: The quantum processor config.
+        """
+
+    @abc.abstractmethod
+    def get_config_by_snapshot(
+        self, config_id: str, snapshot_id: str
+    ) -> abstract_processor_config.AbstractProcessorConfig | None:
+        """Retrieves a ProcessorConfig from a given snapshot id.
+
+        Args:
+            processor_id: The processor unique identifier.
+            config_id: The quantum processor's unique identifier.
+            snapshot_id: The snapshot's unique identifier.
+
+        Returns: The quantum processor config.
+        """

cirq-google/cirq_google/engine/abstract_processor_config.py

@@ -0,0 +1,65 @@
+# Copyright 2025 The Cirq Developers
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import abc
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import cirq
+    import cirq_google as cg
+
+
+class AbstractProcessorConfig(abc.ABC):
+    """Interface for a QuantumProcessorConfig.
+
+    Describes available qubits, gates, and calivration data associated with
+    a processor configuration.
+    """
+
+    @property
+    @abc.abstractmethod
+    def effective_device(self) -> cirq.Device:
+        """The Device generated from thi configuration's device specification"""
+
+    @property
+    @abc.abstractmethod
+    def calibration(self) -> cg.Calibration:
+        """Charicterization metrics captured for this configuration"""
+
+    @property
+    @abc.abstractmethod
+    def snapshot_id(self) -> str:
+        """The snapshot that contains this processor config"""
+
+    @property
+    @abc.abstractmethod
+    def run_name(self) -> str:
+        """The run that generated this config if avaiable."""
+
+    @property
+    @abc.abstractmethod
+    def project_id(self) -> str:
+        """The if of the project that contains this config."""
+
+    @property
+    @abc.abstractmethod
+    def processor_id(self) -> str:
+        """The processor id for this config."""
+
+    @property
+    @abc.abstractmethod
+    def config_id(self) -> str:
+        """The unique identifier for this config."""

cirq-google/cirq_google/engine/engine.py

@@ -43,6 +43,7 @@
     engine_job,
     engine_processor,
     engine_program,
+    processor_config,
     util,
 )
 from cirq_google.serialization import CIRCUIT_SERIALIZER, Serializer
@@ -623,6 +624,61 @@ def get_sampler(
             max_concurrent_jobs=max_concurrent_jobs,
         )
 
+    async def get_processor_config_by_snapshot_id_async(
+        self, processor_id: str, snapshot_id: str, config_id: str
+    ) -> processor_config.ProcessorConfig | None:
+        """Returns a ProcessorConfig from this project and the given processor id.
+
+        Args:
+           processor_id: The processor unique identifier.
+           snapshot_id: The unique identifier for the snapshot.
+           config_id: The unique identifier for the snapshot.
+
+        Returns:
+           The ProcessorConfig from this project and processor.
+        """
+        client = self.context.client
+        quantum_config = await client.get_quantum_processor_config_by_snapshot_id_async(
+            project_id=self.project_id,
+            processor_id=processor_id,
+            snapshot_id=snapshot_id,
+            config_id=config_id,
+        )
+        if quantum_config:
+            return processor_config.ProcessorConfig(quantum_processor_config=quantum_config)
+        return None
+
+    get_processor_config_by_snapshot_id = duet.sync(get_processor_config_by_snapshot_id_async)
+
+    async def get_processor_config_by_run_name_async(
+        self, processor_id: str, config_id: str, run_name: str = 'current'
+    ) -> processor_config.ProcessorConfig | None:
+        """Returns a ProcessorConfig from this project and the given processor id.
+
+        If no run_name is provided, the config from the most recent run is returned.
+
+        Args:
+            processor_id: The processor unique identifier.
+            run_name: The unique identifier for the automation run.
+            config_id: The unique identifier for the snapshot.
+
+        Returns:
+            The ProcessorConfig from this project and processor.
+        """
+        quantum_config = await self.context.client.get_quantum_processor_config_by_run_name_async(
+            project_id=self.project_id,
+            processor_id=processor_id,
+            run_name=run_name,
+            config_id=config_id,
+        )
+        if quantum_config:
+            return processor_config.ProcessorConfig(
+                quantum_processor_config=quantum_config, run_name=run_name
+            )
+        return None
+
+    get_processor_config_by_run_name = duet.sync(get_processor_config_by_run_name_async)
+
 
 def get_engine(project_id: str | None = None) -> Engine:
     """Get an Engine instance assuming some sensible defaults.