etiket-sync-agent-qcodes 0.3.0b1__py3-none-any.whl

etiket_sync_agent_qcodes/__init__.py

@@ -0,0 +1,4 @@
+from etiket_sync_agent_qcodes.qcodes_sync_class import QCoDeSSync, QCoDeSConfigData
+
+__all__ = ["QCoDeSSync", "QCoDeSConfigData"]
+__version__ = "0.3.0b1"

etiket_sync_agent_qcodes/qcodes_config_class.py

@@ -0,0 +1,93 @@
+import pathlib
+import dataclasses
+import sqlite3
+from typing import Optional
+
+import etiket_sync_agent_qcodes
+
+from etiket_sync_agent.crud.sync_sources import crud_sync_sources, SyncSources
+from etiket_sync_agent.db import get_db_session_context
+
+@dataclasses.dataclass
+class QCoDeSConfigData:
+    database_path: pathlib.Path
+    set_up : str
+    static_attributes : Optional[dict] = dataclasses.field(default_factory=dict)
+    
+    def __post_init__(self):
+        # ensure the path is of the type pathlib.Path (str is converted to Path) and expand ~
+        self.database_path = pathlib.Path(self.database_path).expanduser()
+    
+    async def validate(self, current_sync_source : Optional[SyncSources] = None):
+        """
+        Validates the QCoDeS database configuration.
+
+        Checks:
+        1. If the database_path path points to an existing file.
+        2. If the file has a .db extension.
+        3. If the file can be opened as an SQLite database.
+        4. If the database file has already been added as a QCoDeS sync source.
+
+        Args:
+            current_source (Optional[SyncSources]): in case of update, the current sync source is provided.
+
+        Raises:
+            ValueError: If any validation check fails.
+
+        Returns:
+            True if all checks pass.
+        """
+        try:
+            abs_db_path = pathlib.Path(self.database_path).expanduser().resolve(strict=True)
+        except FileNotFoundError:
+            raise ValueError(f"The specified database file does not exist: {self.database_path}")
+        
+        if not abs_db_path.is_file():
+            raise ValueError(f"The specified path is not a file: {abs_db_path}")
+
+        if abs_db_path.suffix != ".db":
+            raise ValueError(f"A QCoDeS database file must have a .db extension, not '{abs_db_path.suffix}'. Provided path: {abs_db_path}")
+
+        # test basic sqlite3 connection and verify QCoDeS database structure
+        try:
+            conn = sqlite3.connect(f'file:{abs_db_path}?mode=ro', uri=True)
+            cursor = conn.cursor()
+            
+            # Query sqlite_master to check for QCoDeS-specific tables
+            cursor.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name IN ('runs', 'experiments')"
+            )
+            tables = {row[0] for row in cursor.fetchall()}
+            
+            conn.close()
+            
+            # Verify required QCoDeS tables exist
+            required_tables = {'runs', 'experiments'}
+            missing_tables = required_tables - tables
+            if missing_tables:
+                raise ValueError(
+                    f"The database '{abs_db_path}' does not appear to be a valid QCoDeS database. "
+                    f"Missing required tables: {', '.join(sorted(missing_tables))}"
+                )
+        except sqlite3.Error as e:
+            raise ValueError(f"Error opening SQLite database file '{abs_db_path}': {e}") from e
+        
+        # check if the database file is already added.
+        async with get_db_session_context() as session:
+            sync_sources = await crud_sync_sources.list_sync_sources(session)
+            for sync_source in sync_sources:
+                if sync_source.backend == etiket_sync_agent_qcodes.__name__:
+                    try:
+                        existing_path_str = sync_source.config_data['database_path']
+                        existing_path = pathlib.Path(existing_path_str).resolve()
+                    except Exception as e:
+                        # If an existing path can't be resolved, log it but continue validation
+                        print(f"Warning: Could not resolve existing database path '{existing_path_str}' for sync source '{sync_source.name}' ({sync_source.id}): {e}")
+                        continue
+                    
+                    if abs_db_path == existing_path:
+                        if current_sync_source is not None and current_sync_source.id == sync_source.id:
+                            continue
+                        raise ValueError(f"The database file '{abs_db_path}' is already added as sync source '{sync_source.name}'.")
+
+        return True

etiket_sync_agent_qcodes/qcodes_metadata.py

