Pymablock

Pymablock#

✨ NEW! Second Quantization Support ✨

Pymablock now fully supports operator formalism and works with second-quantized operators: fermions, bosons, spins, and ladder (Floquet)! Check out our dispersive shift tutorial and Jaynes-Cummings model tutorial to see second quantization in action, and see the theoretical background in second quantization notes.

What is Pymablock?#

Pymablock (Python matrix block-diagonalization) is a Python package that constructs effective models using quasi-degenerate perturbation theory. It handles both numerical and symbolic inputs, and it efficiently block-diagonalizes Hamiltonians with multivariate perturbations to arbitrary order.

Building an effective model using Pymablock is a three step process:

  • Define a Hamiltonian

  • Call block_diagonalize

  • Request the desired order of the effective Hamiltonian

from pymablock import block_diagonalize

# Define perturbation theory
H_tilde, *_ = block_diagonalize([h_0, h_p], subspace_eigenvectors=[vecs_A, vecs_B])

# Request correction to the effective Hamiltonian
H_AA_4 = H_tilde[0, 0, 4]

Why Pymablock?#

Here is why you should use Pymablock:

  • Do not reinvent the wheel

    Pymablock provides a tested reference implementation

  • Apply to any problem

    Pymablock supports numpy arrays, scipy sparse arrays, sympy matrices and quantum operators

  • Speed up your code

    Due to several optimizations, Pymablock can reliably handle both higher orders and large Hamiltonians

How does Pymablock work?#

Pymablock considers a Hamiltonian as a series of block operators with the zeroth order block-diagonal. To carry out the block-diagonalization procedure, Pymablock finds a minimal unitary transformation \(U\) that cancels the off-diagonal blocks of the Hamiltonian order by order.

(1)#\[\begin{gather} \mathcal{H} = \begin{pmatrix}H_0^{AA} & 0 \\ 0 & H_0^{BB}\end{pmatrix} + \sum_{n\geq 1} H'_n,\quad \mathcal{U} = \sum_{n=0}^\infty U_n \end{gather}\]

The result of this procedure is a perturbative series of the transformed block-diagonal Hamiltonian.

(2)#\[\begin{gather} \tilde{\mathcal{H}} = \mathcal{U}^\dagger \mathcal{H} \mathcal{U}=\sum_{n=0} \begin{pmatrix} \tilde{H}_n^{AA} & 0 \\ 0 & \tilde{H}_n^{BB} \end{pmatrix}. \end{gather}\]

Similar to Lowdin perturbation theory or the Schrieffer–Wolff transformation, Pymablock solves Sylvester’s equation and imposes unitarity at every order. However, Pymablock is unique because it uses efficient algorithms by choosing a different parametrization of the series of the unitary transformation. As a consequence, the computational cost of every order scales linearly with the order, while the algorithms are still mathematically equivalent. Additionally, this parametrization allows Pymablock to perform selective diagonalization and eliminate an arbitrary subset of offdiagonal matrix elements, and to go beyond the standard \(2\times 2\) block-diagonalization.

To see Pymablock in action, check out the tutorial. See its algorithms to learn about the underlying ideas, or read the reference documentation for the package API.

What does Pymablock not do yet?#

  • Pymablock only supports periodic time-dependent perturbations, general time-dependent perturbations are in progress.

Installation#

The preferred way of installing pymablock is to use mamba/conda:

mamba install pymablock -c conda-forge

Or use pip

pip install pymablock

Important

Be aware that using pymablock on large Hamiltonians benefits from a direct sparse solver. Pymablock prefers MUMPS via the python-mumps package when available, but it can also use SciPy’s SuperLU through scipy.sparse.linalg. In our experience, the MUMPS backend is typically more performant than SuperLU. python-mumps is only pip-installable on Linux, so use conda on other platforms if you want the MUMPS backend.

Citing#

If you have used Pymablock for work that has lead to a scientific publication, please cite the accompanying paper as

@Article{10.21468/SciPostPhysCodeb.50,
  title={{Pymablock: An algorithm and a package for quasi-degenerate perturbation theory}},
  author={Isidora {Araya Day} and Sebastian Miles and Hugo K. Kerstens and Daniel Varjas and Anton R. Akhmerov},
  journal={SciPost Phys. Codebases},
  pages={50},
  year={2025},
  publisher={SciPost},
  doi={10.21468/SciPostPhysCodeb.50},
  url={https://scipost.org/10.21468/SciPostPhysCodeb.50},
}

@Article{10.21468/SciPostPhysCodeb.50-r2.1,
  title={{Codebase release 2.1 for Pymablock}},
  author={Isidora {Araya Day} and Sebastian Miles and Hugo K. Kerstens and Daniel Varjas and Anton R. Akhmerov},
  journal={SciPost Phys. Codebases},
  pages={50-r2.1},
  year={2025},
  publisher={SciPost},
  doi={10.21468/SciPostPhysCodeb.50-r2.1},
  url={https://scipost.org/10.21468/SciPostPhysCodeb.50-r2.1},
}

Contributing#

Pymablock is an open source package, and we invite you to contribute! You contribute by opening issues, fixing them, and spreading the word about pymablock. If you want to contribute code, please read the developer documentation.

Contents