qlinks.open_system package

The open-system package provides Lindblad operators, Liouvillian solvers, Monte-Carlo wavefunction sampling, random state helpers, and dark-state diagnostics. Shared local-RDM and local-operator algebra is owned by qlinks.local_structure; local_recycling contains the Lindblad-specific selection and recycling workflow built on those primitives.

Submodules

qlinks.open_system.backend module

class qlinks.open_system.backend.OpenSystemBackend(name, array_module, sparse_module, sparse_linalg_module, supports_expm_multiply)

Bases: object

Array/sparse backend bundle for open-system solvers.

name

Backend name.

Type:

Literal[‘scipy’, ‘cupy’]

array_module

Dense array module, such as NumPy or CuPy.

Type:

Any

sparse_module

Sparse matrix module.

Type:

Any

sparse_linalg_module

Sparse linear-algebra module, if available.

Type:

Any | None

supports_expm_multiply

Whether the backend can run Krylov expm_multiply evolution.

Type:

bool

name: Literal['scipy', 'cupy']

array_module: Any

sparse_module: Any

sparse_linalg_module: Any | None

supports_expm_multiply: bool

asarray(value, *, dtype=<class 'numpy.complex128'>)

to_numpy(value)

sparse_identity(dim, *, format='csr', dtype=<class 'numpy.complex128'>)

sparse_kron(left, right, *, format='csr')

norm(value)

__init__(name, array_module, sparse_module, sparse_linalg_module, supports_expm_multiply)

qlinks.open_system.backend.get_open_system_backend(backend)

Resolve an open-system backend name or backend object.

Parameters:

backend (Literal['scipy', 'cupy'] | ~qlinks.open_system.backend.OpenSystemBackend) – "scipy", "cupy", or an existing backend object.

Returns:

Backend object used by open-system operators and solvers.

Raises:

• ImportError – If backend="cupy" is requested but CuPy is not installed.

• ValueError – If the backend name is unknown.

Return type:

OpenSystemBackend

qlinks.open_system.backend.as_backend_sparse_matrix(matrix, *, backend, format='csr', dtype=<class 'numpy.complex128'>)

Convert a dense or sparse matrix to a backend sparse matrix.

Parameters:

• matrix (Any) – Input matrix in dense, SciPy sparse, or backend sparse form.

• backend (OpenSystemBackend) – Target backend.

• format (str) – Sparse format requested from the backend.

• dtype – Complex dtype for the converted matrix.

Returns:

Sparse matrix on the requested backend.

qlinks.open_system.backend.as_backend_dense_array(matrix, *, backend, dtype=<class 'numpy.complex128'>)

Convert a dense or sparse matrix to a backend dense array.

Parameters:

• matrix (Any) – Input matrix in dense, SciPy sparse, or backend sparse form.

• backend (OpenSystemBackend) – Target backend.

• dtype – Complex dtype for the converted array.

Returns:

Dense array on the requested backend.

qlinks.open_system.diagnostics module

class qlinks.open_system.diagnostics.EvolutionDiagnostics(trace_errors, hermiticity_errors, min_eigenvalues, purities, fidelities, lindblad_residuals, times=None, source='density_matrices', density_check_mode='full', trajectory_counts=None, state_norm_errors=None)

Bases: object

Diagnostics for density-matrix or MCWF evolution output.

trace_errors

Absolute errors of Tr(rho) from one.

Type:

numpy.ndarray

hermiticity_errors

Frobenius norm of anti-Hermitian parts.

Type:

numpy.ndarray

min_eigenvalues

Smallest density-matrix eigenvalue at each time.

Type:

numpy.ndarray

purities

Tr(rho^2) values.

Type:

numpy.ndarray

fidelities

Optional fidelity with a target state/density matrix.

Type:

numpy.ndarray | None

lindblad_residuals

Optional norm of the Lindblad RHS at each time.

Type:

numpy.ndarray | None

times

Optional time grid.

Type:

numpy.ndarray | None

source

Description of the analyzed data source.

Type:

str

density_check_mode

Density check strategy used by the analyzer.

Type:

str

trajectory_counts

Optional number of trajectories per time point.

Type:

numpy.ndarray | None

state_norm_errors

Optional norm errors for pure-state trajectories.

Type:

numpy.ndarray | None

trace_errors: ndarray

hermiticity_errors: ndarray

min_eigenvalues: ndarray

purities: ndarray

fidelities: ndarray | None

lindblad_residuals: ndarray | None

times: ndarray | None

source: str

density_check_mode: str

trajectory_counts: ndarray | None

state_norm_errors: ndarray | None

__init__(trace_errors, hermiticity_errors, min_eigenvalues, purities, fidelities, lindblad_residuals, times=None, source='density_matrices', density_check_mode='full', trajectory_counts=None, state_norm_errors=None)

qlinks.open_system.diagnostics.target_manifold_projector(target_states, *, tolerance=1e-10)

Return the projector onto a target manifold.

target_states may be one target vector, a (dim, n_states) matrix, or an (n_states, dim) matrix. The columns/rows are orthonormalized before building the projector, so linearly dependent target vectors are harmless.

qlinks.open_system.diagnostics.target_manifold_weight(density_matrix, *, target_states=None, target_basis=None, projector=None, tolerance=1e-10)

Return Tr(P_target rho) for one density matrix.

Pass either target_states/target_basis or an explicit projector. When a target basis is supplied, the computation uses Tr(Q^dagger rho Q) and avoids materializing the full projector.

qlinks.open_system.diagnostics.target_manifold_weight_series(*, density_matrices=None, evolution_result=None, ensemble_result=None, state_snapshots=None, target_states=None, target_basis=None, projector=None, tolerance=1e-10)

Return Tr(P_target rho(t)) for evolution or MCWF output.

Exactly one data source must be supplied: density_matrices, a LindbladEvolutionResult via evolution_result, an EnsembleResult via ensemble_result, or MCWF state_snapshots. For state snapshots, each snapshot is expected to be a (dim, n_trajectories) state matrix and the returned weight is the trajectory average of <psi|P_target|psi>.

qlinks.open_system.diagnostics.target_manifold_density_matrix(density_matrix, *, target_states=None, target_basis=None, normalize=True, tolerance=1e-10)

Return the density matrix reduced to the target manifold basis.

The returned matrix is Q^dagger rho Q where columns of Q are an orthonormal target basis. When normalize=True this is conditioned on being in the manifold by dividing by Tr(Q^dagger rho Q). If the weight is numerically zero, the unnormalized zero matrix is returned.

qlinks.open_system.diagnostics.target_manifold_density_matrix_series(*, density_matrices=None, evolution_result=None, ensemble_result=None, state_snapshots=None, target_states=None, target_basis=None, normalize=True, tolerance=1e-10)

Return Q^dagger rho(t) Q for a target manifold basis.

The result has shape (n_times, manifold_dimension, manifold_dimension). With normalize=True each time slice is conditioned by its target-manifold weight, i.e. it is divided by Tr(P_target rho(t)) when the weight is nonzero.

qlinks.open_system.diagnostics.target_manifold_populations_series(**kwargs)

Return diagonal populations of the target-manifold density matrices.

qlinks.open_system.diagnostics.target_manifold_coherence_series(*, norm='fro', **kwargs)

Return off-diagonal coherence of target-manifold density matrices.

norm="fro" returns the Frobenius norm of off-diagonal entries, while norm="l1" returns their elementwise absolute sum.

qlinks.open_system.diagnostics.target_manifold_purity_series(**kwargs)

Return Tr(rho_target(t)^2) for target-manifold density matrices.

qlinks.open_system.diagnostics.target_manifold_entropy_series(*, base=None, tolerance=1e-12, **kwargs)

Return von Neumann entropy of target-manifold density matrices.

The input density matrices are usually conditioned by leaving normalize=True in kwargs. Eigenvalues below tolerance are ignored in the logarithm.

qlinks.open_system.diagnostics.jump_activity(density_matrix, jumps)

Return total Lindblad jump activity sum_mu Tr(J_mu^dag J_mu rho).

qlinks.open_system.diagnostics.jump_activity_series(*, jumps, density_matrices=None, evolution_result=None, ensemble_result=None, state_snapshots=None)

Return total jump activity for each time point.

For density matrices this evaluates sum_mu Tr(J_mu^dagger J_mu rho(t)). For MCWF state snapshots it returns the trajectory average of sum_mu ||J_mu |psi(t)>||^2.

class qlinks.open_system.diagnostics.JumpSpanDiagnostics(dim, n_jumps, span_rank, dependent_jump_count, compression_ratio, rank_tolerance, absolute_rank_threshold, gram_eigenvalues, effective_rank, participation_rank, total_jump_nnz, span_matrix_nnz, max_normalized_overlap, mean_normalized_overlap)

Bases: object

Hilbert-Schmidt span diagnostics for a Lindblad jump list.

dim: int

n_jumps: int

span_rank: int

dependent_jump_count: int

compression_ratio: float

rank_tolerance: float

absolute_rank_threshold: float

gram_eigenvalues: ndarray

effective_rank: float

participation_rank: float

total_jump_nnz: int | None

span_matrix_nnz: int | None

max_normalized_overlap: float

mean_normalized_overlap: float

property has_exact_dependencies: bool

to_summary_dict(*, n_eigenvalues=8)

Return a compact JSON-friendly benchmark summary.

__init__(dim, n_jumps, span_rank, dependent_jump_count, compression_ratio, rank_tolerance, absolute_rank_threshold, gram_eigenvalues, effective_rank, participation_rank, total_jump_nnz, span_matrix_nnz, max_normalized_overlap, mean_normalized_overlap)

qlinks.open_system.diagnostics.diagnose_jump_span(jumps, *, rank_tolerance=1e-10)

Diagnose exact/near linear dependencies among jump operators.

The jump-operator span is measured in the Hilbert-Schmidt inner product, <J_i, J_j> = Tr(J_i† J_j). The rank of this Gram matrix is the number of independent jump directions. If this rank is much smaller than the raw number of jumps, a future compression pass can rotate/drop jumps before MCWF sampling without changing the Lindblad dissipator.

qlinks.open_system.diagnostics.analyze_lindblad_evolution(density_matrices=None, *, ensemble_result=None, state_snapshots=None, trajectories=None, times=None, target_state=None, hamiltonian=None, jumps=None, atol=1e-10, backend='scipy', density_check_mode='auto')

Analyze diagnostics along Lindblad or MCWF evolution output.

The function accepts dense density matrices directly, but it can also read MCWF ensemble outputs. When an ensemble stores low-rank state snapshots but not rho_t, diagnostics can be computed without materializing dense density matrices unless density_check_mode="full" is requested.

Parameters:

• density_matrices (Sequence[Any] | None) – Optional sequence of density matrices.

• ensemble_result (Any | None) – Optional MCWF ensemble result. The analyzer prefers populated rho_t, then state_snapshots, then stored trajectories.

• state_snapshots (Sequence[Any] | None) – Optional sequence of matrices with shape (dim, n_trajectories).

• trajectories (Sequence[Any] | None) – Optional trajectory results with stored states.

• times (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None) – Optional time grid.

• target_state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None) – Optional pure state for fidelity diagnostics.

• hamiltonian – Optional Hamiltonian for Lindblad residual diagnostics.

• jumps – Optional jump operators for Lindblad residual diagnostics.

• atol (float) – Numerical tolerance for density-matrix checks.

• backend (Literal['scipy', 'cupy'] | ~qlinks.open_system.backend.OpenSystemBackend) – Open-system backend name or object.

• density_check_mode (str) – "auto", "full", or "low_rank". "low_rank" avoids materializing density matrices from MCWF snapshots and reports NaN for minimum eigenvalues.

Returns:

Evolution diagnostics arrays.

Return type:

EvolutionDiagnostics

class qlinks.open_system.diagnostics.DensityMatrixVerification(trace, trace_error, hermiticity_error, min_eigenvalue, purity, fidelity_with_target, is_hermitian, is_trace_one, is_positive_semidefinite, is_density_matrix)

Bases: object

Numerical checks for a candidate density matrix.

trace

Matrix trace.

Type:

complex

trace_error

Absolute error of the trace from one.

Type:

float

hermiticity_error

Frobenius norm of rho - rho^dagger.

Type:

float

min_eigenvalue

Smallest Hermitian eigenvalue after symmetrization.

Type:

float

purity

Tr(rho^2).

Type:

float

fidelity_with_target

Optional fidelity <psi|rho|psi>.

Type:

float | None

is_hermitian

Whether the Hermiticity check passes.

Type:

bool

is_trace_one

Whether the trace-one check passes.

Type:

bool

is_positive_semidefinite

Whether the minimum eigenvalue is above -atol.

Type:

bool

is_density_matrix

Combined validity flag.

Type:

bool

trace: complex

trace_error: float

hermiticity_error: float

min_eigenvalue: float

purity: float

fidelity_with_target: float | None

is_hermitian: bool

is_trace_one: bool

is_positive_semidefinite: bool

is_density_matrix: bool

__init__(trace, trace_error, hermiticity_error, min_eigenvalue, purity, fidelity_with_target, is_hermitian, is_trace_one, is_positive_semidefinite, is_density_matrix)

qlinks.open_system.diagnostics.verify_density_matrix(rho, *, target_state=None, atol=1e-10)

Check whether an array is a valid density matrix.

Parameters:

• rho (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Candidate density matrix.

• target_state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None) – Optional pure state used to compute <psi|rho|psi>.

• atol (float) – Absolute tolerance for trace, Hermiticity, and positivity checks.

Returns:

Verification record with scalar diagnostics and boolean flags.

Raises:

ValueError – If rho is not square or target_state is invalid.

Return type:

DensityMatrixVerification

class qlinks.open_system.diagnostics.LindbladFinalStateVerification(density_matrix, lindblad_residual, relative_lindblad_residual)

Bases: object

Verification of a final Lindblad density matrix.

density_matrix

Basic density-matrix validity diagnostics.

Type:

qlinks.open_system.diagnostics.DensityMatrixVerification

lindblad_residual

Norm of the Lindblad RHS evaluated at the final state.

Type:

float

relative_lindblad_residual

Residual normalized by the density-matrix norm scale.

Type:

float

density_matrix: DensityMatrixVerification

lindblad_residual: float

relative_lindblad_residual: float

__init__(density_matrix, lindblad_residual, relative_lindblad_residual)

qlinks.open_system.diagnostics.verify_lindblad_final_state(rho, *, hamiltonian, jumps, target_state=None, atol=1e-10, backend='scipy')

Verify density-matrix validity and Lindblad stationarity.

Parameters:

• rho (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Candidate final density matrix.

• hamiltonian (Any) – Hamiltonian matrix.

• jumps (list[Any] | tuple[Any, ...]) – Lindblad jump operators.

• target_state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None) – Optional pure state for fidelity diagnostics.

• atol (float) – Absolute tolerance passed to verify_density_matrix().

• backend (Literal['scipy', 'cupy'] | ~qlinks.open_system.backend.OpenSystemBackend) – Open-system backend name or object.

Returns:

Final-state verification record.

Return type:

LindbladFinalStateVerification

class qlinks.open_system.diagnostics.MonitorKernelClosureDiagnostics(dim, n_monitors, closure_order, max_target_monitor_residual, target_monitor_residuals, monitor_kernel_dimension, target_projection_onto_monitor_kernel, target_distance_from_monitor_kernel, target_in_monitor_kernel, bad_monitor_kernel_dimension, bad_monitor_kernel_iprs, bad_kernel_hamiltonian_leakage_norms, min_bad_kernel_hamiltonian_leakage_norm, mean_bad_kernel_hamiltonian_leakage_norm, max_bad_kernel_hamiltonian_leakage_norm, closure_kernel_dimension, target_projection_onto_closure_kernel, target_distance_from_closure_kernel, target_in_closure_kernel, bad_closure_kernel_dimension, bad_closure_kernel_iprs)

Bases: object

Diagnostics for monitor-kernel closure under Hamiltonian mixing.

The monitor kernel is intersection_i ker(M_i). For a monitor-recycler design L_i = V_i M_i, this kernel is always contained in the jump kernel and therefore measures what the recyclers cannot see directly.

The first Hamiltonian-closure layer appends the constraints M_i H. If this sharply reduces the bad kernel, attraction is possible but can be slow because the Hamiltonian must rotate bad monitor-kernel states into the monitored subspace before dissipation acts.

dim: int

n_monitors: int

closure_order: int

max_target_monitor_residual: float

target_monitor_residuals: tuple[float, ...]

monitor_kernel_dimension: int

target_projection_onto_monitor_kernel: float

target_distance_from_monitor_kernel: float

target_in_monitor_kernel: bool

bad_monitor_kernel_dimension: int

bad_monitor_kernel_iprs: tuple[float, ...]

bad_kernel_hamiltonian_leakage_norms: tuple[float, ...]

min_bad_kernel_hamiltonian_leakage_norm: float | None

mean_bad_kernel_hamiltonian_leakage_norm: float | None

max_bad_kernel_hamiltonian_leakage_norm: float | None

closure_kernel_dimension: int

target_projection_onto_closure_kernel: float

target_distance_from_closure_kernel: float

target_in_closure_kernel: bool

bad_closure_kernel_dimension: int

bad_closure_kernel_iprs: tuple[float, ...]

to_summary_dict()

to_rich()

__init__(dim, n_monitors, closure_order, max_target_monitor_residual, target_monitor_residuals, monitor_kernel_dimension, target_projection_onto_monitor_kernel, target_distance_from_monitor_kernel, target_in_monitor_kernel, bad_monitor_kernel_dimension, bad_monitor_kernel_iprs, bad_kernel_hamiltonian_leakage_norms, min_bad_kernel_hamiltonian_leakage_norm, mean_bad_kernel_hamiltonian_leakage_norm, max_bad_kernel_hamiltonian_leakage_norm, closure_kernel_dimension, target_projection_onto_closure_kernel, target_distance_from_closure_kernel, target_in_closure_kernel, bad_closure_kernel_dimension, bad_closure_kernel_iprs)

qlinks.open_system.diagnostics.diagnose_monitor_kernel_closure(*, hamiltonian, monitors, target_state, closure_order=1, tolerance=1e-10)

Diagnose whether local monitors are closed by Hamiltonian mixing.

This is designed for monitor-recycler jumps L_i = V_i M_i. Recyclers cannot act on states in intersection_i ker(M_i), so the size of this kernel and its leakage under H are the first diagnostics to inspect.

Currently closure_order supports 0 or 1. Order 1 appends the constraints M_i H and computes the common kernel of {M_i, M_i H}.

class qlinks.open_system.diagnostics.DarkSubspaceDiagnostics(dim, n_jumps, target_norm, target_jump_residuals, max_target_jump_residual, target_liouvillian_residual, common_jump_kernel_dimension, target_projection_onto_common_kernel, target_distance_from_common_kernel, target_in_common_jump_kernel, bad_common_jump_kernel_dimension, bad_common_jump_kernel_iprs, liouvillian_zero_mode_count, liouvillian_zero_mode_count_is_lower_bound, liouvillian_spectral_gap, liouvillian_decay_gap, liouvillian_peripheral_mode_count, liouvillian_spectrum_method, liouvillian_eigenvalues, likely_unique_dark_state)

Bases: object

Diagnostics for whether a dark target is unique/attractive.

dim: int

n_jumps: int

target_norm: float

target_jump_residuals: tuple[float, ...]

max_target_jump_residual: float

target_liouvillian_residual: float

common_jump_kernel_dimension: int

target_projection_onto_common_kernel: float

target_distance_from_common_kernel: float

target_in_common_jump_kernel: bool

bad_common_jump_kernel_dimension: int

bad_common_jump_kernel_iprs: tuple[float, ...]

liouvillian_zero_mode_count: int | None

liouvillian_zero_mode_count_is_lower_bound: bool

liouvillian_spectral_gap: float | None

liouvillian_decay_gap: float | None

liouvillian_peripheral_mode_count: int | None

liouvillian_spectrum_method: str

liouvillian_eigenvalues: tuple[complex, ...]

likely_unique_dark_state: bool | None

to_summary_dict()

to_rich()

__init__(dim, n_jumps, target_norm, target_jump_residuals, max_target_jump_residual, target_liouvillian_residual, common_jump_kernel_dimension, target_projection_onto_common_kernel, target_distance_from_common_kernel, target_in_common_jump_kernel, bad_common_jump_kernel_dimension, bad_common_jump_kernel_iprs, liouvillian_zero_mode_count, liouvillian_zero_mode_count_is_lower_bound, liouvillian_spectral_gap, liouvillian_decay_gap, liouvillian_peripheral_mode_count, liouvillian_spectrum_method, liouvillian_eigenvalues, likely_unique_dark_state)

class qlinks.open_system.diagnostics.DarkManifoldDiagnostics(dim, n_jumps, manifold_dimension, hamiltonian_closure_residual, target_jump_residuals, max_target_jump_residual, target_density_liouvillian_residual, inflow_norm, common_jump_kernel_dimension, target_projection_onto_common_kernel, target_distance_from_common_kernel, target_in_common_jump_kernel, bad_common_jump_kernel_dimension, bad_common_jump_kernel_iprs, internal_hamiltonian_eigenvalues, expected_internal_liouvillian_eigenvalues, expected_internal_zero_mode_count, expected_internal_peripheral_mode_count, liouvillian_zero_mode_count, liouvillian_zero_mode_count_is_lower_bound, liouvillian_spectral_gap, liouvillian_decay_gap, liouvillian_peripheral_mode_count, liouvillian_spectrum_method, liouvillian_eigenvalues, matched_internal_nondecaying_mode_count, missing_internal_nondecaying_mode_count, extra_nondecaying_mode_count, extra_zero_mode_count, external_decay_gap, likely_attractive_dark_manifold)

