QuantumToolboxCore Library

.buildkite/CUDA_Ext.yml

@@ -1,4 +1,31 @@
 steps:
+  # Julia 1.10 doesn't support [sources] in Project.toml,
+  # so we need to manually dev workspace packages before instantiating.
+  - label: "Dev local libs for Julia < 1.11"
+    plugins:
+      - JuliaCI/julia#v1:
+          version: "1.10"
+      - JuliaCI/julia-coverage#v1:
+          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.instantiate()
+      '
+
   - label: "CUDA Julia {{matrix.version}}"
     matrix:
       setup:
@@ -14,6 +41,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/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/**'

.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/**'
@@ -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,6 +18,7 @@ on:
     paths:
       - '.github/workflows/Code-Quality.yml'
       - 'src/**'
+      - 'lib/**'
       - 'ext/**'
       - 'test/runtests.jl'
       - 'test/core-test/**'
@@ -39,7 +41,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - 'lts'
+          - '1.10' # oldest
           - '1'
         os:
           - 'ubuntu-latest'
@@ -55,6 +57,20 @@ 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:

.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- 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 = "- 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'

Project.toml

@@ -20,7 +20,9 @@ OrdinaryDiffEqLowOrderRK = "1344f307-1e59-4825-a18e-ace9aa3fa4c6"
 OrdinaryDiffEqVerner = "79d7bb75-1356-48c1-b8c0-6832512096c2"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
+QuantumToolboxUtils = "02afad9e-e2b8-4f9a-965f-b5dca5b538ca"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+Reexport = "189a3867-3050-52da-a836-e630ba90ab69"
 SciMLBase = "0bca4576-84f4-4d90-8ffe-ffa030f20462"
 SciMLOperators = "c0aeaf25-5076-4817-a8d5-81caf7dfa961"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
@@ -36,6 +38,9 @@ GPUArrays = "0c68f7d7-f131-5f86-a1c3-88cf8149b2d7"
 KernelAbstractions = "63c18a36-062a-441e-b654-da1e3ab1ce7c"
 Makie = "ee78f7c6-11fb-53f2-987a-cfe4a2b5a57a"
 
+[sources]
+QuantumToolboxUtils = {path = "lib/QuantumToolboxUtils"}
+
 [extensions]
 QuantumToolboxCUDAExt = "CUDA"
 QuantumToolboxChainRulesCoreExt = "ChainRulesCore"
@@ -64,7 +69,9 @@ OrdinaryDiffEqLowOrderRK = "1"
 OrdinaryDiffEqVerner = "1"
 Pkg = "1"
 ProgressMeter = "1.11.0"
+QuantumToolboxUtils = "0.1"
 Random = "1"
+Reexport = "1"
 SciMLBase = "2.105"
 SciMLOperators = "1.12"
 SparseArrays = "1"

docs/make.jl

@@ -83,6 +83,7 @@ const PAGES = [
 
 makedocs(;
     modules = [
+        QuantumToolboxUtils,
         QuantumToolbox,
         Base.get_extension(QuantumToolbox, :QuantumToolboxMakieExt),
     ],

lib/QuantumToolboxUtils/LICENSE

@@ -0,0 +1,29 @@
+BSD 3-Clause License
+
+Copyright (c) 2022 to 2026 inclusive, QuTiP developers and contributors.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+   may be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

lib/QuantumToolboxUtils/Project.toml

@@ -0,0 +1,17 @@
+name = "QuantumToolboxUtils"
+uuid = "02afad9e-e2b8-4f9a-965f-b5dca5b538ca"
+authors = ["Alberto Mercurio", "Yi-Te Huang"]
+version = "0.1.0"
+
+[deps]
+Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
+SciMLOperators = "c0aeaf25-5076-4817-a8d5-81caf7dfa961"
+SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
+StaticArraysCore = "1e83bf80-4336-4d27-bf5d-d5a4f845583c"
+
+[compat]
+Random = "1"
+SciMLOperators = "1.12"
+SparseArrays = "1"
+StaticArraysCore = "1"
+julia = "1.10"