Files
marqdo/ext/quantum/density/index.mq.md
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

11 KiB
Executable File

markup, title, description, import
markup title description import
occlusion ext/quantum/density Density-operator skill — mixed states, partial trace, expectations.
cap
ext/quantum/_capability/index.mq.md

Density operators — inspect a subsystem or a mixed-state matrix.

Build rho from an ideal circuit/state with from_state, or from a square Hermitian 2^n matrix with from_matrix. Density operations and Schmidt support at most six qubits. The matrix constructor checks shape and Hermiticity; it does not certify positive semidefiniteness or trace one. For physical inputs, check the trace and eig eigenvalues yourself before interpreting purity.

An independent mixed-state check

This one-qubit maximally mixed matrix has trace one, purity 0.5 and Z expectation zero. The complete example needs no prior circuit or saved handle. For entanglement, start from a Bell circuit, call from_state, then partial_trace with keep=[0]; purity of that reduced density is also 0.5.

marqdo call ext/quantum/density/index.mq.md from_matrix 'matrix=[[0.5,0],[0,0.5]]' --effects plugin --session handbook --toget rho --json
marqdo call ext/quantum/density/index.mq.md purity 'density=$rho' --effects plugin --session handbook --json
marqdo call ext/quantum/density/index.mq.md expect 'density=$rho' 'obs="Z"' --effects plugin --session handbook --json
marqdo call ext/quantum/density/index.mq.md eig 'density=$rho' --effects plugin --session handbook --json

partial_trace keeps the listed zero-based wires and discards the others. Pauli strings put the highest bit on the left; ZZ measures correlation on two wires. matrix exports nested complex entries, and eig returns eigenvalues and eigenvectors. Use viz.draw_density for hinton, city, density or paulivec plots. from_state ignores attached teaching noise, just like the ideal simulator; it is not a noisy density evolution engine.

Development route

Add mixed-state mathematics to plugins/quantum/src/linalg.rs, export it through src/lib.rs and update this file plus its Chinese mirror. Keep physical input validation claims aligned with the constructor. Validate pure-state purity one, Bell reduced purity one-half and observable expectations against independent matrices in tests/ext/quantum-linalg-smoke.mq.md.

from_state

参数 类型 默认 说明
state any required pure state or circuit
返回 类型 说明
result any density handle

Use state as the inputs for this operation.

Form rho as the outer product of a pure state (or the ideal state of a circuit). Use this when you trust the pure-state picture and want mixed-state tools without writing a matrix by hand.

We Load the native plugin required by this operation. Return Form rho as the outer product of a pure state (or the ideal state of a circuit).

from_matrix

参数 类型 默认 说明
matrix any required Hermitian matrix
返回 类型 说明
result any density handle

Use matrix as the inputs for this operation.

Build rho from an explicit Hermitian matrix. Pair with formula blocks in the lecture so the matrix on the page is the matrix in the simulator. Size is limited by the plugin.

We Load the native plugin required by this operation. Return Build rho from an explicit Hermitian matrix.

purity

参数 类型 默认 说明
density any required density operator
返回 类型 说明
result number purity

Use density as the inputs for this operation.

Compute the trace of rho squared for density. Values near one mean nearly pure; lower values mean classical mixing or traced-out entanglement.

We Load the native plugin required by this operation. Return Compute the trace of rho squared for density. Values near one mean nearly pure; lower values mean classical mixing or traced-out entanglement..

partial_trace

参数 类型 默认 说明
keep any required qubit index list to keep
density any required joint density
返回 类型 说明
result any reduced density

Use keep, density as the inputs for this operation.

Keep listed qubits in keep and trace out the rest of density. Indices use LSB equals zero. The result is generally mixed even when the joint state was pure.

We Load the native plugin required by this operation. Return [Keep listed qubits in keep and trace out the rest of density](quantum_density_partial_trace(density=density, keep=keep)).

expect

参数 类型 默认 说明
obs any required Pauli string or matrix
density any required density operator
返回 类型 说明
result number expectation value

Use obs, density as the inputs for this operation.