Bases: object

Diagnostics for an attractive dark manifold/DFS target.

The target is a column-orthonormal basis M and the target projector is P_M = M M†. Unlike DarkSubspaceDiagnostics, this report does not expect a unique pure steady state. Internal zero or imaginary-axis Liouvillian modes generated by the projected Hamiltonian on the target manifold are treated as expected modes; only additional non-decaying modes outside the target manifold are flagged as obstructions.

dim: int

n_jumps: int

manifold_dimension: int

hamiltonian_closure_residual: float

target_jump_residuals: tuple[float, ...]

max_target_jump_residual: float

target_density_liouvillian_residual: float

inflow_norm: float

common_jump_kernel_dimension: int

target_projection_onto_common_kernel: float

target_distance_from_common_kernel: float

target_in_common_jump_kernel: bool

bad_common_jump_kernel_dimension: int

bad_common_jump_kernel_iprs: tuple[float, ...]

internal_hamiltonian_eigenvalues: tuple[complex, ...]

expected_internal_liouvillian_eigenvalues: tuple[complex, ...]

expected_internal_zero_mode_count: int

expected_internal_peripheral_mode_count: int

liouvillian_zero_mode_count: int | None

liouvillian_zero_mode_count_is_lower_bound: bool

liouvillian_spectral_gap: float | None

liouvillian_decay_gap: float | None

liouvillian_peripheral_mode_count: int | None

liouvillian_spectrum_method: str

liouvillian_eigenvalues: tuple[complex, ...]

matched_internal_nondecaying_mode_count: int | None

missing_internal_nondecaying_mode_count: int | None

extra_nondecaying_mode_count: int | None

extra_zero_mode_count: int | None

external_decay_gap: float | None

likely_attractive_dark_manifold: bool | None

to_summary_dict()

to_rich()

__init__(dim, n_jumps, manifold_dimension, hamiltonian_closure_residual, target_jump_residuals, max_target_jump_residual, target_density_liouvillian_residual, inflow_norm, common_jump_kernel_dimension, target_projection_onto_common_kernel, target_distance_from_common_kernel, target_in_common_jump_kernel, bad_common_jump_kernel_dimension, bad_common_jump_kernel_iprs, internal_hamiltonian_eigenvalues, expected_internal_liouvillian_eigenvalues, expected_internal_zero_mode_count, expected_internal_peripheral_mode_count, liouvillian_zero_mode_count, liouvillian_zero_mode_count_is_lower_bound, liouvillian_spectral_gap, liouvillian_decay_gap, liouvillian_peripheral_mode_count, liouvillian_spectrum_method, liouvillian_eigenvalues, matched_internal_nondecaying_mode_count, missing_internal_nondecaying_mode_count, extra_nondecaying_mode_count, extra_zero_mode_count, external_decay_gap, likely_attractive_dark_manifold)

class qlinks.open_system.diagnostics.CommonKernelHamiltonianInvariantSectorReport(dim, n_jumps, manifold_dimension, common_jump_kernel_dimension, bad_common_jump_kernel_dimension, bad_h_invariant_kernel_dimension, h_leakage_norm_from_bad_kernel, h_leakage_norm_from_invariant_kernel, h_target_coupling_norm_from_bad_kernel, h_bad_block_norm, h_invariant_block_eigenvalues, bad_h_invariant_kernel_iprs, target_in_common_jump_kernel, kernel_tolerance)

Bases: object

Cheap obstruction diagnostic inside the common jump kernel.

The common jump-kernel condition cap_mu ker J_mu = M is sufficient but stronger than necessary. A complement vector in the common kernel is only a Hamiltonian-stable dark obstruction if its whole Krylov orbit under H remains inside the common jump kernel. This report computes the largest such subspace inside (cap_mu ker J_mu) cap M^perp using a small dense nullspace problem.

dim: int

n_jumps: int

manifold_dimension: int

common_jump_kernel_dimension: int

bad_common_jump_kernel_dimension: int

bad_h_invariant_kernel_dimension: int

h_leakage_norm_from_bad_kernel: float

h_leakage_norm_from_invariant_kernel: float

h_target_coupling_norm_from_bad_kernel: float

h_bad_block_norm: float

h_invariant_block_eigenvalues: tuple[complex, ...]

bad_h_invariant_kernel_iprs: tuple[float, ...]

target_in_common_jump_kernel: bool

kernel_tolerance: float

property has_bad_common_kernel: bool

property has_bad_h_invariant_kernel: bool

property likely_attractive_by_h_invariant_kernel: bool

to_summary_dict()

to_rich()

__init__(dim, n_jumps, manifold_dimension, common_jump_kernel_dimension, bad_common_jump_kernel_dimension, bad_h_invariant_kernel_dimension, h_leakage_norm_from_bad_kernel, h_leakage_norm_from_invariant_kernel, h_target_coupling_norm_from_bad_kernel, h_bad_block_norm, h_invariant_block_eigenvalues, bad_h_invariant_kernel_iprs, target_in_common_jump_kernel, kernel_tolerance)

qlinks.open_system.diagnostics.bad_h_invariant_common_kernel_basis(*, hamiltonian, jumps, target_states, kernel_tolerance=1e-10)

Return the bad H-invariant sector inside the common jump kernel.

The returned columns form an orthonormal basis for the largest subspace of (cap_mu ker J_mu) cap M^perp whose Hamiltonian orbit stays inside the common jump kernel. An empty (dim, 0) array means the selected jumps have no Hamiltonian-stable dark obstruction outside the target manifold.

This helper exposes the obstruction basis used internally by diagnose_common_kernel_h_invariant_sector(), so jump-design routines can add a targeted completion stage without recomputing or interpreting a Liouvillian spectrum.

qlinks.open_system.diagnostics.diagnose_common_kernel_h_invariant_sector(*, hamiltonian, jumps, target_states, kernel_tolerance=1e-10)

Diagnose Hamiltonian-stable obstructions inside the common jump kernel.

This is a cheap alternative to a Liouvillian spectrum check. It first computes the common jump kernel K = cap_mu ker J_mu and the bad complement B = K cap M^perp. It then computes the largest subspace of B whose Hamiltonian Krylov orbit stays inside K. Only this H-invariant part is a purely dark Hamiltonian-stable complement sector.

qlinks.open_system.diagnostics.diagnose_dark_manifold(*, hamiltonian, jumps, target_states, backend='scipy', kernel_tolerance=1e-10, liouvillian_zero_tolerance=1e-09, check_liouvillian_spectrum=True, max_liouvillian_dense_dimension=4096, liouvillian_spectrum_method='auto', sparse_liouvillian_eigenvalue_count=32)

Diagnose whether a target manifold is an attractive dark manifold.

The columns of target_states span the target manifold. They need not be orthonormal; this function orthonormalizes them and uses the target projector P_M. The diagnostic accepts the internal non-decaying Liouvillian modes generated by the projected Hamiltonian M† H M and reports additional zero/peripheral modes as possible complement obstructions.

qlinks.open_system.diagnostics.diagnose_dark_subspace(*, hamiltonian, jumps, target_state, backend='scipy', kernel_tolerance=1e-10, liouvillian_zero_tolerance=1e-09, check_liouvillian_spectrum=True, max_liouvillian_dense_dimension=4096, liouvillian_spectrum_method='auto', sparse_liouvillian_eigenvalue_count=16)

Diagnose whether a dark target is likely unique/attractive.

This is intended for small systems. It computes:

1. target jump residuals ||J_mu psi||;

2. common jump kernel dim intersection_mu ker J_mu;

3. bad common-kernel dimension after removing the target direction;

4. target Liouvillian residual ||L(|psi><psi|)||;

5. optional Liouvillian zero-mode count.

The Liouvillian spectrum check uses a dense solver for small Liouvillians and a sparse shift-invert Arnoldi solver for larger ones when liouvillian_spectrum_method="auto". The sparse zero-mode count is a lower bound if all requested eigenvalues are numerically zero; increase sparse_liouvillian_eigenvalue_count to resolve more zero modes.

class qlinks.open_system.diagnostics.AbsorbingProjectorJumpDiagnostics(jump_index, target_residual, outflow_norm, inflow_norm, commutator_norm, dissipator_adjoint_projector_norm)

Bases: object

Diagnostics for one jump relative to a target projector.

jump_index: int

target_residual: float

outflow_norm: float

inflow_norm: float

commutator_norm: float

dissipator_adjoint_projector_norm: float

property is_dark_on_target: bool

property has_inflow: bool

__init__(jump_index, target_residual, outflow_norm, inflow_norm, commutator_norm, dissipator_adjoint_projector_norm)

class qlinks.open_system.diagnostics.AbsorbingProjectorSymmetryDiagnostics(dim, n_jumps, hamiltonian_commutator_norm, liouvillian_adjoint_projector_norm, max_target_residual, max_outflow_norm, max_inflow_norm, max_jump_projector_commutator_norm, jump_diagnostics, absorbing_projector_is_conserved, target_is_dark, has_recycling_inflow, has_absorbing_projector_symmetry)

Bases: object

Diagnostics for the absorbing-state projector symmetry P_psi.

dim: int

n_jumps: int

hamiltonian_commutator_norm: float

liouvillian_adjoint_projector_norm: float

max_target_residual: float

max_outflow_norm: float

max_inflow_norm: float

max_jump_projector_commutator_norm: float

jump_diagnostics: tuple[AbsorbingProjectorJumpDiagnostics, ...]

absorbing_projector_is_conserved: bool

target_is_dark: bool

has_recycling_inflow: bool

has_absorbing_projector_symmetry: bool

to_summary_dict()

to_rich()

__init__(dim, n_jumps, hamiltonian_commutator_norm, liouvillian_adjoint_projector_norm, max_target_residual, max_outflow_norm, max_inflow_norm, max_jump_projector_commutator_norm, jump_diagnostics, absorbing_projector_is_conserved, target_is_dark, has_recycling_inflow, has_absorbing_projector_symmetry)

qlinks.open_system.diagnostics.diagnose_absorbing_projector_symmetry(*, hamiltonian, jumps, target_state, backend='scipy', tolerance=1e-10)

Diagnose whether P_psi is an absorbing-state projector symmetry.

The target projector is

P_psi = |psi><psi|.

The relevant obstruction to attraction is:

J_mu |psi> = 0 and P_psi J_mu (I - P_psi) = 0

for all jumps. Then the target is dark, but there is no jump-induced inflow from psi_perp into psi. Equivalently, P_psi is conserved by the Heisenberg-picture Lindbladian.

qlinks.open_system.local_recycling module

class qlinks.open_system.local_recycling.TwoPatternRecyclingStructure(variable_indices, pattern_a, pattern_b, alpha_index, beta_index, phase, residual, matrix_unit_terms)

Bases: object

Detected local two-pattern recycling structure.

This represents a local jump of the form |minus><plus|, up to phase and convention.

variable_indices: tuple[int, ...]

pattern_a: tuple[int, ...]

pattern_b: tuple[int, ...]

alpha_index: int

beta_index: int

phase: complex

residual: float

matrix_unit_terms: tuple[LocalMatrixUnitTerm, ...]

property n_variables: int

__init__(variable_indices, pattern_a, pattern_b, alpha_index, beta_index, phase, residual, matrix_unit_terms)

class qlinks.open_system.local_recycling.LocalRecyclingCandidate(variable_indices, alpha_index, beta_index, jump, target_residual, inflow_norm, outflow_norm, projector_commutator_norm, local_alpha_vector, local_beta_vector, local_operator=None)

Bases: object

One embedded local RDM recycling jump candidate.

Most candidates are rank-one maps |alpha><beta| between the local support and null spaces of the target reduced density matrix. A compressed block-reset candidate can instead carry a higher-rank local_operator that maps several null directions into the local target support with one Lindblad channel. The local_alpha_vector and local_beta_vector fields are retained for rank-one readouts and hold representative support and null vectors for block-reset candidates.

variable_indices: tuple[int, ...]

alpha_index: int

beta_index: int

jump: csr_array

target_residual: float

inflow_norm: float

outflow_norm: float

projector_commutator_norm: float

local_alpha_vector: ndarray[tuple[Any, ...], dtype[complex128]]

local_beta_vector: ndarray[tuple[Any, ...], dtype[complex128]]

local_operator: ndarray[tuple[Any, ...], dtype[complex128]] | None

property is_dark: bool

property has_inflow: bool

__init__(variable_indices, alpha_index, beta_index, jump, target_residual, inflow_norm, outflow_norm, projector_commutator_norm, local_alpha_vector, local_beta_vector, local_operator=None)

class qlinks.open_system.local_recycling.LocalRecyclingScanResult(reduced_density_matrix, candidates)

Bases: object

Candidate jumps from one local region.

reduced_density_matrix: LocalReducedDensityMatrix

candidates: tuple[LocalRecyclingCandidate, ...]

property n_candidates: int

property best_candidates: tuple[LocalRecyclingCandidate, ...]

__init__(reduced_density_matrix, candidates)

class qlinks.open_system.local_recycling.LocalRecyclingSelection(candidate, two_pattern_structure, score)

Bases: object

Selected recycling candidate plus optional detected structure.

candidate: LocalRecyclingCandidate

two_pattern_structure: TwoPatternRecyclingStructure | None

score: tuple[float, ...]

__init__(candidate, two_pattern_structure, score)

class qlinks.open_system.local_recycling.LocalRecyclingBuildResult(scan_results, selections)

Bases: object

Selected recycling jumps from several local regions.

scan_results: tuple[LocalRecyclingScanResult, ...]

selections: tuple[LocalRecyclingSelection, ...]

property jumps: tuple[csr_array, ...]

property n_jumps: int

property variable_indices: tuple[tuple[int, ...], ...]

property alpha_beta_indices: tuple[tuple[int, int], ...]

to_subspace_support_report()

Return a local-support/nullity report for the scanned regions.

__init__(scan_results, selections)

class qlinks.open_system.local_recycling.LocalSubspaceSupportReportEntry(variable_indices, local_dim, support_rank, nullity, support_trace, min_nonzero_eigenvalue, max_eigenvalue, n_candidate_jumps, n_selected_jumps)

Bases: object

Local support/nullity diagnostics for one candidate region.

The local RDM is the reduced density matrix of the normalized projector onto a target subspace. nullity is the number of local source directions annihilated by the target manifold. If it is zero, no strictly local right-detector D_R on this region can satisfy D_R P_M = 0.

variable_indices: tuple[int, ...]

local_dim: int

support_rank: int

nullity: int

support_trace: float

min_nonzero_eigenvalue: float | None

max_eigenvalue: float | None

n_candidate_jumps: int

n_selected_jumps: int

property n_variables: int

property has_local_null_detector: bool

property has_selected_recycler: bool

property parent_detector_directions: int

property minimum_block_reset_channels: int

property status: str

to_summary_dict()

__init__(variable_indices, local_dim, support_rank, nullity, support_trace, min_nonzero_eigenvalue, max_eigenvalue, n_candidate_jumps, n_selected_jumps)

class qlinks.open_system.local_recycling.LocalSubspaceSupportReport(entries)

Bases: object

Local-support report explaining manifold recycler availability.

entries: tuple[LocalSubspaceSupportReportEntry, ...]

property n_regions: int

property n_regions_with_nullity: int

property n_regions_with_selected_recyclers: int

property total_candidate_jumps: int

property total_selected_jumps: int

property all_regions_have_full_local_support: bool

to_summary_dict()

to_rich(*, max_regions=24)

__init__(entries)

qlinks.open_system.local_recycling.local_subspace_support_report_from_recycling_build_result(build_result)

Summarize local RDM support/nullity and selected recyclers by region.

qlinks.open_system.local_recycling.local_subspace_support_report_for_subspace(*, basis_configs, states, regions, source='local_rdm_block_reset', deduplicate_regions=False, max_jumps_per_region=1, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, max_candidates_per_region=None, prefer_sparse=True, two_pattern_tolerance=1e-08)

Build only the local manifold-support report for candidate regions.

qlinks.open_system.local_recycling.score_recycling_jump_for_subspace(*, jump, states, tolerance=1e-10)

Return residual/inflow/outflow diagnostics for a target subspace.

The target subspace is represented by an orthonormal basis Q. The returned values are Frobenius norms of J Q and J^† Q; when J Q=0 the second norm equals the direct inflow block Q_perp J^† Q.

qlinks.open_system.local_recycling.score_recycling_jump(*, jump, target_state)

Return target residual, inflow, outflow, and projector commutator.

The diagnostics are Frobenius norms of the corresponding projected operators. They can be evaluated from J|psi> and J^dagger|psi> without materializing the dense projectors |psi><psi| and I-|psi><psi|.

qlinks.open_system.local_recycling.scan_local_recycling_candidates(*, basis_configs, target_state, variable_indices, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-10, max_candidates=None)

Scan local rank-one recycling jumps from rho_Omega.

qlinks.open_system.local_recycling.detect_two_pattern_recycling_structure(*, candidate, local_patterns, tolerance=1e-08)

Detect whether a candidate is a two-pattern |minus><plus| jump.

qlinks.open_system.local_recycling.select_local_recycling_candidates(*, scan_result, source='local_rdm_two_pattern', max_candidates=1, prefer_sparse=True, two_pattern_tolerance=1e-08)

Select recycling candidates from one scan result.

local_rdm_rank_one and local_rdm_two_pattern keep the historical behavior: they choose the best few rank-one reset maps |alpha><beta|.

local_rdm_null_basis is designed for monitor-recycler jumps L=V P. A single rank-one recycler can make V P much more singular than the monitor P itself, because it only tests one local beta direction. This source instead selects one good target-support vector alpha for every local-RDM null vector beta.

local_rdm_block_reset is the compressed version: it groups up to rank(rho_R) null vectors into each reset channel. The max_candidates argument is intentionally ignored for both null-basis and block-reset sources, because their counts are determined by the local RDM ranks.

qlinks.open_system.local_recycling.scan_local_recycling_candidates_for_subspace(*, basis_configs, states, variable_indices, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-10, max_candidates=None)

Scan local rank-one recycling jumps from a target subspace RDM.

qlinks.open_system.local_recycling.build_local_recycling_jumps_from_subspace_regions(*, basis_configs, states, regions, source='local_rdm_block_reset', deduplicate_regions=False, max_jumps_per_region=1, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, max_candidates_per_region=None, prefer_sparse=True, two_pattern_tolerance=1e-08)

Scan local recycling jumps that annihilate a target state subspace.

qlinks.open_system.local_recycling.build_local_recycling_jumps_from_regions(*, basis_configs, target_state, regions, source='local_rdm_two_pattern', deduplicate_regions=False, max_jumps_per_region=1, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, max_candidates_per_region=None, prefer_sparse=True, two_pattern_tolerance=1e-08)

Scan several regions and return selected local recycling jumps.

Set deduplicate_regions=True when repeated monitor components share the same local support and should use one recycler family rather than one copy per component. The default keeps the historical behavior.

qlinks.open_system.operators module

class qlinks.open_system.operators.DenseLindbladOperators(backend, hamiltonian, jumps, jump_daggers, jump_dagger_jumps)

Bases: object

Dense Lindblad operators prepared for repeated RHS evaluations.

backend: OpenSystemBackend

hamiltonian: Any

jumps: tuple[Any, ...]

jump_daggers: tuple[Any, ...]

jump_dagger_jumps: tuple[Any, ...]

__init__(backend, hamiltonian, jumps, jump_daggers, jump_dagger_jumps)

class qlinks.open_system.operators.SparseLindbladOperators(backend, sparse_format, hamiltonian, identity, jumps, jump_dagger_jumps)

Bases: object

Sparse Lindblad operators prepared for Liouville-space construction.

backend: OpenSystemBackend

sparse_format: str

hamiltonian: Any

identity: Any

jumps: tuple[Any, ...]

jump_dagger_jumps: tuple[Any, ...]

property dim: int

__init__(backend, sparse_format, hamiltonian, identity, jumps, jump_dagger_jumps)

qlinks.open_system.operators.prepare_dense_lindblad_operators(*, hamiltonian, jumps, backend='scipy', dtype=<class 'numpy.complex128'>)

Convert Lindblad operators once for repeated dense RHS calls.

qlinks.open_system.operators.prepare_sparse_lindblad_operators(*, hamiltonian, jumps, backend='scipy', sparse_format='csc', dtype=<class 'numpy.complex128'>)

Convert sparse Lindblad operators once for Liouville-space construction.

qlinks.open_system.operators.vectorize_density_matrix(density_matrix)

Vectorize a density matrix in column-major Liouville convention.

Parameters:

density_matrix (Any) – Square density matrix rho.

Returns:

Flattened vector with entries ordered as Fortran/column-major storage.

Return type:

Any

qlinks.open_system.operators.unvectorize_density_matrix(vectorized_density_matrix, dim)

Restore a density matrix from column-major Liouville vectorization.

Parameters:

• vectorized_density_matrix (Any) – Vector returned by vectorize_density_matrix().

• dim (int) – Hilbert-space dimension.

Returns:

(dim, dim) density matrix.

Return type:

Any

qlinks.open_system.operators.build_liouvillian_from_prepared(sparse_operators)

Build the Liouvillian from preconverted sparse Lindblad operators.

qlinks.open_system.operators.build_liouvillian(hamiltonian, jumps, *, backend='scipy', sparse_format='csc', dtype=<class 'numpy.complex128'>)