@@ -0,0 +1,116 @@
+from typing import List, Dict
+
+from qcodes.instrument import Instrument
+from qcodes.parameters import Parameter
+
+class QHMetaData(Instrument):
+    """
+    A QCoDeS Instrument subclass that manages metadata for a dataset within the QHarbor framework.
+
+    This instrument stores tags and attributes, which the synchronization agent will recognize and add as such to the dataset.
+    """
+
+    def __init__(self, name : str, static_tags: List[str] = [],
+                        static_attributes: Dict[str, str] = {}):
+        """
+        Initialize a QHMetaData instance.
+
+        Args:
+            name (str): The name of the instrument, this should be "qh_meta"
+            static_tags (List[str]): A list of static tags that are always included in
+                the metadata. These tags remain after the reset method is called.
+            static_attributes (Dict[str, str]): A dictionary of static attributes that are
+                always included in the metadata. These attributes remain after the reset method is called.
+        """
+        super().__init__(name)
+        
+        self._static_tags = static_tags
+        self._static_attributes = static_attributes
+
+        self._dynamic_tags = []
+        self._dynamic_attributes = {}
+
+        self.add_parameter("tags", get_cmd=self.__get_tags)
+        self.add_parameter("attributes", get_cmd=self.__get_attributes)
+
+    def add_tags(self, tags: List[str]) -> None:
+        """
+        Add dynamic tags to the metadata. These tags will be cleared upon reset.
+
+        Args:
+            tags (List[str]): A list of tags to add.
+        """
+        self._dynamic_tags.extend(tags)
+
+    def add_attributes(self, attributes: Dict[str, str]) -> None:
+        """
+        Add dynamic attributes to the metadata. These attributes will be cleared upon reset.
+
+        Args:
+            attributes (Dict[str, str]): A dictionary of key-value pairs to add as attributes.
+        """
+        self._dynamic_attributes.update(attributes)
+
+    def reset(self) -> None:
+        """
+        Clear all dynamic tags and attributes.
+
+        This does not affect static tags or attributes, nor the list of important parameters.
+        """
+        self._dynamic_tags.clear()
+        self._dynamic_attributes.clear()
+
+    def __get_tags(self) -> List[str]:
+        """
+        Return a combined list of static and dynamic tags.
+
+        Returns:
+            List[str]: The current list of tags (static + dynamic).
+        """
+        return list(set(self._static_tags + self._dynamic_tags))
+
+    def __get_attributes(self) -> Dict[str, str]:
+        """
+        Return a combined dictionary containing static, dynamic attributes, and parameter values.
+
+        Returns:
+            Dict[str, str]: A dictionary with the static and dynamic attributes.
+        """
+        attr = {**self._static_attributes}
+        attr.update(self._dynamic_attributes)
+        return attr
+    
+    def get_idn(self):
+        return {'vendor': 'QHarbor', 'model': 'QHarbor Metadata Manager', 'serial': None, 'firmware': None}
+    
+def validate_parameter(parameter: Parameter) -> Parameter:
+    # for when we add parameters to the metadata.
+    """
+    Validate that a parameter is an instance of qcodes.Parameter and its value is int or float.
+
+    Args:
+        parameter (Parameter): The qcodes.Parameter to validate.
+
+    Raises:
+        ValueError: If the parameter is not a qcodes.Parameter, or if its current value is not a float or int.
+        ValueError: If the parameter value cannot be retrieved (wrapped).
+
+    Returns:
+        Parameter: The original parameter if validation succeeds.
+    """
+    if not isinstance(parameter, Parameter):
+        raise ValueError(f"Invalid parameter type: {type(parameter)}, expected qcodes.Parameter.")
+
+    try:
+        value = parameter.get()
+        if not isinstance(value, (float, int)):
+            raise ValueError(
+                f"Invalid parameter value type: {type(value)}, "
+                f"expected float or int (Parameter: {parameter.name})."
+            )
+    except ValueError as e:
+        raise e
+    except Exception as e:
+        raise ValueError(f"Could not get value from parameter: {parameter.name}") from e
+
+    return parameter

etiket_sync_agent_qcodes/qcodes_sync_class.py

