QuantumToolboxCore Library

.buildkite/CUDA_Ext.yml

@@ -1,9 +1,41 @@
 steps:
+  # Julia 1.10 doesn't support [sources] in Project.toml,
+  # so we need to manually dev workspace packages before instantiating.
+  - label: "CUDA Julia 1.10"
+    plugins:
+      - JuliaCI/julia#v1:
+          version: "1.10"
+      - JuliaCI/julia-coverage#v1:
+          codecov: true
+          dirs:
+            - src
+            - lib
+            - ext
+    agents:
+      queue: "juliagpu"
+      cuda: "*"
+    commands: |
+      julia --project=. -e '
+        using Pkg
+        if VERSION < v"1.11"
+          for lib in readdir("lib"; join=true)
+            isdir(lib) || continue
+            isfile(joinpath(lib, "Project.toml")) || continue
+            Pkg.develop(path=lib)
+          end
+        end
+        Pkg.test(; test_args=["--quickfail"])
+      '
+    env:
+      GROUP: "CUDA_Ext"
+      SECRET_CODECOV_TOKEN: "ZfhQu/IcRLqNyZ//ZNs5sjBPaV76IHfU5gui52Qn+Rp8tOurukqgScuyDt+3HQ4R0hJYBw1/Nqg6jmBsvWSc9NEUx8kGsUJFHfN3no0+b+PFxA8oJkWc9EpyIsjht5ZIjlsFWR3f0DpPqMEle/QyWOPcal63CChXR8oAoR+Fz1Bh8GkokLlnC8F9Ugp9xBlu401GCbyZhvLTZnNIgK5yy9q8HBJnBg1cPOhI81J6JvYpEmcIofEzFV/qkfpTUPclu43WNoFX2DZPzbxilf3fsAd5/+nRkRfkNML8KiN4mnmjHxPPbuY8F5zC/PS5ybXtDpfvaMQc01WApXCkZk0ZAQ==;U2FsdGVkX1+eDT7dqCME5+Ox5i8GvWRTQbwiP/VYjapThDbxXFDeSSIC6Opmon+M8go22Bun3bat6Fzie65ang=="
+    timeout_in_minutes: 60
+
   - label: "CUDA Julia {{matrix.version}}"
     matrix:
       setup:
         version:
-          - "1.10" # oldest
+          - "1.11" # oldest
           - "1"    # latest
     plugins:
       - JuliaCI/julia#v1:
@@ -14,6 +46,7 @@ steps:
           codecov: true
           dirs:
             - src
+            - lib
             - ext
     agents:
       queue: "juliagpu"

.buildkite/pipeline.yml

@@ -18,6 +18,7 @@ steps:
             - ".buildkite/pipeline.yml"
             - ".buildkite/CUDA_Ext.yml"
             - "src/**"
+            - "lib/**"
             - "ext/QuantumToolboxCUDAExt.jl"
             - "test/runtests.jl"
             - "test/ext-test/gpu/**"

.github/copilot-instructions.md

@@ -82,11 +82,11 @@ QuantumToolbox.settings.ProgressMeterKWARGS = (showspeed=true, printed=true)
 ### Running Tests
 ```bash
 make test                    # Run all core tests
-GROUP=Core make test         # Run core tests only
+GROUP=Main make test         # Run Main tests only
 GROUP=CUDA_Ext make test     # Run CUDA extension tests only
 ```
 