Build the sparse Liouvillian superoperator.

The Liouvillian acts on density matrices vectorized with vectorize_density_matrix().

Parameters:

• hamiltonian (Any) – Hamiltonian matrix.

• jumps (list[Any] | tuple[Any, ...]) – Lindblad jump operators.

• backend (Literal['scipy', 'cupy'] | ~qlinks.open_system.backend.OpenSystemBackend) – Open-system backend name or object.

• sparse_format (str) – Sparse format for the returned superoperator.

• dtype – Complex dtype used during conversion.

Returns:

Sparse Liouvillian matrix with shape (dim * dim, dim * dim).

qlinks.open_system.operators.lindblad_rhs_density_matrix(density_matrix, *, hamiltonian, jumps, backend='scipy')

Evaluate the Lindblad master-equation right-hand side.

Computes d rho / dt = -i[H, rho] + sum_j D[J_j](rho) using dense backend arrays. For repeated calls, use prepare_dense_lindblad_operators() and lindblad_rhs_density_matrix_prepared().

Parameters:

• density_matrix (Any) – Current density matrix.

• hamiltonian (Any) – Hamiltonian matrix.

• jumps (list[Any] | tuple[Any, ...]) – Lindblad jump operators.

• backend (Literal['scipy', 'cupy'] | ~qlinks.open_system.backend.OpenSystemBackend) – Open-system backend name or object.

Returns:

Density-matrix derivative on the requested backend.

qlinks.open_system.operators.lindblad_rhs_density_matrix_prepared(density_matrix, *, dense_operators)

Evaluate the dense Lindblad RHS using preconverted operators.

qlinks.open_system.operators.lindblad_rhs_density_matrix_sparse_prepared(density_matrix, *, sparse_operators)

Evaluate the Lindblad RHS using sparse operators on a dense rho.

This is the matrix-free Liouville action in density-matrix form. It avoids constructing the dim^2 x dim^2 Liouvillian and also avoids densifying sparse Hamiltonian/jump operators. It is useful for intermediate dimensions where the explicit Liouvillian is too large but the density matrix itself still fits in memory.

qlinks.open_system.operators.estimate_lindblad_scale(*, hamiltonian, jumps, backend='scipy')

Cheap stiffness scale for RK4 step-size sanity checks.

qlinks.open_system.operators.estimate_lindblad_scale_prepared(dense_operators)

Cheap stiffness scale from preconverted dense operators.

qlinks.open_system.protocols module

Structural interfaces accepted by open-system construction workflows.

class qlinks.open_system.protocols.CageStateRecordLike(*args, **kwargs)

Bases: Protocol

Minimal cage-state record interface needed by Lindblad construction.

Concrete cage-search records satisfy this protocol structurally. Keeping the protocol here avoids coupling the open-system layer to the caging search implementation and also permits lightweight user-defined records.

property support: ndarray[tuple[Any, ...], dtype[int64]]

property local_state: ndarray[tuple[Any, ...], dtype[complex128]]

property full_state: ndarray[tuple[Any, ...], dtype[complex128]] | None

property signature: tuple[int, int]

__init__(*args, **kwargs)

qlinks.open_system.solvers module

class qlinks.open_system.solvers.LindbladEvolutionOptions(method='auto', backend='scipy', rk4_step_policy='adaptive', max_dimension_for_liouvillian=400, max_dimension_for_krylov=400, max_rk4_step_scale=0.05, adaptive_tolerance=1e-08, min_substeps=1, max_substeps=1024, enforce_hermiticity=True, renormalize_trace=True, check_density_matrix=True)

Bases: object

Options controlling Lindblad time evolution.

method

Solver method. "auto" chooses between Krylov and RK4 variants from system size and backend capabilities.

Type:

Literal[‘auto’, ‘krylov’, ‘rk4_matrix’, ‘rk4_sparse_matrix’, ‘rk4_liouville’]

backend

Backend used for dense/sparse array operations.

Type:

Literal[‘scipy’, ‘cupy’]

rk4_step_policy

Policy when the requested time grid is too coarse for RK4 according to the Lindblad scale estimate.

Type:

Literal[‘raise’, ‘warn’, ‘adaptive’, ‘ignore’]

max_dimension_for_liouvillian

Largest Hilbert dimension for explicit Liouville-space RK4 in "auto" mode.

Type:

int

max_dimension_for_krylov

Largest Hilbert dimension for Krylov expm_multiply in "auto" mode.

Type:

int

max_rk4_step_scale

Maximum recommended RK4 step times estimated Lindblad scale.

Type:

float

adaptive_tolerance

Relative tolerance used by adaptive RK4 step subdivision.

Type:

float

min_substeps

Minimum RK4 substeps per interval.

Type:

int

max_substeps

Maximum RK4 substeps per interval.

Type:

int

enforce_hermiticity

Symmetrize density matrices after each interval.

Type:

bool

renormalize_trace

Renormalize trace after each interval.

Type:

bool

check_density_matrix

Record density-matrix diagnostics after evolution steps.

Type:

bool

method: Literal['auto', 'krylov', 'rk4_matrix', 'rk4_sparse_matrix', 'rk4_liouville']

backend: Literal['scipy', 'cupy']

rk4_step_policy: Literal['raise', 'warn', 'adaptive', 'ignore']

max_dimension_for_liouvillian: int

max_dimension_for_krylov: int

max_rk4_step_scale: float

adaptive_tolerance: float

min_substeps: int

max_substeps: int

enforce_hermiticity: bool

renormalize_trace: bool

check_density_matrix: bool

__init__(method='auto', backend='scipy', rk4_step_policy='adaptive', max_dimension_for_liouvillian=400, max_dimension_for_krylov=400, max_rk4_step_scale=0.05, adaptive_tolerance=1e-08, min_substeps=1, max_substeps=1024, enforce_hermiticity=True, renormalize_trace=True, check_density_matrix=True)

class qlinks.open_system.solvers.LindbladEvolutionResult(times, density_matrices, method, backend, diagnostics, n_substeps_per_interval)

Bases: object

Result returned by Lindblad time-evolution solvers.

times

Time grid used by the evolution.

Type:

numpy.ndarray

density_matrices

Density matrix at each time.

Type:

list[Any]

method

Concrete solver method used after resolving "auto".

Type:

str

backend

Backend name.

Type:

str

diagnostics

Per-time density-matrix diagnostics when enabled.

Type:

list[Any]

n_substeps_per_interval

RK4 substep counts for each interval, or an empty tuple for non-RK4 methods.

Type:

tuple[int, …]

times: ndarray

density_matrices: list[Any]

method: str

backend: str

diagnostics: list[Any]

n_substeps_per_interval: tuple[int, ...]

__init__(times, density_matrices, method, backend, diagnostics, n_substeps_per_interval)

class qlinks.open_system.solvers.LindbladProblem(*, hamiltonian, jumps, backend='scipy')

Bases: object

Reusable Lindblad problem with cached prepared operators.

The problem stores a Hamiltonian and jump list, prepares dense/sparse operator bundles lazily, and exposes RHS, Liouvillian, and evolution methods that reuse those caches.

__init__(*, hamiltonian, jumps, backend='scipy')

property dim: int

property dense_operators: DenseLindbladOperators

property rk4_scale: float

sparse_operators(*, sparse_format='csc')

build_liouvillian(*, sparse_format='csc')

rhs(density_matrix)

sparse_rhs(density_matrix)

evolve(density_matrix_initial, times, *, options=None)

qlinks.open_system.solvers.solve_lindblad(*, hamiltonian, jumps, density_matrix_initial, times, method='auto', backend='scipy', options=None)

Evolve a density matrix under a Lindblad master equation.

Parameters:

• hamiltonian (Any) – Hamiltonian matrix.

• jumps (list[Any] | tuple[Any, ...]) – Lindblad jump operators.

• density_matrix_initial (Any) – Initial density matrix.

• times (ndarray) – Strictly increasing one-dimensional time grid.

• method (Literal['auto', 'krylov', 'rk4_matrix', 'rk4_sparse_matrix', 'rk4_liouville']) – Solver method, or "auto".

• backend (Literal['scipy', 'cupy']) – Open-system backend name.

• options (LindbladEvolutionOptions | None) – Optional full options object. When supplied, method and backend override the corresponding fields.

Returns:

Evolution result containing density matrices and diagnostics metadata.

Return type:

LindbladEvolutionResult

qlinks.open_system.states module

qlinks.open_system.states.normalize_state(state, *, atol=0.0)

Return a normalized complex state vector.

qlinks.open_system.states.random_pure_state(dim, *, rng=None)

Draw a Haar-like random complex state vector.

qlinks.open_system.states.density_matrix_from_state(state, *, normalize=True)

Return the pure density matrix associated with a state vector.

Parameters:

• state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – One-dimensional state vector.

• normalize (bool) – Whether to normalize the vector before forming |psi><psi|.

Returns:

Complex density matrix |psi><psi|.

Return type:

ndarray[tuple[Any, …], dtype[complex128]]

qlinks.open_system.states.pure_density_matrix(state, *, normalize=True)

Return |psi><psi|.

qlinks.open_system.states.random_pure_density_matrix(dim, *, rng=None)

Draw a random pure density matrix |psi><psi|.

qlinks.open_system.states.random_mixed_density_matrix(dim, *, rank=None, rng=None)

Draw a random mixed density matrix using a Ginibre ensemble.

The state is generated as rho = X X^\dagger / Tr(X X^\dagger) where X has shape (dim, rank).

Parameters:

• dim (int) – Hilbert-space dimension.

• rank (int | None) – Optional effective rank. If None, use full rank dim.

• rng (Generator | int | None) – NumPy random generator or seed.

Returns:

Hermitian, positive-semidefinite density matrix with trace one.

Return type:

ndarray[tuple[Any, …], dtype[complex128]]

qlinks.open_system.states.random_density_matrix(dim, *, kind='mixed', rank=None, rng=None)

Draw a random pure or mixed density matrix.

Parameters:

• dim (int) – Hilbert-space dimension.

• kind (Literal['pure', 'mixed', 'maximally_mixed']) – "pure" for |psi><psi| or "mixed" for a Ginibre mixed state.

• rank (int | None) – Optional effective rank for kind="mixed".

• rng (Generator | int | None) – NumPy random generator or seed.

Returns:

Density matrix with trace one.

Raises:

ValueError – If kind is unsupported or rank is incompatible.

Return type:

ndarray[tuple[Any, …], dtype[complex128]]

qlinks.open_system.states.initial_density_matrix(dim, *, kind='mixed', rank=None, rng=None)

Create a convenient initial density matrix.

qlinks.open_system.stochastic_schrodinger module

class qlinks.open_system.stochastic_schrodinger.McwfOptions(backend='scipy', n_trajectories=128, seed=None, return_backend_arrays=False, store_states=True, store_trajectories=False, normalize_each_step=True, max_jump_probability=0.1, prefer_sparse_operators=True, prefer_sparse_rate_evaluator=True, use_total_rate_first=True, compress_collinear_jumps=False, jump_compression_tolerance=1e-10, store_density_matrices=True, store_state_snapshots=False, trajectory_chunk_size=None, trajectory_chunk_workers=None, adaptive_trajectory_block_size=None, fidelity_targets=None, timing_collector=None, adaptive_time_step=False, adaptive_safety_factor=0.8, min_step_size=1e-12, max_substeps_per_interval=100000)

Bases: object

Options for Monte Carlo wave-function sampling.

backend: Literal['scipy', 'cupy']

n_trajectories: int

seed: int | None

return_backend_arrays: bool

store_states: bool

store_trajectories: bool

normalize_each_step: bool

max_jump_probability: float

prefer_sparse_operators: bool

prefer_sparse_rate_evaluator: bool

use_total_rate_first: bool

compress_collinear_jumps: bool

jump_compression_tolerance: float

store_density_matrices: bool

store_state_snapshots: bool

trajectory_chunk_size: int | None

trajectory_chunk_workers: int | None

adaptive_trajectory_block_size: int | None

fidelity_targets: Mapping[str, Any] | None

timing_collector: MutableMapping[str, float] | None

adaptive_time_step: bool

adaptive_safety_factor: float

min_step_size: float

max_substeps_per_interval: int

validate()

Validate MCWF time-step control options.

__init__(backend='scipy', n_trajectories=128, seed=None, return_backend_arrays=False, store_states=True, store_trajectories=False, normalize_each_step=True, max_jump_probability=0.1, prefer_sparse_operators=True, prefer_sparse_rate_evaluator=True, use_total_rate_first=True, compress_collinear_jumps=False, jump_compression_tolerance=1e-10, store_density_matrices=True, store_state_snapshots=False, trajectory_chunk_size=None, trajectory_chunk_workers=None, adaptive_trajectory_block_size=None, fidelity_targets=None, timing_collector=None, adaptive_time_step=False, adaptive_safety_factor=0.8, min_step_size=1e-12, max_substeps_per_interval=100000)

class qlinks.open_system.stochastic_schrodinger.TrajectoryResult(times, states, jump_times, jump_indices, norm_errors)

Bases: object

Single Monte Carlo wave-function trajectory.

times: ndarray[tuple[Any, ...], dtype[float64]]

states: list[Any]

jump_times: ndarray[tuple[Any, ...], dtype[float64]]

jump_indices: ndarray[tuple[Any, ...], dtype[int64]]

norm_errors: ndarray[tuple[Any, ...], dtype[float64]]

__init__(times, states, jump_times, jump_indices, norm_errors)

class qlinks.open_system.stochastic_schrodinger.EnsembleResult(times, rho_t, trajectories=None, state_snapshots=None, target_fidelities=None)

Bases: object

Ensemble-averaged MCWF result.

times: ndarray[tuple[Any, ...], dtype[float64]]

rho_t: list[ndarray[tuple[Any, ...], dtype[complex128]]]

trajectories: tuple[TrajectoryResult, ...] | None

state_snapshots: tuple[ndarray[tuple[Any, ...], dtype[complex128]], ...] | None

target_fidelities: dict[str, ndarray[tuple[Any, ...], dtype[float64]]] | None

__init__(times, rho_t, trajectories=None, state_snapshots=None, target_fidelities=None)

qlinks.open_system.stochastic_schrodinger.projector(state)

Return |state><state|.

qlinks.open_system.stochastic_schrodinger.expectation(state, operator)

Return <state|operator|state>.

qlinks.open_system.stochastic_schrodinger.effective_hamiltonian(hamiltonian, jumps)

Return H_eff = H - i/2 sum_mu J_mu^dagger J_mu.

qlinks.open_system.stochastic_schrodinger.jump_probabilities(state, jumps, step_size, *, backend)

Return first-order jump probabilities dt <psi|J^dagger J|psi>.

qlinks.open_system.stochastic_schrodinger.choose_jump(probabilities, rng)

Choose a jump index according to normalized probabilities.

qlinks.open_system.stochastic_schrodinger.evolve_no_jump_first_order(state, effective_hamiltonian_matrix, step_size)

First-order no-jump evolution under H_eff.

qlinks.open_system.stochastic_schrodinger.run_quantum_jump_trajectory(*, hamiltonian, jumps, state_initial, times, rng=None, backend='scipy', return_backend_arrays=False, store_states=True, normalize_each_step=True, max_jump_probability=0.1, prefer_sparse_operators=True, prefer_sparse_rate_evaluator=True, use_total_rate_first=True, adaptive_time_step=False, adaptive_safety_factor=0.8, min_step_size=1e-12, max_substeps_per_interval=100000)

Run one Monte Carlo wave-function trajectory.

This uses a first-order no-jump propagator. It is therefore deliberately conservative: if the total jump probability in one time step is too large, it raises an error and asks the caller to refine the time grid.

qlinks.open_system.stochastic_schrodinger.density_matrix_from_state_matrix(states)

Return the ensemble density matrix represented by state columns.

states[:, trajectory_index] is one normalized MCWF trajectory state. The returned matrix is the average projector over columns.

qlinks.open_system.stochastic_schrodinger.sample_lindblad_mcwf(*, hamiltonian, jumps, times, state_initial=None, state_sampler=None, options=None, rng=None)

Estimate Lindblad evolution with Monte Carlo wavefunction trajectories.

Parameters:

• hamiltonian (Any) – Hamiltonian matrix.

• jumps (list[Any] | tuple[Any, ...]) – Lindblad jump operators.

• times (ndarray[tuple[Any, ...], dtype[float64]]) – Strictly increasing time grid.

• state_initial (Any | None) – Fixed initial pure state used for every trajectory. Mutually exclusive with state_sampler.

• state_sampler (Callable[[Generator], Any] | None) – Optional callable that samples an initial pure state from a NumPy random generator.

• options (McwfOptions | None) – MCWF sampling and storage options.

• rng (Generator | int | None) – Optional RNG or seed. Overrides options.seed when supplied.

Returns:

Ensemble result containing averaged density matrices when requested, optional low-rank state snapshots, and optional stored trajectories.

Return type:

EnsembleResult

qlinks.open_system.stochastic_schrodinger.observable_vs_time(rho_t, observable)

Return Tr[rho(t) observable] for each density matrix.

Module contents

class qlinks.open_system.AbsorbingProjectorJumpDiagnostics(jump_index, target_residual, outflow_norm, inflow_norm, commutator_norm, dissipator_adjoint_projector_norm)

Bases: object

Diagnostics for one jump relative to a target projector.

jump_index: int

target_residual: float

outflow_norm: float

inflow_norm: float

commutator_norm: float

dissipator_adjoint_projector_norm: float

property is_dark_on_target: bool

property has_inflow: bool

__init__(jump_index, target_residual, outflow_norm, inflow_norm, commutator_norm, dissipator_adjoint_projector_norm)

class qlinks.open_system.AbsorbingProjectorSymmetryDiagnostics(dim, n_jumps, hamiltonian_commutator_norm, liouvillian_adjoint_projector_norm, max_target_residual, max_outflow_norm, max_inflow_norm, max_jump_projector_commutator_norm, jump_diagnostics, absorbing_projector_is_conserved, target_is_dark, has_recycling_inflow, has_absorbing_projector_symmetry)

Bases: object

Diagnostics for the absorbing-state projector symmetry P_psi.

dim: int

n_jumps: int

hamiltonian_commutator_norm: float

liouvillian_adjoint_projector_norm: float

max_target_residual: float

max_outflow_norm: float

max_inflow_norm: float

max_jump_projector_commutator_norm: float

jump_diagnostics: tuple[AbsorbingProjectorJumpDiagnostics, ...]

absorbing_projector_is_conserved: bool

target_is_dark: bool

has_recycling_inflow: bool

has_absorbing_projector_symmetry: bool

to_summary_dict()

to_rich()

__init__(dim, n_jumps, hamiltonian_commutator_norm, liouvillian_adjoint_projector_norm, max_target_residual, max_outflow_norm, max_inflow_norm, max_jump_projector_commutator_norm, jump_diagnostics, absorbing_projector_is_conserved, target_is_dark, has_recycling_inflow, has_absorbing_projector_symmetry)

class qlinks.open_system.CageLindbladDesignProblem(build_result, construction)

Bases: object

Unified cage-state Lindblad design problem.

The object stores only the target manifold, basis/configuration metadata, and local regions needed by the successful dark-detector workflow. Use build_cage_lindblad_problem() to construct it from either one state, many states, or cage records.

build_result: ModelBuildResult

construction: DegenerateCageLindbladConstruction

property hamiltonian: Any

property basis_configs: ndarray[tuple[Any, ...], dtype[integer]]

property manifold_basis: ndarray[tuple[Any, ...], dtype[complex128]]

property target_basis: ndarray[tuple[Any, ...], dtype[complex128]]

property target_density_matrix: ndarray[tuple[Any, ...], dtype[complex128]]

property target_manifold_projector: ndarray[tuple[Any, ...], dtype[complex128]]

Projector onto the target dark/cage manifold.

target_manifold_weight_series(**kwargs)

Return Tr(P_target rho(t)) for solver or MCWF output.

The method forwards data-source keywords such as evolution_result, density_matrices, ensemble_result, or state_snapshots to qlinks.open_system.diagnostics.target_manifold_weight_series() and automatically supplies this problem’s target basis.

target_manifold_density_matrix_series(**kwargs)

Return the conditioned density matrix inside the target manifold.

target_manifold_populations_series(**kwargs)

Return target-basis populations inside the target manifold.

target_manifold_coherence_series(**kwargs)

Return off-diagonal target-manifold coherence over time.

target_manifold_purity_series(**kwargs)

Return purity of the conditioned target-manifold state over time.

target_manifold_entropy_series(**kwargs)

Return entropy of the conditioned target-manifold state over time.

property hilbert_dimension: int

property manifold_dimension: int

property is_single_cage_target: bool

property local_regions: tuple[tuple[int, ...], ...]

property regional_units: tuple[tuple[int, ...], ...]

Model-natural region units used by regional-unit modes.

property record_signature: tuple[int, int] | None

to_summary_dict()

to_lindblad_problem(*, jumps, hamiltonian=None, backend=None)

Package a jump set as a solver-ready Lindblad problem.

This method is retained as a low-level helper for custom jump designs. The preferred path is design_jumps(), which returns both the workflow report and the packaged LindbladProblem in one result.

design_workflow(*, detector_operators, detector_operator_names=None, hamiltonian=None, basis_configs=None, **workflow_kwargs)

Run the raw dark-detector/recycler workflow report.

Most users should call design_jumps(), which packages this report together with a solver-ready LindbladProblem. This lower-level method is useful when comparing alternative jump-design workflows.