@@ -0,0 +1,175 @@
+import typing
+import sqlite3
+import qcodes as qc
+import os
+import logging
+import xarray
+import asyncio
+from typing import Tuple
+
+from datetime import datetime
+
+from etiket_sync_agent.backends.sync_source_abstract import SyncSourceDatabaseBase, ScopeRequirement
+from etiket_sync_agent.sync.sync_records.manager import SyncRecordManager
+from etiket_sync_agent.sync.sync_utilities import file_info, sync_utilities,\
+    dataset_info, FileType
+from etiket_sync_agent.schemas import SyncItemSchema, SyncItemCreate
+
+from etiket_sync_agent_qcodes.real_time_sync import QCoDeS_live_sync
+
+from etiket_sync_agent_qcodes.qcodes_config_class import QCoDeSConfigData
+from etiket_sync_agent_qcodes.utility.extract_metadata_from_QCoDeS import extract_labels_and_attributes_from_snapshot, MetaDataExtractionError
+
+from qcodes.dataset import load_by_guid
+from qcodes.dataset.data_set import DataSet
+
+logger = logging.getLogger(__name__)
+
+class QCoDeSSync(SyncSourceDatabaseBase):
+    sync_agent_name: typing.ClassVar[str] = "QCoDeS"
+    config_data_class: typing.ClassVar[typing.Type[QCoDeSConfigData]] = QCoDeSConfigData
+    scope_requirement: typing.ClassVar[ScopeRequirement] = ScopeRequirement.REQUIRED
+    supports_scope_mapping: typing.ClassVar[bool] = False
+    live_sync_implemented: typing.ClassVar[bool] = True
+    has_owner: typing.ClassVar[bool] = True
+
+    @staticmethod
+    async def getNewDatasets(config_data: QCoDeSConfigData, last_sync_item: SyncItemSchema | None) -> typing.List[SyncItemCreate] | None:
+        if not os.path.exists(config_data.database_path):
+            raise FileNotFoundError(f"Database file not found at {config_data.database_path}")
+        
+        qc.config.core.db_location = str(config_data.database_path)
+        
+        newSyncIdentifiers = []
+        
+        with sqlite3.connect(config_data.database_path) as conn:
+            conn.execute("PRAGMA journal_mode=WAL;")
+            last_run_id = -1
+            if last_sync_item is not None:
+                last_run_id = last_sync_item.syncPriority
+            
+            get_newer_guid_query = """SELECT run_id, guid FROM runs WHERE run_id > ? ORDER BY run_id ASC"""
+            
+            cursor = conn.cursor()
+            cursor.execute(get_newer_guid_query, (int(last_run_id),))
+            rows = cursor.fetchall()
+            
+            newSyncIdentifiers += [SyncItemCreate(dataIdentifier=str(row[1]), syncPriority=row[0]) for row in rows]
+        return newSyncIdentifiers
+    
+    @staticmethod
+    async def checkLiveDataset(configData: QCoDeSConfigData, syncIdentifier: SyncItemSchema, maxPriority: bool) -> bool:
+        if maxPriority is False:
+            return False
+        
+        qc.config.core.db_location = str(configData.database_path)
+        
+        ds_qc = load_by_guid(syncIdentifier.dataIdentifier)
+        return not ds_qc.completed
+    
+    @staticmethod
+    async def syncDatasetNormal(configData: QCoDeSConfigData, syncIdentifier: SyncItemSchema, sync_record: SyncRecordManager):
+        qc.config.core.db_location = str(configData.database_path)
+
+        with sync_record.task("Creating dataset from QCoDeS dataset (not live)"):
+            ds_qc, ds_xr = await create_ds_from_qcodes(configData, syncIdentifier, False, sync_record)
+
+        with sync_record.task("Getting and uploading the measured data to the server"):
+            if ds_qc.run_timestamp_raw is not None:
+                created_time = datetime.fromtimestamp(ds_qc.run_timestamp_raw)
+            else:
+                raise ValueError("Run timestamp is None")
+
+            f_info = file_info(name = 'measurement', fileName = 'measured_data.hdf5',
+                                fileType= FileType.HDF5_NETCDF,
+                                created = created_time, file_generator = "QCoDeS")
+            await sync_utilities.upload_xarray(ds_xr, syncIdentifier, f_info, sync_record)
+
+    @staticmethod
+    async def syncDatasetLive(configData: QCoDeSConfigData, syncIdentifier: SyncItemSchema, sync_record: SyncRecordManager):
+        qc.config.core.db_location = str(configData.database_path)
+
+        with sync_record.task("Creating dataset from QCoDeS dataset (live)"):
+            await create_ds_from_qcodes(configData, syncIdentifier, True, sync_record)
+        with sync_record.task("Starting live feed to a local hdf5 file"):
+            await asyncio.get_event_loop().run_in_executor(
+                None, QCoDeS_live_sync,
+                syncIdentifier.dataIdentifier, str(configData.database_path), syncIdentifier.datasetUUID
+            )
+            sync_record.add_log("Live feed completed.")
+
+async def create_ds_from_qcodes(configData: QCoDeSConfigData, syncIdentifier: SyncItemSchema, live : bool, sync_record: SyncRecordManager) -> Tuple[DataSet, xarray.Dataset]:
+    sync_record.add_log("Loading dataset and extracting metadata from QCoDeS with GUID: " + syncIdentifier.dataIdentifier)
+    ds_qc = load_by_guid(syncIdentifier.dataIdentifier)
+    sync_record.add_log("Dataset loaded from QCoDeS, will start extracting metadata")
+
+    if ds_qc.run_timestamp_raw is not None:
+        collected_time = datetime.fromtimestamp(ds_qc.run_timestamp_raw)
+    else:
+        raise ValueError("Run timestamp is None")
+    
+    ranking = 0
+    if 'inspectr_tag' in ds_qc.metadata.keys():
+        if ds_qc.metadata['inspectr_tag'] == 'star':
+            ranking = 1
+        if ds_qc.metadata['inspectr_tag'] == 'cross':
+            ranking = -1
+        
+    # get variable names in the dataset, this is handy for searching!
+    ds_xr = ds_qc.to_xarray_dataset()
+    keywords = set()
+    try:
+        for key in ds_xr.keys():
+            if 'long_name' in ds_xr[key].attrs.keys():
+                keywords.add(ds_xr[key].attrs['long_name'])
+                continue
+            if 'name' in ds_xr[key].attrs.keys():
+                keywords.add(ds_xr[key].attrs['name'])
+
+        for key in ds_xr.coords:
+            if 'long_name' in ds_xr[key].attrs.keys():
+                keywords.add(ds_xr[key].attrs['long_name'])
+                continue
+            if 'name' in ds_xr[key].attrs.keys():
+                keywords.add(ds_xr[key].attrs['name'])
+    except Exception:
+        pass
+    
+    name_lines = ds_qc.name.splitlines()
+    name = name_lines[0] if name_lines else ""
+
+    additional_description = "\n".join(name_lines[1:]) if len(name_lines) > 1 else ""
+    description = f"database : {os.path.basename(configData.database_path)} | run ID : {ds_qc.run_id} | GUID : {ds_qc.guid} | exp name : {ds_qc.exp_name}"
+    
+    if additional_description:
+        description += f"\n\n{additional_description}"
+    
+    attributes = {"sample" : ds_qc.sample_name,
+                    "set-up" : configData.set_up}
+    if configData.static_attributes is not None:
+        attributes.update(configData.static_attributes) 
+    
+    try: # experimental
+        if ds_qc.snapshot is not None:
+            extra_labels, extra_attributes = extract_labels_and_attributes_from_snapshot(ds_qc.snapshot)
+        else:
+            extra_labels = []
+            extra_attributes = {}
+    except MetaDataExtractionError:
+        logger.exception("Could not extract labels and attributes from snapshot.")
+        extra_labels = []
+        extra_attributes = {}
+    
+    keywords.update(extra_labels)
+    attributes.update(extra_attributes)   
+    
+    sync_record.add_log("Creating dataset info")
+    ds_info = dataset_info(name = name, datasetUUID = syncIdentifier.datasetUUID,
+                alt_uid = ds_qc.guid, scopeUUID = syncIdentifier.scopeIdentifier,
+                created = collected_time, keywords = list(keywords),  description = description,
+                ranking=ranking,
+                # exp_name not added, since some people use it to name their experiments ...
+                attributes = attributes)
+    
+    await sync_utilities.create_or_update_dataset(live, syncIdentifier, ds_info, sync_record)
+    return ds_qc, ds_xr

