API reference
Paper notation
The notation follows that of the reference paper for the DiSLOU method.
| Code | Paper quantity |
|---|---|
gauge_set[μ, g] or gauges.shifts[μ, g] | $ζ_μ^{(g)}$ (Eq. 9) |
hysteresis | $η$ (Eq. 13) |
layer3_sizes[g] | Requested $m^{(g)}$; degenerate modes can increase it (Eq. 20) |
residual_tolerance | $r_{tol}$, applied to $r_m^{(g)}(ψ)$ for normalized states (Eq. 21) |
average_states(sol) | Averaged density matrices $ρ_{MC}(t)$ at sol.times_states (Section 4.1) |
sol.expect | Average $⟨O⟩(t)$ |
With keep_runs_results = Val(false) (the default), sol.states[time] contains the density matrices. With keep_runs_results = Val(true), sol.states[trajectory, time] contains a ket for each trajectory and saved time. average_states(sol) returns the averaged density matrices in either case.
Solver
DiSLOUTrajectories.dislou_solve — Function
dislou_solve(H, ψ0, tlist, c_ops; gauge_set, <keyword arguments>)Quantum trajectories of the time-independent Lindblad equation
\[\frac{d\hat{\rho}}{dt} = -i[\hat{H}, \hat{\rho}] + \sum_\mu \left( \hat{C}_\mu \hat{\rho} \hat{C}_\mu^\dagger - \frac{1}{2} \{\hat{C}_\mu^\dagger \hat{C}_\mu, \hat{\rho}\} \right),\]
with the Diagonal, Switching, and Locally Optimal Unraveling (DiSLOU). The trajectories are run by QuantumToolbox's mcsolve, which receives all the other keyword arguments and returns its usual TimeEvolutionMCSol.
A gauge $g$ (column g of gauge_set) shifts the collapse operators and the Hamiltonian without changing the master equation (Eq. 9):
\[\hat{C}_\mu^{(g)} = \hat{C}_\mu + \zeta_\mu^{(g)}, \qquad \hat{H}^{(g)} = \hat{H} + \frac{i}{2} \sum_\mu \left( \zeta_\mu^{(g)} \hat{C}_\mu^\dagger - \zeta_\mu^{(g)*} \hat{C}_\mu \right).\]
- Layer I: each trajectory starts in the gauge with the lowest jump activity $A_g(\psi) = \sum_\mu \| \hat{C}_\mu^{(g)} \psi \|^2$. After each jump, it moves to the least active gauge if that activity is below
hysteresistimes the current one (Eqs. 11–13). - Layer II: between jumps, the state evolves exactly in the eigenbasis of the effective Hamiltonian of the gauge, with
GaugeEigenExponential. Jump times are found by root finding on this exact solution. - Layer III (optional): after a jump, a state within
residual_toleranceof thelayer3_sizesslowest eigenmodes of its gauge is projected on them, and evolves in that smaller basis until the next jump (Eqs. 20–21).
Arguments
H: Time-independent Hamiltonian $\hat{H}$, aQuantumObjectoperator.ψ0: Initial state, aQuantumObjectket. As inmcsolve, it is not normalized.tlist: Times at which the expectation values are computed.c_ops: Nonempty vector of time-independent collapse operators $\hat{C}_\mu$.gauge_set:Nc × Ngmatrix of shifts $\zeta_\mu^{(g)}$, with one row per collapse operator and one column per gauge, or the result ofdiscover_gauges.hysteresis: The threshold $\eta \in (0, 1]$ for switching gauge. Default0.5.layer3_sizes: Number of slow modes kept for Layer III, one integer for all gauges or one per gauge. Modes degenerate with the kept ones are added. Defaultnothing, which disables Layer III.residual_tolerance: Largest relative distance $r_{\rm tol} \in (0, 1)$ of the state from the slow modes for Layer III. Default1e-3.kwargs: Keyword arguments ofmcsolve, such ase_ops,ntraj,rng,ensemblealg,saveat,keep_runs_results,progress_barorcallback.
Notes
- After a user
callbackchanges the state, the next step chooses the gauge and, with Layer III, the basis again from the new state. With Layer III, such a callback must act at times where the state is saved, for example times ofsaveat: elsewhereintegrator.ucan hold coordinates on the slow modes instead of the state (see below). Otherwise, disable Layer III withlayer3_sizes = nothing. dislou_solvesets thealgofmcsolveitself.- Jump records (
col_times,col_which) refer to the shifted operators of the gauge that was active at each jump. - Layers I and II are exact up to floating-point errors, which grow with the condition number of the eigenvectors of each effective Hamiltonian.
dislou_solvewarns when half of the digits can be lost, and throws when an effective Hamiltonian is not diagonalizable. Layer III replaces the state by its projection after each accepted jump, an error belowresidual_tolerance. - On the $m$ slow modes of Layer III, a trajectory stores its state as its coordinates on these modes, followed by zeros, except at the times where the state is saved. The steps, jumps and expectation values then take $O(m^2)$ operations instead of $O(N m)$. A callback that reads
integrator.u, orintegrator(t), gets these coordinates. - Each gauge is diagonalized once, which takes $O(N^3)$ time and $O(N^2)$ memory for an $N$-dimensional Hilbert space. With
e_ops = nothing,sol.expectis an empty matrix instead ofnothing.
Returns
sol::TimeEvolutionMCSol: the result ofmcsolve.
Examples
A driven cavity relaxes to the coherent state $|\alpha\rangle$. With a gauge centered on it, jumps become rare while the photon number follows the exact result:
julia> using QuantumToolbox, DiSLOUTrajectories
julia> N, κ, α = 15, 1.0, 1.0;
julia> a = destroy(N);
julia> H = 0.5im * κ * (α * a' - conj(α) * a);
julia> tlist = 0:0.5:5;
julia> sol = dislou_solve(H, fock(N, 0), tlist, [sqrt(κ) * a];
gauge_set = fill(-sqrt(κ) * α, 1, 1), e_ops = [a' * a], ntraj = 20,
progress_bar = Val(false));
julia> isapprox(real(sol.expect[1, :]), abs2.(α .* (1 .- exp.(-κ .* tlist ./ 2))); atol = 1e-6)
trueDiSLOUTrajectories.GaugeEigenExponential — Type
GaugeEigenExponential(H, c_ops)Exact propagator for the no-jump evolution of mcsolve with a time-independent Hamiltonian H and collapse operators c_ops:
\[|\psi(t + \tau)\rangle = e^{-i H_{\rm eff} \tau} |\psi(t)\rangle = V e^{\Lambda \tau} V^{-1} |\psi(t)\rangle, \qquad H_{\rm eff} = H - \frac{i}{2} \sum_\mu C_\mu^\dagger C_\mu .\]
The decomposition $-i H_{\rm eff} = V \Lambda V^{-1}$ is computed once. Each step, and each evaluation of the dense output used to locate the jumps and to save results, is exact, so steps can be as long as the time between jumps. The arrays follow those of H and c_ops: with GPU operators, for example, the decomposition and the propagation run on the GPU.
Pass it to mcsolve together with the same H and c_ops, which it also uses for the jumps, and with the times of tlist as stops. mcsolve computes the expectation values at these times after the jumps of their step, which can change the basis of the dense output, so they must be step ends. The stops also shorten the search for each jump:
mcsolve(H, ψ0, tlist, c_ops; alg = GaugeEigenExponential(H, c_ops), tstops = tlist)dislou_solve builds it with one eigenbasis per gauge, plus the slow modes of Layer III when requested. Each trajectory then switches gauge and basis at its jumps.
Examples
dislou_solve accepts the keyword arguments of QuantumToolbox's mcsolve and returns its TimeEvolutionMCSol. Here the states are saved at two times, and the results of every trajectory are kept so that their spread can be computed.
using QuantumToolbox, DiSLOUTrajectories, Random
N, κ, α = 15, 1.0, 1.0
a = destroy(N)
H = 0.5im * κ * (α * a' - conj(α) * a)
tlist = 0:0.5:10
sol = dislou_solve(H, fock(N, 0), tlist, [sqrt(κ) * a];
gauge_set = fill(-sqrt(κ) * α, 1, 1), e_ops = [a' * a],
ntraj = 50, rng = Xoshiro(1), saveat = [5.0, 10.0],
keep_runs_results = Val(true), progress_bar = Val(false))
(size(sol.expect), size(sol.states), length(average_states(sol)), size(std_expect(sol)))
# output
((1, 50, 21), (50, 2), 2, (1, 21))Gauge discovery
DiSLOUTrajectories.discover_gauges — Function
discover_gauges(H, c_ops; <keyword arguments>)Discover the gauge shifts ζ_μ^(g) (Eq. 9) for dislou_solve.
The default method=:trajectories clusters terminal amplitudes from preliminary quantum trajectories. With method=:semiclassical, it instead finds the stable fixed points of the mean-field equations of the bosonic modes.
See also dislou_solve.
Examples
Find the single vacuum gauge of a damped mode with trajectory discovery:
julia> using DiSLOUTrajectories, QuantumToolbox
julia> a = destroy(2);
julia> gauges = discover_gauges(0.0 * a, [a];
mode_ops = [a], mode_dims = [2], discovery_time = 1.0,
seed_radii = [0.0], cluster_scales = [1.0], step = 1.0,
nseeds = 2, min_neighbors = 1, min_weight = 0.0);
julia> (gauges.method, size(gauges.shifts), all(iszero, gauges.shifts))
(:trajectories, (1, 1), true)Find the same vacuum fixed point from the mean-field equations:
julia> using DiSLOUTrajectories, QuantumToolbox
julia> a = destroy(6);
julia> gauges = discover_gauges(a' * a, [a];
method = :semiclassical, mode_ops = [a], mode_dims = [6], limits = (1.0,));
julia> (gauges.method, size(gauges.shifts), all(z -> abs(z) < 1e-9, gauges.shifts))
(:semiclassical, (1, 1), true)Extended help
Trajectory discovery starts in random coherent product states. Each retained cluster defines shifts from the negative cluster averages of the physical collapse-operator expectations. Semiclassical discovery solves the first-order mean-field equations dα_j/dt = ⟨α|L†(a_j)|α⟩ = 0 for the amplitudes α of the modes, where |α⟩ is a coherent product state and L†(a_j) = i[H, a_j] + Σ_μ (C_μ† a_j C_μ - {C_μ†C_μ, a_j} / 2) is the Heisenberg-picture generator. It keeps the stable solutions and evaluates the collapse-operator expectations ⟨α|C_μ|α⟩ at them. The operators are the truncated matrices of H and c_ops, so the occupations of the solutions must stay well below the Fock cutoffs.
Arguments
The accepted arguments depend on method. The trajectory method is the default; the semiclassical method must be selected explicitly.
Trajectory discovery
H: Time-independent Hermitian Hamiltonian as aQuantumToolbox.QuantumObjectoperator. Its tensor dimensions must matchmode_dims. This method uses QuantumToolbox'smcsolvefor the preliminary trajectories.c_ops: Vector of time-independentQuantumToolbox.QuantumObjectcollapse operators with the same tensor dimensions asH. Include the square root of each physical decay rate in the corresponding operator.method::Symbol: Set to:trajectories(the default).mode_ops: Nonempty collection of bosonic annihilation operators, embedded in the full tensor-product Hilbert space. Each operator must have the same dimensions asH, andmode_ops[j]must act on thej-th tensor factor. Their order defines the rows of the returned centers.mode_dims: One integer Hilbert-space truncation dimension per mode, in tensor-product order. Together they must span the whole space ofH.discovery_time: Positive, finite duration of each preliminary trajectory, which starts at time zero.seed_radii: One finite, nonnegative coherent-amplitude radius per mode. Initial amplitudes are sampled uniformly in each complex disk.cluster_scales: Vector of positive, finite amplitude scales, one per mode. Real and imaginary parts of each terminal mode mean are divided by its scale before Euclidean DBSCAN clustering.step: Positive, finite spacing of the preliminary observation grid. Defaults todiscovery_time / 40. The endpointdiscovery_timeis always included.nseeds::Int: Positive number of initial coherent product states, with one trajectory per state. Defaults to600.terminal_window: Finite, nonnegative duration at the end of the run over which sampled mode, occupation, and collapse expectations are averaged. Defaults to0.0, which uses the final sample. Values greater thandiscovery_timeuse the whole observation grid.preliminary_shifts: Optional vector of finite complex shifts, one per collapse channel, applied during the preliminary runs with a compensating Hamiltonian shift. Defaults tonothing, meaning zero shifts. Returned gauges use expectations of the original physical collapse operators.dbscan_radius: Positive, finite DBSCAN neighborhood radius in the scaled real-imaginary feature space. Defaults to1.5.min_neighbors::Int: Positive DBSCAN core-point threshold: the number of points withindbscan_radius, the point itself included. Defaults to10.min_weight: Minimum retained cluster population as a fraction of allnseedssamples. Must be finite and in[0, 1); defaults to0.02.rng::AbstractRNG: Random number generator for the initial amplitudes and the preliminary trajectory streams. Defaults toRandom.default_rng().save_preliminary_trajectories::Int: Nonnegative number of preliminary trajectories whose state, expectation, and jump traces are retained in the diagnostics. Defaults to0; values abovenseedsretain all trajectories.ensemblealg: How the preliminary trajectories run:EnsembleThreads()(default),EnsembleSerial(), orEnsembleDistributed(). Distributed execution requires worker processes with DiSLOUTrajectories and QuantumToolbox loaded.
Semiclassical discovery
H,c_ops,mode_ops,mode_dims: As for trajectory discovery. The collapse operators may be nonlinear in the modes, such asa^2ora' * a.method::Symbol: Set to:semiclassical.limits: Nonempty tuple or vector of positive, finite occupation bounds, one per mode. Accepted fixed points satisfyabs2(α[m]) ≤ limits[m]up to numerical tolerance. These bounds define the search region, and they should stay a few standard deviations√limits[m]belowmode_dims[m]; operators of higher degree in the modes need more margin.ensemblealg: How the Newton solves from the grid of starting points run:EnsembleThreads()(default),EnsembleSerial(), orEnsembleDistributed(). Distributed execution requires worker processes with DiSLOUTrajectories loaded.
Notes
- The two methods have separate keyword sets. Arbitrary
mcsolveor ODE solver options are not forwarded. - Trajectory cluster weights are fractions of all preliminary samples, including discarded samples in the denominator. Their sum can be less than one. Clusters are ordered by decreasing weight, then by their centers. Noise points and samples from discarded clusters receive label
0. - Stability of the semiclassical solution is determined from the real mean-field Jacobian. The search starts from a regular grid of
5^(2m)points formmodes, so it can miss roots and its cost grows rapidly with the number of modes. It uses the truncated matrices ofHandc_ops, which reproduce the mean-field equations only while the occupations stay well below the cutoffs. - Discovery raises an
ArgumentErrorif no trajectory cluster or stable semiclassical fixed point is retained.
Returns
gauges::NamedTuple:(; shifts, method, centers, weights, diagnostics). WithNccollapse channels,Nmmodes, andNgretained gauges:shifts::Matrix{ComplexF64}:Nc × Ngshiftsζ_μ^(g); columngdefinesC_μ^(g) = C_μ + ζ_μ^(g) I(Eq. 9) for each channelμ.method::Symbol::trajectoriesor:semiclassical.centers::Matrix{ComplexF64}:Nm × Ngcluster-mean mode amplitudes or stable fixed-point amplitudes.weights::Vector{Float64}:Ngcluster population fractions, as described above, or the uniform weights1/Ngof the semiclassical method.diagnostics::NamedTuple: Method-specific discovery data described below.
For trajectory discovery, diagnostics contains:
countsandlabels: Cluster sizes of lengthNgand assignments of lengthnseeds. Positive labels index columns ofcenters.terminal_meansandterminal_occupations:Nm × nseedsterminal-window averages of mode amplitudes and occupations.terminal_collapse_means:Nc × nseedsterminal-window averages of the physical collapse-operator expectations.times: Preliminary observation grid, including zero anddiscovery_time.preliminary_traces:(; indices, states, means, occupations)for the retained preliminary runs.indicescontains their one-based seed indices; the other fields are vectors of matrices. ForNt = length(times)andN = prod(mode_dims), each state matrix isN × Nt, and each mode-mean or occupation matrix isNm × Nt. These vectors are empty by default.preliminary_jump_timesandpreliminary_jump_channels: Vectors of event-time and one-based collapse-channel vectors for the retained runs.- The resolved discovery settings:
mode_dims,discovery_time,seed_radii,cluster_scales,step,nseeds,terminal_window,preliminary_shifts,dbscan_radius,min_neighbors,min_weight,save_preliminary_trajectories, andensemblealg. Thesave_preliminary_trajectoriesfield records the retained count, capped atnseeds.
For semiclassical discovery, diagnostics contains:
roots: Matrix with one column per distinct fixed point found, including unstable points, and one row per mode.stability: One(; stable, max_real_eigenvalue, residual)record per column ofroots.max_real_eigenvalueis the largest real part of the Jacobian eigenvalues, andresidualis the norm of the mean-field drift.rejected: Matrix of the unstable fixed points excluded fromcenters.stable: Boolean vector of lengthNg, with every entrytrue.
Package information
DiSLOUTrajectories.versioninfo — Function
DiSLOUTrajectories.versioninfo(io::IO = stdout)Command line output of the version of DiSLOUTrajectories.jl, followed by QuantumToolbox.versioninfo, with the dependencies and the system. Same as DiSLOUTrajectories.about.
DiSLOUTrajectories.about — Function
DiSLOUTrajectories.about(io::IO = stdout)Same as DiSLOUTrajectories.versioninfo.
DiSLOUTrajectories.cite — Function
DiSLOUTrajectories.cite(io::IO = stdout)Command line output of the BibTeX entry for the DiSLOUTrajectories.jl publication.