design_jumps(*, detector_operators, detector_operator_names=None, hamiltonian=None, basis_configs=None, backend=None, **workflow_kwargs)

Design jumps and return a solver-ready result.

The returned object exposes the workflow report through .workflow and delegates common report properties/methods, while .lindblad_problem can be passed directly to solvers. This avoids the older two-step pattern workflow = problem.design_jumps(...); problem = workflow.to_lindblad_problem(...).

design_lindblad_problem(*, detector_operators, detector_operator_names=None, hamiltonian=None, basis_configs=None, backend=None, **workflow_kwargs)

Design jumps and return only the solver-ready Lindblad problem.

__init__(build_result, construction)

class qlinks.open_system.CageLindbladDesignResult(problem, workflow, lindblad_problem, detector_operators=(), detector_operator_names=(), detector_terms=())

Bases: object

Result of the unified cage-Lindblad jump-design workflow.

workflow contains all diagnostic/readout detail. lindblad_problem is the solver-ready object with the final jump set already packaged. Common workflow methods and attributes are delegated for notebook convenience. Detector metadata is retained so the design can be exported as a reconstructable analytical J = R D data bundle.

problem: CageLindbladDesignProblem

workflow: DegenerateCageJumpDesignWorkflowReport

lindblad_problem: LindbladProblem

detector_operators: tuple[Any, ...]

detector_operator_names: tuple[str, ...]

detector_terms: tuple[LocalTermDescriptor, ...]

property jumps: tuple[csr_array, ...]

property recycled_jumps: tuple[csr_array, ...]

property targeted_jumps: tuple[csr_array, ...]

property n_jumps: int

property h_invariant_report: CommonKernelHamiltonianInvariantSectorReport | None

property likely_successful_h_invariant_design: bool | None

property solver_problem: LindbladProblem

Alias for lindblad_problem used by some solver-oriented notebooks.

property target_manifold_projector: ndarray[tuple[Any, ...], dtype[complex128]]

Projector onto this design’s target dark/cage manifold.

target_manifold_weight_series(**kwargs)

Return Tr(P_target rho(t)) for evolution or MCWF output.

Examples

design.target_manifold_weight_series(evolution_result=result) for Lindblad density-matrix solvers, or design.target_manifold_weight_series(ensemble_result=mcwf) for MCWF results containing rho_t or state_snapshots.

target_manifold_density_matrix_series(**kwargs)

Return the conditioned density matrix inside the target manifold.

target_manifold_populations_series(**kwargs)

Return target-basis populations inside the target manifold.

target_manifold_coherence_series(**kwargs)

Return off-diagonal target-manifold coherence over time.

target_manifold_purity_series(**kwargs)

Return purity of the conditioned target-manifold state over time.

target_manifold_entropy_series(**kwargs)

Return entropy of the conditioned target-manifold state over time.

jump_activity_series(**kwargs)

Return total jump activity sum_mu Tr(J_mu^dag J_mu rho(t)).

evolve_with_target_weight(density_matrix_initial, times, *, options=None)

Evolve this Lindblad problem and return target-manifold weights.

This is a convenience wrapper around self.lindblad_problem.evolve followed by Tr(P_target rho(t)).

to_lindblad_problem()

Return the already packaged solver problem.

to_summary_dict()

export(path, *, include_basis=True, include_global_matrices=False, include_detector_matrices=False, include_readouts=True, matrix_element_tolerance=0.0, overwrite=False)

Export this design as a versioned JSON/JSONL data bundle.

The export stores the analytical jump structure by default: dark detectors as coefficient combinations and recycled/targeted local matrices in COO form. Full sparse matrices are optional and stored as SciPy .npz files when requested.

to_rich()

__init__(problem, workflow, lindblad_problem, detector_operators=(), detector_operator_names=(), detector_terms=())

class qlinks.open_system.CageLindbladDetectorOperators(operators, names, terms=())

Bases: object

Named local operators used to build dark detector combinations.

operators are the matrices O_i supplied to the dark-detector solver, while names are the corresponding labels used in workflow/readout reports.

operators: tuple[Any, ...]

names: tuple[str, ...]

terms: tuple[LocalTermDescriptor, ...]

to_summary_dict()

__init__(operators, names, terms=())

class qlinks.open_system.CageLindbladExportResult(path, manifest_path)

Bases: object

Paths written by export_cage_lindblad_design().

path: Path

manifest_path: Path

to_summary_dict()

__init__(path, manifest_path)

qlinks.open_system.CageLindbladWorkflowReport

alias of DegenerateCageJumpDesignWorkflowReport

class qlinks.open_system.CommonKernelHamiltonianInvariantSectorReport(dim, n_jumps, manifold_dimension, common_jump_kernel_dimension, bad_common_jump_kernel_dimension, bad_h_invariant_kernel_dimension, h_leakage_norm_from_bad_kernel, h_leakage_norm_from_invariant_kernel, h_target_coupling_norm_from_bad_kernel, h_bad_block_norm, h_invariant_block_eigenvalues, bad_h_invariant_kernel_iprs, target_in_common_jump_kernel, kernel_tolerance)

Bases: object

Cheap obstruction diagnostic inside the common jump kernel.

The common jump-kernel condition cap_mu ker J_mu = M is sufficient but stronger than necessary. A complement vector in the common kernel is only a Hamiltonian-stable dark obstruction if its whole Krylov orbit under H remains inside the common jump kernel. This report computes the largest such subspace inside (cap_mu ker J_mu) cap M^perp using a small dense nullspace problem.

dim: int

n_jumps: int

manifold_dimension: int

common_jump_kernel_dimension: int

bad_common_jump_kernel_dimension: int

bad_h_invariant_kernel_dimension: int

h_leakage_norm_from_bad_kernel: float

h_leakage_norm_from_invariant_kernel: float

h_target_coupling_norm_from_bad_kernel: float

h_bad_block_norm: float

h_invariant_block_eigenvalues: tuple[complex, ...]

bad_h_invariant_kernel_iprs: tuple[float, ...]

target_in_common_jump_kernel: bool

kernel_tolerance: float

property has_bad_common_kernel: bool

property has_bad_h_invariant_kernel: bool

property likely_attractive_by_h_invariant_kernel: bool

to_summary_dict()

to_rich()

__init__(dim, n_jumps, manifold_dimension, common_jump_kernel_dimension, bad_common_jump_kernel_dimension, bad_h_invariant_kernel_dimension, h_leakage_norm_from_bad_kernel, h_leakage_norm_from_invariant_kernel, h_target_coupling_norm_from_bad_kernel, h_bad_block_norm, h_invariant_block_eigenvalues, bad_h_invariant_kernel_iprs, target_in_common_jump_kernel, kernel_tolerance)

class qlinks.open_system.DarkDetectorMatrixReadout(detector_index, label, coefficients, operator_names, terms, action_residual, relative_action_residual, operator_frobenius_norm, coefficient_ipr, effective_operator_count)

Bases: object

Coefficient readout for a collective dark detector.

This intentionally does not store a dense global matrix. The detector is a linear combination of the supplied detector operator family; the readout is meant for inspecting the algebraic structure of that combination.

detector_index: int

label: str

coefficients: ndarray[tuple[Any, ...], dtype[complex128]]

operator_names: tuple[str, ...]

terms: tuple[DarkOperatorTerm, ...]

action_residual: float

relative_action_residual: float

operator_frobenius_norm: float

coefficient_ipr: float

effective_operator_count: float

property n_terms: int

property is_local_matrix_readout: bool

Whether this readout can be drawn by LocalBasisGridVisualizer.

to_summary_dict()

__init__(detector_index, label, coefficients, operator_names, terms, action_residual, relative_action_residual, operator_frobenius_norm, coefficient_ipr, effective_operator_count)

class qlinks.open_system.DarkManifoldDiagnostics(dim, n_jumps, manifold_dimension, hamiltonian_closure_residual, target_jump_residuals, max_target_jump_residual, target_density_liouvillian_residual, inflow_norm, common_jump_kernel_dimension, target_projection_onto_common_kernel, target_distance_from_common_kernel, target_in_common_jump_kernel, bad_common_jump_kernel_dimension, bad_common_jump_kernel_iprs, internal_hamiltonian_eigenvalues, expected_internal_liouvillian_eigenvalues, expected_internal_zero_mode_count, expected_internal_peripheral_mode_count, liouvillian_zero_mode_count, liouvillian_zero_mode_count_is_lower_bound, liouvillian_spectral_gap, liouvillian_decay_gap, liouvillian_peripheral_mode_count, liouvillian_spectrum_method, liouvillian_eigenvalues, matched_internal_nondecaying_mode_count, missing_internal_nondecaying_mode_count, extra_nondecaying_mode_count, extra_zero_mode_count, external_decay_gap, likely_attractive_dark_manifold)

Bases: object

Diagnostics for an attractive dark manifold/DFS target.

The target is a column-orthonormal basis M and the target projector is P_M = M M†. Unlike DarkSubspaceDiagnostics, this report does not expect a unique pure steady state. Internal zero or imaginary-axis Liouvillian modes generated by the projected Hamiltonian on the target manifold are treated as expected modes; only additional non-decaying modes outside the target manifold are flagged as obstructions.

dim: int

n_jumps: int

manifold_dimension: int

hamiltonian_closure_residual: float

target_jump_residuals: tuple[float, ...]

max_target_jump_residual: float

target_density_liouvillian_residual: float

inflow_norm: float

common_jump_kernel_dimension: int

target_projection_onto_common_kernel: float

target_distance_from_common_kernel: float

target_in_common_jump_kernel: bool

bad_common_jump_kernel_dimension: int

bad_common_jump_kernel_iprs: tuple[float, ...]

internal_hamiltonian_eigenvalues: tuple[complex, ...]

expected_internal_liouvillian_eigenvalues: tuple[complex, ...]

expected_internal_zero_mode_count: int

expected_internal_peripheral_mode_count: int

liouvillian_zero_mode_count: int | None

liouvillian_zero_mode_count_is_lower_bound: bool

liouvillian_spectral_gap: float | None

liouvillian_decay_gap: float | None

liouvillian_peripheral_mode_count: int | None

liouvillian_spectrum_method: str

liouvillian_eigenvalues: tuple[complex, ...]

matched_internal_nondecaying_mode_count: int | None

missing_internal_nondecaying_mode_count: int | None

extra_nondecaying_mode_count: int | None

extra_zero_mode_count: int | None

external_decay_gap: float | None

likely_attractive_dark_manifold: bool | None

to_summary_dict()

to_rich()

__init__(dim, n_jumps, manifold_dimension, hamiltonian_closure_residual, target_jump_residuals, max_target_jump_residual, target_density_liouvillian_residual, inflow_norm, common_jump_kernel_dimension, target_projection_onto_common_kernel, target_distance_from_common_kernel, target_in_common_jump_kernel, bad_common_jump_kernel_dimension, bad_common_jump_kernel_iprs, internal_hamiltonian_eigenvalues, expected_internal_liouvillian_eigenvalues, expected_internal_zero_mode_count, expected_internal_peripheral_mode_count, liouvillian_zero_mode_count, liouvillian_zero_mode_count_is_lower_bound, liouvillian_spectral_gap, liouvillian_decay_gap, liouvillian_peripheral_mode_count, liouvillian_spectrum_method, liouvillian_eigenvalues, matched_internal_nondecaying_mode_count, missing_internal_nondecaying_mode_count, extra_nondecaying_mode_count, extra_zero_mode_count, external_decay_gap, likely_attractive_dark_manifold)

class qlinks.open_system.DarkOperatorTerm(operator_index, operator_name, coefficient, weight)

Bases: object

One non-negligible coefficient in a dark detector candidate.

operator_index: int

operator_name: str

coefficient: complex

weight: float

to_summary_dict()

__init__(operator_index, operator_name, coefficient, weight)

class qlinks.open_system.DarkSubspaceDiagnostics(dim, n_jumps, target_norm, target_jump_residuals, max_target_jump_residual, target_liouvillian_residual, common_jump_kernel_dimension, target_projection_onto_common_kernel, target_distance_from_common_kernel, target_in_common_jump_kernel, bad_common_jump_kernel_dimension, bad_common_jump_kernel_iprs, liouvillian_zero_mode_count, liouvillian_zero_mode_count_is_lower_bound, liouvillian_spectral_gap, liouvillian_decay_gap, liouvillian_peripheral_mode_count, liouvillian_spectrum_method, liouvillian_eigenvalues, likely_unique_dark_state)

Bases: object

Diagnostics for whether a dark target is unique/attractive.

dim: int

n_jumps: int

target_norm: float

target_jump_residuals: tuple[float, ...]

max_target_jump_residual: float

target_liouvillian_residual: float

common_jump_kernel_dimension: int

target_projection_onto_common_kernel: float

target_distance_from_common_kernel: float

target_in_common_jump_kernel: bool

bad_common_jump_kernel_dimension: int

bad_common_jump_kernel_iprs: tuple[float, ...]

liouvillian_zero_mode_count: int | None

liouvillian_zero_mode_count_is_lower_bound: bool

liouvillian_spectral_gap: float | None

liouvillian_decay_gap: float | None

liouvillian_peripheral_mode_count: int | None

liouvillian_spectrum_method: str

liouvillian_eigenvalues: tuple[complex, ...]

likely_unique_dark_state: bool | None

to_summary_dict()

to_rich()

__init__(dim, n_jumps, target_norm, target_jump_residuals, max_target_jump_residual, target_liouvillian_residual, common_jump_kernel_dimension, target_projection_onto_common_kernel, target_distance_from_common_kernel, target_in_common_jump_kernel, bad_common_jump_kernel_dimension, bad_common_jump_kernel_iprs, liouvillian_zero_mode_count, liouvillian_zero_mode_count_is_lower_bound, liouvillian_spectral_gap, liouvillian_decay_gap, liouvillian_peripheral_mode_count, liouvillian_spectrum_method, liouvillian_eigenvalues, likely_unique_dark_state)

class qlinks.open_system.DenseLindbladOperators(backend, hamiltonian, jumps, jump_daggers, jump_dagger_jumps)

Bases: object

Dense Lindblad operators prepared for repeated RHS evaluations.

backend: OpenSystemBackend

hamiltonian: Any

jumps: tuple[Any, ...]

jump_daggers: tuple[Any, ...]

jump_dagger_jumps: tuple[Any, ...]

__init__(backend, hamiltonian, jumps, jump_daggers, jump_dagger_jumps)

class qlinks.open_system.DensityMatrixVerification(trace, trace_error, hermiticity_error, min_eigenvalue, purity, fidelity_with_target, is_hermitian, is_trace_one, is_positive_semidefinite, is_density_matrix)

Bases: object

Numerical checks for a candidate density matrix.

trace

Matrix trace.

Type:

complex

trace_error

Absolute error of the trace from one.

Type:

float

hermiticity_error

Frobenius norm of rho - rho^dagger.

Type:

float

min_eigenvalue

Smallest Hermitian eigenvalue after symmetrization.

Type:

float

purity

Tr(rho^2).

Type:

float

fidelity_with_target

Optional fidelity <psi|rho|psi>.

Type:

float | None

is_hermitian

Whether the Hermiticity check passes.

Type:

bool

is_trace_one

Whether the trace-one check passes.

Type:

bool

is_positive_semidefinite

Whether the minimum eigenvalue is above -atol.

Type:

bool

is_density_matrix

Combined validity flag.

Type:

bool

trace: complex

trace_error: float

hermiticity_error: float

min_eigenvalue: float

purity: float

fidelity_with_target: float | None

is_hermitian: bool

is_trace_one: bool

is_positive_semidefinite: bool

is_density_matrix: bool

__init__(trace, trace_error, hermiticity_error, min_eigenvalue, purity, fidelity_with_target, is_hermitian, is_trace_one, is_positive_semidefinite, is_density_matrix)

class qlinks.open_system.DressedManifoldDarkDetectorCandidate(candidate_index, detector_index, detector_name, left_multiplier_index, left_multiplier_name, dark_residual, relative_dark_residual, inflow_norm, jump_frobenius_norm, target_block_norm, detector_action_residual, detector_relative_action_residual)

Bases: object

One dressed jump candidate J = V D for a dark manifold.

D is a collective detector satisfying D P_M ~= 0. The left multiplier V is tested as a possible recycler/inflow operator.

candidate_index: int

detector_index: int

detector_name: str

left_multiplier_index: int

left_multiplier_name: str

dark_residual: float

relative_dark_residual: float

inflow_norm: float

jump_frobenius_norm: float

target_block_norm: float

detector_action_residual: float

detector_relative_action_residual: float

property is_dark: bool

property has_inflow: bool

to_summary_dict()

__init__(candidate_index, detector_index, detector_name, left_multiplier_index, left_multiplier_name, dark_residual, relative_dark_residual, inflow_norm, jump_frobenius_norm, target_block_norm, detector_action_residual, detector_relative_action_residual)

class qlinks.open_system.DressedManifoldDarkDetectorReport(manifold_dimension, hilbert_dimension, gram_residual, detector_names, left_multiplier_names, dark_tolerance, inflow_tolerance, candidates)

Bases: object

Report for paper-style dressed jumps J = V D.

The supplied detector coefficients define operators D_alpha that are expected to annihilate the target manifold. This report tests whether left multipliers V_beta turn those dark detectors into jump operators with direct inflow into the manifold.

manifold_dimension: int

hilbert_dimension: int

gram_residual: float

detector_names: tuple[str, ...]

left_multiplier_names: tuple[str, ...]

dark_tolerance: float

inflow_tolerance: float

candidates: tuple[DressedManifoldDarkDetectorCandidate, ...]

property n_detectors: int

property n_left_multipliers: int

property n_candidates: int

property n_dark_candidates: int

property n_candidates_with_inflow: int

property has_attractive_candidates: bool

property best_inflow_norm: float

to_summary_dict()

to_rich(*, max_candidates=24)

__init__(manifold_dimension, hilbert_dimension, gram_residual, detector_names, left_multiplier_names, dark_tolerance, inflow_tolerance, candidates)

class qlinks.open_system.EnsembleResult(times, rho_t, trajectories=None, state_snapshots=None, target_fidelities=None)

Bases: object

Ensemble-averaged MCWF result.

times: ndarray[tuple[Any, ...], dtype[float64]]

rho_t: list[ndarray[tuple[Any, ...], dtype[complex128]]]

trajectories: tuple[TrajectoryResult, ...] | None

state_snapshots: tuple[ndarray[tuple[Any, ...], dtype[complex128]], ...] | None

target_fidelities: dict[str, ndarray[tuple[Any, ...], dtype[float64]]] | None

__init__(times, rho_t, trajectories=None, state_snapshots=None, target_fidelities=None)

class qlinks.open_system.EvolutionDiagnostics(trace_errors, hermiticity_errors, min_eigenvalues, purities, fidelities, lindblad_residuals, times=None, source='density_matrices', density_check_mode='full', trajectory_counts=None, state_norm_errors=None)

Bases: object

Diagnostics for density-matrix or MCWF evolution output.

trace_errors

Absolute errors of Tr(rho) from one.

Type:

numpy.ndarray

hermiticity_errors

Frobenius norm of anti-Hermitian parts.

Type:

numpy.ndarray

min_eigenvalues

Smallest density-matrix eigenvalue at each time.

Type:

numpy.ndarray

purities

Tr(rho^2) values.

Type:

numpy.ndarray

fidelities

Optional fidelity with a target state/density matrix.

Type:

numpy.ndarray | None

lindblad_residuals

Optional norm of the Lindblad RHS at each time.

Type:

numpy.ndarray | None

times

Optional time grid.

Type:

numpy.ndarray | None

source

Description of the analyzed data source.

Type:

str

density_check_mode

Density check strategy used by the analyzer.

Type:

str

trajectory_counts

Optional number of trajectories per time point.

Type:

numpy.ndarray | None

state_norm_errors

Optional norm errors for pure-state trajectories.

Type:

numpy.ndarray | None

trace_errors: ndarray

hermiticity_errors: ndarray

min_eigenvalues: ndarray

purities: ndarray

fidelities: ndarray | None

lindblad_residuals: ndarray | None

times: ndarray | None

source: str

density_check_mode: str

trajectory_counts: ndarray | None

state_norm_errors: ndarray | None

__init__(trace_errors, hermiticity_errors, min_eigenvalues, purities, fidelities, lindblad_residuals, times=None, source='density_matrices', density_check_mode='full', trajectory_counts=None, state_norm_errors=None)

class qlinks.open_system.JumpSpanDiagnostics(dim, n_jumps, span_rank, dependent_jump_count, compression_ratio, rank_tolerance, absolute_rank_threshold, gram_eigenvalues, effective_rank, participation_rank, total_jump_nnz, span_matrix_nnz, max_normalized_overlap, mean_normalized_overlap)

Bases: object

Hilbert-Schmidt span diagnostics for a Lindblad jump list.

dim: int

n_jumps: int

span_rank: int

dependent_jump_count: int

compression_ratio: float

rank_tolerance: float

absolute_rank_threshold: float

gram_eigenvalues: ndarray

effective_rank: float

participation_rank: float

total_jump_nnz: int | None

span_matrix_nnz: int | None

max_normalized_overlap: float

mean_normalized_overlap: float

property has_exact_dependencies: bool

to_summary_dict(*, n_eigenvalues=8)

Return a compact JSON-friendly benchmark summary.