Expectation of observable obs on density. Pauli strings use left equals high bit. Pass a matrix when the observable is not a Pauli product.

We Load the native plugin required by this operation. Return [Expectation of observable obs on density. Pauli strings use left equals high bit. Pass a matrix when the observable is not a Pauli product.](quantum_density_expect(density=density, obs=obs)).

eig

参数 类型 默认 说明
density any required Hermitian density
返回 类型 说明
result any eigenvalues and eigenvectors

Use density as the inputs for this operation.

Hermitian spectrum of density as eigenvalues and eigenvectors. Useful when a lecture needs the eigenbasis of rho.

We Load the native plugin required by this operation. Return Hermitian spectrum of density as eigenvalues and eigenvectors. Useful when a lecture needs the eigenbasis of rho..

matrix

参数 类型 默认 说明
density any required Density handle / 密度句柄
返回 类型 说明
result any Nested complex entries with re and im

Use density as the inputs for this operation.

Export the explicit nested complex matrix of density. Reading entries does not change the density operator. Use the exported entries for an independent trace check or further linear algebra; the caller remains responsible for physicality.

We Load the native plugin required by this operation. Return Export the explicit nested complex matrix of density.

density

参数 类型 默认 说明
state any None Default None
matrix any None Default None
返回 类型 说明
result any Returned value

Use state=None, matrix=None as the inputs for this operation.

Construct a density operator from a pure state or circuit (state=) or from an explicit Hermitian matrix=. Density operations support at most six qubits. Pure and mixed states share this object surface for purity, partial trace, and expectation.

We Load the native plugin required by this operation.

  1. matrix Return Construct a density operator from a pure state or circuit (state=) or from an explicit Hermitian matrix=.

Return Construct a density operator from a pure state or circuit (state=) or from an explicit Hermitian matrix=.

matrix

返回 类型 说明
result any Nested complex entries with re and im

Return the explicit matrix of this density operator so authors can inspect entries or hand the array to further linear-algebra steps outside the quantum package.

Return Return the explicit matrix of this density operator so authors can inspect entries or hand the array to further linear-algebra steps outside the quantum package.

purity

返回 类型 说明
result number Scalar observation

Compute Tr(ρ²). Values near one mean a pure state; mixed states are strictly less than one. Use this as a quick entanglement or decoherence check after a partial trace.

Return Compute Tr(ρ²).

partial_trace

参数 类型 默认 说明
keep any required Required
返回 类型 说明
result any Density operator handle

Use keep as the inputs for this operation.

Trace out every qubit except those listed in keep (LSB index 0). Returns the reduced density on the kept subsystem for entanglement lectures and purity checks.

Return [Trace out every qubit except those listed in keep (LSB index 0). Returns the reduced density on the kept subsystem for entanglement lectures and purity checks.](quantum_density_partial_trace(density=self, keep=keep)).

eig

返回 类型 说明
result any eigenvalues and eigenvectors

Compute the Hermitian spectrum of this density operator as eigenvalues and eigenvectors. Handy for lecture plots and for verifying that a constructed rho is physical.

Return Compute the Hermitian spectrum of this density operator as eigenvalues and eigenvectors.

expect

参数 类型 默认 说明
obs any required Required
返回 类型 说明
result number Scalar observation

Use obs as the inputs for this operation.

Expectation value of observable obs on this density. obs may be a Pauli string with the left end as the high bit, or an explicit matrix matching the density dimension.

Return [Expectation value of observable obs on this density](quantum_density_expect(density=self, obs=obs)).

draw

参数 类型 默认 说明
path any None Default None
kind any "hinton" Default hinton
返回 类型 说明
result any quantum_svg with kind and svg

Use path=None, kind="hinton" as the inputs for this operation.

Draw a Hinton diagram, city plot, density grid, or Pauli vector for this density. Optional path writes SVG; kind selects which visual metaphor the lecture uses.

Return [Draw a Hinton diagram, city plot, density grid, or Pauli vector for this density](quantum_density_draw(density=self, path=path, kind=kind)).