Merged
Conversation
…instead of timesteps; refactor integrator functions for consistency
…ps; update system initialization parameters for consistency across tests.
… use N instead of T for consistency; update integrator functions accordingly.
…l problems - Changed control variable name from `a` to `u` across multiple problem templates: - `unitary_sampling_problem.jl` - `unitary_smooth_pulse_problem.jl` - `unitary_variational_problem.jl` - Updated associated bounds and regularization weights to reflect the new naming convention. - Enhanced trajectory initialization functions to support new control variable naming and added documentation for new methods. - Introduced new functions for generating initial unitary and control trajectories with detailed docstrings.
* update readme for docs building instructions * use new docs CI separate from rest * use PiccoloDocsTemplate * minor docs fixes --------- Co-authored-by: Gennadi Ryan <gennadiryan@gmail.com> Co-authored-by: Gennadi Ryan <41800392+gennadiryan@users.noreply.github.com>
* feat: add julia 1.12 to test matrix and update compat * chore: use 'pre' Julia version in nightly.yml
- Updated all manual pages and examples to use u, du, ddu naming - Changed .trajectory.a → .trajectory.u - Updated function parameters: a_bound → u_bound, da_bound → du_bound, etc. - Updated regularizers: R_a → R_u, R_da → R_du, R_dda → R_ddu - Updated math notation in index.md: a_t → u_t - Consistent with source code refactoring
- Created comprehensive comparison table of all 8 problem templates - Added selection guide for choosing the right template - Documented key differences: Unitary vs Ket, Smooth vs MinTime, etc. - Listed common parameters with examples - Updated make.jl to include overview as first manual page
- Created "Working with Solutions" guide covering: * Solving problems with solve!() options * Extracting controls, states, and time data * Fidelity evaluation (direct vs rollout) * Saving/loading trajectories * Post-processing and exporting for experiments * Best practices and debugging tips - Created "PiccoloOptions Reference" documenting: * All available options with examples * Common configuration patterns * Leakage suppression setup * When to use bound_state, geodesic, etc. * Tips and tricks for each option - Updated docs structure to include new manual pages
- Updated QuantumSystem constructors to include required T_max and drive_bounds - Updated VariationalQuantumSystem constructor with required parameters - Simplified solve!() calls (removed verbose and print_level to avoid issues) - Fixed all driftless_system instantiations in examples - Ensures all code blocks execute without UndefVarError or MethodError
- Added required T_max (10.0) and drive_bounds ([1.0, 1.0]) parameters - Updated all QuantumSystem calls with drift Hamiltonian - Fixed in: ket_problem_templates, unitary_problem_templates, working_with_solutions, and piccolo_options - Matches updated PiccoloQuantumObjects API signature
- Use EmbeddedOperator for matrix goals with QuantumSystem - Changed (system, matrix, T, Δt) → (system, EmbeddedOperator(matrix, system), T) - Removed Δt parameter (not used in current API, calculated from T and T_max) - Fixed in ket_problem_templates, unitary_problem_templates, working_with_solutions, and piccolo_options - Matches actual function signatures in problem templates
…jectory strategies
…riationalProblem examples
…moothPulseProblem examples for consistency
- Add unitary_trajectory(sys, U_goal, N) for unitary gate synthesis
- Takes goal unitary as positional arg, initial defaults to identity
- Supports geodesic interpolation and custom timestep bounds
- Add ket_trajectory(sys, ψ_init(s), ψ_goal(s), N) for quantum state transfer
- Supports single state or multiple states with shared controls
- Auto-generates state names (:ψ̃1, :ψ̃2) or accepts custom names
- Convenience constructor for single state: ket_trajectory(sys, ψ_init, ψ_goal, N)
- Add density_trajectory(sys, ρ_init, ρ_goal, N) for open system evolution
- Direct positional arguments for initial and goal density matrices
All functions:
- Accept Δt_min and Δt_max kwargs for timestep bounds
- Support free_time flag to toggle between variable/fixed timesteps
- Build NamedTrajectory directly without calling existing initialize_trajectory
- Properly convert sys.drive_bounds from Vector{Tuple} to (lower, upper) format
Added comprehensive tests for all functions including:
- Default parameters
- Fixed vs free time
- Custom timestep bounds
- Multiple states (for ket_trajectory)
- Custom state names
- Introduced the `QuantumTrajectories` module with three main trajectory types: `UnitaryTrajectory`, `KetTrajectory`, and `DensityTrajectory`. - Each trajectory type encapsulates quantum-specific metadata and provides high-level constructors for easy initialization. - Implemented accessor functions for trajectory properties and integrated with existing quantum systems. - Added tests for each trajectory type to ensure correct functionality and integration with quantum systems. - Created a new test suite for default integrators and smooth pulse problems, demonstrating the use of the new trajectory types.
- Implemented UnitaryMinimumTimeProblem for minimum-time unitary control optimization. - Developed UnitarySamplingProblem for robust control pulse generation across multiple quantum systems. - Created UnitarySmoothPulseProblem for free-time unitary gate problems with smooth control pulses. - Introduced UnitaryVariationalProblem for optimizing quantum control trajectories with variational parameters. - Added QuantumControlProblem wrapper to combine quantum trajectory information with optimization problems. - Included comprehensive documentation for each problem type and their respective arguments. - Implemented tests for various problem scenarios to ensure functionality and correctness. - Updated test_load.jl to verify the availability of new problem types in the QuantumCollocation module.
…jective type check in SmoothPulseProblem tests; add empty sampling_problem.jl file
…and Clarity - Updated SmoothPulseProblem to streamline control derivative handling and integrate new PiccoloQuantumObjects functions. - Improved integrator initialization logic to support both single and multiple integrators more intuitively. - Added support for SamplingTrajectory and EnsembleTrajectory in BilinearIntegrator, allowing for dynamic handling of multiple systems and state variables. - Introduced new KetInfidelityObjective variants to accommodate shared goals across multiple state variables in ensemble contexts. - Enhanced tests for various trajectory types, ensuring robust validation of integrator functionality and objective definitions.
…ing objectives for DensityTrajectory
…g the control problem
…ation features - Removed T_max parameter from QuantumSystem constructions in smooth pulse problems. - Updated SplinePulseProblem to support spline-based pulse optimization with detailed documentation. - Introduced robust control optimization using SamplingProblem for parameter uncertainty. - Added comprehensive tests for control scaling in SmoothPulseProblem with both KetTrajectory and UnitaryTrajectory. - Enhanced context documentation for QuantumCollocation.jl, detailing workflows and key abstractions.
…m/harmoniqs/QuantumCollocation.jl into feature/problem-template-redesign
…ry in MinimumTimeProblem
- Updated references from EnsembleKetTrajectory to MultiKetTrajectory across multiple files. - Enhanced SmoothPulseProblem and SplinePulseProblem to accommodate the new trajectory type. - Modified fidelity and constraint functions to work with MultiKetTrajectory. - Improved documentation to reflect changes in trajectory handling. - Removed deprecated test file for control scaling integration tests. - Adjusted test cases to validate functionality with MultiKetTrajectory.
- Bump DirectTrajOpt compatibility from 0.7 to 0.8 - Update PiccoloQuantumObjects compatibility from 0.9 to 0.10 - Add global parameter update functionality in sync_trajectory! function - Remove obsolete test scripts for integrators and quantum trajectories
Contributor
There was a problem hiding this comment.
Pull request overview
This pull request introduces a major refactor to QuantumCollocation.jl, modernizing the API and improving documentation. The changes remove deprecated arguments from QuantumSystem constructors (notably T_max and Δt), introduce new problem templates with cleaner abstractions (QuantumControlProblem, SmoothPulseProblem, SplinePulseProblem), and add comprehensive documentation including a new CONTEXT.md file and literate examples for minimum time optimization.
Changes:
- Removed deprecated
T_maxand time-dependent flags fromQuantumSystemconstructors across test files and examples - Introduced new problem template architecture with
QuantumControlProblemwrapper - Added coherent ket fidelity objectives and constraints for multi-state optimization
- Refactored integrators to use dispatch-based construction
- Consolidated problem templates (deleted old templates, added unified
SmoothPulseProblemandSplinePulseProblem) - Added comprehensive documentation for robust control, working with solutions, and problem template selection
Reviewed changes
Copilot reviewed 46 out of 47 changed files in this pull request and generated no comments.
Show a summary per file
| File | Description |
|---|---|
| test/test_utils.jl | Removed deprecated T_max argument from QuantumSystem constructor calls |
| test/scripts/*.jl | Deleted obsolete integrator test scripts |
| test/runtests.jl | Added filter to exclude experimental tests |
| src/trajectory_initialization.jl | Deleted - functionality moved to PiccoloQuantumObjects |
| src/quantum_system_templates/*.jl | Deleted - templates moved to PiccoloQuantumObjects |
| src/quantum_objectives.jl | Added CoherentKetInfidelityObjective for phase-aligned multi-state optimization |
| src/quantum_integrators.jl | Refactored to dispatch-based construction pattern with BilinearIntegrator |
| src/quantum_control_problem.jl | New - Wrapper type combining quantum trajectory with optimization problem |
| src/quantum_constraints.jl | Added FinalCoherentKetFidelityConstraint |
| src/problem_templates/*.jl | Major refactor - deleted old templates, added SmoothPulseProblem, SplinePulseProblem, MinimumTimeProblem, SamplingProblem |
| src/QuantumCollocation.jl | Updated module structure, removed reexport of DirectTrajOpt |
| docs/*.md | Added comprehensive documentation and new literate examples |
| Project.toml | Updated dependency versions (DirectTrajOpt 0.8, PiccoloQuantumObjects 0.10) |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This pull request introduces extensive documentation improvements and updates to QuantumCollocation.jl, focusing on clarifying canonical workflows, problem templates, and recent API changes. The changes include a new comprehensive
CONTEXT.mdfile, updated example scripts to match the latest API (removing deprecated arguments and patterns), and a new literate example for minimum time optimization. These updates ensure consistency, modern usage, and clearer guidance for users and developers.Major documentation and example updates:
General documentation and context:
CONTEXT.mdfile outlining package purpose, canonical workflows, key abstractions, best practices, recent changes, and common pitfalls. This serves as a central reference for the package's structure and usage.API modernization and example consistency:
T_maxandΔtinQuantumSystemand problem constructors), ensuring that system and problem construction follows the latest conventions (e.g., always including:tin trajectories, usingdrive_bounds, and not passing time-dependent flags). [1] [2] [3] [4] [5] [6]New and improved examples:
minimum_time_problem.jldemonstrating how to solve minimum time quantum control problems, including visualization and tradeoff analysis between fidelity and duration.These changes significantly improve the clarity, usability, and maintainability of the documentation and examples, aligning them with the latest package design and best practices.