__init__(dim, n_jumps, span_rank, dependent_jump_count, compression_ratio, rank_tolerance, absolute_rank_threshold, gram_eigenvalues, effective_rank, participation_rank, total_jump_nnz, span_matrix_nnz, max_normalized_overlap, mean_normalized_overlap)

class qlinks.open_system.LindbladEvolutionOptions(method='auto', backend='scipy', rk4_step_policy='adaptive', max_dimension_for_liouvillian=400, max_dimension_for_krylov=400, max_rk4_step_scale=0.05, adaptive_tolerance=1e-08, min_substeps=1, max_substeps=1024, enforce_hermiticity=True, renormalize_trace=True, check_density_matrix=True)

Bases: object

Options controlling Lindblad time evolution.

method

Solver method. "auto" chooses between Krylov and RK4 variants from system size and backend capabilities.

Type:

Literal[‘auto’, ‘krylov’, ‘rk4_matrix’, ‘rk4_sparse_matrix’, ‘rk4_liouville’]

backend

Backend used for dense/sparse array operations.

Type:

Literal[‘scipy’, ‘cupy’]

rk4_step_policy

Policy when the requested time grid is too coarse for RK4 according to the Lindblad scale estimate.

Type:

Literal[‘raise’, ‘warn’, ‘adaptive’, ‘ignore’]

max_dimension_for_liouvillian

Largest Hilbert dimension for explicit Liouville-space RK4 in "auto" mode.

Type:

int

max_dimension_for_krylov

Largest Hilbert dimension for Krylov expm_multiply in "auto" mode.

Type:

int

max_rk4_step_scale

Maximum recommended RK4 step times estimated Lindblad scale.

Type:

float

adaptive_tolerance

Relative tolerance used by adaptive RK4 step subdivision.

Type:

float

min_substeps

Minimum RK4 substeps per interval.

Type:

int

max_substeps

Maximum RK4 substeps per interval.

Type:

int

enforce_hermiticity

Symmetrize density matrices after each interval.

Type:

bool

renormalize_trace

Renormalize trace after each interval.

Type:

bool

check_density_matrix

Record density-matrix diagnostics after evolution steps.

Type:

bool

method: Literal['auto', 'krylov', 'rk4_matrix', 'rk4_sparse_matrix', 'rk4_liouville']

backend: Literal['scipy', 'cupy']

rk4_step_policy: Literal['raise', 'warn', 'adaptive', 'ignore']

max_dimension_for_liouvillian: int

max_dimension_for_krylov: int

max_rk4_step_scale: float

adaptive_tolerance: float

min_substeps: int

max_substeps: int

enforce_hermiticity: bool

renormalize_trace: bool

check_density_matrix: bool

__init__(method='auto', backend='scipy', rk4_step_policy='adaptive', max_dimension_for_liouvillian=400, max_dimension_for_krylov=400, max_rk4_step_scale=0.05, adaptive_tolerance=1e-08, min_substeps=1, max_substeps=1024, enforce_hermiticity=True, renormalize_trace=True, check_density_matrix=True)

class qlinks.open_system.LindbladEvolutionResult(times, density_matrices, method, backend, diagnostics, n_substeps_per_interval)

Bases: object

Result returned by Lindblad time-evolution solvers.

times

Time grid used by the evolution.

Type:

numpy.ndarray

density_matrices

Density matrix at each time.

Type:

list[Any]

method

Concrete solver method used after resolving "auto".

Type:

str

backend

Backend name.

Type:

str

diagnostics

Per-time density-matrix diagnostics when enabled.

Type:

list[Any]

n_substeps_per_interval

RK4 substep counts for each interval, or an empty tuple for non-RK4 methods.

Type:

tuple[int, …]

times: ndarray

density_matrices: list[Any]

method: str

backend: str

diagnostics: list[Any]

n_substeps_per_interval: tuple[int, ...]

__init__(times, density_matrices, method, backend, diagnostics, n_substeps_per_interval)

class qlinks.open_system.LindbladFinalStateVerification(density_matrix, lindblad_residual, relative_lindblad_residual)

Bases: object

Verification of a final Lindblad density matrix.

density_matrix

Basic density-matrix validity diagnostics.

Type:

qlinks.open_system.diagnostics.DensityMatrixVerification

lindblad_residual

Norm of the Lindblad RHS evaluated at the final state.

Type:

float

relative_lindblad_residual

Residual normalized by the density-matrix norm scale.

Type:

float

density_matrix: DensityMatrixVerification

lindblad_residual: float

relative_lindblad_residual: float

__init__(density_matrix, lindblad_residual, relative_lindblad_residual)

class qlinks.open_system.LindbladProblem(*, hamiltonian, jumps, backend='scipy')

Bases: object

Reusable Lindblad problem with cached prepared operators.

The problem stores a Hamiltonian and jump list, prepares dense/sparse operator bundles lazily, and exposes RHS, Liouvillian, and evolution methods that reuse those caches.

__init__(*, hamiltonian, jumps, backend='scipy')

property dim: int

property dense_operators: DenseLindbladOperators

property rk4_scale: float

sparse_operators(*, sparse_format='csc')

build_liouvillian(*, sparse_format='csc')

rhs(density_matrix)

sparse_rhs(density_matrix)

evolve(density_matrix_initial, times, *, options=None)

class qlinks.open_system.LocalMatrixUnitTerm(coefficient, target_pattern, source_pattern)

Bases: object

One local matrix-unit term coefficient * |target><source|.

coefficient: complex

target_pattern: tuple[int, ...]

source_pattern: tuple[int, ...]

__init__(coefficient, target_pattern, source_pattern)

class qlinks.open_system.LocalOperatorMatrixReadout(label, source, variable_indices, local_patterns, local_operator, metadata=())

Bases: object

Local matrix readout compatible with LocalBasisGridVisualizer.

The visualizer only requires variable_indices, local_patterns, and a local_operator/density_matrix attribute. This readout carries the extra candidate metadata needed to interpret selected Lindblad recyclers and targeted completion operators in notebooks.

label: str

source: str

variable_indices: tuple[int, ...]

local_patterns: tuple[tuple[int, ...], ...]

local_operator: ndarray[tuple[Any, ...], dtype[complex128]]

metadata: tuple[tuple[str, object], ...]

property local_dim: int

property is_local_matrix_readout: bool

Whether this readout can be drawn by LocalBasisGridVisualizer.

property shape: tuple[int, int]

property nnz: int

nonzero_matrix_elements(*, tolerance=0.0)

Return (target_index, source_index, value) nonzero local entries.

to_summary_dict()

__init__(label, source, variable_indices, local_patterns, local_operator, metadata=())

class qlinks.open_system.LocalRecyclingBuildResult(scan_results, selections)

Bases: object

Selected recycling jumps from several local regions.

scan_results: tuple[LocalRecyclingScanResult, ...]

selections: tuple[LocalRecyclingSelection, ...]

property jumps: tuple[csr_array, ...]

property n_jumps: int

property variable_indices: tuple[tuple[int, ...], ...]

property alpha_beta_indices: tuple[tuple[int, int], ...]

to_subspace_support_report()

Return a local-support/nullity report for the scanned regions.

__init__(scan_results, selections)

class qlinks.open_system.LocalRecyclingCandidate(variable_indices, alpha_index, beta_index, jump, target_residual, inflow_norm, outflow_norm, projector_commutator_norm, local_alpha_vector, local_beta_vector, local_operator=None)

Bases: object

One embedded local RDM recycling jump candidate.

Most candidates are rank-one maps |alpha><beta| between the local support and null spaces of the target reduced density matrix. A compressed block-reset candidate can instead carry a higher-rank local_operator that maps several null directions into the local target support with one Lindblad channel. The local_alpha_vector and local_beta_vector fields are retained for rank-one readouts and hold representative support and null vectors for block-reset candidates.

variable_indices: tuple[int, ...]

alpha_index: int

beta_index: int

jump: csr_array

target_residual: float

inflow_norm: float

outflow_norm: float

projector_commutator_norm: float

local_alpha_vector: ndarray[tuple[Any, ...], dtype[complex128]]

local_beta_vector: ndarray[tuple[Any, ...], dtype[complex128]]

local_operator: ndarray[tuple[Any, ...], dtype[complex128]] | None

property is_dark: bool

property has_inflow: bool

__init__(variable_indices, alpha_index, beta_index, jump, target_residual, inflow_norm, outflow_norm, projector_commutator_norm, local_alpha_vector, local_beta_vector, local_operator=None)

class qlinks.open_system.LocalRecyclingScanResult(reduced_density_matrix, candidates)

Bases: object

Candidate jumps from one local region.

reduced_density_matrix: LocalReducedDensityMatrix

candidates: tuple[LocalRecyclingCandidate, ...]

property n_candidates: int

property best_candidates: tuple[LocalRecyclingCandidate, ...]

__init__(reduced_density_matrix, candidates)

class qlinks.open_system.LocalRecyclingSelection(candidate, two_pattern_structure, score)

Bases: object

Selected recycling candidate plus optional detected structure.

candidate: LocalRecyclingCandidate

two_pattern_structure: TwoPatternRecyclingStructure | None

score: tuple[float, ...]

__init__(candidate, two_pattern_structure, score)

class qlinks.open_system.LocalReducedDensityMatrix(variable_indices, local_patterns, density_matrix, eigenvalues, support_basis, null_basis)

Bases: object

Reduced density matrix of a pure state or subspace on selected variables.

variable_indices: tuple[int, ...]

local_patterns: tuple[tuple[int, ...], ...]

density_matrix: ndarray[tuple[Any, ...], dtype[complex128]]

eigenvalues: ndarray[tuple[Any, ...], dtype[float64]]

support_basis: ndarray[tuple[Any, ...], dtype[complex128]]

null_basis: ndarray[tuple[Any, ...], dtype[complex128]]

property local_dim: int

property support_rank: int

property nullity: int

__init__(variable_indices, local_patterns, density_matrix, eigenvalues, support_basis, null_basis)

class qlinks.open_system.LocalSubspaceSupportReport(entries)

Bases: object

Local-support report explaining manifold recycler availability.

entries: tuple[LocalSubspaceSupportReportEntry, ...]

property n_regions: int

property n_regions_with_nullity: int

property n_regions_with_selected_recyclers: int

property total_candidate_jumps: int

property total_selected_jumps: int

property all_regions_have_full_local_support: bool

to_summary_dict()

to_rich(*, max_regions=24)

__init__(entries)

class qlinks.open_system.LocalSubspaceSupportReportEntry(variable_indices, local_dim, support_rank, nullity, support_trace, min_nonzero_eigenvalue, max_eigenvalue, n_candidate_jumps, n_selected_jumps)

Bases: object

Local support/nullity diagnostics for one candidate region.

The local RDM is the reduced density matrix of the normalized projector onto a target subspace. nullity is the number of local source directions annihilated by the target manifold. If it is zero, no strictly local right-detector D_R on this region can satisfy D_R P_M = 0.

variable_indices: tuple[int, ...]

local_dim: int

support_rank: int

nullity: int

support_trace: float

min_nonzero_eigenvalue: float | None

max_eigenvalue: float | None

n_candidate_jumps: int

n_selected_jumps: int

property n_variables: int

property has_local_null_detector: bool

property has_selected_recycler: bool

property parent_detector_directions: int

property minimum_block_reset_channels: int

property status: str

to_summary_dict()

__init__(variable_indices, local_dim, support_rank, nullity, support_trace, min_nonzero_eigenvalue, max_eigenvalue, n_candidate_jumps, n_selected_jumps)

class qlinks.open_system.ManifoldDarkOperatorBasisReport(operator_names, manifold_dimension, hilbert_dimension, gram_residual, constraint_matrix_shape, constraint_rank, detector_nullity, singular_values, cutoff, candidates, tolerance, candidate_strategy='svd_basis')

Bases: object

Nullspace report for collective local operators dark on a manifold.

Given an operator basis O_a and target manifold basis Q, this report solves

sum_a c_a O_a Q = 0.

A nonzero solution is a collective dark detector for the supplied manifold. This is strictly more general than the local RDM null-space test: each individual region may have full local support, while a sum of local terms can still annihilate the manifold by cancellation.

operator_names: tuple[str, ...]

manifold_dimension: int

hilbert_dimension: int

gram_residual: float

constraint_matrix_shape: tuple[int, int]

constraint_rank: int

detector_nullity: int

singular_values: ndarray[tuple[Any, ...], dtype[float64]]

cutoff: float

candidates: tuple[ManifoldDarkOperatorCandidate, ...]

tolerance: float

candidate_strategy: str

property n_operators: int

property has_dark_detectors: bool

detector_readout(detector_index=0)

Return a coefficient readout for one dark detector candidate.

detector_readouts(*, max_readouts=None)

Return coefficient readouts for reported dark detector candidates.

to_summary_dict()

to_rich(*, max_candidates=8, max_terms=8)

__init__(operator_names, manifold_dimension, hilbert_dimension, gram_residual, constraint_matrix_shape, constraint_rank, detector_nullity, singular_values, cutoff, candidates, tolerance, candidate_strategy='svd_basis')

class qlinks.open_system.ManifoldDarkOperatorCandidate(candidate_index, coefficients, action_residual, relative_action_residual, operator_frobenius_norm, coefficient_ipr, effective_operator_count, terms)

Bases: object

Linear-combination detector satisfying D P_M ~= 0.

candidate_index: int

coefficients: ndarray[tuple[Any, ...], dtype[complex128]]

action_residual: float

relative_action_residual: float

operator_frobenius_norm: float

coefficient_ipr: float

effective_operator_count: float

terms: tuple[DarkOperatorTerm, ...]

property n_terms: int

property is_dark: bool

to_summary_dict()

__init__(candidate_index, coefficients, action_residual, relative_action_residual, operator_frobenius_norm, coefficient_ipr, effective_operator_count, terms)

class qlinks.open_system.McwfOptions(backend='scipy', n_trajectories=128, seed=None, return_backend_arrays=False, store_states=True, store_trajectories=False, normalize_each_step=True, max_jump_probability=0.1, prefer_sparse_operators=True, prefer_sparse_rate_evaluator=True, use_total_rate_first=True, compress_collinear_jumps=False, jump_compression_tolerance=1e-10, store_density_matrices=True, store_state_snapshots=False, trajectory_chunk_size=None, trajectory_chunk_workers=None, adaptive_trajectory_block_size=None, fidelity_targets=None, timing_collector=None, adaptive_time_step=False, adaptive_safety_factor=0.8, min_step_size=1e-12, max_substeps_per_interval=100000)

Bases: object

Options for Monte Carlo wave-function sampling.

backend: Literal['scipy', 'cupy']

n_trajectories: int

seed: int | None

return_backend_arrays: bool

store_states: bool

store_trajectories: bool

normalize_each_step: bool

max_jump_probability: float

prefer_sparse_operators: bool

prefer_sparse_rate_evaluator: bool

use_total_rate_first: bool

compress_collinear_jumps: bool

jump_compression_tolerance: float

store_density_matrices: bool

store_state_snapshots: bool

trajectory_chunk_size: int | None

trajectory_chunk_workers: int | None

adaptive_trajectory_block_size: int | None

fidelity_targets: Mapping[str, Any] | None

timing_collector: MutableMapping[str, float] | None

adaptive_time_step: bool

adaptive_safety_factor: float

min_step_size: float

max_substeps_per_interval: int

validate()

Validate MCWF time-step control options.

__init__(backend='scipy', n_trajectories=128, seed=None, return_backend_arrays=False, store_states=True, store_trajectories=False, normalize_each_step=True, max_jump_probability=0.1, prefer_sparse_operators=True, prefer_sparse_rate_evaluator=True, use_total_rate_first=True, compress_collinear_jumps=False, jump_compression_tolerance=1e-10, store_density_matrices=True, store_state_snapshots=False, trajectory_chunk_size=None, trajectory_chunk_workers=None, adaptive_trajectory_block_size=None, fidelity_targets=None, timing_collector=None, adaptive_time_step=False, adaptive_safety_factor=0.8, min_step_size=1e-12, max_substeps_per_interval=100000)

class qlinks.open_system.MonitorKernelClosureDiagnostics(dim, n_monitors, closure_order, max_target_monitor_residual, target_monitor_residuals, monitor_kernel_dimension, target_projection_onto_monitor_kernel, target_distance_from_monitor_kernel, target_in_monitor_kernel, bad_monitor_kernel_dimension, bad_monitor_kernel_iprs, bad_kernel_hamiltonian_leakage_norms, min_bad_kernel_hamiltonian_leakage_norm, mean_bad_kernel_hamiltonian_leakage_norm, max_bad_kernel_hamiltonian_leakage_norm, closure_kernel_dimension, target_projection_onto_closure_kernel, target_distance_from_closure_kernel, target_in_closure_kernel, bad_closure_kernel_dimension, bad_closure_kernel_iprs)

Bases: object

Diagnostics for monitor-kernel closure under Hamiltonian mixing.

The monitor kernel is intersection_i ker(M_i). For a monitor-recycler design L_i = V_i M_i, this kernel is always contained in the jump kernel and therefore measures what the recyclers cannot see directly.

The first Hamiltonian-closure layer appends the constraints M_i H. If this sharply reduces the bad kernel, attraction is possible but can be slow because the Hamiltonian must rotate bad monitor-kernel states into the monitored subspace before dissipation acts.

dim: int

n_monitors: int

closure_order: int

max_target_monitor_residual: float

target_monitor_residuals: tuple[float, ...]

monitor_kernel_dimension: int

target_projection_onto_monitor_kernel: float

target_distance_from_monitor_kernel: float

target_in_monitor_kernel: bool

bad_monitor_kernel_dimension: int

bad_monitor_kernel_iprs: tuple[float, ...]

bad_kernel_hamiltonian_leakage_norms: tuple[float, ...]

min_bad_kernel_hamiltonian_leakage_norm: float | None

mean_bad_kernel_hamiltonian_leakage_norm: float | None

max_bad_kernel_hamiltonian_leakage_norm: float | None

closure_kernel_dimension: int

target_projection_onto_closure_kernel: float

target_distance_from_closure_kernel: float

target_in_closure_kernel: bool

bad_closure_kernel_dimension: int

bad_closure_kernel_iprs: tuple[float, ...]

to_summary_dict()

to_rich()

__init__(dim, n_monitors, closure_order, max_target_monitor_residual, target_monitor_residuals, monitor_kernel_dimension, target_projection_onto_monitor_kernel, target_distance_from_monitor_kernel, target_in_monitor_kernel, bad_monitor_kernel_dimension, bad_monitor_kernel_iprs, bad_kernel_hamiltonian_leakage_norms, min_bad_kernel_hamiltonian_leakage_norm, mean_bad_kernel_hamiltonian_leakage_norm, max_bad_kernel_hamiltonian_leakage_norm, closure_kernel_dimension, target_projection_onto_closure_kernel, target_distance_from_closure_kernel, target_in_closure_kernel, bad_closure_kernel_dimension, bad_closure_kernel_iprs)

class qlinks.open_system.OpenSystemBackend(name, array_module, sparse_module, sparse_linalg_module, supports_expm_multiply)

Bases: object

Array/sparse backend bundle for open-system solvers.

name

Backend name.

Type:

Literal[‘scipy’, ‘cupy’]

array_module

Dense array module, such as NumPy or CuPy.

Type:

Any

sparse_module

Sparse matrix module.

Type:

Any

sparse_linalg_module

Sparse linear-algebra module, if available.

Type:

Any | None

supports_expm_multiply

Whether the backend can run Krylov expm_multiply evolution.

Type:

bool

name: Literal['scipy', 'cupy']

array_module: Any

sparse_module: Any

sparse_linalg_module: Any | None

supports_expm_multiply: bool

asarray(value, *, dtype=<class 'numpy.complex128'>)

to_numpy(value)

sparse_identity(dim, *, format='csr', dtype=<class 'numpy.complex128'>)

sparse_kron(left, right, *, format='csr')

norm(value)

__init__(name, array_module, sparse_module, sparse_linalg_module, supports_expm_multiply)

class qlinks.open_system.RecycledManifoldCandidateFamilyKernelReport(manifold_dimension, hilbert_dimension, candidate_report, candidate_report_was_expanded, dark_tolerance, inflow_tolerance, candidate_jumps, diagnostics, candidate_jump_count=None, candidate_total_jump_nnz=None, candidate_max_jump_nnz=None)

Bases: object

Common-kernel diagnostic for an entire recycled-detector family.

This report answers a different question from greedy subset selection: if all eligible local candidates are used as jumps, does the family itself remove the complement common jump kernel? If the bad kernel remains nonzero for the full family, no subset of that candidate family can remove it.

manifold_dimension: int

hilbert_dimension: int

candidate_report: RecycledManifoldDarkDetectorReport

candidate_report_was_expanded: bool

dark_tolerance: float

inflow_tolerance: float

candidate_jumps: tuple[csr_array, ...]

diagnostics: Any

candidate_jump_count: int | None

candidate_total_jump_nnz: int | None

candidate_max_jump_nnz: int | None

property n_candidate_jumps: int

property n_reported_candidates: int

property n_nonzero_candidates: int

property n_tested_candidates: int

property candidate_report_is_truncated: bool

property total_jump_nnz: int

property max_jump_nnz: int

property family_bad_common_jump_kernel_dimension: int

property family_common_jump_kernel_dimension: int

property family_inflow_norm: float

property family_kernel_method: str

property complement_common_kernel_removed: bool

property bad_kernel_iprs: tuple[float, ...]

property bad_kernel_ipr_min: float | None

property bad_kernel_ipr_max: float | None

to_summary_dict()

