Repository navigation
Highlights for this release include: 2D periodic local expectations, fermionic and abelian compression method support and a 1D compression guide.
Breaking changes
Decomposition and compression defaults
array_splitand low-level rank-revealing decompositions now default tocutoff_mode="rel"instead of"rsum2". 1Dzipupcompression also defaults to"rel".- Randomized SVD and batched decompositions reject active cumulative cutoff modes. Use
"abs"or"rel"instead. tensor_network_1d_compresswith an arbitrary-geometrymethodalways returns a 1D network, inserting identities along long-range bonds. To keep the geometry, calltensor_network_ag_compressdirectly, as 2D boundary contraction now does for periodic boundaries, which therefore need an arbitrary-geometrymethod.
Hilbert spaces and Hubbard models
HilbertSpace: site ordering is now immutable.set_orderingraisesTypeError. Usewith_orderingto create a space with a different ordering.fermi_hubbard_from_edges: default toorder="interleaved", alternating spins at each coordinate to avoid MPO bond dimensions growing with system size, with slightly slower matrix-vector products. Rebuild anything keyed by rank or flat configuration. Useorder="blocked"for the old layout.
Partial traces and local expectations
- 2D
compute_local_expectation: computetr(rho G)from each term's reduced density matrix and normalize locally by default (normalized=True). Withreturn_all=True, return plain values, or(expec, trace)pairs withnormalized="return". - 2D
compute_local_expectationand the new 2D partial trace, expectation, and environment methods requiremax_bond. SupplyNoneexplicitly for no limit, which is not recommended in 2D. - 2D
partial_traceandlocal_expectationuse the boundary or envs routes. For the previous arbitrary-geometry compressed contraction withoptimize, callTensorNetworkGenVector.partial_traceorTensorNetworkGenVector.local_expectationdirectly. - Partial traces derive bra index names by replacing a leading
kwithb, falling back to random uuids on a name collision. This affectspartial_trace_exact,make_reduced_density_matrix, and 3D partial traces. Seeget_bra_inds. - Cluster expectations default to
smudge=1e-12andoptimize="auto-hq", matching cluster partial traces.
Dependencies
- Require
autorayv0.10.0 or newer andcotengrav0.8.3 or newer.
Enhancements
Tensor decompositions
qr_via_choleskysupports repeated orthogonalization withpasses.- Add
method="qr:auto", which tries Cholesky QR for suitable matrices and uses standard QR if it fails or loses too much orthogonality. - Split functions accept
cutoff="auto":1e-10for exact decompositions, disabled for randomized SVD. svd_rand_truncated: support"abs"and"rel"cutoffs on the sketched spectrum, andnoise_dist="normal"or"rademacher"for the random sketch.- Batched
"abs"and"rel"cutoffs treat blocks as one spectrum and retain a common bond dimension. Both modes support renormalization, including for batched decompositions.
1D compression and MPS
- Add successive deterministic compression (
method="sdc"),sdc-oversample, and randomized variantssdcrandsdcr-oversample, supporting fermionic networks, based on https://arxiv.org/abs/2601.19650. direct,dm,zipup,sdc,sdcr,src,srcmps,fit, and their oversampling variants handle long-range bonds directly, supportingsymmrayabelian and fermionic tensors (forsrcmpsandfit, with a suppliedtn_fit).dmuses QR-SVD when a site's density matrix would exceed its rank bound, reducing layered PEPS norm boundary contraction costs (https://arxiv.org/abs/2406.09769), including for fermionic networks.src,srcmps,fit, and their oversampling variants accept aseedor random generator and match the backend's device and dtype. By default, use the backend's global random state.tensor_network_1d_compressdefaults tocutoff="auto", choosing the cutoff for each method:0.0forsrcandsrcmps, disabled forsdcrwith its default randomized SVD, and1e-10otherwise.zipup,sdc, andsdcroversampling acceptcutoff_mode_oversample. Zipup also acceptscutoff_oversample="auto". All 1D oversampling methods acceptcompress_opts_finalto configure the final direct sweep separately.fitwithbsz=1now supports fermionic tensor networks, including odd-parity tensors.- Add
MatrixProductState.from_product, also used byMPS_product_state, with support for block-sparse single-site vectors. - Compression functions accept tag groups in
site_tags; seeparse_site_tag_groups. The 1D, 2D, and arbitrary-geometry wrappers also accept custommethodcallables.
Partial traces, environments, and 2D contraction
- Add
quimb.tensor.environmentsfor computing many block or plane environments in one sweep on open or periodic geometries.EnvironmentPlansupports"tree","cut"and"cutpair"schedules.gen_exact_environmentsandgen_compressed_environmentsyield environments as they become ready. Choose a 1D, 2D, or arbitrary-geometry compressor withcompress_fn. - 1D partial traces and local expectations support periodic MPS with
route=None,"canonical", or"envs".MatrixProductState.partial_tracereturns a dense reduced density matrix;compute_partial_tracescomputes many at once. Addlocal_expectationalongsidecompute_local_expectation, with explicit methods for each route. - Add
TensorNetwork1D.gen_block_environmentsandcompute_block_environmentsfor exact block environments, andis_cyclicto check for periodic chains. - 2D partial traces and local expectations support periodic PEPS with
route=None,"boundary", or"envs"and optionsmax_bond,cutoff, andmethod. AddTensorNetwork2DVector.partial_trace,compute_partial_traces, andlocal_expectation, with explicit methods for each route. - Add
TensorNetwork2D.gen_block_environmentsandcompute_block_environmentsfor compressed row or column block environments, andcompute_plaquette_environments_via_envsfor plaquettes, including those crossing periodic boundaries. - The 2D
"envs"route supportssecond_denseto control exact contraction of the remaining strip, by default only for strips one plane wide, alongsideautogroup,first_contract, customlayer_tags, fixedplaquette_sizes, andcallback_rhosto save reduced density matrices as they finish.max_separation=0.5enables half-layer compression, including with a single periodic environment. - Add the 2D
"cluster_boundary"route:partial_trace_cluster_boundary,compute_partial_traces_cluster_boundary, andcompute_local_expectation_cluster_boundary. Control cluster size withmax_distance, including across periodic boundaries or over a whole periodic direction, optionally insert simple-updategauges, and use 1D boundary compression methods.max_separationcontrols uncompressed lines around kept sites, with0.5enabling half-layer compression even with only one boundary. contract_boundarywitharoundnow respectsmax_separationon each side of the target region.- Add
compute_partial_traces_exactandcompute_partial_traces_clusterfor computing many reduced density matrices at once. - Exact and cluster partial traces now accept
get="tn"for an uncontracted network.D2BP.partial_tracenow acceptsnormalized="return"for(rho, trace)without normalization. - 2D
contract_boundarywithmethod="full-bond"acceptscompress_optsto configure the similarity decomposition, orsimilarity_methodas a shortcut. - Norm, overlap, and reduced density matrix constructors, and 2D norm, normalization, partial trace, and expectation methods accept
layer_tags=Trueor1for the default ket and bra tags andFalseor0to disable them. Methods operating on an existing network reject these boolean and integer options with a clear error. 2Dnormalizeand boundary route partial traces now use custom layer tags, which were previously ignored.
Gates and circuits
- Add
daggerandtransposeoptions to tensor-network gating methods, includingtensor_network_gate_inds,tensor_network_gate_sandwich_inds,tensor_network_ag_gate,tensor_network_ag_gate_simple, andgate_sandwich_with_op_lazy. These apply$G^\dagger$ or$G^T$ instead of$G$ .MatrixProductState.gate_nonlocalalso acceptstranspose. - Add
MatrixProductOperator.gate_sandwich_with_auto_swapfor two-site gate sandwiches that preserve canonical form, including long-range gates, with optional exponent stripping. -
CircuitPEPOSimpleUpdate: adddtype,to_backend, andconvert_eageroptions, matchingCircuitPEPSSimpleUpdate.
Time evolution and run management
- Add
LocalHamGen.get_trotter_gatesfor first-, second-, and fourth-order Trotter approximations over multiple steps, inherited by 1D, 2D, and 3D Hamiltonians.TrotterGateobjects unpack asU, where. Consecutive uses of the same commuting layer are fused by default.trotter_schedulereturns the product formula alone. build_mpo_propagator_trotterizedandbuild_pepo_propagator_trotterizedacceptorder(default 1). The 1D method also gainsordering, matching the 2D method.- TEBD and simple-update classes accept
logdirandlog_everyto writeprogress.json. Useplot_progress_logwithwatch=Trueto monitor a running job, orload_progress_logfor raw data. - These classes accept
checkpoint_everyto savecheckpoint.pklinlogdir, including a final checkpoint on normal or graceful completion. Continue withresume=Trueor load withfrom_checkpoint; resumed runs restore state and evolution options, so omitpsi0andham. log_everyandcheckpoint_everyaccept sweep counts or durations such as"10mins"; seeparse_time_spec.- A
STOPfile inlogdiror the first Ctrl-C duringevolvestops the run after the current sweep. The file is removed once seen; a second interrupt stops immediately. Usegraceful_interrupt=Falsefor the previous interrupt behavior.
Belief propagation and loop expansions
- Add
Tensor.multiply_index_diagonalsfor applying multiple diagonal weights together, also used by simple gauging. - Support fermionic BP projector compression with
method="projector", canonize="bp"and fermionic gates withD2BP.gate_. - All BP classes accept
diisanddampingin both__init__andrun. Values passed torunbecome the new defaults. D1BP,D2BP,L1BP,L2BP, andTensorNetwork.gauge_all_simpleacceptsweep_order, with an efficient alternating schedule for trees. SeeSweepSchedulerfor other options.- Add
gen_gloops_edge_induced(tn.gen_gloops_edge_induced), yieldingNetworkPatchobjects that distinguish loops using different bonds on the same tensors. - Infinite 2D generalized-loop expectations accept
max_sizeandnum_joins. Reuse theirinfocache across loop settings while the state, gauges, and operators remain unchanged.
Network construction
TN_from_strings: addjoin_prefer="short"or"long"to favor smaller or larger loops, andjoin_avoid_loop_length(default 2) to avoid loops up to a given length. Set it to 0 to disable loop avoidance.join_preferdoes not supportjoin="all".- Add hidden-cactus networks
TN2D_rand_hidden_cactus,TN3D_rand_hidden_cactus, andTN_rand_hidden_cactusto extend hidden correlations while preserving lattice bond dimensions and low exact contraction cost. Also available throughTN_from_strings(..., join_trees=True). - Add
TN_rand_hidden_loop, the arbitrary-graph counterpart ofTN2D_rand_hidden_loop. - Add
TensorNetwork.insert_projectors_between_regionsto insert precomputed projector arrays between regions. TN_matching: addedgesto choose which sites to join, for example a plain chain ignoring long-range bonds.
Hilbert spaces and utilities
HilbertSpace: supportU1U1sectors with any site ordering and aspeciesargument selecting each site's conserved charge. Accept sector forms{species: filling},(ka, kb), and((na, ka), (nb, kb)).order="blocked"groups species;"interleaved"alternates them at each position.- Add
distance_from_overlapsfor normalized distances and infidelities from three precomputed overlaps. save_to_disk: addatomicto prevent partially written targets.
Contraction
TensorNetwork.contractwithstrip_exponent=Truecan now takecheck_zero=Trueto return an exactly zero result as(0.0, 0.0)instead ofnan(not yet for compressed contraction).
Deprecations
Tensor.gate: renametransposedtotranspose. The old name raisesFutureWarning.- 2D boundary contraction, environment, and norm methods: rename
modetomethod, withFutureWarningfor the old name. Withmode="full-bond", amethodsupplied as well is taken assimilarity_method. MatrixProductState.compute_local_expectation: renamemethodtoroute, withFutureWarningfor the old name.- Rename
MatrixProductState.partial_trace_to_dense_canonicaltopartial_trace_canonical. The old name still works but raises a warning. TN_from_strings: deprecatejoin_avoid_self_loopsin favor ofjoin_avoid_loop_length.
Bug fixes
Sparse matrices
csr_matrix @ vector: fix wrong results for tall matrices and segfaults for wide matrices on the parallel path, used fornnz > 50000oncequimbis imported (#432).
Operators and time evolution
SpinHam1D.build_sparse: include the last term withcyclic=True(#419).ikron: raiseValueErrorfor out-of-range or repeated indices, which previously placed fewer operators than supplied without an error.build_matrix_ikron: fix incorrect matrices with non-identity ordering or non-integer site labels.HilbertSpace: prevent incorrect rank-to-configuration mappings after reordering, including invalid configurations for mixed dimensions. Ordering is now immutable, as described above.TEBD: fixorder=4to achieve fourth-order accuracy. Correct Suzuki weights include backward evolution during part of each step. Also acceptorder=1.build_mpo_propagator_trotterized: fix cyclic wrapping terms that are not symmetric under a site swap.FullUpdate: reuse the cached plaquette map incompute_energy.
Decompositions and compression
compute_oblique_projectors: avoidinfornanprojectors for rank-deficient environments withcutoff=0.0. The same fix applies to shared diagonal division helpers andD2BP.gauge_insertwithreturn_gauges="inverse".safe_inverse: fixTypeErrorin projector boundary contractions with block-sparse backends such assymmray.tensor_split: fixmethod="svd:rand"for complex and single-precision arrays, preserving dtype and device, andmethod="svd:eig"with nonzerocutofffor single precision and Numba.- Oblique projector compression, including
L2BP.compress, CTMRG, and HOTRG: fixshape-mismatcherrors withsymmrayblock-sparse arrays. - 3D boundary contraction: remove temporary site tags from replaced tensors, including those shared with cached environments.
- 1D
fitwithmax_iterations=1: build any initial guess atmax_bondrather than padding a smaller one, and fix aTypeErrorwhen onlycutoffis given. - 1D
srcmps: conjugate the sampling MPS, so a supplied guess helps for complex arrays, and odd-parity fermionic networks work.
Fermionic tensors
- 1D compression: fix
fitfor fermionic networks, anddmfor mixed bond orientations and truncated odd-parity norm networks. - Projector compression (
method="projector"): fix zero projectors for odd-parity fermionic norm networks with everycanonizeoption. D2BP.compressandD2BP.gauge_symmetric: preserve positive messages and full-rank identity matrices for fermionic networks.Tensor.conj: addoutput_indsto select output legs for fermionic conjugation phases. Fix conjugation phases for subnetworks and paired and unpaired odd-parity dummy modes inTensorNetwork.conjandTensor.conj.
Belief propagation and overlaps
D1BP.contract_loop_series_expansionandD2BP.contract_loop_series_expansion: include all distinct loops in each region and correct suppression factors. Multi-excitation corrections raiseRuntimeErrorif they fail to converge.D2BP.normalize_tensorsand single-siteD2BP.gate_: keep contractions consistent after updates. Reject distinct supplied networks, and fix message ordering for complex two-site gates.D2BP.gauge_temp: restore gauges when its body raises. Fix relativesmudgescaling for unsorted symmetry-block spectra.tensor_network_distance: remove incorrect dependence of infidelity on relative phase.
Partial traces and general tensor operations
partial_trace_exact: fixAttributeErrorwithget="tensor"andnormalized=True.- Exact, cluster, and arbitrary-geometry partial traces and local expectations accept a single site as
whereinstead of raisingTypeError. local_expectation_cluster: supportmax_bondon MPS.- 2D
compute_local_expectation: accept reversed two-site terms withoutKeyErrorin the boundary route. compute_local_expectation_exactandcompute_local_expectation_cluster: correctly sum normalized expectations withnormalized="return"andreturn_all=False. Methods that compute terms individually also complete their progress bars.MPS_product_state: fixTypeErrorfor backends requiring a single shape tuple when reshaping single-site vectors.TensorNetwork.tids_are_connected: make results independent of tensor order.compute_plaquette_environmentsandcompute_environments: environments now have the correct scale withequalize_norms, and plaquette environments also include the network's own exponent.TensorNetwork.contract_tags: include the network's existingexponentwhen contracting all tensors.
Documentation
- Add a 1D compression guide with method comparisons, benchmarks, and usage examples.
- Move quantum circuits to a top level Quantum Circuit Guide, with circuit examples grouped separately.
PRs
- operator: arbitrary orders with u1u1 symmetry sectors by @jcmgray in #407
- gate-sandwich and other variants: add dagger kwarg, gate: also add transpose kwarg by @jcmgray in #408
- LocalHam: add get_trotter_gates method by @jcmgray in #409
- MatrixProductOperator: add gate_sandwich_with_auto_swap by @jcmgray in #410
- TN compress 1d fns: use autoray 'random.array' for src, srcmps, fit methods by @jcmgray in #411
- TN 1d compress: add successive deterministic compression (method="sdc") by @jcmgray in #412
- TN1D compression: fix sdc for fermionic networks, safe_inverse for symmray arrays by @jcmgray in #414
- fix various fermionic compression routines by @jcmgray in #416
- D1BP: for sparse coo tensors, use specialized numba contraction kernels by @jcmgray in #417
- BP: fix loop series expansion by enumerating edge induced gloops by @jcmgray in #418
- fully fix dm and fit methods fermionic compression, extend test matrix by @jcmgray in #420
- fix #419, SpinHam1D with cyclic=True dropping a term by @jcmgray in #421
- tn1d compress: add "sdcr" and "sdcr-oversample" methods by @jcmgray in #423
- TN: add rand_hidden_cactus builders by @jcmgray in #424
- Bump prefix-dev/setup-pixi from 0.10.0 to 0.10.1 in the dependencies group by @dependabot[bot] in #422
- tensor network compress methods: accept site_tags as sequence of groups by @jcmgray in #425
- cutoff_mode changes include default 'rel' by @jcmgray in #426
- TEBDSweepMixin: add logging features and graceful stopping by @jcmgray in #427
- D2BP: fix fermionic TNs for most use cases including gating and projector gauging by @jcmgray in #428
- Add machinery for 1d/2d/3d periodic boundary expectations by @jcmgray in #429
- more fermionic compression fixes: support norm networks with odd parities in dm+projector methods by @jcmgray in #430
- Bump prefix-dev/setup-pixi from 0.10.1 to 0.10.2 in the dependencies group by @dependabot[bot] in #431
- add cutpair pbc contract schedule, more max_separation=0.5 support and other improvements by @jcmgray in #433
- Bump the dependencies group with 2 updates by @dependabot[bot] in #435
- Respect tol parameter in decomp print mode by @davrens101 in #436
New Contributors
- @davrens101 made their first contribution in #436
Full Changelog: v1.15.0...v1.16.0