-Test groups (set `GROUP` env var): "All", "Core", "Code-Quality", "AutoDiff_Ext", "Makie_Ext", "CUDA_Ext", "Arbitrary-Precision"
+Test groups (set `GROUP` env var): "All", "Main", "Code-Quality", "AutoDiff_Ext", "Makie_Ext", "CUDA_Ext", "Arbitrary-Precision"
 
 ### Code Quality & Formatting
 ```bash

.github/workflows/Benchmarks.yml

@@ -6,6 +6,7 @@ on:
     paths:
       - '.github/workflows/Benchmarks.yml'
       - 'src/**'
+      - 'lib/**'
       - 'ext/**'
       - 'benchmarks/**'
       - 'Project.toml'
@@ -15,6 +16,7 @@ on:
     paths:
       - '.github/workflows/Benchmarks.yml'
       - 'src/**'
+      - 'lib/**'
       - 'ext/**'
       - 'benchmarks/**'
       - 'Project.toml'

.github/workflows/CI-Julia-nightly.yml

@@ -7,6 +7,7 @@ on:
     paths:
       - '.github/workflows/CI-Julia-nightly.yml'
       - 'src/**'
+      - 'lib/**'
       - 'ext/**'
       - 'test/runtests.jl'
       - 'test/core-test/**'
@@ -17,6 +18,7 @@ on:
     paths:
       - '.github/workflows/CI-Julia-nightly.yml'
       - 'src/**'
+      - 'lib/**'
       - 'ext/**'
       - 'test/runtests.jl'
       - 'test/core-test/**'
@@ -45,7 +47,7 @@ jobs:
         arch:
           - 'x64'
         group:
-          - 'Core'
+          - 'Main'
 
     steps:
       - uses: actions/checkout@v6

.github/workflows/CI.yml

@@ -7,6 +7,7 @@ on:
     paths:
       - '.github/workflows/CI.yml'
       - 'src/**'
+      - 'lib/**'
       - 'ext/**'
       - 'test/runtests.jl'
       - 'test/core-test/**'
@@ -18,6 +19,7 @@ on:
     paths:
       - '.github/workflows/CI.yml'
       - 'src/**'
+      - 'lib/**'
       - 'ext/**'
       - 'test/runtests.jl'
       - 'test/core-test/**'
@@ -52,15 +54,15 @@ jobs:
           - os: 'macOS-latest'
             arch: 'arm64'
         group:
-          - 'Core'
+          - 'Main'
 
         include:
           # for core tests (intermediate versions)
           - version: '1.11'
             node:
               os: 'ubuntu-latest'
               arch: 'x64'
-            group: 'Core'
+            group: 'Main'
 
           # for extension tests
           - version: '1'
@@ -86,6 +88,20 @@ jobs:
           version: ${{ matrix.version }}
           arch: ${{ matrix.node.arch }}
       - uses: julia-actions/cache@v3
+      - name: Dev local libs for Julia < 1.11
+        shell: bash
+        run: |
+          julia --project=. -e '
+            using Pkg
+            if VERSION < v"1.11"
+              for lib in readdir("lib"; join=true)
+                isdir(lib) || continue
+                isfile(joinpath(lib, "Project.toml")) || continue
+                Pkg.develop(path=lib)
+              end
+            end
+            Pkg.instantiate()
+          '
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
         env:

.github/workflows/Code-Quality.yml

@@ -7,6 +7,7 @@ on:
     paths:
       - '.github/workflows/Code-Quality.yml'
       - 'src/**'
+      - 'lib/**'
       - 'ext/**'
       - 'test/runtests.jl'
       - 'test/core-test/**'
@@ -17,9 +18,10 @@ on:
     paths:
       - '.github/workflows/Code-Quality.yml'
       - 'src/**'
+      - 'lib/**'
       - 'ext/**'
       - 'test/runtests.jl'
-      - 'test/core-test/**'
+      - 'test/code-quality/**'
       - 'Project.toml'
     types:
       - opened
@@ -39,14 +41,12 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - 'lts'
+          - '1.10' # oldest
           - '1'
         os:
           - 'ubuntu-latest'
         arch:
           - 'x64'
-        group:
-          - 'Code-Quality'
 
     steps:
       - uses: actions/checkout@v6
@@ -55,7 +55,21 @@ jobs:
           version: ${{ matrix.version }}
           arch: ${{ matrix.arch }}
       - uses: julia-actions/cache@v3
+      - name: Dev local libs for Julia < 1.11
+        shell: bash
+        run: |
+          julia --project=. -e '
+            using Pkg
+            if VERSION < v"1.11"
+              for lib in readdir("lib"; join=true)
+                isdir(lib) || continue
+                isfile(joinpath(lib, "Project.toml")) || continue
+                Pkg.develop(path=lib)
+              end
+            end
+            Pkg.instantiate()
+          '
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
         env:
-          GROUP: ${{ matrix.group }}
+          GROUP: 'Code-Quality'

.github/workflows/bump-version.yml

@@ -3,6 +3,14 @@ name: Bump Version
 on:
   workflow_dispatch:
     inputs:
+      package:
+        description: 'Package to bump'
+        required: true
+        default: 'QuantumToolbox'
+        type: choice
+        options:
+        - QuantumToolbox
+        - QuantumToolboxUtils
       bump_type:
         description: 'Version bump type'
         required: true
@@ -37,12 +45,20 @@ jobs:
           julia -e '
             using Pkg; Pkg.add("Changelog")
             using TOML, Dates, Changelog
-            project_file = "Project.toml"
+            package = ENV["PACKAGE"]
+            project_file = package == "QuantumToolbox" ? "Project.toml" : "lib/$(package)/Project.toml"
             changelog_file = "CHANGELOG.md"
 
             # --- PART 1: Calculate new version number ---
+            # the current version of QuantumToolbox 
+            p_QT = TOML.parsefile("Project.toml")
+            v_QT = VersionNumber(p_QT["version"])
+
+            # the current version of selected package 
             p = TOML.parsefile(project_file)
             v = VersionNumber(p["version"])
+
+            # the version bump type (major, minor, patch)
             type = ENV["BUMP_TYPE"]
             new_v = if type == "major"
                 VersionNumber(v.major + 1, 0, 0)
@@ -53,9 +69,10 @@ jobs:
             end
 
             # --- PART 2: Output version number to GitHub Actions variables ---
-            println("Bump version from v$v to v$new_v")
+            println("Bump $package version from v$v to v$new_v")
             open(ENV["GITHUB_OUTPUT"], "a") do io
               println(io, "new_version=$new_v")
+              println(io, "project_file=$project_file")
             end
 
             # --- PART 3: Update Project.toml (using Regex to preserve formatting) ---
@@ -66,35 +83,79 @@ jobs:
 
             # --- PART 4: Update CHANGELOG.md ---
             content = read(changelog_file, String)
-            marker = "## [Unreleased](https://github.com/qutip/QuantumToolbox.jl/tree/main)"
-            insertion = "$marker\n\n\n\n## [v$new_v]\nRelease date: $(Dates.format(now(), "yyyy-mm-dd"))"
-            new_content = replace(content, marker => insertion)
+
+            marker1 = "\n\n## [v$v_QT]"
+            insertion1 = "\n- [lib] Bump `$package` version to `v$new_v`.\n$marker1"
+            new_content = replace(content, marker1 => insertion1)
+
+            if package == "QuantumToolbox"
+              marker2 = "## [Unreleased](https://github.com/qutip/QuantumToolbox.jl/tree/main)"
+              insertion2 = "$marker2\n\n\n\n## [v$new_v]\nRelease date: $(Dates.format(now(), "yyyy-mm-dd"))"
+              new_content = replace(new_content, marker2 => insertion2)
+            end
+
             write(changelog_file, new_content)
             Changelog.generate(Changelog.CommonMark(), changelog_file; repo = "qutip/QuantumToolbox.jl")
             println("Updated $changelog_file")
           '
         env:
+          PACKAGE: ${{ inputs.package }}
           BUMP_TYPE: ${{ inputs.bump_type }}
 
       - name: Create Branch
         run: |
           git config user.name "github-actions[bot]"
           git config user.email "github-actions[bot]@users.noreply.github.com"
-          
-          BRANCH_NAME="bump-to-${{ steps.updates.outputs.new_version }}"
+
+          BRANCH_NAME="bump-${{ inputs.package }}-version-to-v${{ steps.updates.outputs.new_version }}"
           git checkout -b $BRANCH_NAME
-          git add Project.toml CHANGELOG.md
-          git commit -m "[no ci] Bump version to v${{ steps.updates.outputs.new_version }}"
+          git add "${{ steps.updates.outputs.project_file }}" CHANGELOG.md
+          git commit -m "[no ci] Bump ${{ inputs.package }}.jl version to v${{ steps.updates.outputs.new_version }}"
           git push origin $BRANCH_NAME
 
       - name: Create Pull Request
+        id: create_pr
         env:
           GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
-          BRANCH_NAME="bump-to-${{ steps.updates.outputs.new_version }}"
-          gh pr create \
+          BRANCH_NAME="bump-${{ inputs.package }}-version-to-v${{ steps.updates.outputs.new_version }}"
+          PR_URL=$(gh pr create \
             --base main \
             --head $BRANCH_NAME \
-            --title "Bump version to v${{ steps.updates.outputs.new_version }}" \
-            --body "This PR bumps the package version to v${{ steps.updates.outputs.new_version }} and updates CHANGELOG.md." \
-            --label "Skip ChangeLog"
+            --title "Bump ${{ inputs.package }} version to v${{ steps.updates.outputs.new_version }}" \
+            --body "This PR bumps ${{ inputs.package }} version to v${{ steps.updates.outputs.new_version }} and updates CHANGELOG.md.")
+
+          PR_NUMBER="${PR_URL##*/}"
+
+          echo "Created PR: $PR_URL"
+          {
+            echo "pr_url=$PR_URL"
+            echo "pr_number=$PR_NUMBER"
+          } >> "$GITHUB_OUTPUT"
+
+      - name: Update CHANGELOG with PR number
+        run: |
+          julia -e '
+            using Pkg; Pkg.add("Changelog")
+            using Changelog
+
+            package = ENV["PACKAGE"]
+            new_v = ENV["NEW_VERSION"]
+            pr_number = ENV["PR_NUMBER"]
+            changelog_file = "CHANGELOG.md"
+
+            content = read(changelog_file, String)
+            old_entry = "- [lib] Bump `$package` version to `v$new_v`."
+            new_entry = "$old_entry ([#$pr_number])"
+
+            write(changelog_file, replace(content, old_entry => new_entry))
+            Changelog.generate(Changelog.CommonMark(), changelog_file; repo = "qutip/QuantumToolbox.jl")
+          '
+
+          git add CHANGELOG.md
+          git commit -m "[no ci] Add PR reference to CHANGELOG"
+          git push origin "bump-${{ inputs.package }}-version-to-v${{ steps.updates.outputs.new_version }}"
+        env:
+          PACKAGE: ${{ inputs.package }}
+          NEW_VERSION: ${{ steps.updates.outputs.new_version }}
+          PR_NUMBER: ${{ steps.create_pr.outputs.pr_number }}

.github/workflows/documentation.yml

@@ -12,6 +12,7 @@ on:
     paths:
       - '.github/workflows/documentation.yml'
       - 'src/**'
+      - 'lib/**'
       - 'ext/**'
       - 'docs/**'
       - 'Project.toml'

CHANGELOG.md

@@ -7,7 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased](https://github.com/qutip/QuantumToolbox.jl/tree/main)
 
-
+- [lib] Introduce QuantumToolboxUtils library. ([#686])
 
 ## [v0.45.0]
 Release date: 2026-04-19
@@ -484,6 +484,7 @@ Release date: 2024-11-13
 [#681]: https://github.com/qutip/QuantumToolbox.jl/issues/681
 [#682]: https://github.com/qutip/QuantumToolbox.jl/issues/682
 [#683]: https://github.com/qutip/QuantumToolbox.jl/issues/683
+[#686]: https://github.com/qutip/QuantumToolbox.jl/issues/686
 [#688]: https://github.com/qutip/QuantumToolbox.jl/issues/688
 [#689]: https://github.com/qutip/QuantumToolbox.jl/issues/689
 [#690]: https://github.com/qutip/QuantumToolbox.jl/issues/690