to_rich()

__init__(manifold_dimension, hilbert_dimension, candidate_report, candidate_report_was_expanded, dark_tolerance, inflow_tolerance, candidate_jumps, diagnostics, candidate_jump_count=None, candidate_total_jump_nnz=None, candidate_max_jump_nnz=None)

class qlinks.open_system.RecycledManifoldCollectiveRecyclerGroup(group_index, detector_index, detector_name, region_index, variable_indices, local_dim, candidate_indices, recycler_indices, recycler_names, weights, local_operator, jump_frobenius_norm, recycler_frobenius_norm, recycler_nnz, jump_nnz, unbundled_inflow_norm=None, bundled_inflow_norm=None)

Bases: object

One collective local recycler replacing selected microscopic recyclers.

The bundled jump has the form J = R_bundle D where D is the selected dark detector and R_bundle is a local matrix supported on one region. Bundling only within a fixed (detector_index, region_index) preserves the same real-space support as the selected microscopic recyclers while reducing the number of Lindblad channels.

group_index: int

detector_index: int

detector_name: str

region_index: int

variable_indices: tuple[int, ...]

local_dim: int

candidate_indices: tuple[int, ...]

recycler_indices: tuple[int, ...]

recycler_names: tuple[str, ...]

weights: tuple[complex, ...]

local_operator: ndarray[tuple[Any, ...], dtype[complex128]]

jump_frobenius_norm: float

recycler_frobenius_norm: float

recycler_nnz: int

jump_nnz: int

unbundled_inflow_norm: float | None

bundled_inflow_norm: float | None

property n_variables: int

property n_bundled_recyclers: int

property recycler_name: str

to_summary_dict()

__init__(group_index, detector_index, detector_name, region_index, variable_indices, local_dim, candidate_indices, recycler_indices, recycler_names, weights, local_operator, jump_frobenius_norm, recycler_frobenius_norm, recycler_nnz, jump_nnz, unbundled_inflow_norm=None, bundled_inflow_norm=None)

class qlinks.open_system.RecycledManifoldDarkDetectorCandidate(candidate_index, detector_index, detector_name, region_index, variable_indices, local_dim, recycler_index, recycler_name, dark_residual, relative_dark_residual, inflow_norm, jump_frobenius_norm, target_block_norm, detector_action_residual, detector_relative_action_residual, recycler_frobenius_norm, recycler_nnz, jump_nnz)

Bases: object

One candidate jump J = R D for a dark manifold.

D is a collective detector satisfying D P_M ~= 0. R is a local recycler/matrix-unit operator embedded on one bounded region. Unlike a standalone RDM recycler, R does not need to annihilate the target manifold because target darkness is supplied by the right detector.

candidate_index: int

detector_index: int

detector_name: str

region_index: int

variable_indices: tuple[int, ...]

local_dim: int

recycler_index: int

recycler_name: str

dark_residual: float

relative_dark_residual: float

inflow_norm: float

jump_frobenius_norm: float

target_block_norm: float

detector_action_residual: float

detector_relative_action_residual: float

recycler_frobenius_norm: float

recycler_nnz: int

jump_nnz: int

property n_variables: int

property is_dark: bool

property has_inflow: bool

to_summary_dict()

__init__(candidate_index, detector_index, detector_name, region_index, variable_indices, local_dim, recycler_index, recycler_name, dark_residual, relative_dark_residual, inflow_norm, jump_frobenius_norm, target_block_norm, detector_action_residual, detector_relative_action_residual, recycler_frobenius_norm, recycler_nnz, jump_nnz)

class qlinks.open_system.RecycledManifoldDarkDetectorReport(manifold_dimension, hilbert_dimension, gram_residual, detector_names, region_variable_indices, local_dims, recycler_source, n_tested_candidates, n_nonzero_candidates, dark_tolerance, inflow_tolerance, candidates)

Bases: object

Report for RDM/matrix-unit recycled dark-detector jumps J = R D.

The report is meant as a necessary-condition scan for attractive manifold Lindblad constructions. Candidates with small dark residual and nonzero inflow satisfy J P_M ~= 0 and P_M J (I-P_M) != 0. A selected set of such jumps still needs the full dark-manifold diagnostic to rule out closed complement sectors.

manifold_dimension: int

hilbert_dimension: int

gram_residual: float

detector_names: tuple[str, ...]

region_variable_indices: tuple[tuple[int, ...], ...]

local_dims: tuple[int, ...]

recycler_source: str

n_tested_candidates: int

n_nonzero_candidates: int

dark_tolerance: float

inflow_tolerance: float

candidates: tuple[RecycledManifoldDarkDetectorCandidate, ...]

property n_detectors: int

property n_regions: int

property max_region_size: int

property max_local_dim: int

property total_local_recyclers_per_detector: int

property n_reported_candidates: int

property candidate_report_is_truncated: bool

property n_dark_candidates: int

property n_candidates_with_inflow: int

property has_attractive_candidates: bool

property best_inflow_norm: float

to_summary_dict()

to_rich(*, max_candidates=24)

__init__(manifold_dimension, hilbert_dimension, gram_residual, detector_names, region_variable_indices, local_dims, recycler_source, n_tested_candidates, n_nonzero_candidates, dark_tolerance, inflow_tolerance, candidates)

class qlinks.open_system.RecycledManifoldJumpSelectionReport(manifold_dimension, hilbert_dimension, candidate_pool_size, max_selected_jumps, target_bad_kernel_dimension, dark_tolerance, inflow_tolerance, jumps, steps, final_diagnostics, candidate_report, candidate_report_was_expanded=False, candidate_pool_was_limited=False, compression_strategy='none', n_compression_passes=0, n_compressed_jumps_removed=0, collective_recycler_strategy='none', unbundled_n_jumps=None, collective_groups=(), selected_inflow_norm=None, unbundled_inflow_norm=None)

Bases: object

Greedy small-subset selection report for recycled dark-detector jumps.

The report owns the selected jump operators. The summary intentionally omits raw sparse matrices, but report.jumps can be passed directly to qlinks.open_system.diagnose_dark_manifold() or a Lindblad solver. The stopping criterion uses the common jump kernel in the complement of the target manifold. Reaching zero is a strong sufficient condition that no complement vector is dark under all selected jumps.

manifold_dimension: int

hilbert_dimension: int

candidate_pool_size: int

max_selected_jumps: int

target_bad_kernel_dimension: int

dark_tolerance: float

inflow_tolerance: float

jumps: tuple[csr_array, ...]

steps: tuple[RecycledManifoldJumpSelectionStep, ...]

final_diagnostics: Any | None

candidate_report: RecycledManifoldDarkDetectorReport

candidate_report_was_expanded: bool

candidate_pool_was_limited: bool

compression_strategy: str

n_compression_passes: int

n_compressed_jumps_removed: int

collective_recycler_strategy: str

unbundled_n_jumps: int | None

collective_groups: tuple[RecycledManifoldCollectiveRecyclerGroup, ...]

selected_inflow_norm: float | None

unbundled_inflow_norm: float | None

property n_selected_jumps: int

property n_unbundled_jumps: int

property n_collective_groups: int

property n_bundled_recyclers: int

property collective_jump_reduction: int

property uses_collective_recyclers: bool

property selected_candidates: tuple[RecycledManifoldDarkDetectorCandidate, ...]

property n_reported_candidates: int

property n_tested_candidates: int

property n_nonzero_candidates: int

property candidate_report_is_truncated: bool

property candidate_pool_is_truncated: bool

property stopped_with_available_candidates: bool

property final_bad_kernel_iprs: tuple[float, ...]

property final_bad_kernel_ipr_min: float | None

property final_bad_kernel_ipr_max: float | None

property final_bad_common_jump_kernel_dimension: int | None

property final_inflow_norm: float | None

property collective_inflow_ratio: float | None

property complement_common_kernel_removed: bool | None

property total_jump_nnz: int

property max_jump_nnz: int

property selected_region_indices: tuple[int, ...]

property selected_detector_indices: tuple[int, ...]

selected_recycler_readouts(*, basis_configs, states=None, max_readouts=None, tolerance=1e-10, rdm_tolerance=1e-10)

Return local-matrix readouts for selected recycled jump recyclers.

The returned objects can be passed directly to LocalBasisGridVisualizer.plot_readout. For rdm_support_matrix_units recyclers, pass the target state/manifold through states so the local RDM support basis can be reconstructed.

to_summary_dict()

to_rich(*, max_steps=24)

__init__(manifold_dimension, hilbert_dimension, candidate_pool_size, max_selected_jumps, target_bad_kernel_dimension, dark_tolerance, inflow_tolerance, jumps, steps, final_diagnostics, candidate_report, candidate_report_was_expanded=False, candidate_pool_was_limited=False, compression_strategy='none', n_compression_passes=0, n_compressed_jumps_removed=0, collective_recycler_strategy='none', unbundled_n_jumps=None, collective_groups=(), selected_inflow_norm=None, unbundled_inflow_norm=None)

class qlinks.open_system.RecycledManifoldJumpSelectionStep(step_index, candidate, bad_common_jump_kernel_dimension, inflow_norm, max_target_jump_residual, n_selected_jumps)

Bases: object

One greedy selection step for recycled dark-detector jumps.

step_index: int

candidate: RecycledManifoldDarkDetectorCandidate

bad_common_jump_kernel_dimension: int

inflow_norm: float

max_target_jump_residual: float

n_selected_jumps: int

to_summary_dict()

__init__(step_index, candidate, bad_common_jump_kernel_dimension, inflow_norm, max_target_jump_residual, n_selected_jumps)

class qlinks.open_system.RecycledManifoldResidualKernelReport(manifold_dimension, hilbert_dimension, family_report, residual_basis, hamiltonian_target_coupling_norm, hamiltonian_residual_block_norm, hamiltonian_outside_residual_norm, hamiltonian_residual_eigenvalues, operator_action_reports, local_support_entries, kernel_tolerance)

Bases: object

Diagnostics for the residual complement kernel left by a recycled family.

The report focuses on the bad subspace

B = (cap_mu ker J_mu) cap M^perp,

where J_mu ranges over the chosen recycled-detector family. It is meant to distinguish a mere subset-selection failure from a structural residual sector that the current local operator family cannot see.

manifold_dimension: int

hilbert_dimension: int

family_report: RecycledManifoldCandidateFamilyKernelReport

residual_basis: ndarray[tuple[Any, ...], dtype[complex128]]

hamiltonian_target_coupling_norm: float

hamiltonian_residual_block_norm: float

hamiltonian_outside_residual_norm: float

hamiltonian_residual_eigenvalues: tuple[complex, ...]

operator_action_reports: tuple[ResidualKernelOperatorActionReport, ...]

local_support_entries: tuple[ResidualKernelLocalSupportEntry, ...]

kernel_tolerance: float

property residual_dimension: int

property residual_iprs: tuple[float, ...]

property residual_ipr_min: float | None

property residual_ipr_max: float | None

property hamiltonian_keeps_residual_sector: bool

property n_local_support_entries: int

property all_local_residual_support_inside_target: bool

to_summary_dict()

to_rich(*, max_operator_rows=12, max_local_rows=16)

__init__(manifold_dimension, hilbert_dimension, family_report, residual_basis, hamiltonian_target_coupling_norm, hamiltonian_residual_block_norm, hamiltonian_outside_residual_norm, hamiltonian_residual_eigenvalues, operator_action_reports, local_support_entries, kernel_tolerance)

class qlinks.open_system.ResidualKernelLocalSupportEntry(variable_indices, local_dim, target_support_rank, target_nullity, residual_support_rank, residual_nullity, combined_support_rank, combined_nullity, residual_support_outside_target_norm)

Bases: object

Local support comparison between target and residual bad-kernel subspaces.

variable_indices: tuple[int, ...]

local_dim: int

target_support_rank: int

target_nullity: int

residual_support_rank: int

residual_nullity: int

combined_support_rank: int

combined_nullity: int

residual_support_outside_target_norm: float

property n_variables: int

property residual_support_inside_target: bool

to_summary_dict()

__init__(variable_indices, local_dim, target_support_rank, target_nullity, residual_support_rank, residual_nullity, combined_support_rank, combined_nullity, residual_support_outside_target_norm)

class qlinks.open_system.ResidualKernelOperatorActionEntry(operator_index, operator_name, action_norm, target_component_norm, residual_component_norm, outside_component_norm)

Bases: object

Action of one probe operator on the residual bad-kernel subspace.

operator_index: int

operator_name: str

action_norm: float

target_component_norm: float

residual_component_norm: float

outside_component_norm: float

to_summary_dict()

__init__(operator_index, operator_name, action_norm, target_component_norm, residual_component_norm, outside_component_norm)

class qlinks.open_system.ResidualKernelOperatorActionReport(group_name, n_operators, entries)

Bases: object

Probe-operator action on the residual bad-kernel subspace.

group_name: str

n_operators: int

entries: tuple[ResidualKernelOperatorActionEntry, ...]

property total_action_norm: float

property total_target_component_norm: float

property total_residual_component_norm: float

property total_outside_component_norm: float

property max_target_component_norm: float

property max_outside_component_norm: float

to_summary_dict()

__init__(group_name, n_operators, entries)

class qlinks.open_system.SparseLindbladOperators(backend, sparse_format, hamiltonian, identity, jumps, jump_dagger_jumps)

Bases: object

Sparse Lindblad operators prepared for Liouville-space construction.

backend: OpenSystemBackend

sparse_format: str

hamiltonian: Any

identity: Any

jumps: tuple[Any, ...]

jump_dagger_jumps: tuple[Any, ...]

property dim: int

__init__(backend, sparse_format, hamiltonian, identity, jumps, jump_dagger_jumps)

class qlinks.open_system.TargetedResidualKernelJumpSelectionReport(manifold_dimension, hilbert_dimension, residual_dimension, max_selected_jumps, target_residual_kernel_dimension, targeted_report, base_jumps, jumps, steps, final_diagnostics, selection_target, initial_selection_kernel_dimension, target_selection_kernel_dimension, kernel_tolerance, dark_tolerance, inflow_tolerance, selected_inflow_norm=None)

Bases: object

Greedy subset of targeted local jumps that removes a residual kernel.

manifold_dimension: int

hilbert_dimension: int

residual_dimension: int

max_selected_jumps: int

target_residual_kernel_dimension: int

targeted_report: TargetedResidualKernelLinearSearchReport

base_jumps: tuple[csr_array, ...]

jumps: tuple[csr_array, ...]

steps: tuple[TargetedResidualKernelJumpSelectionStep, ...]

final_diagnostics: Any | None

selection_target: Literal['reported_residual_kernel', 'combined_common_kernel']

initial_selection_kernel_dimension: int

target_selection_kernel_dimension: int

kernel_tolerance: float

dark_tolerance: float

inflow_tolerance: float

selected_inflow_norm: float | None

property n_selected_jumps: int

property n_base_jumps: int

property n_combined_jumps: int

property all_jumps: tuple[csr_array, ...]

property selected_candidates: tuple[TargetedResidualKernelLinearCandidate, ...]

property selected_region_indices: tuple[int, ...]

selected_operator_readouts(*, basis_configs, max_readouts=None)

Return local-matrix readouts for selected targeted completion operators.

property final_residual_kernel_dimension: int

property residual_kernel_removed: bool

property final_selection_kernel_dimension: int

property selection_kernel_removed: bool

property total_selected_jump_nnz: int

property total_combined_jump_nnz: int

property max_selected_jump_nnz: int

property combined_bad_common_jump_kernel_dimension: int | None

property combined_inflow_norm: float | None

property combined_complement_common_kernel_removed: bool | None

to_summary_dict()

to_rich(*, max_steps=24)

__init__(manifold_dimension, hilbert_dimension, residual_dimension, max_selected_jumps, target_residual_kernel_dimension, targeted_report, base_jumps, jumps, steps, final_diagnostics, selection_target, initial_selection_kernel_dimension, target_selection_kernel_dimension, kernel_tolerance, dark_tolerance, inflow_tolerance, selected_inflow_norm=None)

class qlinks.open_system.TargetedResidualKernelJumpSelectionStep(step_index, candidate, residual_kernel_dimension, n_selected_jumps)

Bases: object

One greedy step selecting a targeted residual-kernel jump.

step_index: int

candidate: TargetedResidualKernelLinearCandidate

residual_kernel_dimension: int

n_selected_jumps: int

to_summary_dict()

__init__(step_index, candidate, residual_kernel_dimension, n_selected_jumps)

class qlinks.open_system.TargetedResidualKernelLinearCandidate(candidate_index, region_index, variable_indices, local_dim, operator_source, dark_constraint_rank, dark_nullity, singular_value, residual_target_inflow_norm, dark_residual, relative_dark_residual, total_inflow_norm, target_block_norm, jump_frobenius_norm, jump_nnz, coefficients, terms, residual_action_norm=0.0, residual_score_norm=0.0, residual_objective='target_inflow')

Bases: object

A local jump candidate found by constrained residual-kernel search.

candidate_index: int

region_index: int

variable_indices: tuple[int, ...]

local_dim: int

operator_source: str

dark_constraint_rank: int

dark_nullity: int

singular_value: float

residual_target_inflow_norm: float

dark_residual: float

relative_dark_residual: float

total_inflow_norm: float

target_block_norm: float

jump_frobenius_norm: float

jump_nnz: int

coefficients: ndarray[tuple[Any, ...], dtype[complex128]]

terms: tuple[TargetedResidualKernelLinearTerm, ...]

residual_action_norm: float

residual_score_norm: float

residual_objective: str

property n_variables: int

property n_terms: int

property is_dark: bool

property hits_residual_kernel: bool

to_summary_dict()

__init__(candidate_index, region_index, variable_indices, local_dim, operator_source, dark_constraint_rank, dark_nullity, singular_value, residual_target_inflow_norm, dark_residual, relative_dark_residual, total_inflow_norm, target_block_norm, jump_frobenius_norm, jump_nnz, coefficients, terms, residual_action_norm=0.0, residual_score_norm=0.0, residual_objective='target_inflow')

class qlinks.open_system.TargetedResidualKernelLinearSearchReport(manifold_dimension, hilbert_dimension, residual_basis, region_variable_indices, operator_source, family_report, candidates, candidate_jumps, tolerance, dark_tolerance, inflow_tolerance, residual_objective='target_inflow', n_regions_evaluated=0, n_regions_skipped_by_local_dim=0, n_regions_with_no_recycler_specs=0, n_regions_with_no_nonzero_local_operators=0, n_regions_with_zero_dark_nullity=0, n_regions_with_dark_nullity_detected=-1, n_regions_with_zero_residual_inflow=0, n_candidate_modes_generated=-1, max_encountered_local_dim=0)

Bases: object

Constrained local search targeting a recycled-family residual kernel.

For each local region with operator basis O_a, the search solves

sum_a c_a O_a P_M = 0

and, inside that dark nullspace, maximizes either

||P_M (sum_a c_a O_a) B||_F

or

||(sum_a c_a O_a) B||_F,

where B is the residual bad common-kernel basis left by a recycled detector family. The first objective emphasizes direct inflow to the target manifold; the second directly attacks a remaining dark kernel sector even when it does not couple to the target in one jump.

manifold_dimension: int

hilbert_dimension: int

residual_basis: ndarray[tuple[Any, ...], dtype[complex128]]

region_variable_indices: tuple[tuple[int, ...], ...]

operator_source: str

family_report: RecycledManifoldCandidateFamilyKernelReport | None

candidates: tuple[TargetedResidualKernelLinearCandidate, ...]

candidate_jumps: tuple[csr_array, ...]

tolerance: float

dark_tolerance: float

inflow_tolerance: float

residual_objective: str

n_regions_evaluated: int

n_regions_skipped_by_local_dim: int

n_regions_with_no_recycler_specs: int

n_regions_with_no_nonzero_local_operators: int

n_regions_with_zero_dark_nullity: int

n_regions_with_dark_nullity_detected: int

n_regions_with_zero_residual_inflow: int

n_candidate_modes_generated: int

max_encountered_local_dim: int

property residual_dimension: int

property n_regions: int

property n_candidates: int

property max_region_size: int

property max_local_dim: int

property n_regions_with_dark_nullity: int

property n_reported_candidate_modes: int

property n_generated_candidate_modes: int

property targeted_search_failure_counts: dict[str, int]

property n_candidates_hitting_residual: int

property best_residual_target_inflow_norm: float

property best_residual_action_norm: float

property best_residual_score_norm: float

property best_total_inflow_norm: float

property has_targeted_solution: bool

residual_kernel_dimension_after_candidate_prefix(n_candidates=None, *, tolerance=None)

Return residual-kernel dimension after the first reported jumps.

property reported_candidate_residual_kernel_dimension: int

Residual-family kernel dimension after all reported targeted candidates.

This is the dimension of the residual bad kernel supplied to this targeted search after applying the reported candidate jumps. In the end-to-end workflow this is the residual left by the full recycled detector family, not necessarily the bad common kernel left by a compact selected recycled subset.

property reported_candidate_family_residual_kernel_dimension: int

Alias with explicit workflow terminology.

property reported_candidates_remove_residual_kernel: bool

property reported_candidates_remove_family_residual_kernel: bool

Whether reported candidates remove the full-family residual kernel.

candidate_readouts(*, basis_configs, max_readouts=None)

Return local-matrix readouts for reported targeted candidates.

to_summary_dict()

to_rich(*, max_candidates=16, max_terms=6)

