Merge pull request #243 from harmoniqs/feat/global-params-in-problems

Feat/global params in problems

Author: aarontrowbridge

CONTEXT.md

@@ -193,11 +193,47 @@ QuantumCollocation.jl **uses** these types and provides problem templates that b
 - Adds derivative variables `:du`, `:ddu` for smoothness
 - Creates `DerivativeIntegrator` constraints enforcing `u[k+1] - u[k] = Δt * du[k]`
 - Applies quadratic regularization on `u`, `du`, `ddu`
+- Supports `global_bounds` for time-invariant parameters (requires custom integrator)
 
 **SplinePulseProblem** (for spline pulses):
 - For `LinearSplinePulse`: `:du` represents slopes (added automatically)
 - For `CubicSplinePulse`: `:du` represents Hermite tangents (built into pulse)
 - Uses `DerivativeIntegrator` with spline semantics
+- Supports `global_bounds` for time-invariant parameters (requires custom integrator)
+
+### Global Variable Bounds
+
+Both `SmoothPulseProblem` and `SplinePulseProblem` support bounds on global (time-invariant) optimization variables:
+
+```julia
+using Piccolissimo  # For HermitianExponentialIntegrator or SplineIntegrator
+
+# System with global parameter
+H = (u, t) -> u[2] * GATES.Z + u[1] * GATES.X  # δ = u[2] is global
+sys = QuantumSystem(H, [1.0]; time_dependent=true, global_params=(δ=0.1,))
+qtraj = UnitaryTrajectory(sys, pulse, U_goal)
+
+# Integrator that supports globals
+integrator = HermitianExponentialIntegrator(qtraj, N)
+
+# Symmetric bounds: -0.5 ≤ δ ≤ 0.5
+qcp = SmoothPulseProblem(qtraj, N; 
+    integrator=integrator, 
+    global_bounds=Dict(:δ => 0.5))
+
+# Asymmetric bounds: 0.1 ≤ δ ≤ 0.8
+qcp = SmoothPulseProblem(qtraj, N; 
+    integrator=integrator,
+    global_bounds=Dict(:δ => (0.1, 0.8)))
+
+# Multiple globals with mixed bound types
+qcp = SplinePulseProblem(qtraj, N;
+    integrator=SplineIntegrator(qtraj, N; global_names=[:δ, :ω]),
+    global_bounds=Dict{Symbol, Union{Float64, Tuple{Float64,Float64}}}(
+        :δ => 0.5,           # Symmetric
+        :ω => (0.001, 0.5)   # Asymmetric
+    ))
+```
 
 **Adding constraints to SplinePulseProblem:** When working with `SplinePulseProblem`, especially with dynamical timesteps (`Δt_bounds`), add constraints to the existing problem rather than recreating it:
 
@@ -276,6 +312,7 @@ Run tests with `TestItemRunner.@run_package_tests`.
 ## Recent Changes (Update This!)
 
 ### January 2026
+- Added `global_bounds` parameter to `SmoothPulseProblem` and `SplinePulseProblem` for constraining time-invariant optimization variables
 - Removed `time_dependent=true` from test QuantumSystem constructions (`:t` is now always in trajectories)
 - Removed `adapt_trajectory`/`unadapt_trajectory` usage (control scaling removed)
 - Updated `BilinearIntegrator` signatures from `(qtraj, traj)` to `(qtraj, N)`

Project.toml

@@ -1,6 +1,6 @@
 name = "QuantumCollocation"
 uuid = "0dc23a59-5ffb-49af-b6bd-932a8ae77adf"
-version = "0.10.1"
+version = "0.10.2"
 authors = ["Aaron Trowbridge <aaron.j.trowbridge@gmail.com> and contributors"]
 
 [deps]

docs/literate/man/problem_templates_overview.jl

@@ -8,7 +8,7 @@
 # |:---------|:-----------|:-----|:---------|
 # | [`SmoothPulseProblem`](@ref) | Minimize control effort + infidelity | Fixed | Standard gate/state synthesis with smooth pulses |
 # | [`MinimumTimeProblem`](@ref) | Minimize duration | Variable | Fastest gate/state synthesis given fidelity constraint |
-# | [`SplinePulseProblem`](@ref) | Minimize control effort + infidelity | Fixed | Gate/state synthesis with spline-based pulses where the derivative variables (`du`) are the actual spline coefficients or slopes. |
+# | [`SplinePulseProblem`](@ref) | Minimize control effort + infidelity | Fixed | Gate/state synthesis with spline-based pulses (linear or cubic Hermite) |
 # | [`SamplingProblem`](@ref) | Minimize control effort + weighted sum of infidelity objectives | Fixed | Robust gate/state synthesis where the controls are shared across all systems, with differing dynamics. |
 
 # ### Smooth Pulse vs Minimum Time

docs/src/index.md

@@ -52,7 +52,7 @@ That's it! You've optimized control pulses for a quantum gate.
 ## What Can QuantumCollocation Do?
 
 - **Unitary gate optimization** - Find pulses to implement quantum gates
