API reference

Paper notation

The notation follows that of the reference paper for the DiSLOU method.

CodePaper 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.expectAverage $⟨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 hysteresis times 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_tolerance of the layer3_sizes slowest 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}$, a QuantumObject operator.
  • ψ0: Initial state, a QuantumObject ket. As in mcsolve, 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 × Ng matrix of shifts $\zeta_\mu^{(g)}$, with one row per collapse operator and one column per gauge, or the result of discover_gauges.
  • hysteresis: The threshold $\eta \in (0, 1]$ for switching gauge. Default 0.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. Default nothing, 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. Default 1e-3.
  • kwargs: Keyword arguments of mcsolve, such as e_ops, ntraj, rng, ensemblealg, saveat, keep_runs_results, progress_bar or callback.

Notes

  • After a user callback changes 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 of saveat: elsewhere integrator.u can hold coordinates on the slow modes instead of the state (see below). Otherwise, disable Layer III with layer3_sizes = nothing.
  • dislou_solve sets the alg of mcsolve itself.
  • 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_solve warns 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 below residual_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, or integrator(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.expect is an empty matrix instead of nothing.

Returns

  • sol::TimeEvolutionMCSol: the result of mcsolve.

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)
true
source
DiSLOUTrajectories.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.

Note

Jump location and saving are supported only during integration. Post-solve interpolation of a direct ODE solution, such as sol(t) between saved times, is unsupported. Request the required times through saveat.

Warning

The algorithm never evaluates the ODE function. It must be built from the same H and c_ops that are given to mcsolve.

source

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 a QuantumToolbox.QuantumObject operator. Its tensor dimensions must match mode_dims. This method uses QuantumToolbox's mcsolve for the preliminary trajectories.
  • c_ops: Vector of time-independent QuantumToolbox.QuantumObject collapse operators with the same tensor dimensions as H. 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 as H, and mode_ops[j] must act on the j-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 of H.
  • 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 to discovery_time / 40. The endpoint discovery_time is always included.
  • nseeds::Int: Positive number of initial coherent product states, with one trajectory per state. Defaults to 600.
  • terminal_window: Finite, nonnegative duration at the end of the run over which sampled mode, occupation, and collapse expectations are averaged. Defaults to 0.0, which uses the final sample. Values greater than discovery_time use 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 to nothing, 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 to 1.5.
  • min_neighbors::Int: Positive DBSCAN core-point threshold: the number of points within dbscan_radius, the point itself included. Defaults to 10.
  • min_weight: Minimum retained cluster population as a fraction of all nseeds samples. Must be finite and in [0, 1); defaults to 0.02.
  • rng::AbstractRNG: Random number generator for the initial amplitudes and the preliminary trajectory streams. Defaults to Random.default_rng().
  • save_preliminary_trajectories::Int: Nonnegative number of preliminary trajectories whose state, expectation, and jump traces are retained in the diagnostics. Defaults to 0; values above nseeds retain all trajectories.
  • ensemblealg: How the preliminary trajectories run: EnsembleThreads() (default), EnsembleSerial(), or EnsembleDistributed(). 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 as a^2 or a' * a.
  • method::Symbol: Set to :semiclassical.
  • limits: Nonempty tuple or vector of positive, finite occupation bounds, one per mode. Accepted fixed points satisfy abs2(α[m]) ≤ limits[m] up to numerical tolerance. These bounds define the search region, and they should stay a few standard deviations √limits[m] below mode_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(), or EnsembleDistributed(). Distributed execution requires worker processes with DiSLOUTrajectories loaded.

Notes

  • The two methods have separate keyword sets. Arbitrary mcsolve or 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 for m modes, so it can miss roots and its cost grows rapidly with the number of modes. It uses the truncated matrices of H and c_ops, which reproduce the mean-field equations only while the occupations stay well below the cutoffs.
  • Discovery raises an ArgumentError if no trajectory cluster or stable semiclassical fixed point is retained.

Returns

  • gauges::NamedTuple: (; shifts, method, centers, weights, diagnostics). With Nc collapse channels, Nm modes, and Ng retained gauges:
    • shifts::Matrix{ComplexF64}: Nc × Ng shifts ζ_μ^(g); column g defines C_μ^(g) = C_μ + ζ_μ^(g) I (Eq. 9) for each channel μ.
    • method::Symbol: :trajectories or :semiclassical.
    • centers::Matrix{ComplexF64}: Nm × Ng cluster-mean mode amplitudes or stable fixed-point amplitudes.
    • weights::Vector{Float64}: Ng cluster population fractions, as described above, or the uniform weights 1/Ng of the semiclassical method.
    • diagnostics::NamedTuple: Method-specific discovery data described below.

For trajectory discovery, diagnostics contains:

  • counts and labels: Cluster sizes of length Ng and assignments of length nseeds. Positive labels index columns of centers.
  • terminal_means and terminal_occupations: Nm × nseeds terminal-window averages of mode amplitudes and occupations.
  • terminal_collapse_means: Nc × nseeds terminal-window averages of the physical collapse-operator expectations.
  • times: Preliminary observation grid, including zero and discovery_time.
  • preliminary_traces: (; indices, states, means, occupations) for the retained preliminary runs. indices contains their one-based seed indices; the other fields are vectors of matrices. For Nt = length(times) and N = prod(mode_dims), each state matrix is N × Nt, and each mode-mean or occupation matrix is Nm × Nt. These vectors are empty by default.
  • preliminary_jump_times and preliminary_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, and ensemblealg. The save_preliminary_trajectories field records the retained count, capped at nseeds.

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 of roots. max_real_eigenvalue is the largest real part of the Jacobian eigenvalues, and residual is the norm of the mean-field drift.
  • rejected: Matrix of the unstable fixed points excluded from centers.
  • stable: Boolean vector of length Ng, with every entry true.
source

Package information

DiSLOUTrajectories.cite — Function
DiSLOUTrajectories.cite(io::IO = stdout)

Command line output of the BibTeX entry for the DiSLOUTrajectories.jl publication.

source