Add differentiable Gray-coded QAM modulation and demodulation

.github/workflows/deploy.yml

@@ -0,0 +1,141 @@
+name: Deploy to PyPI
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch: # Allow manual triggering
+  workflow_run:
+    workflows: [
+        "Python CI",
+        "Tests",
+        "Generate Auto Examples",
+        "Update Changelog Documentation",
+        "Pre-commit Checks",
+      ] # Trigger after CI and Tests complete
+    types:
+      - completed
+    branches: [main]
+
+permissions:
+  contents: read
+  id-token: write # For trusted publishing to PyPI
+
+jobs:
+  check-version:
+    runs-on: ubuntu-latest
+    # Only run if workflow_run was successful or if triggered by push/manual
+    if: github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'
+    outputs:
+      version-changed: ${{ steps.version-check.outputs.changed }}
+      current-version: ${{ steps.version-check.outputs.version }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch full history for version comparison
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+
+      - name: Check if version changed
+        id: version-check
+        run: |
+          # Get current version from kaira/version.py
+          CURRENT_VERSION=$(python -c "from kaira.version import __version__; print(__version__)")
+          echo "current-version=$CURRENT_VERSION" >> $GITHUB_OUTPUT
+          echo "Current version: $CURRENT_VERSION"
+
+          # Check if this version exists on PyPI using simple curl
+          if curl -f -s "https://pypi.org/pypi/pykaira/$CURRENT_VERSION/json" > /dev/null 2>&1; then
+            echo "Version $CURRENT_VERSION already exists on PyPI"
+            echo "changed=false" >> $GITHUB_OUTPUT
+          else
+            echo "Version $CURRENT_VERSION is new"
+            echo "changed=true" >> $GITHUB_OUTPUT
+          fi
+
+  deploy-pypi:
+    needs: check-version
+    if: needs.check-version.outputs.version-changed == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v4
+        with:
+          python-version: "3.10"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build twine setuptools wheel
+
+      - name: Clean build artifacts
+        run: |
+          # Clean Python build artifacts and cache files
+          find . -type d -name "__pycache__" -exec rm -rf {} + || true
+          find . -type d -name "*.egg-info" -exec rm -rf {} + || true
+          find . -type d -name ".eggs" -exec rm -rf {} + || true
+          find . -type f -name "*.pyc" -delete || true
+          find . -type f -name "*.pyo" -delete || true
+          find . -type f -name "*.pyd" -delete || true
+          find . -type f -name ".coverage" -delete || true
+          find . -type f -name "coverage.xml" -delete || true
+          find . -type d -name ".pytest_cache" -exec rm -rf {} + || true
+          find . -type d -name ".coverage*" -exec rm -rf {} + || true
+          find . -type d -name "htmlcov" -exec rm -rf {} + || true
+
+          # Clean documentation build artifacts
+          rm -rf docs/_build/ || true
+          rm -rf docs/gen_modules/ || true
+          rm -rf docs/generated/ || true
+          rm -rf docs/auto_examples/ || true
+
+          # Remove build and dist directories
+          rm -rf build/ dist/ ./*.egg-info/ || true
+
+      - name: Build distribution packages
+        run: |
+          echo "Building distribution for version ${{ needs.check-version.outputs.current-version }}"
+          python setup.py sdist bdist_wheel
+
+      - name: Check package with twine
+        run: twine check dist/*
+
+      - name: Upload to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          # Use API token stored in repository secrets
+          password: ${{ secrets.PYPI_API_TOKEN }}
+          verbose: true
+
+      - name: Verify deployment
+        run: |
+          # Wait a bit for the package to be available
+          sleep 30
+
+          # Try to install from PyPI
+          pip install pykaira==${{ needs.check-version.outputs.current-version }}
+
+          # Basic import test
+          python -c "import kaira; print(f'Successfully deployed kaira version: {kaira.__version__}')"
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: v${{ needs.check-version.outputs.current-version }}
+          name: Release v${{ needs.check-version.outputs.current-version }}
+          body: |
+            ## Changes in v${{ needs.check-version.outputs.current-version }}
+
+            This release has been automatically deployed to PyPI.
+
+            Install with: `pip install pykaira==${{ needs.check-version.outputs.current-version }}`
+          draft: false
+          prerelease: false

.gitignore

@@ -12,6 +12,7 @@ examples/benchmarks/example_results
 examples/benchmarks/benchmark_results
 examples/benchmarks/visualization_results
 .gradio
+wandb
 
 # Distribution / packaging
 .Python

CODE_OF_CONDUCT.md

@@ -0,0 +1,3 @@
+# Code of Conduct
+
+We follow the [Python Software Foundation Code of Conduct](https://www.python.org/psf/codeofconduct/). All contributors are expected to adhere to its principles of openness, respect, and collaboration.

configs/training_example.yaml

@@ -0,0 +1,101 @@
+# @package _global_
+
+# Hydra configuration for Kaira training
+# This configuration demonstrates how to set up training parameters
+# for communication system models using Hydra
+
+defaults:
+  - _self_
+
+# Model configuration
+model:
+  _target_: kaira.models.DeepJSCCModel
+  type: deepjscc
+  input_dim: 512
+  channel_uses: 64
+  hidden_dim: 256
+  encoder_layers: 3
+  decoder_layers: 3
+  activation: relu
+
+# Training configuration
+training:
+  output_dir: ./training_results
+  num_train_epochs: 10
+  per_device_train_batch_size: 32
+  per_device_eval_batch_size: 32
+  learning_rate: 1e-4
+  weight_decay: 0.01
+  warmup_steps: 1000
+  logging_steps: 100
+  eval_steps: 500
+  save_steps: 1000
+  eval_strategy: steps
+  save_strategy: steps
+  save_total_limit: 3
+
+  # Communication-specific parameters
+  snr_min: 0.0
+  snr_max: 20.0
+  noise_variance_min: 0.1
+  noise_variance_max: 2.0
+  channel_uses: 64
+  channel_type: awgn
+
+  # Training flags
+  do_eval: true
+  do_predict: false
+  fp16: false
+  dataloader_num_workers: 0
+
+  # Optimization
+  gradient_accumulation_steps: 1
+  max_grad_norm: 1.0
+  lr_scheduler_type: linear
+
+  # Logging and monitoring
+  logging_dir: ${training.output_dir}/logs
+  run_name: deepjscc_training
+  report_to: [] # Can be set to ["wandb", "tensorboard"] for monitoring
+
+# Data configuration
+data:
+  dataset_name: null # Most communication models generate synthetic data
+  train_batch_size: ${training.per_device_train_batch_size}
+  eval_batch_size: ${training.per_device_eval_batch_size}
+  max_train_samples: null
+  max_eval_samples: null
+  preprocessing_num_workers: 4
+
+# Channel simulation configuration
+channel:
+  type: ${training.channel_type}
+  snr_range:
+    - ${training.snr_min}
+    - ${training.snr_max}
+  noise_type: gaussian
+  fading: false
+
+# Optimizer configuration
+optimizer:
+  type: adamw
+  lr: ${training.learning_rate}
+  weight_decay: ${training.weight_decay}
+  betas:
+    - 0.9
+    - 0.999
+  eps: 1e-8
+
+# Scheduler configuration
+scheduler:
+  type: ${training.lr_scheduler_type}
+  warmup_steps: ${training.warmup_steps}
+  num_training_steps: null # Will be calculated automatically
+
+# Hydra configuration
+hydra:
+  run:
+    dir: ${training.output_dir}/hydra_outputs/${now:%Y-%m-%d_%H-%M-%S}
+  job:
+    name: kaira_training
+    chdir: true

configs/training_simple.yaml

@@ -0,0 +1,26 @@
+# @package _global_
+
+# Simple Hydra configuration for Kaira training
+defaults:
+  - _self_
+
+# Model configuration
+model:
+  _target_: kaira.models.DeepJSCCModel
+  type: deepjscc
+  input_dim: 256
+  channel_uses: 32
+  hidden_dim: 128
+
+# Training configuration
+training:
+  output_dir: ./simple_training
+  num_train_epochs: 5
+  per_device_train_batch_size: 16
+  learning_rate: 1e-3
+  snr_min: 0.0
+  snr_max: 10.0
+  channel_type: awgn
+  eval_strategy: no
+  save_strategy: epoch
+  logging_steps: 50