etiket_sync_agent_qcodes/real_time_sync.py

@@ -0,0 +1,143 @@
+import sqlite3
+import logging
+import time
+import io
+import os
+import numpy as np
+
+from qcodes import Parameter
+from uuid import UUID
+
+from etiket_client.remote.endpoints.models.types import FileType
+from qdrive.measurement.data_collector import data_collector, from_QCoDeS_parameter
+from qdrive.dataset.dataset import dataset
+
+logger = logging.getLogger(__name__)
+
+# Timeout for live sync - if no new data is received within this time, sync exits
+LIVE_SYNC_TIMEOUT_SECONDS = 10 * 60  # 10 minutes
+
+# Polling interval when waiting for new data
+LIVE_SYNC_POLL_INTERVAL_SECONDS = 0.1
+
+def QCoDeS_live_sync(guid : str, database : str, datasetUUID : UUID):
+    print("Starting real time sync")
+    conn = sqlite3.connect(f'{database}')
+    conn.execute('pragma journal_mode=wal')
+
+    c = conn.cursor()
+    
+    # Get run_id from guid
+    c.execute("SELECT run_id FROM runs WHERE guid = ?", (guid,))
+    result = c.fetchone()
+    if result is None:
+        raise ValueError(f"No run found with guid: {guid}")
+    run_id = result[0]
+    
+    c.execute("SELECT * FROM layouts WHERE run_id = ?", (run_id,))
+    layout = c.fetchall()
+    
+    parameters = {}
+    parameters_by_name = {}
+    for layout_item in layout:
+        parameters[layout_item[0]] = Parameter(layout_item[2], label=layout_item[3], unit=layout_item[4])
+        parameters_by_name[layout_item[2]] = parameters[layout_item[0]]
+    
+    dependency_ids= list(parameters.keys())
+    c.execute(f"Select * from dependencies where dependent in ({','.join(['?']*len(dependency_ids))})",
+                dependency_ids)
+    dependencies = c.fetchall()
+    
+    relationships = {}
+    for dep in dependencies:
+        if dep[0] not in relationships.keys():
+            relationships[dep[0]] = []
+        relationships[dep[0]].append(dep[1])
+    
+    native_ds = dataset(datasetUUID)
+    dc = data_collector(native_ds, FileType.HDF5_CACHE)
+    
+    try :
+        for k, v in relationships.items():
+            dep = [parameters[i] for i in v]
+            dc += from_QCoDeS_parameter(parameters[k], dep, dc)
+
+        sync_idx = 0
+        res = c.execute("Select result_table_name, snapshot from runs where run_id = ?", (run_id,)).fetchone()
+        table_name = res[0]
+        snapshot_json = res[1]
+        
+        dc.set_attr('snapshot', snapshot_json)
+        dc._enable_swmr() # manually set this, sometimes it takes long for qCoDeS to start writing data ... .
+    except Exception as e:
+        if (hasattr(dc, 'lock_file')):
+            if (dc.lock_file is not None):
+                if os.path.isfile(dc.lock_file):
+                    os.remove(dc.lock_file)
+        dc.complete()
+        raise e
+    
+    t_last_fetch = time.time()
+    
+    try: 
+        while not (check_complete(c, run_id) and sync_idx == getMaxId(c, table_name)):            
+            c.execute(f"SELECT * FROM '{table_name}' WHERE id > ?", (sync_idx,))
+            c_names = [description[0] for description in c.description]
+            
+            data = c.fetchall()
+            if len(data) == 0:
+                if t_last_fetch + LIVE_SYNC_TIMEOUT_SECONDS < time.time():
+                    logger.warning(f"No new data found in the last {LIVE_SYNC_TIMEOUT_SECONDS} seconds. Exiting real time sync.")
+                    raise TimeoutError(f"No new data found in the last {LIVE_SYNC_TIMEOUT_SECONDS} seconds. Exiting real time sync. Expected that the measurement was set to complete.")
+                
+                # check if a new run has already been started:
+                max_run_id = c.execute("SELECT MAX(run_id) FROM runs").fetchone()[0]
+                if max_run_id != run_id:
+                    break
+                
+                time.sleep(LIVE_SYNC_POLL_INTERVAL_SECONDS)
+                continue
+            else:
+                t_last_fetch = time.time()
+            
+            for d in data:
+                array_size = None
+                data_to_write = {}
+                for i, name in enumerate(c_names[1:]):
+                    value = d[i+1]
+                    if value is not None:
+                        try: 
+                            value = float(value)
+                        except Exception as e:
+                            # array parameters are stored as a blob :/
+                            value = np.load(io.BytesIO(value))
+                            if array_size is not None and array_size != value.size:
+                                raise ValueError("Array size mismatch in the data") from e
+                            array_size = value.size
+                        data_to_write[parameters_by_name[name]] = value
+                
+                if array_size is None:
+                    dc.add_data(data_to_write)
+                else:
+                    for i in range(array_size):
+                        data_item_to_write = {}
+                        for k, v in data_to_write.items():
+                            if isinstance(v, np.ndarray):
+                                data_item_to_write[k] = v[i]
+                            else:
+                                data_item_to_write[k] = v
+                        dc.add_data(data_item_to_write)
+            
+            sync_idx = data[-1][0]
+    except Exception as e:
+        logger.exception("Real time sync failed with error :: %s", e)
+    finally:
+        dc.complete()
+    
+def check_complete(cursor : sqlite3.Cursor, run_id : int):
+    cursor.execute("Select is_completed from runs where run_id = ?", (run_id,))
+    return cursor.fetchone()[0]
+
+def getMaxId(cursor : sqlite3.Cursor, table_name : str):
+    cursor.execute(f"SELECT MAX(id) FROM '{table_name}'")
+    return cursor.fetchone()[0]

