** Pymablock **#

## 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 implementationApply to any problem

**Pymablock**supports`numpy`

arrays,`scipy`

sparse arrays,`sympy`

matrices and quantum operatorsSpeed 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 \(2\times 2\) 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 block of the
Hamiltonian order by order.

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

Similar to Lowdin perturbation theory or the Schrieffer–Wolff transformation,
** Pymablock ** solves Sylvester’s equation and imposes unitarity at every order.
However, differently from other approaches, ** Pymablock ** uses efficient algorithms
by choosing an appropriate 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.

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**is not able to treat time-dependent perturbations yet**Pymablock**does not block diagonalize more than two subspaces simultaneously

## 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 the using `pymablock`

on large Hamiltonians requires `Kwant`

with MUMPS support.
For this purpose, install Kwant
via conda in Linux and MAC OS.
Unfortunately, MUMPS support in Kwant is not available for Windows.
If you need it, try
Windows Subsystem for Linux (WSL).

## Citing#

If you have used ** Pymablock ** for work that has lead to a scientific publication,
please cite it as

```
@misc{Pymablock,
author = {{Araya Day}, Isidora and Miles, Sebastian and Varjas, Daniel and Akhmerov, Anton R.},
doi = {10.5281/zenodo.7995684},
month = {6},
title = {Pymablock},
year = {2023}
}
```

## 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`

.