Styx-ci-cd

.gitignore

@@ -1,3 +1,50 @@
-.idea
-__pycache__
-.pytest_cache/
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Ruff
+.ruff_cache/
+
+# Pre-commit
+.pre-commit-cache/
+
+# Project specific
+*.log

qualibration_graphs/superconducting/.pre-commit-config.yaml

@@ -0,0 +1,43 @@
+repos:
+      # 1. Generic hygiene hooks
+      - repo: https://github.com/pre-commit/pre-commit-hooks
+        rev: v4.6.0
+        hooks:
+          - id: trailing-whitespace
+          - id: end-of-file-fixer
+          - id: check-merge-conflict
+          - id: check-added-large-files
+          - id: check-yaml
+          - id: check-json
+
+      # 2. Black: code formatting
+      - repo: https://github.com/psf/black
+        rev: 24.10.0
+        hooks:
+          - id: black
+            language_version: python3
+
+      # 3. Pylint: linting
+      - repo: https://github.com/pycqa/pylint
+        rev: v3.3.1
+        hooks:
+          - id: pylint
+            args: [--rcfile=.pylintrc]
+
+      # 4. Type checking – heavier, so run on push instead of every commit
+      - repo: https://github.com/pre-commit/mirrors-mypy
+        rev: v1.11.1
+        hooks:
+          - id: mypy
+            stages: [pre-push]
+            additional_dependencies:
+              # Add stubs/internal deps here as needed
+              - types-setuptools
+
+      # 5. Conventional commit messages (commitizen)
+      - repo: https://github.com/commitizen-tools/commitizen
+        rev: v3.29.0
+        hooks:
+          - id: commitizen
+            stages: [commit-msg]
+            additional_dependencies: ["commitizen"]

qualibration_graphs/superconducting/.pylintrc

@@ -0,0 +1,26 @@
+
+[MESSAGES CONTROL]
+# Enable ONLY:
+#   E = Errors
+#   R = Refactor suggestions
+#   C = Convention checks
+#   F = fatal
+enable=E, R, F, C
+
+# Disable W (Warnings), and I (Information)
+disable=W, I
+
+
+[REPORTS]
+# Cleaner output, no extra reports
+reports=no
+
+
+[MASTER]
+# You can add folders to ignore if needed
+ignore=venv
+
+
+[FORMAT]
+# Optional — set your preferred line length
+max-line-length=120

qualibration_graphs/superconducting/CONTRIBUTING.md