etiket_sync_agent_qcodes/utility/extract_metadata_from_QCoDeS.py

@@ -0,0 +1,36 @@
+from typing import List, Dict, Union, Tuple
+
+class MetaDataExtractionError(Exception):
+	pass
+
+def extract_labels_and_attributes_from_snapshot(snapshot : dict) -> Tuple[List[str], Dict[str, Union[Dict, str]]]:
+    """
+    Extract labels and attributes from a snapshot dictionary from the QH_MetadataManager.
+
+    Args:
+        snapshot (dict): The snapshot dictionary to extract metadata from.
+
+    Returns:
+        List[str]: A list of labels extracted from the snapshot.
+        Dict[str, Union[float, int, str]]: A dictionary of attributes extracted from the snapshot.
+    """
+    try:
+        station = snapshot.get("station", {})
+        instruments = station.get("instruments", {})
+        metadata = instruments.get("qh_meta", {})
+        params = metadata.get("parameters", {})
+        tags = params.get("tags", {}).get("value", [])
+        attributes = params.get("attributes", {}).get("value", {})
+        
+        # fix attr (currently no good support for parameter on the server side)
+        attr = {}
+        for key, value in attributes.items():
+            if isinstance(value, dict):
+                if "value" in value:
+                    attr[key] = str(value.get("value"))
+            else:
+                attr[key] = value
+        
+        return tags, attr
+    except Exception as e:
+        raise MetaDataExtractionError("Could not extract labels and attributes from snapshot.") from e

