Skip to content

Migration Paths

This guide explains how to move from qsp-stack to individual packages as your project matures, and when it makes sense to do so.

Why migrate?

Starting with qsp-stack is the recommended path for exploration and prototyping. As your project moves toward production, you may want to:

  • Reduce your dependency footprint — only install what you actually use
  • Pin specific package versions — allow qsp-filter to upgrade independently of qsp-orientation
  • Clarify intent — make explicit which packages your code depends on
  • Improve reproducibility — avoid unexpected behavior when one ecosystem package is updated

Step 1: Audit your imports

Before migrating, identify exactly which QSP packages your code uses. Search your codebase for imports:

grep -r "import qsp" .

Common patterns:

import qsp_core        # → add qsp-core to requirements
import qsp_fft         # → add qsp-fft to requirements
import qsp_filter      # → add qsp-filter to requirements
import qsp_modulation  # → add qsp-modulation to requirements
import qsp_orientation # → add qsp-orientation to requirements

Step 2: Update your requirements

Replace qsp-stack with the specific packages you identified:

Before:

qsp-stack>=1.0.0

After:

qsp-core>=1.0.0
qsp-filter>=1.0.0
qsp-orientation>=1.0.0

(Adjust versions to match your tested compatibility range.)

Step 3: Test your environment

Install from your updated requirements into a clean environment and run your tests:

python -m venv .venv-test
source .venv-test/bin/activate
pip install -r requirements.txt
python -m pytest

If any imports fail, you may have missed a package in step 1. Add it to your requirements.

Step 4: Verify transitive dependencies

All QSP packages except qsp-stack depend only on qsp-core. If you install qsp-fft without explicitly listing qsp-core, it will still be installed as a transitive dependency. However, for clarity and reproducibility, it is good practice to list all direct imports explicitly.

Staying on qsp-stack

If any of the following are true, staying on qsp-stack is reasonable:

  • Your workflow spans most or all of the ecosystem packages
  • Your environment does not have strict dependency size constraints
  • You prefer a single versioned entry point to the ecosystem
  • You are not yet ready to manage individual package version constraints

qsp-stack is not a shortcut or a workaround — it is a supported, first-class installation method.

Partial migration

You can also do a partial migration: replace qsp-stack with most specific packages, but keep qsp-stack if your codebase touches all layers. This is an uncommon but valid approach during a transition period.

Next steps