sqil-core 0.0.1__tar.gz

sqil_core-0.0.1/PKG-INFO

@@ -0,0 +1,115 @@
+Metadata-Version: 2.1
+Name: sqil-core
+Version: 0.0.1
+Summary: The codebase of the SQIL group in EPFL
+Author: Andrea Duina
+Requires-Python: >=3.10,<4.0
+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
+Requires-Dist: h5py (>=3.12.1,<4.0.0)
+Requires-Dist: isort (==5.9.3)
+Requires-Dist: matplotlib (>=3.9.3,<4.0.0)
+Requires-Dist: numpy (>=2.2.0,<3.0.0)
+Requires-Dist: scipy (>=1.14.1,<2.0.0)
+Requires-Dist: seaborn (>=0.13.2,<0.14.0)
+Description-Content-Type: text/markdown
+
+# For users
+
+## Installation
+
+```bash
+$ pip install sqil_core
+```
+
+## Usage
+
+You can find all the functions available and examples in the documentation.
+
+```python
+import sqil_core as sqil
+
+path = 'path to your data folder'
+
+# Extract data
+mag, phase, freq = sqil.extract_h5_data(path, ['mag_dB', 'phase', 'ro_freq'])
+```
+
+# For developers
+
+## Development
+
+1. **Install poetry if you haven't already**
+```bash
+$ pip install poetry
+```
+
+2. **Install the required packages using poetry**
+```bash
+$ poetry install
+```
+
+3. **Install the pre-commit hooks**
+If you are on windows you need to install git ([https://git-scm.com/downloads](here)) and add it to your windows PATH.
+After the installation open a new terminal.
+```bash
+$ poetry run pre-commit install
+```
+This will check if your python files are formatted correctly when you try to commit.
+If that's not the case the commit will be canceled and the files will be automatically formatted.
+Then you'll have to add and commit again the new files.
+
+4. **Start the virtual environment**
+```bash
+$ poetry shell
+```
+To exit the virtual environment just use `exit`
+
+#### Test your changes
+
+```bash
+$ pip install -e . --user
+```
+
+**Anaconda**
+If you want to install in a specific anaconda environment
+
+- from your poetry shell build the package
+
+```bash
+$ poetry run build
+```
+
+- open an anaconda shell
+- activate the desired environemnt
+- pip install the wheel file (.whl) in the dist folder of the sqil-core project
+
+```bash
+$ pip install PATH_TO_SQIL_CORE_FOLDER/dist/SQIL_CORE-VERSION.whl
+```
+
+If you're using a jupyter notebook remember to restart the kernel
+
+## Build
+
+```bash
+$ poetry run build
+```
+
+## Docs
+
+Serve docs
+
+```bash
+$ poetry run docs_serve
+```
+
+Build docs
+
+```bash
+$ poetry run docs_build
+```
+

sqil_core-0.0.1/README.md

@@ -0,0 +1,95 @@
+# For users
+
+## Installation
+
+```bash
+$ pip install sqil_core
+```
+
+## Usage
+
+You can find all the functions available and examples in the documentation.
+
+```python
+import sqil_core as sqil
+
+path = 'path to your data folder'
+
+# Extract data
+mag, phase, freq = sqil.extract_h5_data(path, ['mag_dB', 'phase', 'ro_freq'])
+```
+
+# For developers
+
+## Development
+
+1. **Install poetry if you haven't already**
+```bash
+$ pip install poetry
+```
+
+2. **Install the required packages using poetry**
+```bash
+$ poetry install
+```
+
+3. **Install the pre-commit hooks**
+If you are on windows you need to install git ([https://git-scm.com/downloads](here)) and add it to your windows PATH.
+After the installation open a new terminal.
+```bash
+$ poetry run pre-commit install
+```
+This will check if your python files are formatted correctly when you try to commit.
+If that's not the case the commit will be canceled and the files will be automatically formatted.
+Then you'll have to add and commit again the new files.
+
+4. **Start the virtual environment**
+```bash
+$ poetry shell
+```
+To exit the virtual environment just use `exit`
+
+#### Test your changes
+
+```bash
+$ pip install -e . --user
+```
+
+**Anaconda**
+If you want to install in a specific anaconda environment
+
+- from your poetry shell build the package
+
+```bash
+$ poetry run build
+```
+
+- open an anaconda shell
+- activate the desired environemnt
+- pip install the wheel file (.whl) in the dist folder of the sqil-core project
+
+```bash
+$ pip install PATH_TO_SQIL_CORE_FOLDER/dist/SQIL_CORE-VERSION.whl
+```
+
+If you're using a jupyter notebook remember to restart the kernel
+
+## Build
+
+```bash
+$ poetry run build
+```
+
+## Docs
+
+Serve docs
+
+```bash
+$ poetry run docs_serve
+```
+
+Build docs
+
+```bash
+$ poetry run docs_build
+```

sqil_core-0.0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[tool.poetry]
+name = "sqil-core"
+version = "0.0.1"
+description = "The codebase of the SQIL group in EPFL"
+authors = ["Andrea Duina"]
+readme = "README.md"
+
+[tool.poetry.scripts]
+build = "scripts:build"
+docs-serve = "scripts:docs_serve"
+docs-build = "scripts:docs_build"
+
+[tool.poetry.dependencies]
+python = "^3.10"
+numpy = "^2.2.0"
+scipy = "^1.14.1"
+h5py = "^3.12.1"
+matplotlib = "^3.9.3"
+seaborn = "^0.13.2"
+isort = "5.9.3"
+
+
+[tool.poetry.group.dev.dependencies]
+black = "^24.10.0"
+pre-commit = "^4.0.1"
+mkdocs = "^1.6.1"
+mkdocs-material = "^9.5.48"
+mkdocstrings-python = "^1.12.2"
+pytest = "^8.3.4"
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.black]
+line-length = 88
+target-version = ["py310"]
+exclude = '''
+/(
+    \.git
+    | \.venv
+    | build
+    | dist
+)/
+'''
+
+[tool.isort]
+profile = "black"
+known_first_party = ["sqil-core"]

sqil_core-0.0.1/sqil_core/__init__.py

@@ -0,0 +1,3 @@
+from .utils import extract_h5_data, read_param_dict
+
+__all__ = ["extract_h5_data", "read_param_dict"]

sqil_core-0.0.1/sqil_core/utils/__init__.py

@@ -0,0 +1,6 @@
+from .analysis import *
+from .formatter import *
+from .read import *
+
+__all__ = []
+__all__.extend(name for name in dir() if not name.startswith("_"))

sqil_core-0.0.1/sqil_core/utils/analysis.py

@@ -0,0 +1,68 @@
+import numpy as np
+
+
+def remove_offset(data: np.ndarray, avg: int = 3) -> np.ndarray:
+    """Removes the initial offset from a data matrix or vector by subtracting
+    the average of the first `avg` points. After applying this function,
+    the first point of each column of the data will be shifted to (about) 0.
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Input data, either a 1D vector or a 2D matrix
+    avg : int, optional
+        The number of initial points to average when calculating
+        the offset, by default 3
+
+    Returns
+    -------
+    np.ndarray
+       The input data with the offset removed
+    """
+    is1D = len(data.shape) == 1
+    if is1D:
+        return data - np.mean(data[0:avg])
+    return data - np.mean(data[:, 0:avg], axis=1).reshape(data.shape[0], 1)
+
+
+def estimate_linear_background(x: np.ndarray, data: np.ndarray, points_cut=0.1) -> list:
+    is1D = len(data.shape) == 1
+    points = data.shape[0] if is1D else data.shape[1]
+    cut = int(points * points_cut)
+
+    # Consider just the cut points
+    x_data = x[0:cut] if is1D else x[0:cut, :]
+    X = np.vstack([np.ones_like(x_data), x_data]).T
+    y_data = data[0:cut] if is1D else data[0:cut, :]
+
+    # Linear fit
+    coefficients, residuals, _, _ = np.linalg.lstsq(
+        X, y_data if is1D else y_data.T, rcond=None
+    )
+
+    return coefficients
+
+
+def remove_linear_background(
+    x: np.ndarray, data: np.ndarray, points_cut=0.1
+) -> np.ndarray:
+    """Removes a linear background from the input data (e.g. the phase background
+    of a spectroscopy).
+
+
+    Parameters
+    ----------
+    data : np.ndarray
+        Input data. Can be a 1D vector or a 2D matrix.
+
+    Returns
+    -------
+    np.ndarray
+        The input data with the linear background removed. The shape of the
+        returned array matches the input `data`.
+    """
+    coefficients = estimate_linear_background(x, data, points_cut)
+
+    # Remove background over the whole array
+    X = np.vstack([np.ones_like(x), x]).T
+    return data - (X @ coefficients).T

sqil_core-0.0.1/sqil_core/utils/const.py

@@ -0,0 +1,38 @@
+EXP_UNIT_MAP = {
+    -15: "p",
+    -12: "f",
+    -9: "n",
+    -6: "\mu",
+    -3: "m",
+    0: "",
+    3: "k",
+    6: "M",
+    9: "G",
+    12: "T",
+    15: "P",
+}
+
+PARAM_METADATA = {
+    "current": {"name": "Current", "symbol": "I", "unit": "A", "scale": 1e3},
+    "ro_freq": {
+        "name": "Readout frequency",
+        "symbol": "f_{RO}",
+        "unit": "Hz",
+        "scale": 1e-9,
+    },
+    "ro_power": {
+        "name": "Readout power",
+        "symbol": "P_{RO}",
+        "unit": "dBm",
+        "scale": 1,
+    },
+    "qu_freq": {
+        "name": "Qubit frequency",
+        "symbol": "f_q",
+        "unit": "Hz",
+        "scale": 1e-9,
+    },
+    "qu_power": {"name": "Qubit power", "symbol": "P_q", "unit": "dBm", "scale": 1},
+    "vna_bw": {"name": "VNA bandwidth", "symbol": "BW_{VNA}", "unit": "Hz", "scale": 1},
+    "vna_avg": {"name": "VNA averages", "symbol": "avg_{VNA}", "unit": "", "scale": 1},
+}

sqil_core-0.0.1/sqil_core/utils/formatter.py

@@ -0,0 +1,134 @@
+from decimal import ROUND_DOWN, Decimal
+
+import numpy as np
+
+from .const import EXP_UNIT_MAP, PARAM_METADATA
+from .read import read_json
+
+
+def _cut_to_significant_digits(number, n):
+    """Cut a number to n significant digits."""
+    if number == 0:
+        return 0  # Zero has no significant digits
+    d = Decimal(str(number))
+    shift = d.adjusted()  # Get the exponent of the number
+    rounded = d.scaleb(-shift).quantize(
+        Decimal("1e-{0}".format(n - 1)), rounding=ROUND_DOWN
+    )
+    return float(rounded.scaleb(shift))
+
+
+def format_number(
+    num: float | np.ndarray, precision: int = 3, unit: str = "", latex: bool = True
+) -> str:
+    """Format a number (or an array of numbers) in a nice way for printing.
+
+    Parameters
+    ----------
+    num : float | np.ndarray
+        Input number (or array). Should not be rescaled,
+        e.g. input values in Hz, NOT GHz
+    precision : int
+        The number of digits of the output number. Must be >= 3.
+    unit : str, optional
+        Unit of measurement, by default ''
+    latex : bool, optional
+        Include Latex syntax, by default True
+
+    Returns
+    -------
+    str
+        Formatted number
+    """
+    # Handle arrays
+    if isinstance(num, (list, np.ndarray)):
+        return [format_number(n, unit, latex) for n in num]
+
+    # Return if not a number
+    if not isinstance(num, (int, float, complex)):
+        return num
+
+    # Format number
+    exp_form = f"{num:.12e}"
+    base, exponent = exp_form.split("e")
+    # Make exponent a multiple of 3
+    base = float(base) * 10 ** (int(exponent) % 3)
+    exponent = (int(exponent) // 3) * 3
+    # Apply precision to the base
+    if precision < 3:
+        precision = 3
+    base_precise = _cut_to_significant_digits(
+        base, precision + 1
+    )  # np.round(base, precision - (int(exponent) % 3))
+    base_precise = np.round(
+        base_precise, precision - len(str(base_precise).split(".")[0])
+    )
+    if int(base_precise) == float(base_precise):
+        base_precise = int(base_precise)
+
+    # Build string
+    if unit:
+        res = f"{base_precise}{'~' if latex else ' '}{EXP_UNIT_MAP[exponent]}{unit}"
+    else:
+        res = f"{base_precise}" + (f" x 10^{{{exponent}}}" if exponent != 0 else "")
+    return f"${res}$" if latex else res
+
+
+def get_name_and_unit(param_id: str) -> str:
+    """Get the name and unit of measurement of a prameter, e.g. Frequency [GHz].
+
+    Parameters
+    ----------
+    param : str
+        Parameter ID, as defined in the param_dict.json file.
+
+    Returns
+    -------
+    str
+        Name and [unit]
+    """
+    meta = PARAM_METADATA[param_id]
+    scale = meta["scale"] if "scale" in meta else 1
+    exponent = -(int(f"{scale:.0e}".split("e")[1]) // 3) * 3
+    return f"{meta['name']} [{EXP_UNIT_MAP[exponent]}{meta['unit']}]"
+
+
+def get_x_id_by_plot_dim(exp_id: str, plot_dim: str, sweep_param: str | None) -> str:
+    if exp_id == "CW_onetone":
+        if plot_dim == "1":
+            return sweep_param or "ro_freq"
+        return "ro_freq"
+
+
+def build_title(title: str, path: str, params: list[str]) -> str:
+    """Build a plot title that includes the values of given parameters found in
+    the params_dict.json file, e.g. One tone with I = 0.5 mA.
+
+    Parameters
+    ----------
+    title : str
+        Title of the plot to which the parameters will be appended.
+
+    path: str
+        Path to the param_dict.json file.
+
+    params : List[str]
+        List of keys of parameters in the param_dict.json file.
+
+    Returns
+    -------
+    str
+        The original title followed by parameter values.
+    """
+    dic = read_json(f"{path}/param_dict.json")
+    title += " with "
+    for idx, param in enumerate(params):
+        if not (param in PARAM_METADATA.keys()) or not (param in dic):
+            title += f"{param} = ? & "
+            continue
+        meta = PARAM_METADATA[param]
+        value = format_number(dic[param], meta["unit"])
+        title += f"${meta['symbol']} =${value} & "
+        if idx % 2 == 0 and idx != 0:
+            title += "\n"
+    return title[0:-3]

sqil_core-0.0.1/sqil_core/utils/read.py

@@ -0,0 +1,156 @@
+import json
+import os
+
+import h5py
+import numpy as np
+
+from .const import PARAM_METADATA
+
+
+def extract_h5_data(
+    path: str, keys: list[str] | None = None
+) -> dict | tuple[np.ndarray, ...]:
+    """Extract data at the given keys from an HDF5 file. If no keys are
+    given (None) returns the data field of the object.
+
+    Parameters
+    ----------
+    path : str
+        path to the HDF5 file or a folder in which is contained a data.ddh5 file
+    keys : None or List, optional
+        list of keys to extract from file['data'], by default None
+
+    Returns
+    -------
+    Dict or Tuple[np.ndarray, ...]
+        The full data dictionary if keys = None.
+        The tuple with the requested keys otherwise.
+
+    Example
+    -------
+        Extract the data object from the dataset:
+        >>> data = extract_h5_data(path)
+        Extracting only 'amp' and 'phase' from the dataset:
+        >>> amp, phase = extract_h5_data(path, ['amp', 'phase'])
+        Extracting only 'phase':
+        >>> phase, = extract_h5_data(path, ['phase'])
+    """
+    # If the path is to a folder open /data.ddh5
+    if os.path.isdir(path):
+        path = os.path.join(path, "data.ddh5")
+
+    with h5py.File(path, "r") as h5file:
+        data = h5file["data"]
+        data_keys = data.keys()
+        # Extract only the requested keys
+        if bool(keys) and (len(keys) > 0):
+            res = []
+            for key in keys:
+                key = str(key)
+                if (not bool(key)) | (key not in data_keys):
+                    res.append([])
+                    continue
+                res.append(np.array(data[key][:]))
+            return tuple(res)
+        # Extract the whole data dictionary
+        return _h5_to_dict(data)
+
+
+def _h5_to_dict(obj) -> dict:
+    """Convert h5 data into a dictionary"""
+    data_dict = {}
+    for key in obj.keys():
+        item = obj[key]
+        if isinstance(item, h5py.Dataset):
+            data_dict[key] = item[:]
+        elif isinstance(item, h5py.Group):
+            data_dict[key] = extract_h5_data(item)
+    return data_dict
+
+
+def read_json(path: str) -> dict:
+    """Reads a json file and returns the data as a dictionary."""
+    with open(path) as f:
+        dictionary = json.load(f)
+    return dictionary
+
+
+class ParamInfo:
+    """Parameter information for items of param_dict
+
+    Attributes:
+        id (str): param_dict key
+        value (any): the value of the parameter
+        name (str): full name of the parameter (e.g. Readout frequency)
+        symbol (str): symbol of the parameter in Latex notation (e.g. f_{RO})
+        unit (str): base unit of measurement (e.g. Hz)
+        scale (int): the scale that should be generally applied to raw data (e.g. 1e-9 to take raw Hz to GHz)
+    """
+
+    def __init__(self, id, value):
+        self.id = id
+        self.value = value
+        if id in PARAM_METADATA:
+            meta = PARAM_METADATA[id]
+        else:
+            meta = {}
+        self.name = meta["name"] if "name" in meta else id
+        self.symbol = meta["symbol"] if "symbol" in meta else id
+        self.unit = meta["unit"] if "unit" in meta else ""
+        self.scale = meta["scale"] if "scale" in meta else 1
+
+    def to_dict(self):
+        """Convert ParamInfo to a dictionary."""
+        return {
+            "id": self.id,
+            "value": self.value,
+            "name": self.name,
+            "symbol": self.symbol,
+            "unit": self.unit,
+            "scale": self.scale,
+        }
+
+    def __str__(self):
+        """Return a JSON-formatted string of the object."""
+        return json.dumps(self.to_dict())
+
+    def __eq__(self, other):
+        if isinstance(other, ParamInfo):
+            return (self.id == other.id) & (self.value == other.value)
+        if isinstance(other, (int, float, complex, str)):
+            return self.value == other
+        return False
+
+
+ParamDict = dict[str, ParamInfo | dict[str, ParamInfo]]
+
+
+def _enrich_param_dict(param_dict: dict) -> ParamDict:
+    """Add metadata to param_dict entries."""
+    res = {}
+    for key, value in param_dict.items():
+        if isinstance(value, dict):
+            # Recursive step for nested dictionaries
+            res[key] = _enrich_param_dict(value)
+        else:
+            res[key] = ParamInfo(key, value)
+    return res
+
+
+def read_param_dict(path: str) -> ParamDict:
+    """Read param_dict and include additional information for each entry.
+
+    Parameters
+    ----------
+    path : str
+        Path to the file or a folder in which is contained a param_dict.json file
+
+    Returns
+    -------
+    ParamDict
+        The param_dict with additional metadata
+    """
+    # If the path is to a folder open /param_dict.json
+    if os.path.isdir(path):
+        path = os.path.join(path, "param_dict.json")
+    return _enrich_param_dict(read_json(path))