etiket_sync_agent_qcodes-0.3.0b1.dist-info/METADATA

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: etiket_sync_agent_qcodes
+Version: 0.3.0b1
+Summary: QCoDeS backend for eTiKeT sync agent
+Author: QHarbor team
+License-Expression: LicenseRef-Proprietary
+Project-URL: Homepage, https://qharbor.nl
+Project-URL: Documentation, https://docs.qharbor.nl
+Keywords: etiket,sync,backend,qcodes,quantum
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS :: MacOS X
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENCE
+Requires-Dist: etiket_sync_agent>=0.3.0b1
+Requires-Dist: qcodes
+Requires-Dist: xarray
+Dynamic: license-file
+
+# eTiKeT Sync Agent - QCoDeS Backend
+
+Backend for synchronizing QCoDeS datasets with the eTiKeT platform. This backend reads measurements from QCoDeS SQLite databases and syncs them to the cloud.
+
+## Installation
+
+Install the QCoDeS backend using the eTiKeT Sync SDK:
+
+```python
+from etiket_sdk.sync import Backends
+
+# Install the latest version
+Backends.install_from_pypi("etiket-sync-agent-qcodes")
+```
+
+> ⚠️ **Important:** This backend installs a specific version of QCoDeS. If the installed version is newer than what your main environment uses, it may upgrade your database schema, making it unreadable by older QCoDeS versions. See [Version Pinning](#version-pinning) below.
+
+The package is automatically discovered by `etiket_sync_agent` through the entry-point system. Once installed, you can verify with:
+
+```python
+# List installed backends
+print(Backends.list())
+
+# Get details for the QCoDeS backend
+backend = Backends.get("etiket_sync_agent_qcodes")
+print(backend)
+```
+
+### Version Pinning
+
+By default, installing the backend also installs the latest version of `qcodes`. If you need a specific QCoDeS version to match your main working environment, you can install it separately:
+
+**Why this matters:** Newer QCoDeS versions may upgrade your SQLite database schema. Once upgraded, older QCoDeS versions may not be able to read the database. This is primarily a concern for very old QCoDeS versions.
+
+```python
+# Check your current QCoDeS version in your working environment
+import qcodes
+print(qcodes.__version__)
+
+# Then install a specific QCoDeS version in the sync agent
+Backends.install_from_pypi("qcodes", version="x.x.x")
+```
+
+### Updating the Backend
+
+```python
+# Update to the latest version
+Backends.update_from_pypi("etiket-sync-agent-qcodes")
+```
+
+## What Gets Synchronized
+
+When a QCoDeS measurement is synced, the following data is extracted and uploaded:
+
+| QCoDeS Data | eTiKeT Field | Description |
+|-------------|--------------|-------------|
+| `guid` | `alt_uid` | Unique identifier for the measurement |
+| Measurement name | `name` | Name of the dataset |
+| `run_timestamp` | `collected` | When the measurement was taken |
+| Parameter labels | `tags` | Extracted from instrument/parameter metadata |
+| Snapshot instruments | `attributes` | Instrument settings stored in the snapshot |
+| xarray dataset | HDF5 file | The actual measurement data |
+
+
+### Metadata Sources
+
+The backend extracts metadata from multiple sources:
+
+1. **QCoDeS Snapshot**: Instrument labels and parameter values used in the measurement are added as tags.
+2. **QHMetaData Instrument**: Custom tags and attributes (see below)
+3. **`inspectr_tag` metadata**: Ranking (`star` = +1, `cross` = -1)
+4. **Config `static_attributes`**: Static attributes defined in the sync source configuration
+
+## Configuration
+
+The QCoDeS backend requires a `QCoDeSConfigData` configuration with the following fields:
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `database_path` | `Path` or `str` | Yes | Path to the QCoDeS SQLite database file (`.db`) |
+| `set_up` | `str` | Yes | Name of the experimental setup (added as `set-up` attribute) |
+| `static_attributes` | `dict[str, str]` | No | Optional static key-value pairs added to every dataset |
+
+### Example Configuration
+
+Example using the `etiket-sdk` package:
+
+```python
+from etiket_sdk.sync import SyncSources
+
+SyncSources.create(
+    name="my_qcodes_source",
+    backend_identifier="etiket_sync_agent_qcodes",
+    config_data={
+        "database_path": "/path/to/experiments.db", 
+        "set_up": "dilution_fridge_1",
+        "static_attributes": { # optional
+            "project": "qubit_calibration",
+            "lab": "Building A - Room 101"
+        }
+    },
+    default_scope="xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
+)
+```
+
+---
+
+## Adding QCoDeS Metadata to a Dataset
+
+You can attach tags and attributes to a dataset by adding the `QHMetaData` instrument to your QCoDeS Station. Because the instrument is recorded in the QCoDeS snapshot, the sync agent extracts the tags and attributes and adds them to the QHarbor dataset.
+
+You can add both **static** and **dynamic** metadata:
+
+- **Static metadata**: Stays the same for all measurements (e.g., project, lab PC)
+- **Dynamic metadata**: Changes per run (e.g., calibration type, measurement type)
+
+### Initializing the Instrument
+
+There are two ways to define the instrument: directly in Python or via a Station YAML file.
+
+#### Using Python
+
+```python
+from etiket_sync_agent_qcodes.qcodes_metadata import QHMetaData
+from qcodes import Station
+
+station = Station()
+
+# Create and register the instrument
+qh_meta = QHMetaData(
+    "qh_meta",
+    static_tags=["cool_experiment"],
+    static_attributes={"project": "resonator project"},
+)
+station.add_component(qh_meta)
+```
+
+> **Note**: The instrument name **must** be `qh_meta`. Do not change this.
+
+#### Using a YAML Configuration File
+
+Add the following to your Station YAML config:
+
+```yaml
+instruments:
+  qh_meta:
+    type: etiket_sync_agent_qcodes.qcodes_metadata.QHMetaData
+    init:
+      static_tags:
+        - "cool_experiment"
+      static_attributes:
+        project: "resonator project"
+        measurement_computer: "LAB-A-PC-5"
+```
+
+> **Note**: The key **must** be `qh_meta`. Do not change this.
+
+Load the instrument from the config:
+
+```python
+from qcodes import Station
+
+# Replace with your config file name
+station = Station(config_file='qc_config.yaml')
+station.load_instrument("qh_meta")
+```
+
+For more information, see the QCoDeS docs: [Configuring the Station by using a YAML configuration file](https://microsoft.github.io/Qcodes/examples/basic_examples/Station.html#Configuring-the-Station-by-using-a-YAML-configuration-file).
+
+### Runtime Usage
+
+Access the instrument and set per-run metadata:
+
+```python
+# If defined via Station YAML
+qh_meta = station.components["qh_meta"]
+
+# Start of run: clear dynamic values, then set new ones
+qh_meta.reset()
+qh_meta.add_tags(["testing", "calibration"])
+qh_meta.add_attributes({
+    "calibration": "ALLXY",
+    "qubit": "Q1",
+})
+
+# ... measurement happens here ...
+```
+
+### Behavior Notes
+
+| Aspect | Behavior |
+|--------|----------|
+| **Static vs Dynamic** | Static tags/attributes are set at construction and persist across `reset()`. Dynamic ones are cleared by `reset()`. |
+| **Attribute Overrides** | Dynamic attributes with the same key as a static attribute will override the static value. |
+| **Tag Duplicates** | Tags are deduplicated using a `set()`. |
+
+---
+
+## Features
+
+- Direct integration with QCoDeS datasets
+- Automatic metadata extraction from snapshots
+- Live sync support for running measurements
+- xarray dataset conversion
+- Custom metadata via `QHMetaData` instrument
+
+## Requirements
+
+- Python >= 3.10
+- QCoDeS >= 0.52
+
+## License
+
+Copyright © 2025 QHarbor. All Rights Reserved. See [LICENCE](LICENCE) for details.

etiket_sync_agent_qcodes-0.3.0b1.dist-info/RECORD

@@ -0,0 +1,13 @@
+etiket_sync_agent_qcodes/__init__.py,sha256=sGDfPK9czy7e0IrJup6IIW9wAq3byIuJfqolWOSapPE,154
+etiket_sync_agent_qcodes/qcodes_config_class.py,sha256=nNODFGd_qOKMY2ZlKwKuMV8-n0rz-lvQK6yKtgKFiH8,4171
+etiket_sync_agent_qcodes/qcodes_metadata.py,sha256=mLHAUyHlvcDf3hT8wIvJMll7ZH6FLzcvSOj0hFJMQVU,4226
+etiket_sync_agent_qcodes/qcodes_sync_class.py,sha256=wesnxBnLZAF4a0qNW7axNxq4Hp09R3Vwc9nSA6wPtDU,7933
+etiket_sync_agent_qcodes/real_time_sync.py,sha256=OnMnzLfhdabHszeVEaFEeiVLVHu2KtCw2eJwhC0j_ic,5669
+etiket_sync_agent_qcodes/utility/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+etiket_sync_agent_qcodes/utility/extract_metadata_from_QCoDeS.py,sha256=ue8B-Dc_WJUvugYSze4C-sDzmw8lZo_wtQ45RRvl1AU,1409
+etiket_sync_agent_qcodes-0.3.0b1.dist-info/licenses/LICENCE,sha256=tdZwE43Th9efUgN8-4UpMUyh0kYQ4Dk678agSuhpnc0,2357
+etiket_sync_agent_qcodes-0.3.0b1.dist-info/METADATA,sha256=ySUKAIkwj_BzBqlKMCE62wJtAE8tAGIvsqWQSzMiP3c,8114
+etiket_sync_agent_qcodes-0.3.0b1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+etiket_sync_agent_qcodes-0.3.0b1.dist-info/entry_points.txt,sha256=u_Pnr-oNRlteD5NRFmWhv8c-w1gp9shK506jDkK9orQ,85
+etiket_sync_agent_qcodes-0.3.0b1.dist-info/top_level.txt,sha256=6oQt56X8ztFEYdi6-us5iNDTKWpcl2e9uKmDGUzY3pU,25
+etiket_sync_agent_qcodes-0.3.0b1.dist-info/RECORD,,

etiket_sync_agent_qcodes-0.3.0b1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

etiket_sync_agent_qcodes-0.3.0b1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[etiket_sync_agent.backends]
+qcodes_sync_agent = etiket_sync_agent_qcodes:QCoDeSSync

etiket_sync_agent_qcodes-0.3.0b1.dist-info/licenses/LICENCE

@@ -0,0 +1,34 @@
+All Rights Reserved License
+Copyright ©️ 2024-2026 QHarbor B.V. All Rights Reserved.
+
+Agreement to Terms
+By accessing, downloading, installing, or viewing this Software (including its source code, binaries, or application files), you acknowledge and agree to the terms outlined below.
+
+Terms and Conditions
+This software and its source code (the "Software") are the exclusive property of QHarbor B.V. and are protected by copyright and other intellectual property laws.
+
+License and Testing Exemptions
+Commercial License: If you have entered into a separate commercial license agreement with QHarbor B.V., the terms of that agreement shall supersede the restrictions listed below.
+Testing Permission: If you have obtained written permission for testing/evaluation from QHarbor B.V., you are permitted to install and use the Software for evaluation purposes. However, this permission strictly excludes the right to modify, alter, create derivative works, or reverse engineer the Software.
+
+Prohibited Actions
+Unless explicitly authorized by the exemptions above, you are NOT permitted to:
+	•	Copy, reproduce, or duplicate the Software in any form (except as reasonably necessary for viewing or authorized installation)
+	•	Modify, alter, or create derivative works based on the Software
+	•	Distribute, publish, or share the Software with others
+	•	Reverse engineer, decompile, or disassemble the Software
+	•	Use the Software for any commercial or non-commercial purposes
+	•	Transfer, sell, lease, or sublicense the Software
+	•	Remove or alter any copyright notices or proprietary markings
+
+Viewing Only 
+For those without a commercial license or written testing permission, the Software is made available for viewing and reference purposes only. Any access to view the source code or application does not grant any rights to use, copy, or modify the Software.
+
+No Implied Rights
+No rights are granted by implication, estoppel, or otherwise. All rights not expressly granted are reserved by the copyright holder.
+
+Governing Law 
+This license and any disputes arising from it shall be governed by the laws of the Netherlands.
+
+Disclaimer 
+This Software is provided "AS IS" without warranty of any kind. The copyright holder disclaims all warranties and shall not be liable for any damages arising from the use or inability to use this Software.

etiket_sync_agent_qcodes-0.3.0b1.dist-info/top_level.txt

@@ -0,0 +1 @@
+etiket_sync_agent_qcodes