__init__(manifold_dimension, hilbert_dimension, residual_basis, region_variable_indices, operator_source, family_report, candidates, candidate_jumps, tolerance, dark_tolerance, inflow_tolerance, residual_objective='target_inflow', n_regions_evaluated=0, n_regions_skipped_by_local_dim=0, n_regions_with_no_recycler_specs=0, n_regions_with_no_nonzero_local_operators=0, n_regions_with_zero_dark_nullity=0, n_regions_with_dark_nullity_detected=-1, n_regions_with_zero_residual_inflow=0, n_candidate_modes_generated=-1, max_encountered_local_dim=0)

class qlinks.open_system.TargetedResidualKernelLinearTerm(operator_index, operator_name, coefficient, weight)

Bases: object

One local matrix-unit term in a targeted residual-kernel jump.

operator_index: int

operator_name: str

coefficient: complex

weight: float

to_summary_dict()

__init__(operator_index, operator_name, coefficient, weight)

class qlinks.open_system.TrajectoryResult(times, states, jump_times, jump_indices, norm_errors)

Bases: object

Single Monte Carlo wave-function trajectory.

times: ndarray[tuple[Any, ...], dtype[float64]]

states: list[Any]

jump_times: ndarray[tuple[Any, ...], dtype[float64]]

jump_indices: ndarray[tuple[Any, ...], dtype[int64]]

norm_errors: ndarray[tuple[Any, ...], dtype[float64]]

__init__(times, states, jump_times, jump_indices, norm_errors)

class qlinks.open_system.TwoPatternRecyclingStructure(variable_indices, pattern_a, pattern_b, alpha_index, beta_index, phase, residual, matrix_unit_terms)

Bases: object

Detected local two-pattern recycling structure.

This represents a local jump of the form |minus><plus|, up to phase and convention.

variable_indices: tuple[int, ...]

pattern_a: tuple[int, ...]

pattern_b: tuple[int, ...]

alpha_index: int

beta_index: int

phase: complex

residual: float

matrix_unit_terms: tuple[LocalMatrixUnitTerm, ...]

property n_variables: int

__init__(variable_indices, pattern_a, pattern_b, alpha_index, beta_index, phase, residual, matrix_unit_terms)

qlinks.open_system.analyze_lindblad_evolution(density_matrices=None, *, ensemble_result=None, state_snapshots=None, trajectories=None, times=None, target_state=None, hamiltonian=None, jumps=None, atol=1e-10, backend='scipy', density_check_mode='auto')

Analyze diagnostics along Lindblad or MCWF evolution output.

The function accepts dense density matrices directly, but it can also read MCWF ensemble outputs. When an ensemble stores low-rank state snapshots but not rho_t, diagnostics can be computed without materializing dense density matrices unless density_check_mode="full" is requested.

Parameters:

• density_matrices (Sequence[Any] | None) – Optional sequence of density matrices.

• ensemble_result (Any | None) – Optional MCWF ensemble result. The analyzer prefers populated rho_t, then state_snapshots, then stored trajectories.

• state_snapshots (Sequence[Any] | None) – Optional sequence of matrices with shape (dim, n_trajectories).

• trajectories (Sequence[Any] | None) – Optional trajectory results with stored states.

• times (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None) – Optional time grid.

• target_state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None) – Optional pure state for fidelity diagnostics.

• hamiltonian – Optional Hamiltonian for Lindblad residual diagnostics.

• jumps – Optional jump operators for Lindblad residual diagnostics.

• atol (float) – Numerical tolerance for density-matrix checks.

• backend (Literal['scipy', 'cupy'] | ~qlinks.open_system.backend.OpenSystemBackend) – Open-system backend name or object.

• density_check_mode (str) – "auto", "full", or "low_rank". "low_rank" avoids materializing density matrices from MCWF snapshots and reports NaN for minimum eigenvalues.

Returns:

Evolution diagnostics arrays.

Return type:

EvolutionDiagnostics

qlinks.open_system.as_backend_dense_array(matrix, *, backend, dtype=<class 'numpy.complex128'>)

Convert a dense or sparse matrix to a backend dense array.

Parameters:

• matrix (Any) – Input matrix in dense, SciPy sparse, or backend sparse form.

• backend (OpenSystemBackend) – Target backend.

• dtype – Complex dtype for the converted array.

Returns:

Dense array on the requested backend.

qlinks.open_system.as_backend_sparse_matrix(matrix, *, backend, format='csr', dtype=<class 'numpy.complex128'>)

Convert a dense or sparse matrix to a backend sparse matrix.

Parameters:

• matrix (Any) – Input matrix in dense, SciPy sparse, or backend sparse form.

• backend (OpenSystemBackend) – Target backend.

• format (str) – Sparse format requested from the backend.

• dtype – Complex dtype for the converted matrix.

Returns:

Sparse matrix on the requested backend.

qlinks.open_system.bad_h_invariant_common_kernel_basis(*, hamiltonian, jumps, target_states, kernel_tolerance=1e-10)

Return the bad H-invariant sector inside the common jump kernel.

The returned columns form an orthonormal basis for the largest subspace of (cap_mu ker J_mu) cap M^perp whose Hamiltonian orbit stays inside the common jump kernel. An empty (dim, 0) array means the selected jumps have no Hamiltonian-stable dark obstruction outside the target manifold.

This helper exposes the obstruction basis used internally by diagnose_common_kernel_h_invariant_sector(), so jump-design routines can add a targeted completion stage without recomputing or interpreting a Liouvillian spectrum.

qlinks.open_system.build_cage_lindblad_detector_operators(*, model, build_result, term_kind='plaquette', operator_kind='potential', builder='sparse', backend='scipy', on_missing='skip', name_prefix=None)

Build a named local detector-operator family from model local terms.

operator_kind='hamiltonian' includes both kinetic and potential terms when the model exposes them. The returned bundle can be passed directly to CageLindbladDesignProblem.design_jumps().

qlinks.open_system.build_cage_lindblad_problem(*, build_result, target_state=None, target_states=None, states=None, records=None, model=None, local_regions=None, regional_units=None, local_term_kind=None, region_source='kinetic', validate_record_signature=True, open_system_backend='scipy', residual_tolerance=1e-10, target_tolerance=1e-10)

Create a unified cage Lindblad design problem.

A single cage state is supplied with target_state. A degenerate cage manifold is supplied with target_states/states or records. The returned object uses the same design_jumps method in both cases.

qlinks.open_system.build_liouvillian(hamiltonian, jumps, *, backend='scipy', sparse_format='csc', dtype=<class 'numpy.complex128'>)

Build the sparse Liouvillian superoperator.

The Liouvillian acts on density matrices vectorized with vectorize_density_matrix().

Parameters:

• hamiltonian (Any) – Hamiltonian matrix.

• jumps (list[Any] | tuple[Any, ...]) – Lindblad jump operators.

• backend (Literal['scipy', 'cupy'] | ~qlinks.open_system.backend.OpenSystemBackend) – Open-system backend name or object.

• sparse_format (str) – Sparse format for the returned superoperator.

• dtype – Complex dtype used during conversion.

Returns:

Sparse Liouvillian matrix with shape (dim * dim, dim * dim).

qlinks.open_system.build_liouvillian_from_prepared(sparse_operators)

Build the Liouvillian from preconverted sparse Lindblad operators.

qlinks.open_system.build_local_recycling_jumps_from_regions(*, basis_configs, target_state, regions, source='local_rdm_two_pattern', deduplicate_regions=False, max_jumps_per_region=1, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, max_candidates_per_region=None, prefer_sparse=True, two_pattern_tolerance=1e-08)

Scan several regions and return selected local recycling jumps.

Set deduplicate_regions=True when repeated monitor components share the same local support and should use one recycler family rather than one copy per component. The default keeps the historical behavior.

qlinks.open_system.build_local_recycling_jumps_from_subspace_regions(*, basis_configs, states, regions, source='local_rdm_block_reset', deduplicate_regions=False, max_jumps_per_region=1, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, max_candidates_per_region=None, prefer_sparse=True, two_pattern_tolerance=1e-08)

Scan local recycling jumps that annihilate a target state subspace.

qlinks.open_system.density_matrix_from_state(state, *, normalize=True)

Return the pure density matrix associated with a state vector.

Parameters:

• state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – One-dimensional state vector.

• normalize (bool) – Whether to normalize the vector before forming |psi><psi|.

Returns:

Complex density matrix |psi><psi|.

Return type:

ndarray[tuple[Any, …], dtype[complex128]]

qlinks.open_system.density_matrix_from_state_matrix(states)

Return the ensemble density matrix represented by state columns.

states[:, trajectory_index] is one normalized MCWF trajectory state. The returned matrix is the average projector over columns.

qlinks.open_system.detect_two_pattern_recycling_structure(*, candidate, local_patterns, tolerance=1e-08)

Detect whether a candidate is a two-pattern |minus><plus| jump.

qlinks.open_system.diagnose_absorbing_projector_symmetry(*, hamiltonian, jumps, target_state, backend='scipy', tolerance=1e-10)

Diagnose whether P_psi is an absorbing-state projector symmetry.

The target projector is

P_psi = |psi><psi|.

The relevant obstruction to attraction is:

J_mu |psi> = 0 and P_psi J_mu (I - P_psi) = 0

for all jumps. Then the target is dark, but there is no jump-induced inflow from psi_perp into psi. Equivalently, P_psi is conserved by the Heisenberg-picture Lindbladian.

qlinks.open_system.diagnose_common_kernel_h_invariant_sector(*, hamiltonian, jumps, target_states, kernel_tolerance=1e-10)

Diagnose Hamiltonian-stable obstructions inside the common jump kernel.

This is a cheap alternative to a Liouvillian spectrum check. It first computes the common jump kernel K = cap_mu ker J_mu and the bad complement B = K cap M^perp. It then computes the largest subspace of B whose Hamiltonian Krylov orbit stays inside K. Only this H-invariant part is a purely dark Hamiltonian-stable complement sector.

qlinks.open_system.diagnose_dark_manifold(*, hamiltonian, jumps, target_states, backend='scipy', kernel_tolerance=1e-10, liouvillian_zero_tolerance=1e-09, check_liouvillian_spectrum=True, max_liouvillian_dense_dimension=4096, liouvillian_spectrum_method='auto', sparse_liouvillian_eigenvalue_count=32)

Diagnose whether a target manifold is an attractive dark manifold.

The columns of target_states span the target manifold. They need not be orthonormal; this function orthonormalizes them and uses the target projector P_M. The diagnostic accepts the internal non-decaying Liouvillian modes generated by the projected Hamiltonian M† H M and reports additional zero/peripheral modes as possible complement obstructions.

qlinks.open_system.diagnose_dark_subspace(*, hamiltonian, jumps, target_state, backend='scipy', kernel_tolerance=1e-10, liouvillian_zero_tolerance=1e-09, check_liouvillian_spectrum=True, max_liouvillian_dense_dimension=4096, liouvillian_spectrum_method='auto', sparse_liouvillian_eigenvalue_count=16)

Diagnose whether a dark target is likely unique/attractive.

This is intended for small systems. It computes:

1. target jump residuals ||J_mu psi||;

2. common jump kernel dim intersection_mu ker J_mu;

3. bad common-kernel dimension after removing the target direction;

4. target Liouvillian residual ||L(|psi><psi|)||;

5. optional Liouvillian zero-mode count.

The Liouvillian spectrum check uses a dense solver for small Liouvillians and a sparse shift-invert Arnoldi solver for larger ones when liouvillian_spectrum_method="auto". The sparse zero-mode count is a lower bound if all requested eigenvalues are numerically zero; increase sparse_liouvillian_eigenvalue_count to resolve more zero modes.

qlinks.open_system.diagnose_dressed_manifold_dark_detectors(*, states, detector_operators, left_multipliers, detector_coefficients=None, dark_operator_report=None, detector_operator_names=None, left_multiplier_names=None, detector_names=None, tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, max_detectors=None, sort_by_inflow=True)

Test paper-style dressed jumps J = V D for a dark manifold.

Parameters:

• states (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Target manifold basis. Columns are orthonormalized.

• detector_operators (tuple[Any, ...] | list[Any]) – Operator basis O_a used to assemble D=sum_a c_a O_a.

• left_multipliers (tuple[Any, ...] | list[Any]) – Candidate left multipliers V_beta.

• detector_coefficients (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None) – Optional coefficient matrix for the detectors. If omitted, coefficients are taken from dark_operator_report.

• dark_operator_report (ManifoldDarkOperatorBasisReport | None) – Optional report from diagnose_manifold_dark_operator_basis().

• detector_operator_names (tuple[str, ...] | list[str] | None) – Names for detector_operators. Only used to build default detector names.

• left_multiplier_names (tuple[str, ...] | list[str] | None) – Names for the left multipliers.

• detector_names (tuple[str, ...] | list[str] | None) – Optional explicit detector names.

• tolerance (float) – Orthonormalization and shape-check tolerance.

• dark_tolerance (float) – Relative dark residual threshold.

• inflow_tolerance (float) – Direct-inflow threshold.

• max_detectors (int | None) – Optional maximum number of detectors to test.

• sort_by_inflow (bool) – If true, store candidates with largest inflow first.

Returns:

A report of dressed candidates. A candidate with small dark residual and positive inflow satisfies the necessary direct-inflow condition for manifold attraction, but does not by itself rule out invariant sectors in the complement.

Return type:

DressedManifoldDarkDetectorReport

qlinks.open_system.diagnose_jump_span(jumps, *, rank_tolerance=1e-10)

Diagnose exact/near linear dependencies among jump operators.

The jump-operator span is measured in the Hilbert-Schmidt inner product, <J_i, J_j> = Tr(J_i† J_j). The rank of this Gram matrix is the number of independent jump directions. If this rank is much smaller than the raw number of jumps, a future compression pass can rotate/drop jumps before MCWF sampling without changing the Lindblad dissipator.

qlinks.open_system.diagnose_manifold_dark_operator_basis(*, states, operators, operator_names=None, tolerance=1e-10, coefficient_tolerance=1e-08, max_candidates=16, candidate_strategy='svd_basis', candidate_overlap_tolerance=1e-07)

Find linear combinations of supplied operators annihilating a manifold.

Parameters:

• states (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Target manifold basis with shape (dim, n_states) or rows as states. The columns are orthonormalized before the nullspace solve.

• operators (tuple[Any, ...] | list[Any]) – Operator basis matrices with the same Hilbert dimension.

• operator_names (tuple[str, ...] | list[str] | None) – Optional names for the operators.

• tolerance (float) – Absolute/relative SVD tolerance used for the dark-detector nullspace.

• coefficient_tolerance (float) – Coefficient magnitude threshold for term readout.

• max_candidates (int | None) – Maximum number of nullspace candidates to store. Use None to keep all candidates.

• candidate_strategy (Literal['svd_basis', 'coordinate_ipr']) – "svd_basis" keeps the numerical nullspace basis. "coordinate_ipr" projects individual supplied operators onto the dark nullspace and ranks the results by coefficient IPR, producing more localized/interpretable detector combinations when the dark solution space is degenerate.

• candidate_overlap_tolerance (float) – Deduplication tolerance for candidate_strategy="coordinate_ipr".

Returns:

A report whose candidate coefficient columns define D=sum_a c_a O_a with D P_M ~= 0.

Return type:

ManifoldDarkOperatorBasisReport

qlinks.open_system.diagnose_monitor_kernel_closure(*, hamiltonian, monitors, target_state, closure_order=1, tolerance=1e-10)

Diagnose whether local monitors are closed by Hamiltonian mixing.

This is designed for monitor-recycler jumps L_i = V_i M_i. Recyclers cannot act on states in intersection_i ker(M_i), so the size of this kernel and its leakage under H are the first diagnostics to inspect.

Currently closure_order supports 0 or 1. Order 1 appends the constraints M_i H and computes the common kernel of {M_i, M_i H}.

qlinks.open_system.diagnose_recycled_manifold_candidate_family_kernel(*, hamiltonian, states, basis_configs, detector_operators, local_regions, detector_coefficients=None, dark_operator_report=None, candidate_report=None, detector_operator_names=None, detector_names=None, recycler_source='rdm_support_matrix_units', tolerance=1e-10, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, kernel_tolerance=1e-10, liouvillian_zero_tolerance=1e-09, max_detectors=None, expand_candidate_report=True, kernel_method='streamed', store_candidate_jumps=False)

Diagnose the common jump kernel of the full recycled-detector family.

This is the decisive follow-up when greedy selection saturates at a nonzero complement kernel. If the family of all eligible local candidates still has a bad common jump kernel, no subset selected from that family can remove it. If the family removes the kernel but the greedy subset does not, the problem is the subset-selection heuristic rather than the operator family.

qlinks.open_system.diagnose_recycled_manifold_dark_detectors(*, states, basis_configs, detector_operators, local_regions, detector_coefficients=None, dark_operator_report=None, detector_operator_names=None, detector_names=None, recycler_source='rdm_support_matrix_units', tolerance=1e-10, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, max_detectors=None, max_report_candidates=256, sort_by_inflow=True)

Test local RDM/matrix-unit recyclers after dark detectors.

This scans jumps of the form J = R D. The right detector D is a collective operator satisfying D P_M ~= 0. The left operator R is a local recycler on one bounded region. Since target darkness comes from D, the recycler can be a general local matrix unit and need not be dark on the target manifold by itself.

Parameters:

• states (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Target manifold basis; columns are orthonormalized.

• basis_configs (ndarray[tuple[Any, ...], dtype[integer]]) – Constrained/product basis configurations aligned with the Hilbert-space basis used by detector_operators.

• detector_operators (tuple[Any, ...] | list[Any]) – Operator basis used to assemble the detectors.

• local_regions (tuple[tuple[int, ...], ...] | list[tuple[int, ...]] | list[list[int]]) – Variable-index regions where local recyclers are embedded.

• detector_coefficients (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None) – Optional coefficient matrix defining detectors. If omitted, coefficients are read from dark_operator_report.

• dark_operator_report (ManifoldDarkOperatorBasisReport | None) – Report from diagnose_manifold_dark_operator_basis().

• detector_operator_names (tuple[str, ...] | list[str] | None) – Names for the detector operator basis.

• detector_names (tuple[str, ...] | list[str] | None) – Optional explicit detector names.

• recycler_source (Literal['matrix_units', 'rdm_support_matrix_units']) – "matrix_units" scans canonical local matrix units; "rdm_support_matrix_units" maps canonical source patterns into the local support eigenvectors of the target manifold RDM.

• tolerance (float) – Orthonormalization and shape-check tolerance.

• rdm_tolerance (float) – Local RDM support threshold.

• dark_tolerance (float) – Relative dark residual threshold for J P_M.

• inflow_tolerance (float) – Threshold for ||P_M J (I-P_M)||_F.

• max_detectors (int | None) – Optional maximum detector columns to scan.

• max_report_candidates (int | None) – Optional maximum number of best candidates to retain in the report. All candidates are still counted in n_tested_candidates.

• sort_by_inflow (bool) – If true, report candidates with largest inflow first.

Returns:

A report of local-recycler dressed candidates. Nonzero inflow is a necessary, not sufficient, condition for attractive dark-manifold dynamics.

Return type:

RecycledManifoldDarkDetectorReport

qlinks.open_system.diagnose_recycled_manifold_residual_kernel(*, hamiltonian, states, basis_configs, detector_operators, local_regions, detector_coefficients=None, dark_operator_report=None, candidate_report=None, family_report=None, detector_operator_names=None, detector_names=None, recycler_source='rdm_support_matrix_units', operator_groups=None, local_support_regions=None, tolerance=1e-10, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, kernel_tolerance=1e-10, liouvillian_zero_tolerance=1e-09, max_detectors=None, expand_candidate_report=True, max_operator_entries=64)

Diagnose the residual bad kernel left by a recycled-detector family.

This function first computes the full-family common jump kernel for the specified recycled-detector candidates. It then extracts the bad complement subspace and reports whether the Hamiltonian and optional probe-operator groups couple that subspace to the target manifold, leave it invariant, or push it outside the target-plus-residual sector.

qlinks.open_system.diagnose_targeted_residual_kernel_linear_search(*, states, basis_configs, local_regions, residual_basis=None, residual_report=None, detector_operators=None, residual_family_local_regions=None, detector_coefficients=None, dark_operator_report=None, candidate_report=None, family_report=None, detector_operator_names=None, detector_names=None, recycler_source='rdm_support_matrix_units', operator_source='matrix_units', residual_objective='target_inflow', tolerance=1e-10, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, kernel_tolerance=1e-10, max_detectors=None, max_modes_per_region=1, max_report_candidates=32, max_local_dim=None, coefficient_tolerance=1e-08)

Search local dark jumps that directly target a residual bad kernel.

This is stronger than optimizing linear combinations of the factorized recycled-detector family R D. For each supplied local region, it builds a local operator basis O_a and solves the constrained problem

sum_a c_a O_a P_M = 0,

then ranks dark combinations by their action

||P_M (sum_a c_a O_a) B||_F,

where B is the residual complement common kernel left by a recycled detector family.

qlinks.open_system.effective_hamiltonian(hamiltonian, jumps)

Return H_eff = H - i/2 sum_mu J_mu^dagger J_mu.

qlinks.open_system.embed_local_pattern_operator(*, basis_configs, variable_indices, local_patterns, local_operator)

Embed a local operator into the constrained full basis.

qlinks.open_system.estimate_lindblad_scale(*, hamiltonian, jumps, backend='scipy')

Cheap stiffness scale for RK4 step-size sanity checks.

qlinks.open_system.estimate_lindblad_scale_prepared(dense_operators)

Cheap stiffness scale from preconverted dense operators.

qlinks.open_system.expand_local_regions_to_cluster_unions(local_regions, *, cluster_size=3, cluster_mode='overlap_connected', min_overlap=1, max_region_size=None, include_single_regions=False, include_smaller_clusters=False)

Return bounded unions of multiple local regions.

This generalizes expand_local_regions_to_pair_unions() to one or more regional units. cluster_size=1 returns the normalized base regions themselves, which is useful when each base region is already a model-natural non-onsite unit such as a plaquette, rhombus, hexagon, or bond. cluster_mode="overlap_connected" keeps larger clusters that are connected in the overlap graph of the base regions; this is the natural setting for connected multi-plaquette QDM patches.

The normalized expansion is cached and the connected mode grows clusters on the overlap graph directly. This makes repeated local_region_mode="regional_unit_clusters" calls much cheaper in notebook sweeps, especially when trying several detector/recycler settings with the same model-natural plaquette or bond units.

qlinks.open_system.expand_local_regions_to_pair_unions(local_regions, *, pair_mode='overlap', min_overlap=1, max_region_size=None, include_single_regions=False)

Return unions of pairs of local regions, useful for two-block recyclers.

The single-plaquette recycled-detector family can leave residual bad kernel sectors when the target manifold is built from two-plaquette singlet-like structures. This helper creates bounded two-region supports that can be supplied to diagnose_recycled_manifold_dark_detectors or diagnose_recycled_manifold_candidate_family_kernel as local_regions.

Parameters:

• local_regions (tuple[tuple[int, ...], ...] | list[tuple[int, ...]] | list[list[int]]) – Base local regions, usually plaquette supports.

• pair_mode (Literal['overlap', 'all']) – "overlap" keeps only pairs sharing at least min_overlap variables; "all" keeps all unordered pairs.

• min_overlap (int) – Minimum number of shared variables when pair_mode="overlap".

• max_region_size (int | None) – Optional upper bound on the size of the union.

• include_single_regions (bool) – Whether to prepend the original regions.

Returns:

Deduplicated sorted variable-index unions.

Return type:

tuple[tuple[int, …], …]

qlinks.open_system.expectation(state, operator)

Return <state|operator|state>.

qlinks.open_system.export_cage_lindblad_design(design, *, path, include_basis=True, include_global_matrices=False, include_detector_matrices=False, include_readouts=True, include_certificates=True, matrix_element_tolerance=0.0, overwrite=False)

Export a cage-Lindblad design as a versioned JSON/JSONL bundle.

The default export is intended for papers and arXiv data: it stores detectors as coefficient combinations, recycled jumps as R D records, targeted jumps as local dark-operator records, and certificates/summary metadata as JSON. Full sparse matrices can be included with include_global_matrices=True and detector matrices with include_detector_matrices=True.

qlinks.open_system.get_open_system_backend(backend)

Resolve an open-system backend name or backend object.

Parameters:

backend (Literal['scipy', 'cupy'] | ~qlinks.open_system.backend.OpenSystemBackend) – "scipy", "cupy", or an existing backend object.

Returns:

Backend object used by open-system operators and solvers.

Raises:

• ImportError – If backend="cupy" is requested but CuPy is not installed.

• ValueError – If the backend name is unknown.

Return type:

OpenSystemBackend

qlinks.open_system.initial_density_matrix(dim, *, kind='mixed', rank=None, rng=None)

Create a convenient initial density matrix.

qlinks.open_system.jump_activity(density_matrix, jumps)

Return total Lindblad jump activity sum_mu Tr(J_mu^dag J_mu rho).

qlinks.open_system.jump_activity_series(*, jumps, density_matrices=None, evolution_result=None, ensemble_result=None, state_snapshots=None)

Return total jump activity for each time point.

For density matrices this evaluates sum_mu Tr(J_mu^dagger J_mu rho(t)). For MCWF state snapshots it returns the trajectory average of sum_mu ||J_mu |psi(t)>||^2.

qlinks.open_system.jump_probabilities(state, jumps, step_size, *, backend)

Return first-order jump probabilities dt <psi|J^dagger J|psi>.

qlinks.open_system.lindblad_rhs_density_matrix(density_matrix, *, hamiltonian, jumps, backend='scipy')

Evaluate the Lindblad master-equation right-hand side.

Computes d rho / dt = -i[H, rho] + sum_j D[J_j](rho) using dense backend arrays. For repeated calls, use prepare_dense_lindblad_operators() and lindblad_rhs_density_matrix_prepared().

Parameters:

• density_matrix (Any) – Current density matrix.

• hamiltonian (Any) – Hamiltonian matrix.

• jumps (list[Any] | tuple[Any, ...]) – Lindblad jump operators.

• backend (Literal['scipy', 'cupy'] | ~qlinks.open_system.backend.OpenSystemBackend) – Open-system backend name or object.

Returns:

Density-matrix derivative on the requested backend.

qlinks.open_system.lindblad_rhs_density_matrix_prepared(density_matrix, *, dense_operators)

Evaluate the dense Lindblad RHS using preconverted operators.

qlinks.open_system.lindblad_rhs_density_matrix_sparse_prepared(density_matrix, *, sparse_operators)

Evaluate the Lindblad RHS using sparse operators on a dense rho.

This is the matrix-free Liouville action in density-matrix form. It avoids constructing the dim^2 x dim^2 Liouvillian and also avoids densifying sparse Hamiltonian/jump operators. It is useful for intermediate dimensions where the explicit Liouvillian is too large but the density matrix itself still fits in memory.

qlinks.open_system.local_operator_matrix_unit_expansion(*, local_patterns, local_operator, tolerance=1e-10)

Expand a local operator into matrix-unit terms.

qlinks.open_system.local_rank_one_matrix_unit_expansion(*, local_patterns, alpha, beta, tolerance=1e-10)

Expand |alpha><beta| into local matrix units |a><b|.

qlinks.open_system.local_reduced_density_matrix_from_state(*, basis_configs, state, variable_indices, tolerance=1e-10)

Compute the local RDM of a state represented in a constrained basis.

qlinks.open_system.local_reduced_density_matrix_from_state_matrix(*, basis_configs, states, variable_indices, tolerance=1e-10)

Compute the local RDM of the normalized projector onto a state subspace.

states may have shape (dim, n_states) or (n_states, dim). The columns are orthonormalized before tracing out the environment, so callers may pass linearly dependent representatives without changing local support.

qlinks.open_system.local_subspace_support_report_for_subspace(*, basis_configs, states, regions, source='local_rdm_block_reset', deduplicate_regions=False, max_jumps_per_region=1, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, max_candidates_per_region=None, prefer_sparse=True, two_pattern_tolerance=1e-08)

Build only the local manifold-support report for candidate regions.

qlinks.open_system.local_subspace_support_report_from_recycling_build_result(build_result)

Summarize local RDM support/nullity and selected recyclers by region.

qlinks.open_system.normalize_state(state, *, atol=0.0)

Return a normalized complex state vector.

qlinks.open_system.observable_vs_time(rho_t, observable)

Return Tr[rho(t) observable] for each density matrix.

qlinks.open_system.prepare_dense_lindblad_operators(*, hamiltonian, jumps, backend='scipy', dtype=<class 'numpy.complex128'>)

Convert Lindblad operators once for repeated dense RHS calls.

qlinks.open_system.prepare_sparse_lindblad_operators(*, hamiltonian, jumps, backend='scipy', sparse_format='csc', dtype=<class 'numpy.complex128'>)

Convert sparse Lindblad operators once for Liouville-space construction.

qlinks.open_system.projector(state)

Return |state><state|.

qlinks.open_system.pure_density_matrix(state, *, normalize=True)

Return |psi><psi|.

qlinks.open_system.random_density_matrix(dim, *, kind='mixed', rank=None, rng=None)

Draw a random pure or mixed density matrix.

Parameters:

• dim (int) – Hilbert-space dimension.

• kind (Literal['pure', 'mixed', 'maximally_mixed']) – "pure" for |psi><psi| or "mixed" for a Ginibre mixed state.

• rank (int | None) – Optional effective rank for kind="mixed".

• rng (Generator | int | None) – NumPy random generator or seed.

Returns:

Density matrix with trace one.

Raises:

ValueError – If kind is unsupported or rank is incompatible.

Return type:

ndarray[tuple[Any, …], dtype[complex128]]

qlinks.open_system.random_mixed_density_matrix(dim, *, rank=None, rng=None)

Draw a random mixed density matrix using a Ginibre ensemble.

The state is generated as rho = X X^\dagger / Tr(X X^\dagger) where X has shape (dim, rank).

Parameters:

• dim (int) – Hilbert-space dimension.

• rank (int | None) – Optional effective rank. If None, use full rank dim.

• rng (Generator | int | None) – NumPy random generator or seed.

Returns:

Hermitian, positive-semidefinite density matrix with trace one.

Return type:

ndarray[tuple[Any, …], dtype[complex128]]

qlinks.open_system.random_pure_density_matrix(dim, *, rng=None)

Draw a random pure density matrix |psi><psi|.

qlinks.open_system.random_pure_state(dim, *, rng=None)

Draw a Haar-like random complex state vector.

qlinks.open_system.run_quantum_jump_trajectory(*, hamiltonian, jumps, state_initial, times, rng=None, backend='scipy', return_backend_arrays=False, store_states=True, normalize_each_step=True, max_jump_probability=0.1, prefer_sparse_operators=True, prefer_sparse_rate_evaluator=True, use_total_rate_first=True, adaptive_time_step=False, adaptive_safety_factor=0.8, min_step_size=1e-12, max_substeps_per_interval=100000)

Run one Monte Carlo wave-function trajectory.

This uses a first-order no-jump propagator. It is therefore deliberately conservative: if the total jump probability in one time step is too large, it raises an error and asks the caller to refine the time grid.

qlinks.open_system.sample_lindblad_mcwf(*, hamiltonian, jumps, times, state_initial=None, state_sampler=None, options=None, rng=None)

Estimate Lindblad evolution with Monte Carlo wavefunction trajectories.

Parameters:

• hamiltonian (Any) – Hamiltonian matrix.

• jumps (list[Any] | tuple[Any, ...]) – Lindblad jump operators.

• times (ndarray[tuple[Any, ...], dtype[float64]]) – Strictly increasing time grid.

• state_initial (Any | None) – Fixed initial pure state used for every trajectory. Mutually exclusive with state_sampler.

• state_sampler (Callable[[Generator], Any] | None) – Optional callable that samples an initial pure state from a NumPy random generator.

• options (McwfOptions | None) – MCWF sampling and storage options.

• rng (Generator | int | None) – Optional RNG or seed. Overrides options.seed when supplied.

Returns:

Ensemble result containing averaged density matrices when requested, optional low-rank state snapshots, and optional stored trajectories.

Return type:

EnsembleResult

qlinks.open_system.scan_local_recycling_candidates(*, basis_configs, target_state, variable_indices, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-10, max_candidates=None)

Scan local rank-one recycling jumps from rho_Omega.

qlinks.open_system.scan_local_recycling_candidates_for_subspace(*, basis_configs, states, variable_indices, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-10, max_candidates=None)

Scan local rank-one recycling jumps from a target subspace RDM.

qlinks.open_system.score_recycling_jump(*, jump, target_state)

Return target residual, inflow, outflow, and projector commutator.

The diagnostics are Frobenius norms of the corresponding projected operators. They can be evaluated from J|psi> and J^dagger|psi> without materializing the dense projectors |psi><psi| and I-|psi><psi|.

qlinks.open_system.score_recycling_jump_for_subspace(*, jump, states, tolerance=1e-10)

Return residual/inflow/outflow diagnostics for a target subspace.

The target subspace is represented by an orthonormal basis Q. The returned values are Frobenius norms of J Q and J^† Q; when J Q=0 the second norm equals the direct inflow block Q_perp J^† Q.

qlinks.open_system.select_local_recycling_candidates(*, scan_result, source='local_rdm_two_pattern', max_candidates=1, prefer_sparse=True, two_pattern_tolerance=1e-08)

Select recycling candidates from one scan result.

local_rdm_rank_one and local_rdm_two_pattern keep the historical behavior: they choose the best few rank-one reset maps |alpha><beta|.

local_rdm_null_basis is designed for monitor-recycler jumps L=V P. A single rank-one recycler can make V P much more singular than the monitor P itself, because it only tests one local beta direction. This source instead selects one good target-support vector alpha for every local-RDM null vector beta.

local_rdm_block_reset is the compressed version: it groups up to rank(rho_R) null vectors into each reset channel. The max_candidates argument is intentionally ignored for both null-basis and block-reset sources, because their counts are determined by the local RDM ranks.

qlinks.open_system.select_recycled_manifold_dark_detector_jumps(*, hamiltonian, states, basis_configs, detector_operators, local_regions, detector_coefficients=None, dark_operator_report=None, candidate_report=None, detector_operator_names=None, detector_names=None, recycler_source='rdm_support_matrix_units', tolerance=1e-10, rdm_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, kernel_tolerance=1e-10, liouvillian_zero_tolerance=1e-09, max_detectors=None, max_candidate_pool=128, max_selected_jumps=16, target_bad_kernel_dimension=0, allow_non_improving=False, expand_candidate_report=False, selection_strategy='diagnostics', compression_strategy='none', max_compression_passes=1, collective_recycler_strategy='none', collective_recycler_weighting='unit', normalize_collective_recyclers=True, check_final_diagnostics=None)

Greedily select a small recycled-detector jump subset.

The candidate family is J=R D: D is a collective detector dark on the target manifold, and R is a local matrix-unit/RDM-support recycler. The selector first keeps the best direct-inflow candidates, then adds jumps one at a time to minimize the complement common jump-kernel dimension

dim( intersection_mu ker J_mu ∩ P_M^perp ).

Reaching target_bad_kernel_dimension=0 is a strong, jump-only sufficient condition that no complement vector remains dark under all selected jumps. It is stronger than the true invariant-subspace condition including H, but cheaper and useful before expensive Liouvillian spectrum checks.

If candidate_report is a truncated diagnostic report, set expand_candidate_report=True and max_candidate_pool=None to rescan and use the full local recycler candidate family. This is often the right follow-up when a small inflow-ranked pool leaves a low-dimensional bad complement kernel.

selection_strategy="kernel_projection" is faster for large two-region recycler pools: it updates the current complement common kernel directly by applying each candidate to the current bad subspace, and runs the full diagnostics only once at the end. "ranked_inflow" is the production preselection mode for large scans: it trusts the inflow-ranked candidate report and selects the top candidates directly. By default this production mode skips the expensive final common-kernel diagnostic; pass check_final_diagnostics=True when you want the full certificate.

qlinks.open_system.select_targeted_residual_kernel_jumps(*, targeted_report, hamiltonian=None, states=None, base_jumps=(), max_selected_jumps=16, target_residual_kernel_dimension=0, selection_target='reported_residual_kernel', allow_non_improving=False, kernel_tolerance=1e-10, dark_tolerance=1e-10, inflow_tolerance=1e-12, liouvillian_zero_tolerance=1e-09, check_manifold_diagnostics=True, liouvillian_spectrum_method='none', sparse_liouvillian_eigenvalue_count=32)

Greedily select targeted local jumps removing a residual bad kernel.

The input report is produced by diagnose_targeted_residual_kernel_linear_search().

With selection_target="reported_residual_kernel" this preserves the original behavior: each step minimizes the remaining kernel inside the residual basis stored in targeted_report. With selection_target="combined_common_kernel" the selector instead starts from the complement common jump-kernel of the supplied base_jumps and greedily minimizes the combined bad kernel of base_jumps plus the targeted candidates. The latter is the right mode after a compressed recycled-detector subset leaves a small complement kernel that is not identical to the full-family residual basis used to create the targeted report.

qlinks.open_system.solve_lindblad(*, hamiltonian, jumps, density_matrix_initial, times, method='auto', backend='scipy', options=None)

Evolve a density matrix under a Lindblad master equation.

Parameters:

• hamiltonian (Any) – Hamiltonian matrix.

• jumps (list[Any] | tuple[Any, ...]) – Lindblad jump operators.

• density_matrix_initial (Any) – Initial density matrix.

• times (ndarray) – Strictly increasing one-dimensional time grid.

• method (Literal['auto', 'krylov', 'rk4_matrix', 'rk4_sparse_matrix', 'rk4_liouville']) – Solver method, or "auto".

• backend (Literal['scipy', 'cupy']) – Open-system backend name.

• options (LindbladEvolutionOptions | None) – Optional full options object. When supplied, method and backend override the corresponding fields.

Returns:

Evolution result containing density matrices and diagnostics metadata.

Return type:

LindbladEvolutionResult

qlinks.open_system.target_manifold_coherence_series(*, norm='fro', **kwargs)

Return off-diagonal coherence of target-manifold density matrices.

norm="fro" returns the Frobenius norm of off-diagonal entries, while norm="l1" returns their elementwise absolute sum.

qlinks.open_system.target_manifold_density_matrix(density_matrix, *, target_states=None, target_basis=None, normalize=True, tolerance=1e-10)

Return the density matrix reduced to the target manifold basis.

The returned matrix is Q^dagger rho Q where columns of Q are an orthonormal target basis. When normalize=True this is conditioned on being in the manifold by dividing by Tr(Q^dagger rho Q). If the weight is numerically zero, the unnormalized zero matrix is returned.

qlinks.open_system.target_manifold_density_matrix_series(*, density_matrices=None, evolution_result=None, ensemble_result=None, state_snapshots=None, target_states=None, target_basis=None, normalize=True, tolerance=1e-10)

Return Q^dagger rho(t) Q for a target manifold basis.

The result has shape (n_times, manifold_dimension, manifold_dimension). With normalize=True each time slice is conditioned by its target-manifold weight, i.e. it is divided by Tr(P_target rho(t)) when the weight is nonzero.

qlinks.open_system.target_manifold_entropy_series(*, base=None, tolerance=1e-12, **kwargs)

Return von Neumann entropy of target-manifold density matrices.

The input density matrices are usually conditioned by leaving normalize=True in kwargs. Eigenvalues below tolerance are ignored in the logarithm.

qlinks.open_system.target_manifold_populations_series(**kwargs)

Return diagonal populations of the target-manifold density matrices.

qlinks.open_system.target_manifold_projector(target_states, *, tolerance=1e-10)

Return the projector onto a target manifold.

target_states may be one target vector, a (dim, n_states) matrix, or an (n_states, dim) matrix. The columns/rows are orthonormalized before building the projector, so linearly dependent target vectors are harmless.

qlinks.open_system.target_manifold_purity_series(**kwargs)

Return Tr(rho_target(t)^2) for target-manifold density matrices.

qlinks.open_system.target_manifold_weight(density_matrix, *, target_states=None, target_basis=None, projector=None, tolerance=1e-10)

Return Tr(P_target rho) for one density matrix.

Pass either target_states/target_basis or an explicit projector. When a target basis is supplied, the computation uses Tr(Q^dagger rho Q) and avoids materializing the full projector.

qlinks.open_system.target_manifold_weight_series(*, density_matrices=None, evolution_result=None, ensemble_result=None, state_snapshots=None, target_states=None, target_basis=None, projector=None, tolerance=1e-10)

Return Tr(P_target rho(t)) for evolution or MCWF output.

Exactly one data source must be supplied: density_matrices, a LindbladEvolutionResult via evolution_result, an EnsembleResult via ensemble_result, or MCWF state_snapshots. For state snapshots, each snapshot is expected to be a (dim, n_trajectories) state matrix and the returned weight is the trajectory average of <psi|P_target|psi>.

qlinks.open_system.unvectorize_density_matrix(vectorized_density_matrix, dim)

Restore a density matrix from column-major Liouville vectorization.

Parameters:

• vectorized_density_matrix (Any) – Vector returned by vectorize_density_matrix().

• dim (int) – Hilbert-space dimension.

Returns:

(dim, dim) density matrix.

Return type:

Any

qlinks.open_system.vectorize_density_matrix(density_matrix)

Vectorize a density matrix in column-major Liouville convention.

Parameters:

density_matrix (Any) – Square density matrix rho.

Returns:

Flattened vector with entries ordered as Fortran/column-major storage.

Return type:

Any

qlinks.open_system.verify_density_matrix(rho, *, target_state=None, atol=1e-10)

Check whether an array is a valid density matrix.

Parameters:

• rho (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Candidate density matrix.

• target_state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None) – Optional pure state used to compute <psi|rho|psi>.

• atol (float) – Absolute tolerance for trace, Hermiticity, and positivity checks.

Returns:

Verification record with scalar diagnostics and boolean flags.

Raises:

ValueError – If rho is not square or target_state is invalid.

Return type:

DensityMatrixVerification

qlinks.open_system.verify_lindblad_final_state(rho, *, hamiltonian, jumps, target_state=None, atol=1e-10, backend='scipy')

Verify density-matrix validity and Lindblad stationarity.

Parameters:

• rho (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]) – Candidate final density matrix.

• hamiltonian (Any) – Hamiltonian matrix.

• jumps (list[Any] | tuple[Any, ...]) – Lindblad jump operators.

• target_state (Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str] | None) – Optional pure state for fidelity diagnostics.

• atol (float) – Absolute tolerance passed to verify_density_matrix().

• backend (Literal['scipy', 'cupy'] | ~qlinks.open_system.backend.OpenSystemBackend) – Open-system backend name or object.

Returns:

Final-state verification record.

Return type:

LindbladFinalStateVerification