@@ -0,0 +1,212 @@
+# Contributing Guide
+
+Welcome! This repository contains tools for building and analyzing calibration graphs for superconducting qubits. This guide explains how to set up your development environment, how we use pre-commit hooks, how tests are structured, and what we expect from contributions.
+
+---
+
+## 1. Getting Started
+
+### 1.1. Clone the repository
+
+```bash
+git clone git@github.com:qua-platform/superconducting_qualibrate.git
+cd CS_installations/qualibration_graphs/superconducting
+```
+
+### 1.2. Create a virtual environment and install dependencies
+
+Using `uv` (recommended):
+
+```bash
+# Install uv if you haven't already
+curl -LsSf https://astral.sh/uv/install.sh | sh  # Unix/macOS
+# Or: pip install uv
+
+# Create venv and install dependencies in one command
+uv sync --group dev --prerelease=allow
+source .venv/bin/activate
+```
+
+Alternatively, with `venv`:
+
+```bash
+python3 -m venv .venv
+source .venv/bin/activate  # Windows: .venv\Scripts\activate
+pip install -e ".[dev]"
+```
+
+This installs:
+
+- Runtime deps (numpy, scipy, etc.)
+- Dev tools: `pre-commit`, `black`, `pylint`, `mypy`, `pytest`, `pytest-cov`, `commitizen`, etc.
+
+### 1.3. Branch naming conventions
+
+When creating a new branch, follow these naming conventions:
+
+- **`feature/`** - New features or enhancements
+  - Example: `feature/rabi-calibration`, `feature/add-t2-ramsey`
+
+- **`bugfix/`** - Bug fixes
+  - Example: `bugfix/fix-t1-fitting`, `bugfix/nan-handling`
+
+- **`hotfix/`** - Urgent fixes for production issues
+  - Example: `hotfix/critical-pulse-timing`
+
+- **`chore/`** - Maintenance tasks, dependency updates, tooling
+  - Example: `chore/update-dependencies`, `chore/add-pre-commit`
+
+- **`refactor/`** - Code refactoring without changing functionality
+  - Example: `refactor/simplify-pulse-builder`, `refactor/calibration-pipeline`
+
+- **`experiment/`** - Experimental or exploratory work
+  - Example: `experiment/new-fitting-algorithm`, `experiment/alternative-approach`
+
+- **`release/`** - Release preparation branches
+  - Example: `release/v1.0.0`, `release/v1.1.0`
+
+Use lowercase, hyphen-separated descriptions. Keep branch names concise but descriptive.
+
+---
+
+## 2. Pre-commit Hooks
+
+We use [pre-commit](https://pre-commit.com) to automatically run fast checks before each commit. This ensures consistent style and catches many issues early.
+
+### 2.1. Install the hooks
+
+Run once after cloning:
+
+```bash
+pre-commit install
+pre-commit install --hook-type commit-msg
+```
+
+This sets up two things:
+
+- A **pre-commit** hook that runs on staged files before every commit.
+- A **commit-msg** hook (via Commitizen) that validates your commit messages.
+
+### 2.2. What runs in pre-commit?
+
+On each commit, the following checks run (on changed files):
+
+- **Formatting and linting**
+  - **Black** (`black`) for consistent Python formatting (120 char line length).
+  - **Pylint** (`pylint`) for code quality checks, following the `.pylintrc` configuration.
+
+- **Generic hygiene**
+  - Strip trailing whitespace.
+  - Ensure files end with a newline.
+  - Prevent committing merge conflict markers.
+  - Check YAML/JSON formatting.
+  - Warn on accidental large binary files.
+
+On each **push**, an additional hook runs:
+
+- **mypy**: static type checks on the codebase.
+
+### 2.3. Running pre-commit manually
+
+You can run pre-commit hooks on your staged files at any time:
+
+```bash
+pre-commit run
+```
+
+Or, if you want to check all files in the repository (useful before opening a PR):
+
+```bash
+pre-commit run --all-files
+```
+
+Fixes are usually applied automatically (e.g. for formatting). If a hook fails:
+
+1. Read the error message.
+2. Apply any suggested code changes.
+3. Re-stage your files (`git add ...`).
+4. Re-run the command or attempt the commit again.
+
+---
+
+## 3. Commit Messages (Conventional Commits)
+
+We use [Conventional Commits](https://www.conventionalcommits.org/) enforced by Commitizen. The format is:
+
+```text
+<type>[:scope]: <short summary>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+Common types:
+
+- `feat`: a new feature
+- `fix`: a bug fix
+- `refactor`: code change that neither fixes a bug nor adds a feature
+- `docs`: documentation only changes
+- `test`: adding or updating tests only
+- `chore`: tooling, build, or other non-product code changes
+
+Examples:
+
+- `feat: add rabi calibration pipeline`
+- `fix: handle NaNs in t1 analysis`
+- `refactor: simplify pulse sequence builder`
+
+If your commit message doesn’t follow the convention, the `commit-msg` hook will fail and show an error.
+
+You can also use Commitizen’s CLI to help craft messages and bump versions:
+
+```bash
+cz commit
+cz bump
+```
+
+(See `.cz.toml` or `[tool.commitizen]` in `pyproject.toml` for configuration.)
+
+---
+
+## 4. Tests
+
+We use `pytest` and organize tests into tiers that reflect how the calibration and control stack is validated, from pure Python logic up to hardware-in-the-loop checks.
+
+---
+
+## 5. Pull Requests
+
+Before opening a PR:
+
+1. Ensure your branch is up-to-date with the target branch (`main` or `develop`).
+2. Stage your changes and run:
+   ```bash
+   git add .
+   pre-commit run
+   pytest
+   ```
+   Note: Pre-commit will only check your staged changes. If you want to check all files, use `pre-commit run --all-files`.
+3. Add or update tests for your changes following the tiered test structure above.
+4. Ensure your commit messages follow Conventional Commits.
+
+When you open the PR:
+
+- CI will run linting/formatting checks and the configured test tiers.
+- At least one reviewer must approve before merging.
+- For changes that affect calibration logic, signals, or hardware interaction, please:
+  - Describe the impact on calibration workflows in the PR description.
+  - Indicate which test tiers you updated or verified.
+  - Link any related GitHub Issues or design docs.
+
+---
+
+## 6. Questions
+
+If you’re unsure about:
+
+- Which test tier is appropriate for your change,
+- How to structure calibration or signal validation tests,
+- How to interpret pre-commit or CI errors,
+
+please ask in the development channel or tag a maintainer in your PR.