-- **Open quantum systems** - Find pulses for lindladian dynamics 
+- **Open quantum systems** - Find pulses for Lindbladian dynamics 
 - **State transfer** - Drive quantum states to target states
 - **Minimum time control** - Optimize gate duration
 - **Robust control** - Account for system uncertainties

src/problem_templates/_problem_templates.jl

@@ -82,4 +82,118 @@ function apply_piccolo_options!(
     return J
 end
 
+"""
+    add_global_bounds_constraints!(constraints, global_bounds, traj; verbose=false)
+
+Add GlobalBoundsConstraint entries for each global variable specified in `global_bounds`.
+
+Converts bounds from user-friendly formats to the format expected by GlobalBoundsConstraint:
+- `Float64`: Symmetric scalar bounds (applied symmetrically to all dimensions)
+- `Tuple{Float64, Float64}`: Asymmetric scalar bounds (expanded to vectors)
+- `Vector` or `Tuple{Vector, Vector}`: Already in correct format (passed through)
+
+Modifies `constraints` in place.
+"""
+function add_global_bounds_constraints!(
+    constraints::AbstractVector{<:AbstractConstraint},
+    global_bounds,
+    traj::NamedTrajectory;
+    verbose::Bool=false
+)
+    if isnothing(global_bounds)
+        return
+    end
+    
+    for (name, bounds) in global_bounds
+        if !haskey(traj.global_components, name)
+            error("Global variable :$name not found in trajectory. Available: $(keys(traj.global_components))")
+        end
+        global_dim = length(traj.global_components[name])
+        # Convert bounds to format expected by GlobalBoundsConstraint
+        if bounds isa Float64
+            # Symmetric scalar bounds
+            bounds_value = bounds
+        elseif bounds isa Tuple{Float64, Float64}
+            # Asymmetric scalar bounds -> convert to vector tuple
+            bounds_value = (fill(bounds[1], global_dim), fill(bounds[2], global_dim))
+        else
+            # Already in correct format (Vector or Tuple of Vectors)
+            bounds_value = bounds
+        end
+        push!(constraints, GlobalBoundsConstraint(name, bounds_value))
+        if verbose
+            println("    added GlobalBoundsConstraint for :$name with bounds $bounds_value")
+        end
+    end
+end
+
+@testitem "add_global_bounds_constraints! helper function" begin
+    using QuantumCollocation
+    using NamedTrajectories
+    using DirectTrajOpt
+    
+    # Create a trajectory with global components for testing
+    # global_data is a flat vector, global_components maps names to index ranges
+    N = 5
+    traj = NamedTrajectory(
+        (x = rand(2, N), u = rand(1, N), Δt = fill(0.1, N));
+        timestep=:Δt,
+        controls=:u,
+        global_data=[0.1, 0.5, 0.3],  # flat vector
+        global_components=(δ = 1:1, ω = 2:3)  # δ is scalar, ω is 2D
+    )
+    
+    # Test 1: nothing global_bounds is a no-op
+    constraints1 = AbstractConstraint[]
+    QuantumCollocation.ProblemTemplates.add_global_bounds_constraints!(
+        constraints1, nothing, traj
+    )
+    @test isempty(constraints1)
+    
+    # Test 2: Float64 symmetric scalar bounds
+    constraints2 = AbstractConstraint[]
+    QuantumCollocation.ProblemTemplates.add_global_bounds_constraints!(
+        constraints2, Dict(:δ => 0.5), traj
+    )
+    @test length(constraints2) == 1
+    @test constraints2[1] isa BoundsConstraint
+    @test constraints2[1].is_global
+    
+    # Test 3: Tuple{Float64, Float64} asymmetric scalar bounds (expanded to vectors)
+    constraints3 = AbstractConstraint[]
+    QuantumCollocation.ProblemTemplates.add_global_bounds_constraints!(
+        constraints3, Dict(:ω => (-0.2, 0.8)), traj
+    )
+    @test length(constraints3) == 1
+    @test constraints3[1] isa BoundsConstraint
+    @test constraints3[1].is_global
+    
+    # Test 4: Multiple globals with mixed bound types
+    constraints4 = AbstractConstraint[]
+    global_bounds = Dict{Symbol, Union{Float64, Tuple{Float64, Float64}}}(
+        :δ => 0.5,           # symmetric
+        :ω => (-0.2, 0.8)    # asymmetric
+    )
+    QuantumCollocation.ProblemTemplates.add_global_bounds_constraints!(
+        constraints4, global_bounds, traj
+    )
+    @test length(constraints4) == 2
+    @test all(c -> c isa BoundsConstraint && c.is_global, constraints4)
+    
+    # Test 5: Error when global variable doesn't exist
+    constraints5 = AbstractConstraint[]
+    @test_throws "Global variable :nonexistent not found" begin
+        QuantumCollocation.ProblemTemplates.add_global_bounds_constraints!(
+            constraints5, Dict(:nonexistent => 0.5), traj
+        )
+    end
+    
+    # Test 6: Verbose output (just ensure it doesn't error)
+    constraints6 = AbstractConstraint[]
+    QuantumCollocation.ProblemTemplates.add_global_bounds_constraints!(
+        constraints6, Dict(:δ => 0.5), traj; verbose=true
+    )
+    @test length(constraints6) == 1
+end
+
 end